Azure AI Search Client Library for Python

Warnings

• breaking Version 11 (`azure-search-documents`) is a complete redesign of the client library from previous versions (e.g., `Microsoft.Azure.Search` v10). It introduces new client classes (`SearchClient`, `SearchIndexClient`, `SearchIndexerClient`) and significant API and naming differences, consolidating functionality from four packages into one.
  Fix: Rewrite code to use the new `azure-search-documents` client classes and API surface. Refer to migration guides for detailed changes.
• breaking Azure AI Search API versions are updated regularly, and older preview versions (e.g., `2023-07-01-preview` for vector search) are deprecated and no longer supported. Migrating to newer API versions may require changes to vector search configurations and other features.
  Fix: Regularly check the Azure AI Search documentation for the latest recommended API versions and update your client library and code accordingly, especially for new features like vector search.
• gotcha Always use a query API key for client-side applications to restrict access and operations to read-only queries. Admin keys grant full read-write access to the search service and should be protected and only used for administrative tasks.
  Fix: When creating an `AzureKeyCredential`, ensure you are using a query key retrieved from the Azure portal for client applications. Admin keys should only be used in secure backend services for index management and document ingestion.
• gotcha Modifying or removing an existing field in an Azure AI Search index's schema is not allowed directly. To change an index schema (e.g., changing field types, adding/removing fields, making a field filterable), you must create an entirely new index with the desired schema, re-populate it with all documents, and then update your application to point to the new index.
  Fix: Plan schema changes carefully. Use index aliases to manage seamless transitions between old and new indexes in production environments.
• gotcha Filtering in Azure AI Search is case-sensitive. A filter for `Make eq 'toyota'` will not match a document where `Make` is 'Toyota' or 'TOYOTA'.
  Fix: If case-insensitive filtering is required, consider storing a normalized (e.g., lowercase) version of the field in your index specifically for filtering, alongside the original field for display. Alternatively, use fuzzy search or other query types if exact filtering isn't strictly necessary.
• gotcha In hybrid search, if you intend to apply a strict filter (e.g., using regular expressions in `search_text`), unexpected results might occur because vector search always returns a `k` number of matches, which are then combined. For hard filters where non-matching documents must be excluded, use the `filter` argument with OData syntax.
  Fix: Differentiate between `search_text` for relevance-based matching and the `filter` argument for strict, Boolean-logic filtering. Use `filter` for hard constraints.

Install

• pip install azure-search-documents Install stable version

Imports

• SearchClient

  from azure.search.documents import SearchClient

• SearchIndexClient

  from azure.search.documents.indexes import SearchIndexClient

• SearchIndexerClient

  from azure.search.documents.indexers import SearchIndexerClient

• AzureKeyCredential

  from azure.core.credentials import AzureKeyCredential

• DefaultAzureCredential

  from azure.identity import DefaultAzureCredential

  Required for Azure Active Directory (AAD) authentication.

Quickstart

This quickstart demonstrates how to instantiate a `SearchClient` using an API key and perform a basic search query and retrieve a document. Ensure `AZURE_SEARCH_SERVICE_ENDPOINT`, `AZURE_SEARCH_INDEX_NAME`, and `AZURE_SEARCH_API_KEY` environment variables are set. Replace 'hotelName', 'id', and 'rating' with actual field names from your index schema.

import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set environment variables for your Azure AI Search service endpoint, API key, and index name
service_endpoint = os.environ.get("AZURE_SEARCH_SERVICE_ENDPOINT", "")
index_name = os.environ.get("AZURE_SEARCH_INDEX_NAME", "")
api_key = os.environ.get("AZURE_SEARCH_API_KEY", "")

if not service_endpoint or not index_name or not api_key:
    raise ValueError("Please set AZURE_SEARCH_SERVICE_ENDPOINT, AZURE_SEARCH_INDEX_NAME, and AZURE_SEARCH_API_KEY environment variables.")

# Create a SearchClient
search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(api_key))

# Example: Search for documents
results = search_client.search(search_text="office")

print("Search Results:")
for result in results:
    print(f"ID: {result['id']}, Name: {result['hotelName']}") # Adjust field names based on your index schema

# Example: Get a single document by key
document_key = "23"
try:
    document = search_client.get_document(key=document_key)
    print(f"\nDetails for document '{document_key}':")
    print(f"Name: {document['hotelName']}") # Adjust field name based on your index schema
    print(f"Rating: {document['rating']}")   # Adjust field name based on your index schema
except Exception as e:
    print(f"\nError retrieving document '{document_key}': {e}")