Documents - Graph

Executes a graph query over an index with an edge-list graph profile.

POST {endpoint}/indexes('{indexName}')/docs/search.graph?api-version=2026-11-01-preview

URI Parameters

Name In Required Type Description
endpoint
path True

string (uri)

The endpoint URL of the search service.

indexName
path True

string

The name of the index.

api-version
query True

string

minLength: 1

The API version to use for this operation.

Request Header

Name Required Type Description
x-ms-client-request-id

string (uuid)

An opaque, globally-unique, client-generated string identifier for the request.

Accept

Accept

The Accept header.

x-ms-query-source-authorization

string (password)

Token identifying the user for which the query is being executed. This token is used to enforce security restrictions on documents.

x-ms-enable-elevated-read

boolean

A value that enables elevated read that bypass document level permission checks for the query operation.

Request Body

Name Required Type Description
gql True

string

minLength: 1

The nonempty GQL query to bind and execute.

executionMode

GraphQueryExecutionMode

Executes the query by default. planOnly builds the plan without backend query execution and requires at least one explain stage.

explain

GraphQueryExplainStage[]

Diagnostic plan stages to include in the response. Plan representations are diagnostic information rather than an executable client contract.

filter

string

An OData filter over graph-index fields applied throughout graph execution.

includeDiagnostics

boolean

Whether to include informational diagnostics. Errors and warnings are returned regardless of this setting.

includeStatistics

boolean

Whether to include graph execution statistics. Defaults to true.

provenance

GraphQueryProvenanceParameters

Controls bounded assertion evidence and optional source-document hydration.

search

string

Full-text search text used to constrain graph backend requests.

vectorQueries VectorQuery[]:

Vector queries used to constrain the graph's backend searches.

Responses

Name Type Description
200 OK

GraphQueryResult

The request has succeeded.

Other Status Codes

GraphQueryError

An unexpected error response.

Headers

x-ms-error-code: string

Security

api-key

Type: apiKey
In: header

OAuth2Auth

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Scopes

Name Description
https://search.azure.com/.default

Examples

SearchIndexGraphDocuments

Sample request

POST https://typespecpreviewexampleservice.search.windows.net/indexes('people-graph')/docs/search.graph?api-version=2026-11-01-preview





{
  "gql": "MATCH (p:Person)-[r:worksFor]->(o:Organization) WHERE p.id = 'person:ada' RETURN o.name AS organization",
  "filter": "graph_name eq 'contoso-people'",
  "includeStatistics": false,
  "provenance": {
    "kind": "ids",
    "maxEvidencePerRow": 5
  }
}

Sample response

{
  "@odata.count": 1,
  "value": [
    {
      "@search.graphProvenance": {
        "kind": "ids",
        "evidenceCount": {
          "value": 1,
          "relation": "exact"
        },
        "evidence": [
          {
            "edgeId": "assertion-1",
            "chunkId": "people-chunk-1",
            "parentId": "people-document-1"
          }
        ]
      },
      "organization": "Contoso"
    }
  ]
}

Definitions

Name Description
Accept

The Accept header.

BalancedVectorQueryTopicGraph

Blends pure vector similarity with diversity-aware retrieval. Recommended default to balance diversity with relevance.

DiverseVectorQueryTopicGraph

Uses topic graph diverse retrieval.

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

GraphQueryDiagnostic

A graph planning or execution diagnostic.

GraphQueryDiagnosticPhase

The stage that produced a graph query diagnostic.

GraphQueryDiagnosticSeverity

The importance of a graph query diagnostic.

GraphQueryError

A failed graph request with standard Search error information and optional graph diagnostics.

GraphQueryEvidence

Source assertion identifiers and confidence values retained as graph evidence.

GraphQueryEvidenceConfidence

Confidence values recorded on a supporting assertion.

GraphQueryEvidenceCount

An evidence count whose relation describes whether collection was complete.

GraphQueryEvidenceCountRelation

Completeness of an evidence count.

GraphQueryExecutionMode

Whether a graph query is executed or only planned.

GraphQueryExplainStage

Diagnostic stages available when inspecting a graph query.

GraphQueryProvenanceHydrateDocumentsParameters

Selects fields from the source index configured by graphProfile.provenanceIndexName.

GraphQueryProvenanceKind

The kind of assertion evidence returned with graph rows.

GraphQueryProvenanceParameters

Bounded provenance collection options for a graph query.

GraphQueryRequest

Request fields for querying the logical graph mapped by an index's graphProfile.

GraphQueryResult

A graph query's projected rows and optional execution information.

GraphQueryRow

A dynamic graph projection row with optional bounded assertion evidence.

GraphQueryRowProvenance

Assertion evidence supporting one projected graph row.

GraphQueryStatistics

Execution statistics for a graph query; counters describe work performed rather than result-row counts.

NoneVectorQueryTopicGraph

Uses normal vector search without topic graph diverse retrieval.

QueryRewritesType

This parameter is only valid if the query type is semantic. When QueryRewrites is set to generative, the query terms are sent to a generate model which will produce 10 (default) rewrites to help increase the recall of the request. The requested count can be configured by appending the pipe character | followed by the count-<number of rewrites> option, such as generative|count-3. Defaults to None.

SearchScoreThreshold

The results of the vector query will filter based on the '

VectorizableImageBinaryQuery

The query parameters to use for vector search when a base 64 encoded binary of an image that needs to be vectorized is provided.

VectorizableImageUrlQuery

The query parameters to use for vector search when an url that represents an image value that needs to be vectorized is provided.

VectorizableTextQuery

The query parameters to use for vector search when a text value that needs to be vectorized is provided.

VectorizedQuery

The query parameters to use for vector search when a raw vector value is provided.

VectorQueryKind

The kind of vector query being performed.

VectorSearchTopicGraphKind

The kind of topic graph vector search to use.

VectorSimilarityThreshold

The results of the vector query will be filtered based on the vector similarity metric. Note this is the canonical definition of similarity metric, not the 'distance' version. The threshold direction (larger or smaller) will be chosen automatically according to the metric used by the field.

VectorThresholdKind

The kind of threshold used to filter vector queries.

Accept

The Accept header.

Value Description
application/json;odata.metadata=none

BalancedVectorQueryTopicGraph

Blends pure vector similarity with diversity-aware retrieval. Recommended default to balance diversity with relevance.

Name Type Description
kind string:

balanced

The kind of topic graph vector search to use.

minDiversityPoolSize

integer (int32)

minimum: 250
maximum: 10000

The minimum number of vector candidates to retrieve before topic graph sampling. The default is 1,000.

DiverseVectorQueryTopicGraph

Uses topic graph diverse retrieval.

Name Type Description
diversityFactor

number (float)

minimum: 0
maximum: 1

The diversity factor used for topic graph diverse retrieval. If omitted, the default configured on the topic graph profile is used.

kind string:

diverse

The kind of topic graph vector search to use.

minDiversityPoolSize

integer (int32)

minimum: 250
maximum: 10000

The minimum number of vector candidates to retrieve before topic graph sampling. The default is 1,000.

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

searchservice.documents.graph

The additional info.

type

string

The additional info type.

ErrorDetail

The error detail.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.

code

string

The error code.

details

ErrorDetail[]

The error details.

message

string

The error message.

target

string

The error target.

GraphQueryDiagnostic

A graph planning or execution diagnostic.

Name Type Description
code

string

Stable machine-readable diagnostic identifier.

message

string

Human-readable explanation; applications should use code rather than parse this text.

phase

GraphQueryDiagnosticPhase

The stage that produced the diagnostic.

severity

GraphQueryDiagnosticSeverity

The diagnostic's importance.

span

string

Optional source-span description associated with the diagnostic.

suggestions

string[]

Suggested corrections or alternatives.

GraphQueryDiagnosticPhase

The stage that produced a graph query diagnostic.

Value Description
parse

Query syntax and parsing.

bind

Variable, parameter, function, and semantic binding.

validation

Request-option validation.

planning

Query planning, including unsupported query shapes and query-breadth restrictions.

execution

Runtime evaluation, execution-limit warnings, and execution summaries.

GraphQueryDiagnosticSeverity

The importance of a graph query diagnostic.

Value Description
error

The query was rejected or could not be evaluated successfully.

warning

Execution returned a result with a caveat, such as an execution or provenance limit.

info

Informational diagnostics, such as an optional execution summary.

GraphQueryError

A failed graph request with standard Search error information and optional graph diagnostics.

Name Type Description
@odata.count

integer (int64)

Number of projected rows in this response, not the size of an unbounded graph population.

@search.graphDiagnostics

GraphQueryDiagnostic[]

Structured errors, warnings, and requested informational diagnostics.

@search.graphExplain

GraphQueryExplain

Requested diagnostic stages. Absent stages are omitted.

@search.graphProvenanceDocuments

object

Hydrated source documents keyed by document ID, shared across result rows.

@search.graphStats

GraphQueryStatistics

Execution statistics, when requested and available.

error

ErrorDetail

Standard Search error information. Graph query rejections use InvalidRequestParameter and preserve their specific codes in graph diagnostics.

value

GraphQueryRow[]

Query projection rows. planOnly returns an empty collection.

GraphQueryEvidence

Source assertion identifiers and confidence values retained as graph evidence.

Name Type Description
chunkId

string

Source chunk identifier used for source-document lookup.

confidence

GraphQueryEvidenceConfidence

Confidence values associated with the assertion and its components.

edgeId

string

Assertion document identifier in the graph index.

parentId

string

Parent source document identifier.

GraphQueryEvidenceConfidence

Confidence values recorded on a supporting assertion.

Name Type Description
edge

number (double)

Confidence in the complete relationship.

object

number (double)

Confidence in the object grounding.

predicate

number (double)

Confidence in predicate alignment.

subject

number (double)

Confidence in the subject grounding.

GraphQueryEvidenceCount

An evidence count whose relation describes whether collection was complete.

Name Type Description
relation

GraphQueryEvidenceCountRelation

Whether value is the exact count or a lower bound.

value

integer (int32)

Number of supporting evidence entries observed.

GraphQueryEvidenceCountRelation

Completeness of an evidence count.

Value Description
exact

All supporting evidence was counted.

lowerBound

At least this many supporting entries exist; collection was bounded.

GraphQueryExecutionMode

Whether a graph query is executed or only planned.

Value Description
execute

Build and execute the graph plan.

planOnly

Build the graph plan without executing backend searches.

GraphQueryExplainStage

Diagnostic stages available when inspecting a graph query.

Value Description
syntax

Parsed query syntax.

semanticIr

Bound semantic intermediate representation.

logicalPlan

Logical plan before optimization.

optimizedLogicalPlan

Logical plan after optimization.

physicalPlan

Physical execution plan.

requestAttributions

Attribution of backend requests to execution-plan nodes.

full

All available diagnostic stages.

GraphQueryProvenanceHydrateDocumentsParameters

Selects fields from the source index configured by graphProfile.provenanceIndexName.

Name Type Description
select

string

Comma-separated source document fields to return; omitted selects the service's default retrievable fields.

GraphQueryProvenanceKind

The kind of assertion evidence returned with graph rows.

Value Description
ids

Return evidence identifiers without source documents.

hydrate

Return evidence identifiers and selected documents from the profile-configured provenance index.

GraphQueryProvenanceParameters

Bounded provenance collection options for a graph query.

Name Type Description
hydrateDocuments

GraphQueryProvenanceHydrateDocumentsParameters

Source-document selection options. Required when kind is hydrate.

kind

GraphQueryProvenanceKind

Whether to return evidence identifiers or also hydrate their source documents.

maxEvidencePerRow

integer (int32)

minimum: 1

Maximum evidence entries collected per result row. When bounded, the response indicates whether the evidence count is exact or a lower bound.

GraphQueryRequest

Request fields for querying the logical graph mapped by an index's graphProfile.

Name Type Default value Description
executionMode

GraphQueryExecutionMode

execute

Executes the query by default. planOnly builds the plan without backend query execution and requires at least one explain stage.

explain

GraphQueryExplainStage[]

Diagnostic plan stages to include in the response. Plan representations are diagnostic information rather than an executable client contract.

filter

string

An OData filter over graph-index fields applied throughout graph execution.

gql

string

minLength: 1

The nonempty GQL query to bind and execute.

includeDiagnostics

boolean

False

Whether to include informational diagnostics. Errors and warnings are returned regardless of this setting.

includeStatistics

boolean

True

Whether to include graph execution statistics. Defaults to true.

provenance

GraphQueryProvenanceParameters

Controls bounded assertion evidence and optional source-document hydration.

search

string

Full-text search text used to constrain graph backend requests.

vectorQueries VectorQuery[]:

Vector queries used to constrain the graph's backend searches.

GraphQueryResult

A graph query's projected rows and optional execution information.

Name Type Description
@odata.count

integer (int64)

Number of projected rows in this response, not the size of an unbounded graph population.

@search.graphDiagnostics

GraphQueryDiagnostic[]

Structured errors, warnings, and requested informational diagnostics.

@search.graphExplain

GraphQueryExplain

Requested diagnostic stages. Absent stages are omitted.

@search.graphProvenanceDocuments

object

Hydrated source documents keyed by document ID, shared across result rows.

@search.graphStats

GraphQueryStatistics

Execution statistics, when requested and available.

value

GraphQueryRow[]

Query projection rows. planOnly returns an empty collection.

GraphQueryRow

A dynamic graph projection row with optional bounded assertion evidence.

Name Type Description
@search.graphProvenance

GraphQueryRowProvenance

Assertion evidence supporting this projected row.

GraphQueryRowProvenance

Assertion evidence supporting one projected graph row.

Name Type Description
evidence

GraphQueryEvidence[]

Bounded evidence entries for this result row.

evidenceCount

GraphQueryEvidenceCount

Number of supporting assertions and the completeness relation of that count.

kind

GraphQueryProvenanceKind

Whether the query requested evidence IDs or source hydration.

GraphQueryStatistics

Execution statistics for a graph query; counters describe work performed rather than result-row counts.

Name Type Description
documentsFetched

integer (int32)

Backend assertion documents fetched during execution.

executionMode

GraphQueryExecutionMode

Whether the request executed or only produced a plan.

isEstimated

boolean

Whether execution reports an estimated result.

planningMs

integer (int64)

Time spent producing the query plan, in milliseconds.

queryCount

integer (int32)

Backend search requests performed by the graph query.

searchMs

integer (int64)

Reported search time in milliseconds.

totalMs

integer (int64)

Reported total execution time in milliseconds.

NoneVectorQueryTopicGraph

Uses normal vector search without topic graph diverse retrieval.

Name Type Description
kind string:

none

The kind of topic graph vector search to use.

QueryRewritesType

This parameter is only valid if the query type is semantic. When QueryRewrites is set to generative, the query terms are sent to a generate model which will produce 10 (default) rewrites to help increase the recall of the request. The requested count can be configured by appending the pipe character | followed by the count-<number of rewrites> option, such as generative|count-3. Defaults to None.

Value Description
none

Do not generate additional query rewrites for this query.

generative

Generate alternative query terms to increase the recall of a search request.

SearchScoreThreshold

The results of the vector query will filter based on the '

Name Type Description
kind string:

searchScore

Type of threshold.

value

number (double)

The threshold will filter based on the '

VectorizableImageBinaryQuery

The query parameters to use for vector search when a base 64 encoded binary of an image that needs to be vectorized is provided.

Name Type Description
base64Image

string

The base 64 encoded binary of an image to be vectorized to perform a vector search query.

exhaustive

boolean

When true, triggers an exhaustive k-nearest neighbor search across all vectors within the vector index. Useful for scenarios where exact matches are critical, such as determining ground truth values.

fields

string

Vector Fields of type Collection(Edm.Single) to be included in the vector searched.

filterOverride

string

The OData filter expression to apply to this specific vector query. If no filter expression is defined at the vector level, the expression defined in the top level filter parameter is used instead.

k

integer (int32)

Number of nearest neighbors to return as top hits.

kind string:

imageBinary

Type of query.

oversampling

number (double)

Oversampling factor. Minimum value is 1. It overrides the 'defaultOversampling' parameter configured in the index definition. It can be set only when 'rerankWithOriginalVectors' is true. This parameter is only permitted when a compression method is used on the underlying vector field.

perDocumentVectorLimit

integer (int32)

Controls how many vectors can be matched from each document in a vector search query. Setting it to 1 ensures at most one vector per document is matched, guaranteeing results come from distinct documents. Setting it to 0 (unlimited) allows multiple relevant vectors from the same document to be matched. Default is 0.

threshold VectorThreshold:

The threshold used for vector queries. Note this can only be set if all 'fields' use the same similarity metric.

topicGraph VectorQueryTopicGraph:

Topic graph vector search options.

weight

number (float)

Relative weight of the vector query when compared to other vector query and/or the text query within the same search request. This value is used when combining the results of multiple ranking lists produced by the different vector queries and/or the results retrieved through the text query. The higher the weight, the higher the documents that matched that query will be in the final ranking. Default is 1.0 and the value needs to be a positive number larger than zero.

VectorizableImageUrlQuery

The query parameters to use for vector search when an url that represents an image value that needs to be vectorized is provided.

Name Type Description
exhaustive

boolean

When true, triggers an exhaustive k-nearest neighbor search across all vectors within the vector index. Useful for scenarios where exact matches are critical, such as determining ground truth values.

fields

string

Vector Fields of type Collection(Edm.Single) to be included in the vector searched.

filterOverride

string

The OData filter expression to apply to this specific vector query. If no filter expression is defined at the vector level, the expression defined in the top level filter parameter is used instead.

k

integer (int32)

Number of nearest neighbors to return as top hits.

kind string:

imageUrl

Type of query.

oversampling

number (double)

Oversampling factor. Minimum value is 1. It overrides the 'defaultOversampling' parameter configured in the index definition. It can be set only when 'rerankWithOriginalVectors' is true. This parameter is only permitted when a compression method is used on the underlying vector field.

perDocumentVectorLimit

integer (int32)

Controls how many vectors can be matched from each document in a vector search query. Setting it to 1 ensures at most one vector per document is matched, guaranteeing results come from distinct documents. Setting it to 0 (unlimited) allows multiple relevant vectors from the same document to be matched. Default is 0.

threshold VectorThreshold:

The threshold used for vector queries. Note this can only be set if all 'fields' use the same similarity metric.

topicGraph VectorQueryTopicGraph:

Topic graph vector search options.

url

string

The URL of an image to be vectorized to perform a vector search query.

weight

number (float)

Relative weight of the vector query when compared to other vector query and/or the text query within the same search request. This value is used when combining the results of multiple ranking lists produced by the different vector queries and/or the results retrieved through the text query. The higher the weight, the higher the documents that matched that query will be in the final ranking. Default is 1.0 and the value needs to be a positive number larger than zero.

VectorizableTextQuery

The query parameters to use for vector search when a text value that needs to be vectorized is provided.

Name Type Description
exhaustive

boolean

When true, triggers an exhaustive k-nearest neighbor search across all vectors within the vector index. Useful for scenarios where exact matches are critical, such as determining ground truth values.

fields

string

Vector Fields of type Collection(Edm.Single) to be included in the vector searched.

filterOverride

string

The OData filter expression to apply to this specific vector query. If no filter expression is defined at the vector level, the expression defined in the top level filter parameter is used instead.

k

integer (int32)

Number of nearest neighbors to return as top hits.

kind string:

text

Type of query.

oversampling

number (double)

Oversampling factor. Minimum value is 1. It overrides the 'defaultOversampling' parameter configured in the index definition. It can be set only when 'rerankWithOriginalVectors' is true. This parameter is only permitted when a compression method is used on the underlying vector field.

perDocumentVectorLimit

integer (int32)

Controls how many vectors can be matched from each document in a vector search query. Setting it to 1 ensures at most one vector per document is matched, guaranteeing results come from distinct documents. Setting it to 0 (unlimited) allows multiple relevant vectors from the same document to be matched. Default is 0.

queryRewrites

QueryRewritesType

Can be configured to let a generative model rewrite the query before sending it to be vectorized.

text

string

The text to be vectorized to perform a vector search query.

threshold VectorThreshold:

The threshold used for vector queries. Note this can only be set if all 'fields' use the same similarity metric.

topicGraph VectorQueryTopicGraph:

Topic graph vector search options.

weight

number (float)

Relative weight of the vector query when compared to other vector query and/or the text query within the same search request. This value is used when combining the results of multiple ranking lists produced by the different vector queries and/or the results retrieved through the text query. The higher the weight, the higher the documents that matched that query will be in the final ranking. Default is 1.0 and the value needs to be a positive number larger than zero.

VectorizedQuery

The query parameters to use for vector search when a raw vector value is provided.

Name Type Description
exhaustive

boolean

When true, triggers an exhaustive k-nearest neighbor search across all vectors within the vector index. Useful for scenarios where exact matches are critical, such as determining ground truth values.

fields

string

Vector Fields of type Collection(Edm.Single) to be included in the vector searched.

filterOverride

string

The OData filter expression to apply to this specific vector query. If no filter expression is defined at the vector level, the expression defined in the top level filter parameter is used instead.

k

integer (int32)

Number of nearest neighbors to return as top hits.

kind string:

vector

Type of query.

oversampling

number (double)

Oversampling factor. Minimum value is 1. It overrides the 'defaultOversampling' parameter configured in the index definition. It can be set only when 'rerankWithOriginalVectors' is true. This parameter is only permitted when a compression method is used on the underlying vector field.

perDocumentVectorLimit

integer (int32)

Controls how many vectors can be matched from each document in a vector search query. Setting it to 1 ensures at most one vector per document is matched, guaranteeing results come from distinct documents. Setting it to 0 (unlimited) allows multiple relevant vectors from the same document to be matched. Default is 0.

threshold VectorThreshold:

The threshold used for vector queries. Note this can only be set if all 'fields' use the same similarity metric.

topicGraph VectorQueryTopicGraph:

Topic graph vector search options.

vector

number[] (float)

The vector representation of a search query.

weight

number (float)

Relative weight of the vector query when compared to other vector query and/or the text query within the same search request. This value is used when combining the results of multiple ranking lists produced by the different vector queries and/or the results retrieved through the text query. The higher the weight, the higher the documents that matched that query will be in the final ranking. Default is 1.0 and the value needs to be a positive number larger than zero.

VectorQueryKind

The kind of vector query being performed.

Value Description
vector

Vector query where a raw vector value is provided.

text

Vector query where a text value that needs to be vectorized is provided.

imageUrl

Vector query where an url that represents an image value that needs to be vectorized is provided.

imageBinary

Vector query where a base 64 encoded binary of an image that needs to be vectorized is provided.

VectorSearchTopicGraphKind

The kind of topic graph vector search to use.

Value Description
none

Use normal vector search when topic graph diverse retrieval is off.

diverse

Use topic graph diverse retrieval.

balanced

Blends pure vector similarity with diversity-aware retrieval. Recommended default to balance diversity with relevance.

VectorSimilarityThreshold

The results of the vector query will be filtered based on the vector similarity metric. Note this is the canonical definition of similarity metric, not the 'distance' version. The threshold direction (larger or smaller) will be chosen automatically according to the metric used by the field.

Name Type Description
kind string:

vectorSimilarity

Type of threshold.

value

number (double)

The threshold will filter based on the similarity metric value. Note this is the canonical definition of similarity metric, not the 'distance' version. The threshold direction (larger or smaller) will be chosen automatically according to the metric used by the field.

VectorThresholdKind

The kind of threshold used to filter vector queries.

Value Description
vectorSimilarity

The results of the vector query will be filtered based on the vector similarity metric. Note this is the canonical definition of similarity metric, not the 'distance' version. The threshold direction (larger or smaller) will be chosen automatically according to the metric used by the field.

searchScore

The results of the vector query will filter based on the '@search.score' value. Note this is the @search.score returned as part of the search response. The threshold direction will be chosen for higher @search.score.