Skip to content

Commit f2ba461

Browse files
hizixinCopilot
hizixin
and
Copilot
authored
Add azure-search-documents samples for 2026-05-01-preview (#47212)
Add 18 preview samples covering the 2026-05-01-preview knowledge base and knowledge source scenarios, including sync and async variants for configuration, retrieval response options, service stats, and file, freshness, MCP server, WorkIQ, Fabric ontology, and Fabric data agent sources. Use visible SDK flows with AzureKeyCredential, SDK model classes for request and resource bodies, snippet tags, docstring usage blocks, shared setup data, and cleanup. Update samples README with the preview sample list. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 2697e0c commit f2ba461

25 files changed

Lines changed: 2409 additions & 18 deletions

‎sdk/search/azure-search-documents/.github/skills/azure-search-documents/scripts/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
Set-LiveTestEnvironment.ps1
2+
Set-LiveSampleEnvironment.ps1

‎sdk/search/azure-search-documents/samples/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,25 @@ pip install azure-search-documents
6565
* Custom HTTP requests (SearchIndexClient): [sample_index_client_custom_request.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_index_client_custom_request.py) ([async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_index_client_custom_request_async.py))
6666
* Knowledge base agentic retrieval: [sample_agentic_retrieval.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_agentic_retrieval.py) ([async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_agentic_retrieval_async.py))
6767

68+
### Preview samples (2026-05-01-preview)
69+
70+
The following samples target an `azure-search-documents` build whose default API version is `2026-05-01-preview`. Behavior of preview APIs may change before GA.
71+
72+
Knowledge base and retrieval:
73+
74+
* Knowledge base preview configuration (CORS, model, retrieval defaults): [sample_knowledge_base_configuration_preview.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_base_configuration_preview.py) ([async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_base_configuration_preview_async.py))
75+
* Retrieve response (activity model_name, Purview labels, output modes): [sample_knowledge_retrieval_response_preview.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_retrieval_response_preview.py) ([async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_retrieval_response_preview_async.py))
76+
* Service stats with knowledge base / source counters: [sample_knowledge_service_stats_preview.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_service_stats_preview.py) ([async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_service_stats_preview_async.py))
77+
* Source attach-time defaults (`enable_freshness`, `enable_image_serving`): [sample_knowledge_source_freshness_preview.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_freshness_preview.py) ([async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_freshness_preview_async.py))
78+
79+
Knowledge source kinds:
80+
81+
* File knowledge source: [sample_knowledge_source_file_preview.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_file_preview.py) ([async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_file_preview_async.py))
82+
* MCP server knowledge source: [sample_knowledge_source_mcp_server_preview.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_mcp_server_preview.py) ([async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_mcp_server_preview_async.py))
83+
* WorkIQ knowledge source: [sample_knowledge_source_workiq_preview.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_workiq_preview.py) ([async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_workiq_preview_async.py))
84+
* Fabric ontology knowledge source: [sample_knowledge_source_fabric_ontology_preview.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_fabric_ontology_preview.py) ([async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_fabric_ontology_preview_async.py))
85+
* Fabric data agent knowledge source: [sample_knowledge_source_fabric_data_agent_preview.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_fabric_data_agent_preview.py) ([async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/samples/sample_knowledge_source_fabric_data_agent_preview_async.py))
86+
6887
## Next steps
6988

7089
Check out the [Azure AI Search REST API reference](https://learn.microsoft.com/rest/api/searchservice/)

‎sdk/search/azure-search-documents/samples/sample_index_client_custom_request.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ def sample_send_request():
2525
import os
2626
from azure.core.credentials import AzureKeyCredential
2727
from azure.core.rest import HttpRequest
28+
from azure.search.documents import DEFAULT_VERSION
2829
from azure.search.documents.indexes import SearchIndexClient
29-
from sample_utils import AZURE_SEARCH_API_VERSION
3030

3131
endpoint = os.environ["AZURE_SEARCH_SERVICE_ENDPOINT"]
3232
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
@@ -38,7 +38,7 @@ def sample_send_request():
3838
# while adding convenience for endpoint construction.
3939
request = HttpRequest(
4040
method="GET",
41-
url=f"/indexes('{index_name}')?api-version={AZURE_SEARCH_API_VERSION}",
41+
url=f"/indexes('{index_name}')?api-version={DEFAULT_VERSION.value}",
4242
)
4343
response = index_client.send_request(request)
4444
response.raise_for_status()

‎sdk/search/azure-search-documents/samples/sample_index_client_custom_request_async.py‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,11 @@
2323
async def sample_send_request_async():
2424
# [START sample_send_request_async]
2525
import os
26-
import sys
27-
from pathlib import Path
2826
from azure.core.credentials import AzureKeyCredential
2927
from azure.core.rest import HttpRequest
28+
from azure.search.documents import DEFAULT_VERSION
3029
from azure.search.documents.indexes.aio import SearchIndexClient
3130

32-
sys.path.append(str(Path(__file__).resolve().parent))
33-
from sample_utils import AZURE_SEARCH_API_VERSION
34-
3531
endpoint = os.environ["AZURE_SEARCH_SERVICE_ENDPOINT"]
3632
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
3733
key = os.environ["AZURE_SEARCH_API_KEY"]
@@ -42,7 +38,7 @@ async def sample_send_request_async():
4238
# while adding convenience for endpoint construction.
4339
request = HttpRequest(
4440
method="GET",
45-
url=f"/indexes('{index_name}')?api-version={AZURE_SEARCH_API_VERSION}",
41+
url=f"/indexes('{index_name}')?api-version={DEFAULT_VERSION.value}",
4642
)
4743
async with index_client:
4844
response = await index_client.send_request(request)

‎sdk/search/azure-search-documents/samples/sample_knowledge_base_configuration_preview.py‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# coding: utf-8
2+
3+
# -------------------------------------------------------------------------
4+
# Copyright (c) Microsoft Corporation.
5+
# Licensed under the MIT License.
6+
# --------------------------------------------------------------------------
7+
8+
"""
9+
DESCRIPTION:
10+
Demonstrates preview knowledge base configuration.
11+
12+
USAGE:
13+
python sample_knowledge_base_configuration_preview.py
14+
15+
Set the following environment variables before running the sample:
16+
1) AZURE_SEARCH_SERVICE_ENDPOINT - base URL of your Azure AI Search service
17+
2) AZURE_SEARCH_API_KEY - the admin key for your search service
18+
3) AZURE_OPENAI_ENDPOINT - endpoint for your Azure OpenAI resource
19+
4) AZURE_OPENAI_API_KEY - key for your Azure OpenAI resource
20+
5) AZURE_OPENAI_DEPLOYMENT - deployment name for your chat model
21+
6) AZURE_OPENAI_MODEL - model name for your chat model
22+
"""
23+
24+
import os
25+
26+
from sample_utils import (
27+
cleanup_resources,
28+
get_sample_run_tag,
29+
print_retrieval_summary,
30+
setup_hotel_index,
31+
)
32+
33+
34+
service_endpoint = os.environ["AZURE_SEARCH_SERVICE_ENDPOINT"]
35+
key = os.environ["AZURE_SEARCH_API_KEY"]
36+
run_tag = get_sample_run_tag()
37+
index_name = f"hotels-kb-config-{run_tag}"
38+
knowledge_source_name = f"hotels-kb-config-ks-{run_tag}"
39+
knowledge_base_name = f"hotels-kb-config-kb-{run_tag}"
40+
41+
42+
def main():
43+
index_client = None
44+
setup_hotel_index(index_name, service_endpoint, key)
45+
try:
46+
# [START sample_knowledge_base_configuration_preview]
47+
from azure.core.credentials import AzureKeyCredential
48+
from azure.search.documents.indexes import SearchIndexClient
49+
from azure.search.documents.indexes.models import (
50+
AzureOpenAIVectorizerParameters,
51+
CorsOptions,
52+
KnowledgeBase,
53+
KnowledgeBaseAzureOpenAIModel,
54+
KnowledgeSourceReference,
55+
SearchIndexKnowledgeSource,
56+
SearchIndexKnowledgeSourceParameters,
57+
)
58+
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
59+
from azure.search.documents.knowledgebases.models import (
60+
KnowledgeBaseMessage,
61+
KnowledgeBaseMessageTextContent,
62+
KnowledgeBaseRetrievalRequest,
63+
KnowledgeRetrievalLowReasoningEffort,
64+
)
65+
66+
index_client = SearchIndexClient(service_endpoint, AzureKeyCredential(key))
67+
knowledge_source = SearchIndexKnowledgeSource(
68+
name=knowledge_source_name,
69+
description="Hotel knowledge source with default parking filter",
70+
search_index_parameters=SearchIndexKnowledgeSourceParameters(
71+
search_index_name=index_name,
72+
base_filter="ParkingIncluded eq true and IsDeleted eq false",
73+
),
74+
)
75+
index_client.create_or_update_knowledge_source(knowledge_source)
76+
retrieved_knowledge_source = index_client.get_knowledge_source(knowledge_source_name)
77+
print(f"Retrieved: knowledge source '{retrieved_knowledge_source.name}'")
78+
79+
knowledge_base = KnowledgeBase(
80+
name=knowledge_base_name,
81+
description="Hotel knowledge base with preview configuration",
82+
knowledge_sources=[KnowledgeSourceReference(name=knowledge_source_name)],
83+
cors_options=CorsOptions(allowed_origins=["https://app.contoso.com"], max_age_in_seconds=300),
84+
models=[
85+
KnowledgeBaseAzureOpenAIModel(
86+
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
87+
resource_url=os.environ["AZURE_OPENAI_ENDPOINT"],
88+
api_key=os.environ["AZURE_OPENAI_API_KEY"],
89+
deployment_name=os.environ["AZURE_OPENAI_DEPLOYMENT"],
90+
model_name=os.environ["AZURE_OPENAI_MODEL"],
91+
)
92+
)
93+
],
94+
retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort(),
95+
output_mode="answerSynthesis",
96+
)
97+
created_knowledge_base = index_client.create_or_update_knowledge_base(knowledge_base)
98+
print(f"Created: knowledge base '{created_knowledge_base.name}'")
99+
retrieved_knowledge_base = index_client.get_knowledge_base(knowledge_base_name)
100+
print(f"Retrieved: knowledge base '{retrieved_knowledge_base.name}'")
101+
102+
retrieval_client = KnowledgeBaseRetrievalClient(
103+
service_endpoint, AzureKeyCredential(key), knowledge_base_name=knowledge_base_name
104+
)
105+
try:
106+
request = KnowledgeBaseRetrievalRequest(
107+
include_activity=True,
108+
messages=[
109+
KnowledgeBaseMessage(
110+
role="user",
111+
content=[KnowledgeBaseMessageTextContent(text="Which hotels include parking?")],
112+
)
113+
],
114+
)
115+
retrieval_result = retrieval_client.retrieve(request)
116+
finally:
117+
retrieval_client.close()
118+
print_retrieval_summary(retrieval_result)
119+
# [END sample_knowledge_base_configuration_preview]
120+
finally:
121+
if index_client:
122+
cleanup_resources(
123+
index_client,
124+
knowledge_base_name=knowledge_base_name,
125+
knowledge_source_name=knowledge_source_name,
126+
index_name=index_name,
127+
)
128+
129+
130+
if __name__ == "__main__":
131+
main()

‎sdk/search/azure-search-documents/samples/sample_knowledge_base_configuration_preview_async.py‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# coding: utf-8
2+
3+
# -------------------------------------------------------------------------
4+
# Copyright (c) Microsoft Corporation.
5+
# Licensed under the MIT License.
6+
# --------------------------------------------------------------------------
7+
8+
"""
9+
DESCRIPTION:
10+
Demonstrates preview knowledge base configuration using async clients.
11+
12+
USAGE:
13+
python sample_knowledge_base_configuration_preview_async.py
14+
15+
Set the following environment variables before running the sample:
16+
1) AZURE_SEARCH_SERVICE_ENDPOINT - base URL of your Azure AI Search service
17+
2) AZURE_SEARCH_API_KEY - the admin key for your search service
18+
3) AZURE_OPENAI_ENDPOINT - endpoint for your Azure OpenAI resource
19+
4) AZURE_OPENAI_API_KEY - key for your Azure OpenAI resource
20+
5) AZURE_OPENAI_DEPLOYMENT - deployment name for your chat model
21+
6) AZURE_OPENAI_MODEL - model name for your chat model
22+
"""
23+
24+
import asyncio
25+
import os
26+
27+
from sample_utils import (
28+
cleanup_resources_async,
29+
get_sample_run_tag,
30+
print_retrieval_summary,
31+
setup_hotel_index_async,
32+
)
33+
34+
35+
service_endpoint = os.environ["AZURE_SEARCH_SERVICE_ENDPOINT"]
36+
key = os.environ["AZURE_SEARCH_API_KEY"]
37+
run_tag = get_sample_run_tag()
38+
index_name = f"hotels-kb-config-{run_tag}"
39+
knowledge_source_name = f"hotels-kb-config-ks-{run_tag}"
40+
knowledge_base_name = f"hotels-kb-config-kb-{run_tag}"
41+
42+
43+
async def main():
44+
await setup_hotel_index_async(index_name, service_endpoint, key)
45+
# [START sample_knowledge_base_configuration_preview_async]
46+
from azure.core.credentials import AzureKeyCredential
47+
from azure.search.documents.indexes.aio import SearchIndexClient
48+
from azure.search.documents.indexes.models import (
49+
AzureOpenAIVectorizerParameters,
50+
CorsOptions,
51+
KnowledgeBase,
52+
KnowledgeBaseAzureOpenAIModel,
53+
KnowledgeSourceReference,
54+
SearchIndexKnowledgeSource,
55+
SearchIndexKnowledgeSourceParameters,
56+
)
57+
from azure.search.documents.knowledgebases.aio import KnowledgeBaseRetrievalClient
58+
from azure.search.documents.knowledgebases.models import (
59+
KnowledgeBaseMessage,
60+
KnowledgeBaseMessageTextContent,
61+
KnowledgeBaseRetrievalRequest,
62+
KnowledgeRetrievalLowReasoningEffort,
63+
)
64+
65+
index_client = SearchIndexClient(service_endpoint, AzureKeyCredential(key))
66+
async with index_client:
67+
try:
68+
knowledge_source = SearchIndexKnowledgeSource(
69+
name=knowledge_source_name,
70+
description="Hotel knowledge source with default parking filter",
71+
search_index_parameters=SearchIndexKnowledgeSourceParameters(
72+
search_index_name=index_name,
73+
base_filter="ParkingIncluded eq true and IsDeleted eq false",
74+
),
75+
)
76+
await index_client.create_or_update_knowledge_source(knowledge_source)
77+
retrieved_knowledge_source = await index_client.get_knowledge_source(knowledge_source_name)
78+
print(f"Retrieved: knowledge source '{retrieved_knowledge_source.name}'")
79+
80+
knowledge_base = KnowledgeBase(
81+
name=knowledge_base_name,
82+
description="Hotel knowledge base with preview configuration",
83+
knowledge_sources=[KnowledgeSourceReference(name=knowledge_source_name)],
84+
cors_options=CorsOptions(allowed_origins=["https://app.contoso.com"], max_age_in_seconds=300),
85+
models=[
86+
KnowledgeBaseAzureOpenAIModel(
87+
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
88+
resource_url=os.environ["AZURE_OPENAI_ENDPOINT"],
89+
api_key=os.environ["AZURE_OPENAI_API_KEY"],
90+
deployment_name=os.environ["AZURE_OPENAI_DEPLOYMENT"],
91+
model_name=os.environ["AZURE_OPENAI_MODEL"],
92+
)
93+
)
94+
],
95+
retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort(),
96+
output_mode="answerSynthesis",
97+
)
98+
created_knowledge_base = await index_client.create_or_update_knowledge_base(knowledge_base)
99+
print(f"Created: knowledge base '{created_knowledge_base.name}'")
100+
retrieved_knowledge_base = await index_client.get_knowledge_base(knowledge_base_name)
101+
print(f"Retrieved: knowledge base '{retrieved_knowledge_base.name}'")
102+
103+
retrieval_client = KnowledgeBaseRetrievalClient(
104+
service_endpoint, AzureKeyCredential(key), knowledge_base_name=knowledge_base_name
105+
)
106+
try:
107+
request = KnowledgeBaseRetrievalRequest(
108+
include_activity=True,
109+
messages=[
110+
KnowledgeBaseMessage(
111+
role="user",
112+
content=[KnowledgeBaseMessageTextContent(text="Which hotels include parking?")],
113+
)
114+
],
115+
)
116+
retrieval_result = await retrieval_client.retrieve(request)
117+
finally:
118+
await retrieval_client.close()
119+
print_retrieval_summary(retrieval_result)
120+
# [END sample_knowledge_base_configuration_preview_async]
121+
finally:
122+
await cleanup_resources_async(
123+
index_client,
124+
knowledge_base_name=knowledge_base_name,
125+
knowledge_source_name=knowledge_source_name,
126+
index_name=index_name,
127+
)
128+
129+
130+
if __name__ == "__main__":
131+
asyncio.run(main())

0 commit comments

Comments
 (0)