Python Azure AI Search: Step-by-Step Guide

techhadoop ai, azure, , , ,

Here’s a Python hands-on version for Azure AI Search that does the core setup programmatically:

  • creates a search index
  • uploads sample documents
  • runs a few search queries

This follows Microsoft’s Python quickstart flow using the Azure SDK packages azure-search-documents and azure-identity. Microsoft’s current Python quickstart for Azure AI Search uses those SDKs and shows index creation, document upload, and querying from Python.

What this lab builds

Python script
   ↓
Azure AI Search index
   ↓
Upload sample docs
   ↓
Run search queries

1. Install packages

pip install azure-search-documents azure-identity

These are the main SDK packages Microsoft documents for Python with Azure AI Search.

2. Set environment variables

Set these in your shell:

export AZURE_SEARCH_SERVICE_ENDPOINT="https://YOUR-SERVICE-NAME.search.windows.net"
export AZURE_SEARCH_ADMIN_KEY="YOUR-ADMIN-KEY"

You can get the endpoint and admin key from your Azure AI Search resource in the Azure portal. Microsoft’s quickstart uses the service endpoint plus admin credentials to connect and manage indexes.

3. Python script

Save this as azure_search_lab.py:

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.indexes.models import (
    SearchIndex,
    SearchField,
    SearchFieldDataType,
    SimpleField,
    SearchableField,
)
def get_env(name: str) -> str:
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"Missing environment variable: {name}")
    return value
endpoint = get_env("AZURE_SEARCH_SERVICE_ENDPOINT")
admin_key = get_env("AZURE_SEARCH_ADMIN_KEY")
index_name = "banking-docs-index"
credential = AzureKeyCredential(admin_key)
# 1) Create index client
index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
# 2) Define index schema
fields = [
    SimpleField(name="id", type=SearchFieldDataType.String, key=True),
    SearchableField(name="title", type=SearchFieldDataType.String),
    SearchableField(name="content", type=SearchFieldDataType.String),
    SimpleField(name="category", type=SearchFieldDataType.String, filterable=True, facetable=True),
]
index = SearchIndex(name=index_name, fields=fields)
# 3) Create or update index
index_client.create_or_update_index(index)
print(f"Index '{index_name}' created or updated.")
# 4) Create search client
search_client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
# 5) Upload sample documents
documents = [
    {
        "id": "1",
        "title": "Savings Account",
        "content": "Our savings account offers 3.5 percent annual interest and no monthly fee.",
        "category": "accounts",
    },
    {
        "id": "2",
        "title": "Home Loan Policy",
        "content": "Home loans are available with fixed and floating interest rate options.",
        "category": "loans",
    },
    {
        "id": "3",
        "title": "Credit Card Support",
        "content": "You can block or replace your credit card using the mobile banking app.",
        "category": "cards",
    },
]
result = search_client.upload_documents(documents=documents)
print("Upload results:")
for r in result:
    print(f"  key={r.key}, succeeded={r.succeeded}")
# 6) Run a few searches
queries = ["interest", "credit card", "loan"]
for q in queries:
    print(f"\nSearch query: {q}")
    results = search_client.search(search_text=q)
    for doc in results:
        print(f"- {doc['title']} [{doc['category']}]")

This matches the documented Azure AI Search SDK pattern of using SearchIndexClient for schema management and SearchClient for loading and querying documents.

4. Run it

python azure_search_lab.py

You should see:

  • index created
  • documents uploaded
  • matching results printed for each query

5. What the code is doing

The important pieces are:

  • SearchIndexClient creates or updates the index schema
  • SimpleField(..., key=True) defines the required unique key field
  • SearchableField makes text fields searchable
  • SearchClient.upload_documents() pushes documents into the index
  • SearchClient.search() runs queries against the index

Azure AI Search requires a unique key field for each document in an index, and the Python SDK supports document upload and full-text querying exactly this way.

6. Add filtering

You can also filter on fields like category:

results = search_client.search(
    search_text="interest",
    filter="category eq 'accounts'"
)

Azure AI Search supports filters on fields marked filterable in the schema.

7. Next upgrade: vector and hybrid search

For a chatbot or RAG app, the next step is to add:

  • an embeddings field
  • vector search
  • ideally hybrid search

Microsoft’s current guidance recommends hybrid search for many production use cases because it combines keyword and vector retrieval.

8. Common mistakes

The most common ones are:

  • forgetting the key field
  • using the query key instead of the admin key for index creation
  • not marking fields filterable before trying to filter on them
  • expecting search to work before uploading documents

These are all consistent with Azure AI Search’s index/schema and credential model in the official SDK docs and quickstarts.

Leave a comment