{"id":1389,"library":"azure-search-documents","title":"Azure AI Search Client Library for Python","description":"The `azure-search-documents` library is the Microsoft Azure AI Search client library for Python. Azure AI Search (formerly known as \"Azure Cognitive Search\") is an AI-powered information retrieval platform that enables developers to build rich search experiences and generative AI applications that combine large language models with enterprise data. The current stable version is 11.6.0, and the library follows a regular release cadence as part of the Azure SDK for Python.","status":"active","version":"11.6.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/search/azure-search-documents","tags":["Azure","Search","AI Search","Cloud","Cognitive Search","Information Retrieval"],"install":[{"cmd":"pip install azure-search-documents","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for Azure Active Directory (AAD) authentication using credential types like DefaultAzureCredential.","package":"azure-identity","optional":true}],"imports":[{"symbol":"SearchClient","correct":"from azure.search.documents import SearchClient"},{"symbol":"SearchIndexClient","correct":"from azure.search.documents.indexes import SearchIndexClient"},{"symbol":"SearchIndexerClient","correct":"from azure.search.documents.indexers import SearchIndexerClient"},{"symbol":"AzureKeyCredential","correct":"from azure.core.credentials import AzureKeyCredential"},{"note":"Required for Azure Active Directory (AAD) authentication.","symbol":"DefaultAzureCredential","correct":"from azure.identity import DefaultAzureCredential"}],"quickstart":{"code":"import os\nfrom azure.core.credentials import AzureKeyCredential\nfrom azure.search.documents import SearchClient\n\n# Set environment variables for your Azure AI Search service endpoint, API key, and index name\nservice_endpoint = os.environ.get(\"AZURE_SEARCH_SERVICE_ENDPOINT\", \"\")\nindex_name = os.environ.get(\"AZURE_SEARCH_INDEX_NAME\", \"\")\napi_key = os.environ.get(\"AZURE_SEARCH_API_KEY\", \"\")\n\nif not service_endpoint or not index_name or not api_key:\n    raise ValueError(\"Please set AZURE_SEARCH_SERVICE_ENDPOINT, AZURE_SEARCH_INDEX_NAME, and AZURE_SEARCH_API_KEY environment variables.\")\n\n# Create a SearchClient\nsearch_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(api_key))\n\n# Example: Search for documents\nresults = search_client.search(search_text=\"office\")\n\nprint(\"Search Results:\")\nfor result in results:\n    print(f\"ID: {result['id']}, Name: {result['hotelName']}\") # Adjust field names based on your index schema\n\n# Example: Get a single document by key\ndocument_key = \"23\"\ntry:\n    document = search_client.get_document(key=document_key)\n    print(f\"\\nDetails for document '{document_key}':\")\n    print(f\"Name: {document['hotelName']}\") # Adjust field name based on your index schema\n    print(f\"Rating: {document['rating']}\")   # Adjust field name based on your index schema\nexcept Exception as e:\n    print(f\"\\nError retrieving document '{document_key}': {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Rewrite code to use the new `azure-search-documents` client classes and API surface. Refer to migration guides for detailed changes.","message":"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.","severity":"breaking","affected_versions":"<11.0.0 to 11.x.x"},{"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.","message":"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.","severity":"breaking","affected_versions":"API versions deprecated before current service versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Plan schema changes carefully. Use index aliases to manage seamless transitions between old and new indexes in production environments.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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'.","severity":"gotcha","affected_versions":"All"},{"fix":"Differentiate between `search_text` for relevance-based matching and the `filter` argument for strict, Boolean-logic filtering. Use `filter` for hard constraints.","message":"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.","severity":"gotcha","affected_versions":"All (especially with hybrid search and `search_text` constraints)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}