Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Note
Foundry IQ (Azure AI Search) provides direct indexing and query APIs alongside higher-level knowledge source and knowledge base APIs for managed retrieval. Use the Azure portal, REST APIs, or Azure SDKs to configure these capabilities, or connect agents to knowledge bases in the Microsoft Foundry portal.
Important
Entity graph is in Public Preview and is subject to the Supplemental Terms of Use for Microsoft Azure Previews.
For preview terms specific to this feature, see Preview functionality.
An entity graph (preview) represents people, organizations, places, and other concepts as nodes, with their relationships as edges. It answers questions that depend on connections between entities, such as which people work for organizations in a particular city.
In Foundry IQ (Azure AI Search), graph extraction turns Blob content into an entity graph. Create a graph-enabled blob knowledge source, then query the managed graph through a knowledge base or directly with GQL. Unlike a topic graph, an entity graph captures explicit entities and their relationships based on an ontology.
Prerequisites
- A Foundry IQ service that supports the
2026-11-01-previewREST API. - Python 3.10 or later for Python examples, or .NET 8 or later for C# examples.
- For SDK examples, follow the public-feed preview package instructions in Create a knowledge base.
- The service, model deployments, authentication, and billing prerequisites for a blob knowledge source.
- An Azure Blob Storage container with text content. This graph workflow doesn't support ADLS Gen2, ACL ingestion, or sensitivity-label ingestion.
- Native Blob soft delete enabled before the first indexing run. Blob versioning must be disabled.
- An ingestion chat-completion model. A knowledge base needs its own model configuration for natural-language graph queries.
- Permission to create and delete the test knowledge source and knowledge base. Configure keyless authentication for these examples. For query permissions and the Azure Identity library that the SDK examples use, see the prerequisites for querying knowledge bases.
Limitations
Entity graph retrieval requires a new knowledge base. You can't enable entity graph retrieval on an existing knowledge base.
The entity graph feature is API-only in this release. You can use the built-in UI as part of the Foundry IQ skills plugin.
Best practices
- Use the Foundry IQ skills plugin as the recommended way to get started. For direct setup with the REST API or an SDK, follow the steps in this article.
- Use
gpt-5.6-lunawith low retrieval reasoning effort for the best quality and cost balance. - Design your ontology around the key questions you expect users to ask your knowledge base. The quality of the ontology determines the shape and content of the graph, so include the entity types and relationships that those questions require.
- Start with one key use case and a small set of entity types and relationships. Validate the extracted graph against representative queries before scaling up.
- Estimate graph-building costs based on both corpus size and the number of entities and relationships extracted.
- During preview, there's no additional charge for the entity graph feature itself. You still pay for the model tokens used.
Prepare content and an ontology
An ontology defines the entity types and relationships to extract. Design it around the questions you expect users to ask. This example uses people, their employers, and the cities where those employers are located.
Upload the following fictional content to a text blob named
roster.txtin your container.Avery Chen works for Contoso Robotics. Contoso Robotics is located in Seattle. Jordan Davis works for Fabrikam Analytics. Fabrikam Analytics is located in Austin.Upload a second text blob named
avery.txt. It provides another source assertion for the Seattle relationship.Avery Chen is employed by Contoso Robotics, an organization located in Seattle.Define the ontology as a constrained JSON-LD document. The namespace identifies your application terms; this example defines
Person,Organization,Place,worksFor, andlocatedIn.{ "@context": { "owl": "http://www.w3.org/2002/07/owl#", "rdfs": "http://www.w3.org/2000/01/rdf-schema#", "ex": "https://schema.search.azure.com/entities#" }, "@graph": [ { "@id": "ex:Person", "@type": "owl:Class", "rdfs:comment": "A person." }, { "@id": "ex:Organization", "@type": "owl:Class", "rdfs:comment": "An organization." }, { "@id": "ex:Place", "@type": "owl:Class", "rdfs:comment": "A geographic place." }, { "@id": "ex:worksFor", "@type": "owl:ObjectProperty", "rdfs:domain": {"@id": "ex:Person"}, "rdfs:range": {"@id": "ex:Organization"}, "rdfs:comment": "A person's employer." }, { "@id": "ex:locatedIn", "@type": "owl:ObjectProperty", "rdfs:domain": {"@id": "ex:Organization"}, "rdfs:range": {"@id": "ex:Place"}, "rdfs:comment": "The city where an organization is located." } ] }
Create the graph-enabled knowledge source
This walkthrough supplies the ontology at creation and doesn't configure an ingestion cache. Choose the ontology before creating this source: without a cache, later ontology changes aren't supported. Sources that need ontology updates require a reprocessing-enabled cache configured at creation; you can't add that cache later or remove an attached ontology.
For the REST example, set the following variables in your REST client. Replace the placeholders with your own resource names and access token. To get an access token, see Connect to Foundry IQ.
@search-endpoint = https://<search-service>.search.windows.net @api-version = 2026-11-01-preview @access-token = <search-access-token> @knowledge-source-name = employees-ks @knowledge-base-name = employees-kb @container-name = <blob-container> @storage-resource-id = /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account> @model-endpoint = https://<model-resource>.openai.azure.com @chat-deployment = <chat-completion-deployment> @embedding-deployment = <embedding-deployment>Create a new knowledge source with Python, C#, or REST.
The
graphExtraction.ontologyproperty is a JSON object, not XML. Setkindtoinline, and setvalueto the constrained JSON-LD document serialized as a JSON string. Thenameproperty is optional. For the SDK examples, save the ontology from the previous section asontology.json, and set the following environment variables:SEARCH_ENDPOINT,KNOWLEDGE_SOURCE_NAME,CONTAINER_NAME,STORAGE_RESOURCE_ID,MODEL_ENDPOINT,CHAT_DEPLOYMENT, andEMBEDDING_DEPLOYMENT.
import json
import os
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
AzureBlobKnowledgeSource,
AzureBlobKnowledgeSourceParameters,
AzureOpenAIVectorizerParameters,
KnowledgeBaseAzureOpenAIModel,
KnowledgeSourceContentExtractionMode,
KnowledgeSourceGraphExtractionParameters,
KnowledgeSourceGraphOntology,
)
from azure.search.documents.knowledgebases.models import (
KnowledgeSourceAzureOpenAIVectorizer,
KnowledgeSourceIngestionParameters,
)
with open("ontology.json", encoding="utf-8") as ontology_file:
entity_ontology_value = json.dumps(
json.load(ontology_file), separators=(",", ":")
)
entity_model_endpoint = os.environ["MODEL_ENDPOINT"]
entity_ingestion_parameters = KnowledgeSourceIngestionParameters(
content_extraction_mode=KnowledgeSourceContentExtractionMode.MINIMAL,
disable_image_verbalization=True,
chat_completion_model=KnowledgeBaseAzureOpenAIModel(
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
resource_url=entity_model_endpoint,
deployment_name=os.environ["CHAT_DEPLOYMENT"],
model_name="gpt-5.6-luna",
)
),
embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
resource_url=entity_model_endpoint,
deployment_name=os.environ["EMBEDDING_DEPLOYMENT"],
model_name="text-embedding-3-small",
)
),
)
entity_graph_parameters = KnowledgeSourceGraphExtractionParameters(
graph_name="employees",
page_degree_of_parallelism=2,
ontology=KnowledgeSourceGraphOntology(
kind="inline",
name="employees-v1",
value=entity_ontology_value,
),
)
entity_blob_parameters = AzureBlobKnowledgeSourceParameters(
connection_string=f"ResourceId={os.environ['STORAGE_RESOURCE_ID']}",
container_name=os.environ["CONTAINER_NAME"],
ingestion_parameters=entity_ingestion_parameters,
graph_extraction=entity_graph_parameters,
)
entity_knowledge_source = AzureBlobKnowledgeSource(
name=os.environ["KNOWLEDGE_SOURCE_NAME"],
description="Employees, their employers, and employer locations.",
results_processing="none",
azure_blob_parameters=entity_blob_parameters,
)
entity_index_client = SearchIndexClient(
endpoint=os.environ["SEARCH_ENDPOINT"],
credential=DefaultAzureCredential(),
)
entity_index_client.create_or_update_knowledge_source(
entity_knowledge_source
)
Reference: Python client library.
Read the source back to get the generated resource names after provisioning.
GET {{search-endpoint}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{access-token}}
Reference: Knowledge sources REST API.
Wait for azureBlobParameters.createdResources.graphIndex to appear; it can be absent from the creation response. Use that returned name for direct graph queries and createdResources.index for source-chunk lookups. These properties are read-only. The source owns its generated data source, indexer, skillset, chunk index, and graph index.
Verify extraction completes
Creation starts ingestion. Relationships appear in the graph as the source content is processed.
Get the source status.
GET {{search-endpoint}}/knowledgesources('{{knowledge-source-name}}')/status?api-version={{api-version}} Authorization: Bearer {{access-token}}Reference: Knowledge sources REST API.
Wait until the synchronization finishes. Check that
lastSynchronizationState.endTimeis present,currentSynchronizationStateis empty, andlastSynchronizationState.itemsUpdatesFailedis zero. Inspect synchronization errors and the generated indexer's status if ingestion fails.synchronizationStatus: "active"means the source is available for synchronization, not that extraction is complete. When returned,graphStatistics.triplesWrittendescribes writes during that synchronization, not the graph's total size.
Query the graph through a knowledge base
A knowledge base translates a natural-language relationship question into GQL. Its model configuration is separate from the model used to extract the graph.
Create a knowledge base that references the graph-enabled source with Python, C#, or REST. Reuse an existing model deployment if appropriate, but configure it explicitly on the knowledge base.
For SDK examples, also set
KNOWLEDGE_BASE_NAMEin your process environment.
import os
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
AzureOpenAIVectorizerParameters,
KnowledgeBase,
KnowledgeBaseAzureOpenAIModel,
KnowledgeSourceReference,
)
from azure.search.documents.knowledgebases.models import (
KnowledgeRetrievalLowReasoningEffort,
KnowledgeRetrievalOutputMode,
)
entity_kb_model_parameters = AzureOpenAIVectorizerParameters(
resource_url=os.environ["MODEL_ENDPOINT"],
deployment_name=os.environ["CHAT_DEPLOYMENT"],
model_name="gpt-5.6-luna",
)
entity_knowledge_base = KnowledgeBase(
name=os.environ["KNOWLEDGE_BASE_NAME"],
knowledge_sources=[
KnowledgeSourceReference(
name=os.environ["KNOWLEDGE_SOURCE_NAME"]
)
],
models=[
KnowledgeBaseAzureOpenAIModel(
azure_open_ai_parameters=entity_kb_model_parameters
)
],
retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort(),
output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
retrieval_instructions=(
"Use graph_search for entity relationship questions. "
"Answer the relationship question by traversing the graph, "
"rather than using ordinary text search."
),
)
entity_kb_index_client = SearchIndexClient(
endpoint=os.environ["SEARCH_ENDPOINT"],
credential=DefaultAzureCredential(),
)
entity_kb_index_client.create_or_update_knowledge_base(
entity_knowledge_base
)
Reference: Python client library.
Run the following query with Python, C#, or REST.
The request enables activity and source references. It also opts into generated-query disclosure and source-document hydration.
import os
from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
AgentRuntimeGraphHydrateDocumentsParams,
AgentRuntimeGraphParams,
AgentRuntimeGraphProvenanceParams,
AzureBlobKnowledgeSourceParams,
KnowledgeBaseMessage,
KnowledgeBaseMessageTextContent,
KnowledgeBaseRetrievalRequest,
)
source = AzureBlobKnowledgeSourceParams(
knowledge_source_name=os.environ["KNOWLEDGE_SOURCE_NAME"],
include_references=True,
include_reference_source_data=True,
fail_on_error=True,
graph_parameters=AgentRuntimeGraphParams(
include_query=True,
provenance=AgentRuntimeGraphProvenanceParams(
kind="hydrate",
hydrate_documents=AgentRuntimeGraphHydrateDocumentsParams(
select="uid,snippet,snippet_parent_id,blob_url", top=10
),
),
),
)
request = KnowledgeBaseRetrievalRequest(
messages=[
KnowledgeBaseMessage(
role="user",
content=[
KnowledgeBaseMessageTextContent(
text=(
"Which people work for organizations located in Seattle? "
"Return their names, organization names, and city names."
)
)
],
)
],
include_activity=True,
output_mode="extractiveData",
max_runtime_in_seconds=60,
knowledge_source_params=[source],
)
with KnowledgeBaseRetrievalClient(
endpoint=os.environ["SEARCH_ENDPOINT"],
credential=DefaultAzureCredential(),
knowledge_base_name=os.environ["KNOWLEDGE_BASE_NAME"],
) as client:
result = client.retrieve(request)
Reference: Python client library.
Graph references identify the managed graph in graphIndexName and the executing activity in activitySource. With hydration enabled, additional references contain supporting source chunks in sourceData. Their uid, snippet_parent_id, and blob_url let you trace the result to its chunk and parent document.
Knowledge-base graph provenance defaults to none. To return graph rows without hydrated chunks, omit graphParameters.provenance. The hydration top limits source documents independently of the number of graph rows.
Query the graph directly with GQL
Use the managed graph index when your application supplies the traversal itself. The direct search.graph operation requires gql. Its optional search property applies only to full-text search.
Set
graph-index-namein your REST client, orGRAPH_INDEX_NAMEin your SDK process environment, to the returnedcreatedResources.graphIndexvalue.Run a two-hop traversal from a person to an employer and then a city. The labels and predicates match the ontology defined earlier.
import os
from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient
from azure.search.documents.models import (
GraphQueryProvenanceHydrateDocumentsParameters,
GraphQueryProvenanceParameters,
)
gql = (
"MATCH (person:Person)-[job]->(org:Organization)"
"-[location]->(city:Place) "
"WHERE job.predicate = 'worksFor' "
"AND location.predicate = 'locatedIn' "
"AND city.name = 'Seattle' "
"RETURN person.name AS person, org.name AS organization, "
"city.name AS city LIMIT 10"
)
with SearchClient(
os.environ["SEARCH_ENDPOINT"],
os.environ["GRAPH_INDEX_NAME"],
DefaultAzureCredential(),
) as client:
result = client.graph(
gql=gql,
include_statistics=True,
include_diagnostics=True,
provenance=GraphQueryProvenanceParameters(
kind="hydrate",
max_evidence_per_row=10,
hydrate_documents=GraphQueryProvenanceHydrateDocumentsParameters(
select="uid,snippet,snippet_parent_id,blob_url"
),
),
)
Reference: Python client library.
Each row's @search.graphProvenance contains supporting edgeId, chunkId, and parentId identifiers. Join edgeId to the graph assertion's id, and chunkId to uid in the generated chunk index. Hydrated chunks are shared across rows in @search.graphProvenanceDocuments; for this managed graph, the map keys are chunk IDs.
Use evidenceCount.relation to interpret the evidence count: exact means the count is complete, and lowerBound means collection was bounded, so more supporting evidence can exist. maxEvidencePerRow limits how much evidence is collected.
For identifiers without document hydration, use kind: "ids" and omit hydrateDocuments. Direct hydration supports field selection, but unlike knowledge-base hydration, it doesn't accept top.
Troubleshoot graph queries
For retrieval failures, inspect the top-level error and, when returned, the graphSearch activity.
| Problem | Action |
|---|---|
| Query-model throttling | A retrieve request can return 502 with All retrieval tasks failed when the knowledge base's query model returns 429 (TooManyRequests). Check the token and request rate limits for that model deployment, and follow the rate-limit retry guidance rather than continuously resending requests. This query-model failure doesn't establish an extraction failure or a restriction on serverless graph queries. |
| No expected graph rows | Verify that synchronization completed, then run the direct GQL traversal to check the stored relationships. An empty query result doesn't confirm that extraction succeeded. |
Clean up test resources
Delete the knowledge base you created for this exercise, then delete the knowledge source.
Deleting the source removes its generated Search resources, including the managed graph index, but doesn't delete your blobs. Remove only the test blobs, or the container if you created it for this exercise. Keep shared storage accounts and model deployments.
Related content
For the underlying ingestion setup and retrieval workflow, see: