Azure AI Search

Azure AI Search terms — defined before code

The full indexing pipeline

The 5-component pipeline

Field attributes — which to use when

AI enrichment during indexing

Skills are applied in the skillset during indexing. Each skill reads from the document's enriched field tree and writes new enriched fields back. Skills are chained — the output of one skill can be the input of the next.

Keyword, vector, hybrid, and semantic search

Creating an index, uploading documents, and searching

Install: pip install azure-search-documents azure-core

import os
from azure.search.documents import SearchClient
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    SearchIndex,          # Represents the full index definition
    SearchField,          # Represents one field in the index schema
    SearchFieldDataType,  # Data types: String, Int32, Double, Boolean, etc.
    SimpleField,          # A field that is NOT full-text searchable (filterable/sortable)
    SearchableField,      # A field that IS full-text searchable (analysed and indexed)
)
from azure.core.credentials import AzureKeyCredential

# ── Connection details ─────────────────────────────────────────────────
SEARCH_ENDPOINT = os.environ.get("SEARCH_ENDPOINT")  # https://your-name.search.windows.net
SEARCH_KEY      = os.environ.get("SEARCH_KEY")      # Admin key from the Azure portal
INDEX_NAME      = "products-index"                  # Name for our index

credential = AzureKeyCredential(SEARCH_KEY)

# ── Step 1: Create the index schema ───────────────────────────────────
# SearchIndexClient manages index creation and deletion (admin operations)
index_client = SearchIndexClient(endpoint=SEARCH_ENDPOINT, credential=credential)

# Define the fields for our product index
# SimpleField: NOT full-text searchable — used for filtering, sorting, faceting
# SearchableField: IS full-text searchable — content is analysed and inverted
fields = [
    SimpleField(
        name       = "id",
        type       = SearchFieldDataType.String,
        key        = True,          # key=True makes this the unique document identifier
        filterable = True           # Allow filtering by id
    ),
    SearchableField(
        name      = "name",
        type      = SearchFieldDataType.String,  # Free-text product name — full-text searchable
        sortable  = True                         # Allow sorting results by name
    ),
    SearchableField(
        name = "description",
        type = SearchFieldDataType.String        # Long-form text — full-text searchable only
    ),
    SimpleField(
        name       = "category",
        type       = SearchFieldDataType.String,
        filterable = True,    # Allow filtering: $filter=category eq 'Electronics'
        facetable  = True     # Enable category counts for navigation filters
    ),
    SimpleField(
        name       = "price",
        type       = SearchFieldDataType.Double,
        filterable = True,    # Allow filtering: $filter=price lt 500
        sortable   = True     # Allow sorting by price
    ),
    SimpleField(
        name        = "in_stock",
        type        = SearchFieldDataType.Boolean,
        filterable  = True    # Allow filtering: $filter=in_stock eq true
    ),
]

# Create the index definition and send it to Azure
index = SearchIndex(name=INDEX_NAME, fields=fields)
index_client.create_or_update_index(index)  # Creates if new, updates if exists
print(f"Index '{INDEX_NAME}' created.")


# ── Step 2: Upload documents to the index ─────────────────────────────
# SearchClient is used for document operations (upload, search, delete)
search_client = SearchClient(
    endpoint   = SEARCH_ENDPOINT,
    index_name = INDEX_NAME,
    credential = credential
)

# Documents are plain Python dictionaries
# Field names must exactly match the index schema
documents = [
    {"id": "1", "name": "Dell G15 Gaming Laptop",   "description": "High-performance gaming laptop with RTX 3060", "category": "Laptops",   "price": 999.99,  "in_stock": True},
    {"id": "2", "name": "Sony WH-1000XM5 Headphones", "description": "Industry-leading noise cancelling wireless headphones", "category": "Audio",     "price": 349.99,  "in_stock": True},
    {"id": "3", "name": "Logitech MX Master 3 Mouse",  "description": "Advanced wireless mouse for productivity",              "category": "Peripherals","price": 99.99,   "in_stock": False},
]

# upload_documents() adds or replaces documents in the index
# Returns a list of IndexingResult objects — one per document
result = search_client.upload_documents(documents=documents)
print(f"Uploaded {len(result)} documents.")


# ── Step 3: Basic keyword search ──────────────────────────────────────
print("\n--- Keyword Search: 'wireless' ---")

# search() returns a SearchItemPaged iterator
# search_text: the query string (* = return all documents)
# select: which fields to return (comma-separated)
# filter: OData filter expression (like a WHERE clause)
results = search_client.search(
    search_text = "wireless",
    select      = ["name", "category", "price"],
    filter      = "in_stock eq true"   # Only return in-stock items
)

for doc in results:
    print(f"  {doc['name']} | {doc['category']} | £{doc['price']}")


# ── Step 4: Search with facets ────────────────────────────────────────
print("\n--- Search with Facets ---")

# facets: request aggregated counts for specified facetable fields
# Results include a @search.facets property with the counts
results_with_facets = search_client.search(
    search_text = "*",       # * = all documents
    facets      = ["category", "price,interval:100"]  # Category counts + price buckets of 100
)

# Access facet data from the result's get_facets() method
facets = results_with_facets.get_facets()
print("Category facets:", facets.get("category"))
print("Price facets:",    facets.get("price"))

Python — Semantic search query

Semantic ranking re-ranks results by meaning. Requires the index to have semantic configuration defined and the service to be on Standard tier or above.

from azure.search.documents.models import QueryType

# Semantic search query
# query_type=QueryType.SEMANTIC activates the semantic re-ranking layer
# semantic_configuration_name: the name of your semantic config (set in index definition)
# query_caption: "extractive" returns highlighted excerpts from matching documents
# query_answer: "extractive" extracts a direct answer if one is found in the results
semantic_results = search_client.search(
    search_text                = "best laptop for gaming under 1000",
    query_type                 = QueryType.SEMANTIC,
    semantic_configuration_name= "my-semantic-config",
    query_caption              = "extractive",
    query_answer               = "extractive",
    select                     = ["name", "description", "price"],
    top                        = 3   # Return top 3 results
)

for doc in semantic_results:
    # @search.reranker_score: the semantic model's relevance score (0-4)
    score = doc.get("@search.reranker_score", 0)
    print(f"  [{score:.2f}] {doc['name']} — £{doc['price']}")

    # Semantic captions: highlighted excerpts showing WHY this document is relevant
    captions = doc.get("@search.captions", [])
    if captions:
        print(f"    Caption: {captions[0].text}")

Azure AI Search — what the exam tests

Test your understanding