Azure AI Search Client Library for Python (Preview)

1.0.0b2 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'azure.search.documents'
```
cause The `azure-search` package (or the stable `azure-search-documents` if intended) has not been installed, or the installed version is corrupted.

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).
```
HttpResponseError: The API version '...' is not supported.
```
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.

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.
```
AuthenticationFailed: The provided authentication credentials are not valid.
```
cause The Azure AI Search admin key or service principal credentials are incorrect, expired, or lack the necessary permissions.

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.
```
TypeError: SearchClient.__init__() got an unexpected keyword argument 'api_version'
```
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.

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.

Warnings

breaking 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.
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.
gotcha 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.
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.
gotcha 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.
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`.
gotcha 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.
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.

Install

pip install azure-search==1.0.0b2 Install specific preview version
pip install azure-search Install latest preview version

Imports

SearchClient
wrong:
```
from azure.search import SearchClient
```
correct:
```
from azure.search.documents import SearchClient
```
Despite the package name `azure-search`, the primary client classes are imported from the `azure.search.documents` namespace.
SearchIndexingClient
wrong:
```
from azure.search import SearchIndexingClient
```
correct:
```
from azure.search.documents import SearchIndexingClient
```
Despite the package name `azure-search`, the primary client classes are imported from the `azure.search.documents` namespace.

SearchIndexClient

wrong:

from azure.search.documents import SearchIndexClient

correct:

from azure.search.documents.indexes import SearchIndexClient

The client for managing search indexes is in its own sub-module.

AzureKeyCredential
```
from azure.core.credentials import AzureKeyCredential
```
Standard Azure SDK credential type for API key authentication.

Quickstart

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.

import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.models import SearchableField, SearchFieldDataType, SimpleField, SearchIndex

# Replace with your Azure AI Search service endpoint and admin key
service_endpoint = os.environ.get("SEARCH_SERVICE_ENDPOINT", "https://YOUR_SEARCH_SERVICE_NAME.search.windows.net")
admin_key = os.environ.get("SEARCH_ADMIN_KEY", "YOUR_ADMIN_KEY")
index_name = "test-index"

if not service_endpoint or not admin_key:
    print("Please set the SEARCH_SERVICE_ENDPOINT and SEARCH_ADMIN_KEY environment variables.")
    exit(1)

# Create a SearchIndexClient
credential = AzureKeyCredential(admin_key)
index_client = SearchIndexClient(endpoint=service_endpoint, credential=credential)

# Define a search index
fields = [
    SimpleField(name="id", type=SearchFieldDataType.String, key=True),
    SearchableField(name="title", type=SearchFieldDataType.String, searchable=True),
    SearchableField(name="description", type=SearchFieldDataType.String, searchable=True),
]
index = SearchIndex(name=index_name, fields=fields)

# Create the index
try:
    print(f"Creating index '{index_name}'...")
    index_client.create_index(index)
    print("Index created.")

    # Get a SearchClient to add and search documents
    search_client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)

    # Add documents
    documents = [
        {"id": "1", "title": "Azure AI Search Document 1", "description": "This is the first document."}, 
        {"id": "2", "title": "Azure AI Search Document 2", "description": "This is the second document."}
    ]
    print(f"Uploading {len(documents)} documents...")
    search_client.upload_documents(documents)
    print("Documents uploaded.")

    # Search documents
    print("Searching for 'first'...")
    results = search_client.search(search_text="first")
    for result in results:
        print(f"Found document: {result['title']}")

finally:
    # Clean up (delete index)
    print(f"Deleting index '{index_name}'...")
    index_client.delete_index(index_name)
    print("Index deleted.")

view raw JSON →