{"id":7967,"library":"azure-search","title":"Azure AI Search Client Library for Python (Preview)","description":"The `azure-search` library (version 1.0.0b2, currently in preview) provides a client for interacting with Azure AI Search (formerly Azure Cognitive Search). It's designed for newer API versions and capabilities, distinct from the stable `azure-search-documents` library. As a preview package, it is in active development with rapid changes and is not recommended for production use. Microsoft generally releases updates to its Python SDK packages on a monthly cadence.","status":"active","version":"1.0.0b2","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/search/azure-search","tags":["azure","search","ai-search","cognitive-search","preview","microsoft"],"install":[{"cmd":"pip install azure-search==1.0.0b2","lang":"bash","label":"Install specific preview version"},{"cmd":"pip install azure-search","lang":"bash","label":"Install latest preview version"}],"dependencies":[{"reason":"Core Azure SDK functionalities like credentials, HTTP pipeline.","package":"azure-core","optional":false}],"imports":[{"note":"Despite the package name `azure-search`, the primary client classes are imported from the `azure.search.documents` namespace.","wrong":"from azure.search import SearchClient","symbol":"SearchClient","correct":"from azure.search.documents import SearchClient"},{"note":"Despite the package name `azure-search`, the primary client classes are imported from the `azure.search.documents` namespace.","wrong":"from azure.search import SearchIndexingClient","symbol":"SearchIndexingClient","correct":"from azure.search.documents import SearchIndexingClient"},{"note":"The client for managing search indexes is in its own sub-module.","wrong":"from azure.search.documents import SearchIndexClient","symbol":"SearchIndexClient","correct":"from azure.search.documents.indexes import SearchIndexClient"},{"note":"Standard Azure SDK credential type for API key authentication.","symbol":"AzureKeyCredential","correct":"from azure.core.credentials import AzureKeyCredential"}],"quickstart":{"code":"import os\nfrom azure.core.credentials import AzureKeyCredential\nfrom azure.search.documents import SearchClient\nfrom azure.search.documents.indexes import SearchIndexClient\nfrom azure.search.documents.models import SearchableField, SearchFieldDataType, SimpleField, SearchIndex\n\n# Replace with your Azure AI Search service endpoint and admin key\nservice_endpoint = os.environ.get(\"SEARCH_SERVICE_ENDPOINT\", \"https://YOUR_SEARCH_SERVICE_NAME.search.windows.net\")\nadmin_key = os.environ.get(\"SEARCH_ADMIN_KEY\", \"YOUR_ADMIN_KEY\")\nindex_name = \"test-index\"\n\nif not service_endpoint or not admin_key:\n    print(\"Please set the SEARCH_SERVICE_ENDPOINT and SEARCH_ADMIN_KEY environment variables.\")\n    exit(1)\n\n# Create a SearchIndexClient\ncredential = AzureKeyCredential(admin_key)\nindex_client = SearchIndexClient(endpoint=service_endpoint, credential=credential)\n\n# Define a search index\nfields = [\n    SimpleField(name=\"id\", type=SearchFieldDataType.String, key=True),\n    SearchableField(name=\"title\", type=SearchFieldDataType.String, searchable=True),\n    SearchableField(name=\"description\", type=SearchFieldDataType.String, searchable=True),\n]\nindex = SearchIndex(name=index_name, fields=fields)\n\n# Create the index\ntry:\n    print(f\"Creating index '{index_name}'...\")\n    index_client.create_index(index)\n    print(\"Index created.\")\n\n    # Get a SearchClient to add and search documents\n    search_client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)\n\n    # Add documents\n    documents = [\n        {\"id\": \"1\", \"title\": \"Azure AI Search Document 1\", \"description\": \"This is the first document.\"}, \n        {\"id\": \"2\", \"title\": \"Azure AI Search Document 2\", \"description\": \"This is the second document.\"}\n    ]\n    print(f\"Uploading {len(documents)} documents...\")\n    search_client.upload_documents(documents)\n    print(\"Documents uploaded.\")\n\n    # Search documents\n    print(\"Searching for 'first'...\")\n    results = search_client.search(search_text=\"first\")\n    for result in results:\n        print(f\"Found document: {result['title']}\")\n\nfinally:\n    # Clean up (delete index)\n    print(f\"Deleting index '{index_name}'...\")\n    index_client.delete_index(index_name)\n    print(\"Index deleted.\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `SearchIndexClient` to create an index, then use `SearchClient` to upload documents and perform a basic search, and finally clean up by deleting the index. Ensure you have `SEARCH_SERVICE_ENDPOINT` (e.g., `https://<your-service-name>.search.windows.net`) and `SEARCH_ADMIN_KEY` environment variables set with your Azure AI Search service details."},"warnings":[{"fix":"For stable production use, consider `azure-search-documents` (version 11.x.x) if its features meet your requirements. Otherwise, frequently check release notes for breaking changes and pin to specific beta versions.","message":"The `azure-search` library is currently in a preview (beta) state. APIs, models, and functionalities are subject to change without backward compatibility before a stable release. It is not recommended for production environments.","severity":"breaking","affected_versions":"1.0.0bX"},{"fix":"Always refer to the official documentation or quickstart examples for correct import paths. Do not assume the import path matches the package name directly.","message":"The package name is `azure-search`, but the main client classes are imported from the `azure.search.documents` namespace (e.g., `from azure.search.documents import SearchClient`). This can be a source of confusion.","severity":"gotcha","affected_versions":"1.0.0bX"},{"fix":"Understand which library you intend to use. If you need a stable, production-ready client, use `azure-search-documents`. If you are experimenting with new features or preview API versions, use `azure-search`.","message":"This `azure-search` preview package is distinct from the stable `azure-search-documents` library. While they interact with the same Azure AI Search service, their APIs, features, and target REST API versions may differ.","severity":"gotcha","affected_versions":"1.0.0bX"},{"fix":"Ensure your client library version is compatible with your Azure AI Search service's API version. If encountering `HttpResponseError` with API version messages, consult the service documentation or try explicitly specifying the `api_version` parameter during client instantiation if supported by your client version.","message":"Azure AI Search clients often target a specific REST API version. Mismatches between the client library's default API version and the API version expected by your Azure AI Search service instance can lead to errors.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the package is correctly installed: `pip install azure-search==1.0.0b2` (for the preview) or `pip install azure-search-documents` (for the stable client).","cause":"The `azure-search` package (or the stable `azure-search-documents` if intended) has not been installed, or the installed version is corrupted.","error":"ModuleNotFoundError: No module named 'azure.search.documents'"},{"fix":"Verify the `api_version` parameter if explicitly set, or ensure your client library version is up-to-date and compatible with your Azure AI Search service instance. Check the Azure portal for your service's supported API versions.","cause":"The client library is attempting to use an Azure Search REST API version that your search service instance does not support, or is misconfigured.","error":"HttpResponseError: The API version '...' is not supported."},{"fix":"Double-check your `SEARCH_ADMIN_KEY` environment variable or the `AzureKeyCredential` value. Ensure it matches the primary or secondary admin key from your Azure AI Search service in the Azure portal. For AAD authentication, verify permissions and token validity.","cause":"The Azure AI Search admin key or service principal credentials are incorrect, expired, or lack the necessary permissions.","error":"AuthenticationFailed: The provided authentication credentials are not valid."},{"fix":"Consult the documentation for your specific `azure-search` or `azure-search-documents` client version to confirm the constructor signature. Ensure your code aligns with the installed library's API.","cause":"This typically occurs when trying to pass an `api_version` argument to an older client library version that doesn't support it, or when trying to use an older API signature with a newer client.","error":"TypeError: SearchClient.__init__() got an unexpected keyword argument 'api_version'"}]}