Foundry IQ: Documents

This page covers the two document-oriented Knowledge Sources that Foundry IQ supports in GPT-RAG. Use it when you deploy on Foundry IQ (RETRIEVAL_BACKEND=foundry_iq) and you need to decide how documents get into the Knowledge Base, how permissions are enforced, and how content is extracted.

If you have not read the Grounding sources overview yet, start there. It explains what a Knowledge Base and a Knowledge Source are.

The two document paths

Foundry IQ can ingest documents two ways. Both end up as Knowledge Sources on the same Knowledge Base.

Path	Knowledge Source kind	What it does	Use when
Default Blob path	`azureBlob`	Foundry IQ reads files directly from the `documents` container. Foundry IQ handles source ingestion, chunking, vectorization, index creation, and refresh. GPT-RAG ingestion is not used.	You want the default new-deployment path and do not need a custom ingestion pipeline.
Custom ingestion path	`searchIndex`	GPT-RAG ingestion processes files, writes chunks to Azure AI Search, and that existing index is registered as a Foundry IQ Knowledge Source.	You intentionally keep the GPT-RAG ingestion pipeline (custom chunking, Excel handling, large PDFs, security metadata, low-latency uploads).

Both paths result in retrieval that goes through the same Foundry IQ Knowledge Base. The difference is who owns the ingestion pipeline.

flowchart LR
  Docs[documents container] --> Default[Default Blob path]
  Docs2[documents container] --> Ingest[GPT-RAG ingestion]
  Ingest --> Index[Azure AI Search index]
  Index --> Custom[Custom ingestion path]
  Default --> KB[Foundry IQ Knowledge Base]
  Custom --> KB
  KB --> Orch[Orchestrator]

Default Blob path

For new GPT-RAG v3.0.2+ deployments with AI Landing Zone v2.1.2+, no manual backend configuration is required. The deployment provisions a native Foundry IQ Azure Blob Knowledge Source and a Knowledge Base. Foundry IQ processes files directly from the documents container.

Default configuration:

RETRIEVAL_BACKEND=foundry_iq
FOUNDRY_IQ_PATTERN=azureBlob
FOUNDRY_IQ_KNOWLEDGE_SOURCE_KIND=azureBlob
FOUNDRY_IQ_STORAGE_CONTAINER_NAME=documents
FOUNDRY_IQ_INGESTION_PERMISSION_OPTIONS=["rbacScope"]
FOUNDRY_IQ_CONTENT_EXTRACTION_MODE=standard

No separate Knowledge Source or Knowledge Base creation step is needed after deployment.

Content extraction modes and PDF handling

The default Blob path supports two content extraction modes. The mode controls whether Foundry IQ runs the Content Understanding skill on each document during ingestion.

Mode	What it does	Use when
`standard` (default, recommended)	Foundry IQ runs the `Microsoft.Skills.Util.ContentUnderstandingSkill` on each document for layout, OCR, and structured extraction. Scanned PDFs, image-only PDFs, and PDFs without a text layer are OCR'd and become searchable.	Any real-world document library. Recommended default.
`minimal`	Foundry IQ extracts only the text already present in the source. PDFs without a text layer ingest with empty content and are not searchable. No Content Understanding billing.	You have validated that the corpus is text-only PDFs or non-PDF text files, and you want to skip Content Understanding cost.

Picking minimal for a corpus that contains scanned PDFs is a silent failure: the file lands in the container, ingestion reports success, and every retrieval against it returns nothing. The default is standard so you do not have to think about this.

What standard requires:

The Foundry resource must be in a region that supports Content Understanding. See the region support list.
On first use, Foundry IQ may require a one-time PATCH /contentunderstanding/defaults call against the Foundry resource. If this has not been done, Knowledge Source creation fails with DefaultsNotSet. The GPT-RAG post-provision setup handles this for new deployments. If you still hit DefaultsNotSet, see Troubleshooting below.
standard is billed through Content Understanding meters in addition to the Azure AI Search knowledgeRetrieval plan.
Per-document limits: 300 pages and 5 minutes of processing time.

Documents that exceed those limits, or scenarios that need custom chunking, custom enrichment, or Excel chunking, should use the custom ingestion path below.

Switching content extraction mode after deployment

FOUNDRY_IQ_CONTENT_EXTRACTION_MODE is immutable on an existing Knowledge Source. To change it you have to recreate the Knowledge Source, and because the Knowledge Base references the Knowledge Source by name, you typically recreate both. There is no in-place update.

To switch from minimal to standard (or back) on an existing deployment:

Update the App Configuration value (or azd env set) to the new mode:
```
azd env set FOUNDRY_IQ_CONTENT_EXTRACTION_MODE standard
```
Delete the existing Foundry IQ Knowledge Source and Knowledge Base for the environment from the Azure AI Search resource (data plane). Use the Search data-plane REST API with the 2026-05-01-preview version.
Re-run the GPT-RAG post-provision step that creates the Foundry IQ resources, so the Knowledge Source is recreated with the new mode and the Knowledge Base is rebound to it.
Re-ingest the documents container so the new Knowledge Source processes the files with the chosen mode.

flowchart LR
  Old[Existing KS + KB on minimal] --> Delete[Delete KB and KS]
  Delete --> Update[Update FOUNDRY_IQ_CONTENT_EXTRACTION_MODE]
  Update --> Recreate[Re-run post-provision to recreate KS + KB]
  Recreate --> Reingest[Re-ingest documents container]

Custom ingestion path

Use this path only when you need to keep the GPT-RAG ingestion pipeline. Reasons to keep it:

Scenario	Why the custom ingestion path
PDFs over 300 pages, or single documents that take more than 5 minutes to process.	Exceeds the `standard` content extraction limits. GPT-RAG ingestion uses Azure AI Document Intelligence and can chunk and process longer documents.
Custom chunking strategy (sentence, window, semantic chunking, custom overlap, custom metadata enrichment).	The GPT-RAG ingestion pipeline is the place to customize chunking. The default Blob path uses the Foundry IQ built-in chunker.
Excel and spreadsheet chunking.	GPT-RAG ingestion has dedicated handling for Excel sheets.
Per-document security trimming via custom `metadata_security_*` fields.	The custom ingestion path enforces those fields at query time through `filterAddOn`.
Low-latency ingestion after a runtime upload.	The default Blob path source refresh can take seconds to minutes. GPT-RAG ingestion writes directly into the index.

Enabling the custom ingestion path

Start from a working ai_search deployment.

Set the Foundry IQ parameters before provisioning:

azd env set RETRIEVAL_BACKEND foundry_iq
azd env set FOUNDRY_IQ_PATTERN searchIndex
azd env set FOUNDRY_IQ_API_VERSION 2026-05-01-preview
azd env set FOUNDRY_IQ_KNOWLEDGE_RETRIEVAL_BILLING_PLAN free
azd env set FOUNDRY_IQ_FILTER_ADD_ON_ENABLED true

Run azd provision.
Deploy or restart the orchestrator so it reads the backend selector at startup.

The Knowledge Base and the source index must live on the same Search service. The index must have a semantic configuration, and any vector fields must have the expected vectorizer setup.

Security modes

There are two security mechanisms. They solve different problems.

Security mode	Used by	How it is enforced
Native ingested permissions	The default Blob path and other sources that ingest permissions, such as Azure Blob RBAC scope, ADLS Gen2 ACLs, SharePoint, OneLake/Fabric, or Purview labels.	The orchestrator forwards the user's delegated Search token in `x-ms-query-source-authorization`. Foundry IQ evaluates the ingested permissions.
GPT-RAG security fields	The custom ingestion path with the existing GPT-RAG index.	The orchestrator sends an OData `filterAddOn` over GPT-RAG security fields. Separate from the OBO header.

Rules to keep straight:

Plain Blob storage provides container-level RBAC for this purpose. Do not rely on it for per-document trimming unless you use Purview labels or an equivalent per-document permission source.
ADLS Gen2 ACLs, SharePoint, OneLake/Fabric, and Purview labels can support per-document permission trimming when native permission ingestion is configured.
The custom ingestion path uses the existing GPT-RAG index registered as a searchIndex Knowledge Source. GPT-RAG security fields are enforced through filterAddOn, not through x-ms-query-source-authorization.
The x-ms-query-source-authorization header is for native ingested permissions.
Per-user security uses the 2026-05-01-preview Azure AI Search API.
Security-enabled retrieval must fail closed. Missing token, filter, or permission configuration should be treated as an error, not as permission to run an unfiltered query.

Configuration settings

All runtime settings are stored in Azure App Configuration with the gpt-rag label, or supplied as container environment variables when you use the containerEnv runtime mode.

Setting	Default	Used when	Purpose
`RETRIEVAL_BACKEND`	`foundry_iq` for new v3.0.2+ deployments	Always	Selects `ai_search` or `foundry_iq`. Existing deployments can keep `ai_search` until they migrate.
`KNOWLEDGE_BASE_NAME`	Generated during deployment	`foundry_iq`	Foundry IQ Knowledge Base name.
`KNOWLEDGE_BASE_ENDPOINT`	Generated during deployment	`foundry_iq`	Azure AI Search endpoint that hosts the Knowledge Base.
`KNOWLEDGE_BASE_CONNECTION_ID`	Generated during deployment	`foundry_iq`	Dedicated AI Foundry connection ID for the Knowledge Base. Do not reuse `SEARCH_CONNECTION_ID`.
`FOUNDRY_IQ_PATTERN`	`azureBlob`	`foundry_iq` provisioning	Selects the default Blob path or the custom ingestion path. Use `searchIndex` only when you intentionally keep a custom GPT-RAG ingestion pipeline.
`FOUNDRY_IQ_API_VERSION`	`2026-05-01-preview`	`foundry_iq`	Required for native per-user permissions and custom ingestion path `filterAddOn`.
`FOUNDRY_IQ_KNOWLEDGE_RETRIEVAL_BILLING_PLAN`	`free`	Deployment configuration	Azure AI Search `knowledgeRetrieval` billing plan.
`FOUNDRY_IQ_KNOWLEDGE_SOURCE_NAME`	Generated during deployment	`foundry_iq`	Name of the Foundry IQ Knowledge Source.
`FOUNDRY_IQ_KNOWLEDGE_SOURCE_KIND`	`azureBlob`	`foundry_iq`	Knowledge Source kind sent to Foundry IQ. Use `searchIndex` only for the custom ingestion path.
`FOUNDRY_IQ_STORAGE_CONTAINER_NAME`	`documents`	Default Blob path	Storage container that Foundry IQ reads directly.
`FOUNDRY_IQ_INGESTION_PERMISSION_OPTIONS`	`["rbacScope"]`	Default Blob path	Permission metadata ingested by the native Azure Blob Knowledge Source.
`FOUNDRY_IQ_FILTER_ADD_ON_ENABLED`	`false`	Custom ingestion path	Enables query-time GPT-RAG security filtering through `filterAddOn`.
`FOUNDRY_IQ_SECURITY_FIELD_NAME`	`metadata_security_id`	Custom ingestion path	Field used to build the GPT-RAG security filter.
`FOUNDRY_IQ_MAX_OUTPUT_DOCUMENTS`	`5`	`foundry_iq`	Caps the number of documents returned by the Knowledge Base.
`FOUNDRY_IQ_CONTENT_EXTRACTION_MODE`	`standard`	Default Blob path	Native Blob content extraction mode. `standard` uses the Foundry IQ Content Understanding skill (layout and OCR) so scanned and image-only PDFs are ingested with text. `minimal` skips Content Understanding and only ingests text already present in the source. Immutable on an existing Knowledge Source. See Content extraction modes and PDF handling.

The AI Landing Zone also stamps setup values used by deployment configuration:

Setting	Purpose
`FOUNDRY_IQ_SEARCH_INDEX_NAME`	Existing Azure AI Search index registered as the custom ingestion path Knowledge Source.
`FOUNDRY_IQ_SEMANTIC_CONFIGURATION_NAME`	Semantic configuration on the existing index.
`FOUNDRY_IQ_SOURCE_DATA_FIELDS`	Source fields exposed by the Knowledge Source.
`FOUNDRY_IQ_SEARCH_FIELDS`	Searchable fields used by the Knowledge Source.
`FOUNDRY_IQ_BASE_FILTER`	Optional persisted filter on the Knowledge Source.

Billing

Foundry IQ retrieval uses Azure AI Search agentic retrieval billing through the Search service knowledgeRetrieval plan.

Plan	Use when
`free`	You want to stay within the included allowance. Retrieval can fail when the allowance is exhausted.
`standard`	You explicitly opt in to pay-as-you-go retrieval after the included allowance.

Set the plan before provisioning:

azd env set FOUNDRY_IQ_KNOWLEDGE_RETRIEVAL_BILLING_PLAN free

Use standard only when the operator has approved the billing change.

Rollback to Azure AI Search direct

If you need to move off Foundry IQ, roll back to Direct: Azure AI Search. Rollback is intentionally simple: set RETRIEVAL_BACKEND=ai_search in App Configuration and restart the orchestrator. You do not need to delete the Knowledge Base to roll back. Leave it in place while you investigate.

Troubleshooting

DefaultsNotSet when creating the Knowledge Source on standard. The Foundry resource has not been initialized for Content Understanding. Make a one-time PATCH /contentunderstanding/defaults call against the Foundry resource and re-run the setup. See the Content Understanding skill reference for the payload.
Scanned PDF ingests with empty content. The Knowledge Source is on minimal. Either re-create it on standard (steps above) or move the document through the custom ingestion path.
PDF over 300 pages or processing times out. standard cannot handle it. Use the custom ingestion path with Document Intelligence.

Known limitations

The default Blob path on FOUNDRY_IQ_CONTENT_EXTRACTION_MODE=standard has per-document limits of 300 pages and 5 minutes of processing time.
FOUNDRY_IQ_CONTENT_EXTRACTION_MODE is immutable on an existing Knowledge Source. Switching modes requires deleting and recreating the Knowledge Source and Knowledge Base, and re-ingesting the container.
standard mode requires a Foundry resource in a Content Understanding supported region and is billed through Content Understanding meters in addition to the knowledgeRetrieval plan.
Multimodal captioning parity for the default Blob path is deferred. Keep multimodal on ai_search or the custom ingestion path until the native Foundry IQ output is proven equivalent.
Runtime document uploads still need the self-managed GPT-RAG index for low-latency searchability. Use the custom ingestion path for that.
The default Blob path source refresh can take seconds to minutes. It is not a low-latency upload path.
The custom ingestion path requires the existing index to have a semantic configuration. Vector fields must have the expected vectorizer setup.
The Knowledge Base and the custom ingestion path index must live on the same Search service.
Per-user security and filterAddOn require 2026-05-01-preview.