azure-cognitive-search

name	azure-cognitive-search
description	Expert knowledge for Azure AI Search development including troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. Use when designing indexes/skillsets, vector/semantic search, RAG queries, indexers, or secure multi-tenant setups, and other Azure AI Search related development tasks. Not for Azure Cosmos DB (use azure-cosmos-db), Azure Data Explorer (use azure-data-explorer), Azure Synapse Analytics (use azure-synapse-analytics), Azure Data Factory (use azure-data-factory).
compatibility	Requires network access. Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage to retrieve documentation.
metadata	{"generated_at":"2026-04-19","generator":"docs2skills/1.0.0"}

Azure AI Search Skill

This skill provides expert guidance for Azure AI Search. Covers troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. It combines local quick-reference content with remote documentation fetching capabilities.

How to Use This Skill

IMPORTANT for Agent: Use the Category Index below to locate relevant sections. For categories with line ranges (e.g., L35-L120), use read_file with the specified lines. For categories with file links (e.g., [security.md](security.md)), use read_file on the linked reference file

IMPORTANT for Agent: If metadata.generated_at is more than 3 months old, suggest the user pull the latest version from the repository. If mcp_microsoftdocs tools are not available, suggest the user install it: Installation Guide

This skill requires network access to fetch documentation content:

• Preferred: Use mcp_microsoftdocs:microsoft_docs_fetch with query string from=learn-agent-skill. Returns Markdown.
• Fallback: Use fetch_webpage with query string from=learn-agent-skill&accept=text/markdown. Returns Markdown.

Category Index

Category	Lines	Description
Troubleshooting	L37-L48	Diagnosing and fixing Azure AI Search indexer and skillset issues, including debug sessions, OData filter errors, private link problems, and storage/metrics discrepancies.
Best Practices	L49-L69	Design, scaling, and performance tuning of Azure AI Search indexing/querying, including enrichment pipelines, chunking/vectorization, data modeling, concurrency-safe updates, and vector optimization.
Decision Making	L70-L82	Planning Azure AI Search capacity, SKUs, and costs, and upgrading/migrating REST APIs, skills, SDKs, and service tiers for agentic retrieval and .NET apps
Architecture & Design Patterns	L83-L89	Architectural guidance for Azure AI Search: RAG patterns, knowledge store design, multitenancy and tenant isolation, and multi-region/high-availability deployment designs.
Limits & Quotas	L90-L99	Limits, quotas, and behaviors for Azure AI Search: service and index caps by tier, vector/index size limits, indexer scheduling windows, enrichment quotas, and related FAQs.
Security	L100-L138	Securing Azure AI Search: RBAC/keyless auth, keys, CMK encryption, private endpoints, firewalls, indexer identity/network access, ACL/Purview-based document security, and Azure Policy compliance.
Configuration	L139-L230	Configuring Azure AI Search: data sources, indexes, analyzers, skillsets, enrichment, vector/semantic settings, knowledge bases, monitoring, and relevance/answer tuning.
Integrations & Coding Patterns	L231-L289	Integrating Azure AI Search with data sources, SDKs, vectorizers, and custom skills; building knowledge stores; and crafting queries/filters (OData, Lucene, semantic, vector, agentic).
Deployment	L290-L297	Deploying and moving Azure AI Search services with ARM/Bicep/Terraform, plus guidance on cross-region moves and checking regional feature and SKU availability.

Troubleshooting

Topic	URL
Resolve common Azure AI Search indexer errors and warnings	https://learn.microsoft.com/en-us/azure/search/cognitive-search-common-errors-warnings
Understand Debug Sessions for skillset troubleshooting	https://learn.microsoft.com/en-us/azure/search/cognitive-search-debug-session
Debug and troubleshoot Azure AI Search skillsets	https://learn.microsoft.com/en-us/azure/search/cognitive-search-how-to-debug-skillset
Tutorial: Practice debugging Azure AI Search skillsets	https://learn.microsoft.com/en-us/azure/search/cognitive-search-tutorial-debug-sessions
Troubleshoot Azure AI Search indexer issues without errors	https://learn.microsoft.com/en-us/azure/search/search-indexer-troubleshooting
Troubleshoot OData collection filter errors in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-query-troubleshoot-collection-filters
Troubleshoot shared private link resource issues in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/troubleshoot-shared-private-link-resources
Troubleshoot Azure AI Search storage and metric discrepancies	https://learn.microsoft.com/en-us/azure/search/troubleshoot-storage-metrics

Best Practices

Topic	URL
Design tips and troubleshooting for AI enrichment pipelines	https://learn.microsoft.com/en-us/azure/search/cognitive-search-concept-troubleshooting
Scale and manage custom skills in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/cognitive-search-custom-skill-scale
Model SQL relational data for Azure AI Search indexing	https://learn.microsoft.com/en-us/azure/search/index-sql-relational-data
Apply responsible AI best practices for GenAI Prompt skill	https://learn.microsoft.com/en-us/azure/search/responsible-ai-best-practices-genai-prompt-skill
Handle changed and deleted blobs in Azure AI Search indexers	https://learn.microsoft.com/en-us/azure/search/search-how-to-index-azure-blob-changed-deleted
Optimize Azure Blob plaintext indexing with parsing modes	https://learn.microsoft.com/en-us/azure/search/search-how-to-index-azure-blob-plaintext
Optimize large-scale indexing in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-how-to-large-index
Chunk and vectorize content by document layout	https://learn.microsoft.com/en-us/azure/search/search-how-to-semantic-chunking
Model complex and nested data in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-howto-complex-data-types
Apply optimistic concurrency for Azure AI Search resources	https://learn.microsoft.com/en-us/azure/search/search-howto-concurrency
Update or rebuild Azure AI Search indexes safely	https://learn.microsoft.com/en-us/azure/search/search-howto-reindex

Decision Making

Topic	URL
Migrate Azure AI Search agentic retrieval code between REST API versions	https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-migrate
Migrate from deprecated Azure AI Search skills	https://learn.microsoft.com/en-us/azure/search/cognitive-search-skill-deprecated
Plan and execute Azure AI Search REST API version upgrades	https://learn.microsoft.com/en-us/azure/search/search-api-migration
Estimate Azure AI Search capacity for indexing and queries	https://learn.microsoft.com/en-us/azure/search/search-capacity-planning
Choose and use Azure AI Search management SDKs	https://learn.microsoft.com/en-us/azure/search/search-dotnet-mgmt-sdk-migration
Upgrade Azure AI Search .NET apps to SDK v11	https://learn.microsoft.com/en-us/azure/search/search-dotnet-sdk-migration-version-11
Upgrade Azure AI Search service capacity in portal	https://learn.microsoft.com/en-us/azure/search/search-how-to-upgrade
Plan and manage Azure AI Search costs	https://learn.microsoft.com/en-us/azure/search/search-sku-manage-costs
Choose the right Azure AI Search SKU and tier	https://learn.microsoft.com/en-us/azure/search/search-sku-tier

Architecture & Design Patterns

Topic	URL
Apply RAG patterns with Azure AI Search and generative AI	https://learn.microsoft.com/en-us/azure/search/retrieval-augmented-generation-overview
Implement multitenancy and content isolation in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-modeling-multitenant-saas-applications
Design multi-region architectures for Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-multi-region

Limits & Quotas

Topic	URL
Attach Foundry resource and understand AI enrichment quotas	https://learn.microsoft.com/en-us/azure/search/cognitive-search-attach-cognitive-services
Review Azure AI Search limits and behaviors from FAQ	https://learn.microsoft.com/en-us/azure/search/search-faq-frequently-asked-questions
Schedule Azure AI Search indexers and understand run windows	https://learn.microsoft.com/en-us/azure/search/search-howto-schedule-indexers
Azure AI Search service limits and quotas by tier	https://learn.microsoft.com/en-us/azure/search/search-limits-quotas-capacity
Understand index count limits for Azure AI Search tiers in .NET tutorial	https://learn.microsoft.com/en-us/azure/search/tutorial-csharp-create-load-index
Understand Azure AI Search vector index size limits	https://learn.microsoft.com/en-us/azure/search/vector-search-index-size

Security

Topic	URL
Use built-in Azure Policy definitions for Azure AI Search	https://learn.microsoft.com/en-us/azure/search/policy-reference
Ingest Azure RBAC scopes from Blob Storage into Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-blob-indexer-role-based-access
Configure keyless RBAC access to Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-get-started-rbac
Secure indexer connections to Azure SQL Managed Instance	https://learn.microsoft.com/en-us/azure/search/search-how-to-index-sql-managed-instance
Connect Azure SQL Managed Instance with managed identity	https://learn.microsoft.com/en-us/azure/search/search-how-to-index-sql-managed-instance-with-managed-identity
Secure Azure AI Search indexer connections to SQL Server VMs	https://learn.microsoft.com/en-us/azure/search/search-how-to-index-sql-server
Configure managed identities for Azure AI Search outbound connections	https://learn.microsoft.com/en-us/azure/search/search-how-to-managed-identities
Secure Azure Functions indexer calls with Easy Auth	https://learn.microsoft.com/en-us/azure/search/search-howto-managed-identities-azure-functions
Configure Cosmos DB indexer connections with managed identity	https://learn.microsoft.com/en-us/azure/search/search-howto-managed-identities-cosmos-db
Configure Azure SQL indexer connections with managed identity	https://learn.microsoft.com/en-us/azure/search/search-howto-managed-identities-sql
Connect Azure AI Search indexers to Azure Storage using managed identities

Configuration

Topic	URL
Configure blob knowledge sources for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-blob
Set up indexed OneLake knowledge sources in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-onelake
Configure search index knowledge sources for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-search-index
Configure indexed SharePoint knowledge sources for Azure AI Search	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-sharepoint-indexed
Configure remote SharePoint knowledge sources via Copilot Retrieval API	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-sharepoint-remote
Create and configure Web Knowledge Sources using Bing grounding	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-web
Enable or disable Web Knowledge Source in Azure subscription	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-web-manage
Define knowledge source objects for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-overview
Enable answer synthesis in Azure AI Search knowledge bases	https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-answer-synthesis
Define Azure AI Search index for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-create-index

Integrations & Coding Patterns

Topic	URL
Query Azure AI Search knowledge bases via REST, SDKs, and MCP	https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-retrieve
Use Chat Completion skill for image captioning in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/chat-completion-skill-example-usage
Configure AML custom skill in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/cognitive-search-aml-skill
Implement Azure AI Search custom skill with Bing Entity Search	https://learn.microsoft.com/en-us/azure/search/cognitive-search-create-custom-skill-example
Implement custom skill interface for Azure AI Search enrichment	https://learn.microsoft.com/en-us/azure/search/cognitive-search-custom-skill-interface
Implement Custom Web API skill for enrichment	https://learn.microsoft.com/en-us/azure/search/cognitive-search-custom-skill-web-api
Connect Azure AI Search knowledge stores to Power BI	https://learn.microsoft.com/en-us/azure/search/knowledge-store-connect-power-bi
Create Azure AI Search knowledge stores via REST APIs	https://learn.microsoft.com/en-us/azure/search/knowledge-store-create-rest
Implement complex projection shapes for knowledge stores	https://learn.microsoft.com/en-us/azure/search/knowledge-store-projection-example-long
Define knowledge store projections in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/knowledge-store-projections-examples
Use Lucene query syntax with Azure AI Search

Deployment

Topic	URL
Deploy Azure AI Search service using ARM templates	https://learn.microsoft.com/en-us/azure/search/search-get-started-arm
Deploy Azure AI Search service using Bicep	https://learn.microsoft.com/en-us/azure/search/search-get-started-bicep
Provision Azure AI Search with Terraform	https://learn.microsoft.com/en-us/azure/search/search-get-started-terraform
Manually move Azure AI Search services across regions	https://learn.microsoft.com/en-us/azure/search/search-howto-move-across-regions
Check Azure AI Search regional feature availability	https://learn.microsoft.com/en-us/azure/search/search-region-support