Create an indexed Azure SQL knowledge source (preview)

Important

These features and functionality are part of the 2026-05-01-preview REST API. The 2026-05-01-preview is licensed to you as part of your Azure subscription and is subject to the terms applicable to "Previews" in the Microsoft Product Terms, the Microsoft Products and Services Data Protection Addendum ("DPA"), and the Supplemental Terms of Use for Microsoft Azure Previews.

The 2026-05-01-preview supports connections to other Microsoft services and third-party services. Use of these services is subject to their respective terms and might result in data processing or storage outside of the Azure compliance boundary, as well as data flowing into the Azure compliance boundary.

It's your responsibility to manage whether your data will flow outside of your organization's compliance and geographic boundaries and any related implications, and that appropriate permissions, boundaries, and approvals are provisioned.

You're responsible for carefully reviewing and testing applications you build in the context of your specific use cases and making all appropriate decisions and customizations. This includes implementing your own responsible AI mitigations, such as metaprompts, content filters, or other safety systems, and ensuring your applications meet appropriate quality, reliability, security, and trustworthiness standards. For more information, see the Azure AI Search Transparency Note.

Use an indexed Azure SQL knowledge source (preview) to ingest rows from Azure SQL Database or Azure SQL Managed Instance into an agentic retrieval pipeline. Knowledge sources are created independently, referenced in a knowledge base, and used as grounding data when an agent or chatbot calls a retrieve action at query time.

Unlike file-based knowledge sources, such as Azure Blob Storage and OneLake, each SQL row is treated as one logical document. The index schema is customer driven through explicit column mappings rather than a fixed document schema.

When you create an indexed Azure SQL knowledge source, you specify a SQL data source, optional column mappings, and optional models to automatically generate the following Azure AI Search objects:

A data source that represents the SQL table or view.
An index whose fields are derived from your column mappings.
A skillset that generates embeddings. The service creates a skillset only when you specify embeddingColumns.
An indexer that uses the previous objects to drive the ingestion pipeline.

The generated indexer conforms to the Azure SQL indexer, whose prerequisites, change detection policies, and limitations also apply to indexed Azure SQL knowledge sources. For more information, see the Azure SQL indexer documentation.

Usage support

Azure portal	Microsoft Foundry portal	.NET SDK	Python SDK	Java SDK	JavaScript SDK	REST API
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Prerequisites

Azure AI Search in any region that provides agentic retrieval.
Completion of the Azure SQL indexer prerequisites, including:
- An Azure SQL Database or Azure SQL Managed Instance with a table or view to ingest.
- A single-valued primary key on the source table or view.
- For views, a column suitable for high-water-mark change detection. We strongly recommend a rowversion column.
Permissions to create knowledge sources. Configure keyless authentication with the Search Service Contributor role assigned to your user account (recommended) or use an API key.
If you specify embeddingColumns, the search service must have a managed identity with Cognitive Services User permissions on the Microsoft Foundry resource that hosts the embedding model.

The latest Azure.Search.Documents preview package: dotnet add package Azure.Search.Documents --prerelease

The latest azure-search-documents preview package: pip install --pre azure-search-documents

The 2026-05-01-preview version of the Search Service REST APIs.

Limitations and considerations

A knowledge source can ingest from exactly one table or one view.
The source table or view must have a single-valued primary key. Composite keys aren't supported.
The primary key is auto-discovered and can't be overridden.
contentExtractionMode supports only "minimal".
Image extraction and image verbalization aren't supported.
Real-time synchronization isn't supported. The generated indexer is schedule based.
Real-time SQL retrieval isn't supported. The knowledge source is indexed, not remote.

Check for existing knowledge sources

A knowledge source is a top-level, reusable object. Knowing about existing knowledge sources is helpful for either reuse or naming new objects.

Run the following code to list knowledge sources by name and type.

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

Reference: SearchIndexClient

# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

for ks in index_client.list_knowledge_sources():
    print(f"  - {ks.name} ({ks.kind})")

Reference: SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
api-key: {{api-key}}

Reference: Knowledge Sources - List

You can also return a single knowledge source by name to review its JSON definition.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

Reference: SearchIndexClient

# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))

Reference: SearchIndexClient

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
api-key: {{api-key}}

Reference: Knowledge Sources - Get

The following JSON is an example response for an indexed Azure SQL knowledge source.

{
  "name": "indexedsqlks",
  "kind": "indexedSql",
  "description": "Sample indexed Azure SQL knowledge source.",
  "encryptionKey": null,
  "indexedSqlParameters": {
    "connectionString": "<SQL database connection string>",
    "tableOrView": "dbo.tbl_hotels",
    "contentColumns": [
      { "name": "hotelName", "sourceField": "HotelName", "searchFieldType": "Edm.String" },
      { "name": "description", "sourceField": "Description", "searchFieldType": "Edm.String" }
    ],
    "embeddingColumns": [
      { "name": "descriptionVector", "sourceField": "Description" }
    ],
    "ingestionParameters": {
      "contentExtractionMode": "minimal",
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<Foundry resource endpoint URI>",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      },
      "createdResources": {
        "datasource": "indexedsqlks-datasource",
        "indexer": "indexedsqlks-indexer",
        "skillset": "indexedsqlks-skillset",
        "index": "indexedsqlks-index"
      }
    }
  }
}

Note

The generated resources appear at the end of the response under createdResources.

Create a knowledge source

Run the following code to create an indexed Azure SQL knowledge source.

using Azure;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

var embeddingParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiEmbeddingDeployment,
    ModelName = aoaiEmbeddingModel,
    ApiKey = aoaiKey
};

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    ContentExtractionMode = "minimal",
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    }
};

var sqlParams = new IndexedSqlKnowledgeSourceParameters(
    connectionString: sqlConnectionString,
    tableOrView: "dbo.tbl_hotels")
{
    ContentColumns =
    {
        new ContentColumnMapping("hotelName", "HotelName", "Edm.String"),
        new ContentColumnMapping("description", "Description", "Edm.String")
    },
    EmbeddingColumns =
    {
        new EmbeddingColumnMapping("descriptionVector", "Description")
    },
    IngestionParameters = ingestionParams
};

var knowledgeSource = new IndexedSqlKnowledgeSource(
    name: "indexedsqlks",
    indexedSqlParameters: sqlParams)
{
    Description = "Indexed Azure SQL knowledge source."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

Reference: SearchIndexClient, IndexedSqlKnowledgeSource

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    AzureOpenAIVectorizerParameters,
    ContentColumnMapping,
    EmbeddingColumnMapping,
    IndexedSqlKnowledgeSource,
    IndexedSqlKnowledgeSourceParameters,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeSourceAzureOpenAIVectorizer,
    KnowledgeSourceIngestionParameters,
)

index_client = SearchIndexClient(endpoint="search_url", credential=AzureKeyCredential("api_key"))

embedding_params = AzureOpenAIVectorizerParameters(
    resource_url="aoai_endpoint",
    deployment_name="aoai_embedding_deployment",
    model_name="aoai_embedding_model",
    api_key="aoai_key",
)

ingestion_params = KnowledgeSourceIngestionParameters(
    content_extraction_mode="minimal",
    embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
        azure_open_ai_parameters=embedding_params
    ),
)

knowledge_source = IndexedSqlKnowledgeSource(
    name="indexedsqlks",
    description="Indexed Azure SQL knowledge source.",
    indexed_sql_parameters=IndexedSqlKnowledgeSourceParameters(
        connection_string="Server=tcp:{server}.database.windows.net,1433;Database={db};...;",
        table_or_view="dbo.tbl_hotels",
        content_columns=[
            ContentColumnMapping(
                name="hotelName",
                source_field="HotelName",
                search_field_type="Edm.String",
            ),
            ContentColumnMapping(
                name="description",
                source_field="Description",
                search_field_type="Edm.String",
            ),
        ],
        embedding_columns=[
            EmbeddingColumnMapping(
                name="descriptionVector",
                source_field="Description",
            )
        ],
        ingestion_parameters=ingestion_params,
    ),
)

index_client.create_or_update_knowledge_source(knowledge_source=knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

Reference: SearchIndexClient

### Create an indexed Azure SQL knowledge source
PUT {{search-url}}/knowledgesources/indexedsqlks?api-version=2026-05-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
  "name": "indexedsqlks",
  "kind": "indexedSql",
  "description": "Indexed Azure SQL knowledge source.",
  "indexedSqlParameters": {
    "connectionString": "Server=tcp:{server}.database.windows.net,1433;Database={db};...;",
    "tableOrView": "dbo.tbl_hotels",
    "contentColumns": [
      { "name": "hotelName", "sourceField": "HotelName", "searchFieldType": "Edm.String" },
      { "name": "description", "sourceField": "Description", "searchFieldType": "Edm.String" }
    ],
    "embeddingColumns": [
      { "name": "descriptionVector", "sourceField": "Description" }
    ],
    "ingestionParameters": {
      "contentExtractionMode": "minimal",
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-embedding-deployment}}",
          "modelName": "{{aoai-embedding-model}}",
          "apiKey": "{{aoai-key}}"
        }
      }
    }
  }
}

Reference: Knowledge Sources - Create or Update

Source-specific properties

The following properties apply to indexed Azure SQL knowledge sources.

Property	Description	Required
`name`	The name of the knowledge source. The name must be unique within the knowledge sources collection and follow the naming guidelines for objects in Azure AI Search.	Yes
`kind`	The kind of knowledge source, which is `indexedSql` in this case.	Yes
`description`	A description of the knowledge source.	No
`encryptionKey`	A customer-managed key to encrypt sensitive information in both the knowledge source and the generated objects.	No
`indexedSqlParameters`	Parameters specific to indexed Azure SQL knowledge sources, which are described in the following section.	Yes

`indexedSqlParameters` properties

The following properties are specific to the indexedSqlParameters object of an indexed Azure SQL knowledge source.

Property	Description	Required
`connectionString`	A SQL authentication or managed-identity connection string for Azure SQL Database or Azure SQL Managed Instance. For supported credential formats, see the Azure SQL indexer prerequisites.	Yes
`tableOrView`	The fully qualified name of the SQL table or view to ingest, specified in the `schema.objectName` format. A knowledge source ingests from exactly one table or one view.	Yes
`highWaterMarkColumn`	Required when `tableOrView` refers to a view. The name of the column used for high-water-mark change detection. We strongly recommend a `rowversion` column. For more information, see High water mark change detection policy.	Conditional
`contentColumns`	An array of column mappings that defines which SQL columns are treated as searchable text content in the generated index. Each mapping must use `Edm.String` as the `searchFieldType`.	No
`embeddingColumns`	An array of embedding mappings that defines which SQL columns are used to generate vector fields.	No
`ingestionParameters`	A subset of the standard knowledge source ingestion parameters.	No

Column mapping

contentColumns uses the following column mapping shape.

Property	Description
`name`	The name of the field as it appears in the generated Azure AI Search index.
`sourceField`	The SQL column whose value populates the target field.
`searchFieldType`	The Azure AI Search field type for the generated field. For `contentColumns`, this must be `Edm.String`.

Embedding mapping

embeddingColumns uses the following embedding mapping shape.

Property	Description
`name`	The name of the target vector field that the service creates in the generated index. For example, it could be `descriptionVector`.
`sourceField`	The SQL column whose text content is sent to the embedding model.

`ingestionParameters` properties

For indexed Azure SQL knowledge sources, the existing ingestionParameters schema is unchanged, but only the following properties apply.

Property	Description
`contentExtractionMode`	Must be `"minimal"`. Other modes aren't supported because Azure SQL ingestion is row based and doesn't extract content from binary documents.
`embeddingModel`	An Azure OpenAI embedding model used to vectorize the columns listed in `embeddingColumns`. Required only when `embeddingColumns` is specified.
`identity`	An optional user-assigned managed identity used to authenticate to Azure SQL and Azure OpenAI.
`ingestionSchedule`	An optional schedule that controls how often the generated indexer runs.

Image extraction and image verbalization aren't supported for indexed Azure SQL knowledge sources, so chatCompletionModel, assetStore, aiServices, and image-related settings have no effect.

Defaulting and validation rules

The following defaults apply when you create an indexed Azure SQL knowledge source:

If you omit contentColumns, the service automatically maps SQL columns that can be safely represented as text to Edm.String fields in the generated index, using a 1:1 mapping where name equals sourceField.
If you omit embeddingColumns, the service doesn't create vector fields and doesn't configure an embedding skill.
embeddingColumns is independent of contentColumns. To make vectors correspond to retrievable text, include the same SQL column in both arrays.
The primary key of the source table or view is auto-discovered. Explicit overrides aren't supported, and the source must have a single-valued primary key.

Configure the generated indexer

An indexed Azure SQL knowledge source automatically creates an indexer to drive ingestion. The following sections cover change detection and authentication options for the generated indexer.

Change detection

The generated indexer uses standard Azure SQL indexer change detection:

Tables: The service applies SQL integrated change tracking automatically. Enable SQL change tracking on the source table before you create the knowledge source.
Views: The service applies high-water-mark change detection. Specify the column to use in highWaterMarkColumn. A rowversion column is strongly recommended. To detect deletions in a view, include a soft-delete marker column in the view as described in Soft delete column deletion detection policy.

Authentication

The generated indexer supports two authentication options:

SQL authentication: Provide a username and password in the connection string.
Managed identity authentication: Use a system-assigned or user-assigned managed identity that has Azure RBAC and database-level roles on the SQL resource.

For connection string formats, role requirements, and setup steps, see the Azure SQL indexer prerequisites and Connect through a managed identity.

Assign to a knowledge base

If you're satisfied with the knowledge source, continue to the next step: specify the knowledge source in a knowledge base.

After the knowledge base is configured, use the retrieve action to query the knowledge source.

Delete a knowledge source

Before you can delete a knowledge source, you must delete any knowledge base that references it or update the knowledge base definition to remove the reference. For knowledge sources that generate an index and indexer pipeline, all generated objects are also deleted. However, if you used an existing index to create a knowledge source, your index isn't deleted.

If you try to delete a knowledge source that's in use, the action fails and returns a list of affected knowledge bases.

To delete a knowledge source:

Get a list of all knowledge bases on your search service.

using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeBases = indexClient.GetKnowledgeBasesAsync();

Console.WriteLine("Knowledge Bases:");

await foreach (var kb in knowledgeBases)
{
    Console.WriteLine($"  - {kb.Name}");
}

Reference: SearchIndexClient

An example response might look like the following:

 Knowledge Bases:
   - earth-knowledge-base
   - hotels-sample-knowledge-base
   - my-demo-knowledge-base

Get an individual knowledge base definition to check for knowledge source references.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge base name to retrieve
string kbNameToGet = "earth-knowledge-base";

// Get a specific knowledge base definition
var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
var kb = knowledgeBaseResponse.Value;

// Serialize to JSON for display
string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

Reference: SearchIndexClient

An example response might look like the following:

 {
   "Name": "earth-knowledge-base",
   "KnowledgeSources": [
     {
       "Name": "earth-knowledge-source"
     }
   ],
   "Models": [
     {}
   ],
   "RetrievalReasoningEffort": {},
   "OutputMode": {},
   "ETag": "\u00220x8DE278629D782B3\u0022",
   "EncryptionKey": null,
   "Description": null,
   "RetrievalInstructions": null,
   "AnswerInstructions": null
 }

Either delete the knowledge base or, if you have multiple knowledge sources, update the knowledge base to remove the source. This example shows deletion.

using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");

Reference: SearchIndexClient

Delete the knowledge source.

await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");

Reference: SearchIndexClient

Get a list of all knowledge bases on your search service.

# Get knowledge bases
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

print("Knowledge Bases:")
for kb in index_client.list_knowledge_bases():
    print(f"  - {kb.name}")

Reference: SearchIndexClient

An example response might look like the following:

 {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

Get an individual knowledge base definition to check for knowledge source references.

# Get a knowledge base definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
kb = index_client.get_knowledge_base("knowledge_base_name")
print(kb)

Reference: SearchIndexClient

An example response might look like the following:

 {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks",
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

Either delete the knowledge base or, if you have multiple knowledge sources, update the knowledge base to remove the source. This example shows deletion.

# Delete a knowledge base
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_base("knowledge_base_name")
print(f"Knowledge base deleted successfully.")

Reference: SearchIndexClient

Delete the knowledge source.

# Delete a knowledge source
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_source("knowledge_source_name")
print(f"Knowledge source deleted successfully.")

Reference: SearchIndexClient

Get a list of all knowledge bases on your search service.

### Get knowledge bases
GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
api-key: {{api-key}}

Reference: Knowledge Bases - List

An example response might look like the following:

 {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

Get an individual knowledge base definition to check for knowledge source references.

### Get a knowledge base definition
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
api-key: {{api-key}}

Reference: Knowledge Bases - Get

An example response might look like the following:

 {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks",
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

Either delete the knowledge base or, if you have multiple knowledge sources, update the knowledge base to remove the source. This example shows deletion.
```
### Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
api-key: {{api-key}}
```
Reference: Knowledge Bases - Delete

Delete the knowledge source.

### Delete a knowledge source
DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
api-key: {{api-key}}

Reference: Knowledge Sources - Delete

Feedback

Was this page helpful?

Last updated on 2026-06-02

Create an indexed Azure SQL knowledge source (preview)

Usage support

Prerequisites

Limitations and considerations

Check for existing knowledge sources

Create a knowledge source

Source-specific properties

indexedSqlParameters properties

Column mapping

Embedding mapping

ingestionParameters properties

Defaulting and validation rules

Configure the generated indexer

Change detection

Authentication

Assign to a knowledge base

Delete a knowledge source

Related content

Feedback

Additional resources

`indexedSqlParameters` properties

`ingestionParameters` properties