From b8f0d21619dab588d74736f9d92aaa214945c7a8 Mon Sep 17 00:00:00 2001 From: Farzad Sunavala Date: Sat, 20 Sep 2025 03:12:18 +0100 Subject: [PATCH 1/5] documentation azure ai search --- ...odes-langchain.vectorstoreazureaisearch.md | 175 ++++++++++++++++++ .../builtin/credentials/azureaisearch.md | 103 +++++++++++ 2 files changed, 278 insertions(+) create mode 100644 docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md create mode 100644 docs/integrations/builtin/credentials/azureaisearch.md diff --git a/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md b/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md new file mode 100644 index 00000000000..c9cf4655b05 --- /dev/null +++ b/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md @@ -0,0 +1,175 @@ +--- +title: Azure AI Search Vector Store node documentation +description: Learn how to use the Azure AI Search Vector Store node in n8n. Follow technical documentation to integrate Azure AI Search Vector Store node into your workflows. +contentType: [integration, reference] +priority: medium +--- + +# Azure AI Search Vector Store node + +Azure AI Search (formerly Azure Cognitive Search) is a cloud search service that provides vector search capabilities through its Vector Search feature. Use this node to interact with Vector Search indexes in your Azure AI Search service. You can insert documents, retrieve documents, and use the vector store in chains or as a tool for agents. + +On this page, you'll find the node parameters for the Azure AI Search Vector Store node, and links to more resources. + +/// note | Credentials +You can find authentication information for this node [here](/integrations/builtin/credentials/azureaisearch.md). +/// + +--8<-- "_snippets/integrations/builtin/cluster-nodes/sub-node-expression-resolution.md" + +## Prerequisites + +Before using this node, create a [Vector Search index](https://learn.microsoft.com/en-us/azure/search/vector-search-overview) in your Azure AI Search service. Follow these steps to create one: + +1. Log in to the [Azure Portal](https://portal.azure.com/). + +2. Navigate to your Azure AI Search service or create a new one. +3. Select "Indexes" from the left navigation menu. +4. Click "Add Index" and create a new index with vector fields. +5. Configure your index schema with: + - A vector field for embeddings with appropriate dimensions + - Metadata fields for filtering and content + - Configure the vector search profile with the similarity metric (cosine, euclidean, or dotProduct) + + Example index JSON configuration: + ```json + { + "fields": [ + { + "name": "content_vector", + "type": "Collection(Edm.Single)", + "searchable": true, + "retrievable": true, + "dimensions": 1536, + "vectorSearchProfile": "vector-profile" + }, + { + "name": "content", + "type": "Edm.String", + "searchable": true, + "retrievable": true + } + ], + "vectorSearch": { + "profiles": [ + { + "name": "vector-profile", + "algorithm": "hnsw-algorithm" + } + ], + "algorithms": [ + { + "name": "hnsw-algorithm", + "kind": "hnsw", + "parameters": { + "metric": "cosine" + } + } + ] + } + } + ``` + +6. Note down your service endpoint URL and index name for configuration. + +Make sure to note the following values which are required when configuring the node: + +- Azure AI Search endpoint URL +- Index name +- API key or managed identity configuration + +## Node usage patterns + +You can use the Azure AI Search Vector Store node in the following patterns: + +### Use as a regular node to insert and retrieve documents + +You can use the Azure AI Search Vector Store as a regular node to insert or get documents. This pattern places the Azure AI Search Vector Store in the regular connection flow without using an agent. + +You can see an example of this in scenario 1 of [this template](https://n8n.io/workflows/2621-ai-agent-to-chat-with-files-in-supabase-storage/) (the template uses the Supabase Vector Store, but the pattern is the same). + +### Connect directly to an AI agent as a tool + +You can connect the Azure AI Search Vector Store node directly to the tool connector of an [AI agent](/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/index.md) to use the vector store as a resource when answering queries. + +Here, the connection would be: AI agent (tools connector) -> Azure AI Search Vector Store node. + +### Use a retriever to fetch documents + +You can use the [Vector Store Retriever](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.retrievervectorstore.md) node with the Azure AI Search Vector Store node to fetch documents from the Azure AI Search Vector Store node. This is often used with the [Question and Answer Chain](/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.chainretrievalqa/index.md) node to fetch documents from the vector store that match the given chat input. + +An [example of the connection flow](https://n8n.io/workflows/1960-ask-questions-about-a-pdf-using-ai/) (the linked example uses Pinecone, but the pattern is the same) would be: Question and Answer Chain (Retriever connector) -> Vector Store Retriever (Vector Store connector) -> Azure AI Search Vector Store. + +### Use the Vector Store Question Answer Tool to answer questions + +Another pattern uses the [Vector Store Question Answer Tool](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolvectorstore.md) to summarize results and answer questions from the Azure AI Search Vector Store node. Rather than connecting the Azure AI Search Vector Store directly as a tool, this pattern uses a tool specifically designed to summarize data in the vector store. + +The [connections flow](https://n8n.io/workflows/2465-building-your-first-whatsapp-chatbot/) (the linked example uses the In-Memory Vector Store, but the pattern is the same) in this case would look like this: AI agent (tools connector) -> Vector Store Question Answer Tool (Vector Store connector) -> Azure AI Search Vector Store. + +## Node parameters + +--8<-- "_snippets/integrations/builtin/cluster-nodes/vector-store-mode-with-update.md" + +### Rerank Results + +--8<-- "_snippets/integrations/builtin/cluster-nodes/vector-store-rerank-results.md" + + +### Get Many parameters + + +- **Endpoint**: Enter the Azure AI Search endpoint URL (e.g., `https://your-service.search.windows.net`). +- **Index Name**: Enter the name of the Azure AI Search index to use. +- **Results Count**: Enter the maximum number of documents to return (default: 50). + +### Insert Documents parameters + +- **Endpoint**: Enter the Azure AI Search endpoint URL (e.g., `https://your-service.search.windows.net`). +- **Index Name**: Enter the name of the Azure AI Search index to use. + +### Update Documents parameters + +- **Endpoint**: Enter the Azure AI Search endpoint URL (e.g., `https://your-service.search.windows.net`). +- **Index Name**: Enter the name of the Azure AI Search index to use. + +### Retrieve Documents parameters (As Vector Store for Chain/Tool) + +- **Endpoint**: Enter the Azure AI Search endpoint URL (e.g., `https://your-service.search.windows.net`). +- **Index Name**: Enter the name of the Azure AI Search index to use. + +### Retrieve Documents (As Tool for AI Agent) parameters + +- **Name**: The name of the vector store. +- **Description**: Explain to the LLM what this tool does. A good, specific description allows LLMs to produce expected results more often. +- **Endpoint**: Enter the Azure AI Search endpoint URL (e.g., `https://your-service.search.windows.net`). +- **Index Name**: Enter the name of the Azure AI Search index to use. +- **Limit**: Enter how many results to retrieve from the vector store. For example, set this to `10` to get the ten best results. + +## Node options + +### Options + +- **Filter**: Use [OData filter expressions](https://learn.microsoft.com/en-us/azure/search/search-query-odata-filter) to filter results based on metadata fields. +- **Query Mode**: Choose how to search the index: + - **Vector**: Use only vector search + - **Keyword**: Use only keyword search + - **Hybrid** (default): Combine vector and keyword search + - **Semantic Hybrid**: Combine vector, keyword, and semantic ranking (requires semantic configuration) +- **Semantic Configuration**: Enter the name of the semantic configuration (required when using Semantic Hybrid query mode). + +## Templates and examples + + +[[ templatesWidget(page.title, 'azure-ai-search-vector-store') ]] + +## Related resources + +Refer to: + +- [Azure AI Search Vector Search documentation](https://learn.microsoft.com/en-us/azure/search/vector-search-overview) for more information about the service. +- [LangChain's Azure AI Search documentation](https://js.langchain.com/docs/integrations/vectorstores/azure_aisearch) for more information about the integration. +- [Azure AI Search REST API reference](https://learn.microsoft.com/en-us/rest/api/searchservice/) for detailed API information. + +--8<-- "_snippets/integrations/builtin/cluster-nodes/langchain-overview-link.md" + +--8<-- "_snippets/self-hosting/starter-kits/self-hosted-ai-starter-kit.md" \ No newline at end of file diff --git a/docs/integrations/builtin/credentials/azureaisearch.md b/docs/integrations/builtin/credentials/azureaisearch.md new file mode 100644 index 00000000000..48a82a59b7c --- /dev/null +++ b/docs/integrations/builtin/credentials/azureaisearch.md @@ -0,0 +1,103 @@ +--- +title: Azure AI Search credentials +description: Documentation for Azure AI Search credentials. Use these credentials to authenticate Azure AI Search in n8n, a workflow automation platform. +contentType: [integration, reference] +priority: medium +--- + +# Azure AI Search credentials + +You can use these credentials to authenticate the following nodes: + +- [Azure AI Search Vector Store](/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md) + +## Prerequisites + +- Create an [Azure](https://azure.microsoft.com) subscription. +- Create an Azure AI Search service in the [Azure Portal](https://portal.azure.com/). +- Configure appropriate access to your search service (API key or managed identity). + +## Supported authentication methods + +- API key +- Managed identity (system-assigned) +- Managed identity (user-assigned) + +## Related resources + +Refer to [Azure AI Search documentation](https://learn.microsoft.com/en-us/azure/search/) for more information about the service. + +## Using API key + +To configure this credential, you'll need: + +- An **Endpoint**: The URL of your Azure AI Search service (e.g., `https://your-service.search.windows.net`) +- An **API Key**: The admin or query key for your service + +To get the information above: + +1. Navigate to your Azure AI Search service in the [Azure Portal](https://portal.azure.com/). +2. In the **Overview** section, copy the **URL** for your endpoint. +3. In the **Settings** > **Keys** section, copy either: + - **Admin key** (for read-write access) + - **Query key** (for read-only access) +4. Enter these values into the corresponding fields in n8n. + +/// note | API key permissions +Admin keys provide full access to the search service, including the ability to create and delete indexes. Query keys provide read-only access for querying data. Choose the appropriate key based on your workflow requirements. +/// + +## Using Managed Identity (System-Assigned) + +System-assigned managed identity is automatically created and managed by Azure. To configure: + +1. Enable system-assigned managed identity on your Azure resource (e.g., Azure VM, App Service, Function App). +2. In your Azure AI Search service: + 1. Navigate to **Settings** > **Keys**. + 2. Select **Role-based access control** as the authentication method. + 3. Go to **Access control (IAM)** > **Add role assignment**. + 4. Assign the appropriate role to your system-assigned managed identity: + - **Search Index Data Contributor** for read-write access + - **Search Index Data Reader** for read-only access +3. In n8n, enter only the **Endpoint** URL. +4. Select **Managed Identity (System-Assigned)** as the authentication method. + +## Using Managed Identity (User-Assigned) + +User-assigned managed identity allows you to create and manage the identity separately from the Azure resource. To configure: + +1. Create a user-assigned managed identity in the [Azure Portal](https://portal.azure.com/): + 1. Search for "Managed Identities" and select **Create**. + 2. Provide a name and select your subscription and resource group. + 3. After creation, copy the **Client ID** from the identity's overview page. +2. Assign the identity to your Azure resource (e.g., Azure VM, App Service, Function App). +3. In your Azure AI Search service: + 1. Navigate to **Settings** > **Keys**. + 2. Select **Role-based access control** as the authentication method. + 3. Go to **Access control (IAM)** > **Add role assignment**. + 4. Assign the appropriate role to your user-assigned managed identity: + - **Search Index Data Contributor** for read-write access + - **Search Index Data Reader** for read-only access +4. In n8n: + 1. Enter the **Endpoint** URL. + 2. Select **Managed Identity (User-Assigned)** as the authentication method. + 3. Enter the **Client ID** of your user-assigned managed identity. + +/// note | Managed Identity availability +Managed identity authentication is only available when n8n is running on Azure infrastructure (Azure VM, App Service, Container Instances, etc.). It won't work for local development or non-Azure deployments. +/// + +## Troubleshooting + +### Authentication errors + +If you encounter authentication errors: + +- **API key**: Verify the key is correct and hasn't been regenerated in Azure Portal. +- **Managed Identity**: Ensure the identity has the correct role assignments and that n8n is running on an Azure resource with the identity enabled. + +### Connection issues + +- Verify the endpoint URL is correct and includes the protocol (https://). +- Check that your Azure AI Search service is running and accessible. +- Ensure network security rules allow access from your n8n instance. \ No newline at end of file From 6e82b0077d50be9dd2b1783d58aa4bd7195bf6ba Mon Sep 17 00:00:00 2001 From: Farzad Sunavala Date: Sat, 20 Sep 2025 11:45:46 +0100 Subject: [PATCH 2/5] docs update on mi --- ...odes-langchain.vectorstoreazureaisearch.md | 4 ++- .../builtin/credentials/azureaisearch.md | 26 ++++++++++++++++--- 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md b/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md index c9cf4655b05..7b10f5d3a67 100644 --- a/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md +++ b/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md @@ -72,11 +72,13 @@ Before using this node, create a [Vector Search index](https://learn.microsoft.c 6. Note down your service endpoint URL and index name for configuration. +7. (Optional) If using managed identity authentication, ensure your Microsoft Entra ID (formerly Azure AD) tenant is properly configured with the necessary role assignments for your managed identities. + Make sure to note the following values which are required when configuring the node: - Azure AI Search endpoint URL - Index name -- API key or managed identity configuration +- Authentication method (API key, system-assigned managed identity, or user-assigned managed identity) ## Node usage patterns diff --git a/docs/integrations/builtin/credentials/azureaisearch.md b/docs/integrations/builtin/credentials/azureaisearch.md index 48a82a59b7c..6de2a04d1ae 100644 --- a/docs/integrations/builtin/credentials/azureaisearch.md +++ b/docs/integrations/builtin/credentials/azureaisearch.md @@ -49,7 +49,7 @@ Admin keys provide full access to the search service, including the ability to c ## Using Managed Identity (System-Assigned) -System-assigned managed identity is automatically created and managed by Azure. To configure: +System-assigned managed identity (SAMI) is automatically created and managed by Azure for your specific resource. This identity is tied directly to the Azure resource lifecycle and is recommended for single-resource scenarios. To configure: 1. Enable system-assigned managed identity on your Azure resource (e.g., Azure VM, App Service, Function App). 2. In your Azure AI Search service: @@ -62,9 +62,13 @@ System-assigned managed identity is automatically created and managed by Azure. 3. In n8n, enter only the **Endpoint** URL. 4. Select **Managed Identity (System-Assigned)** as the authentication method. +/// note | When to use System-Assigned Managed Identity +Use SAMI when your n8n instance runs on a single Azure resource and you want the identity to be automatically managed with the resource lifecycle. The identity is automatically deleted when the resource is deleted. +/// + ## Using Managed Identity (User-Assigned) -User-assigned managed identity allows you to create and manage the identity separately from the Azure resource. To configure: +User-assigned managed identity (UAMI) allows you to create and manage the identity separately from Azure resources. This identity can be shared across multiple resources and persists independently of resource lifecycles. To configure: 1. Create a user-assigned managed identity in the [Azure Portal](https://portal.azure.com/): 1. Search for "Managed Identities" and select **Create**. @@ -83,10 +87,25 @@ User-assigned managed identity allows you to create and manage the identity sepa 2. Select **Managed Identity (User-Assigned)** as the authentication method. 3. Enter the **Client ID** of your user-assigned managed identity. +/// note | When to use User-Assigned Managed Identity +Use UAMI when you need to share the same identity across multiple Azure resources, when you want the identity to persist beyond the lifecycle of individual resources, or when you need more granular control over identity management. This is ideal for enterprise scenarios with multiple n8n instances or complex multi-resource deployments. +/// + /// note | Managed Identity availability Managed identity authentication is only available when n8n is running on Azure infrastructure (Azure VM, App Service, Container Instances, etc.). It won't work for local development or non-Azure deployments. /// +## Understanding Microsoft Entra ID Integration + +Managed identity authentication uses Microsoft Entra ID (formerly Azure Active Directory) as the underlying identity platform. When you configure managed identity for Azure AI Search: + +- The identity is registered in your Microsoft Entra ID tenant +- Role assignments are managed through Entra ID's Role-Based Access Control (RBAC) +- Authentication tokens are issued by the Microsoft Entra ID token service +- This provides enterprise-grade security with centralized identity management + +This integration ensures that your n8n workflows benefit from the same identity and access management policies that govern your organization's other Azure resources. + ## Troubleshooting ### Authentication errors @@ -94,7 +113,8 @@ Managed identity authentication is only available when n8n is running on Azure i If you encounter authentication errors: - **API key**: Verify the key is correct and hasn't been regenerated in Azure Portal. -- **Managed Identity**: Ensure the identity has the correct role assignments and that n8n is running on an Azure resource with the identity enabled. +- **System-Assigned Managed Identity**: Ensure the identity is enabled on your Azure resource and has the correct role assignments in both Azure AI Search and Microsoft Entra ID. +- **User-Assigned Managed Identity**: Verify the Client ID is correct, the identity is assigned to your Azure resource, and has proper role assignments. Check that the identity exists in your Microsoft Entra ID tenant. ### Connection issues From d17bd5b1298431b937a6b77def88b05bdaee2a48 Mon Sep 17 00:00:00 2001 From: Farzad Sunavala Date: Fri, 26 Sep 2025 01:12:34 +0100 Subject: [PATCH 3/5] remove locale hardcode and minor updates on Mi --- .../n8n-nodes-langchain.vectorstoreazureaisearch.md | 13 +++++++------ .../builtin/credentials/azureaisearch.md | 2 +- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md b/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md index 7b10f5d3a67..b0e4fff946e 100644 --- a/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md +++ b/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md @@ -19,7 +19,7 @@ You can find authentication information for this node [here](/integrations/built ## Prerequisites -Before using this node, create a [Vector Search index](https://learn.microsoft.com/en-us/azure/search/vector-search-overview) in your Azure AI Search service. Follow these steps to create one: +Before using this node, create a [Vector Search index](https://learn.microsoft.com/azure/search/vector-search-overview) in your Azure AI Search service. Follow these steps to create one: 1. Log in to the [Azure Portal](https://portal.azure.com/). @@ -128,6 +128,7 @@ The [connections flow](https://n8n.io/workflows/2465-building-your-first-whatsap - **Endpoint**: Enter the Azure AI Search endpoint URL (e.g., `https://your-service.search.windows.net`). - **Index Name**: Enter the name of the Azure AI Search index to use. +- **Batch Size**: Controls the number of documents uploaded to Azure AI Search in each indexing batch. This parameter manages document upload batching to the search service, not embedding generation batching (which is configured in upstream embedding nodes). ### Update Documents parameters @@ -151,13 +152,13 @@ The [connections flow](https://n8n.io/workflows/2465-building-your-first-whatsap ### Options -- **Filter**: Use [OData filter expressions](https://learn.microsoft.com/en-us/azure/search/search-query-odata-filter) to filter results based on metadata fields. +- **Filter**: Use [OData filter expressions](https://learn.microsoft.com/azure/search/search-query-odata-filter) to filter results based on metadata fields. - **Query Mode**: Choose how to search the index: - **Vector**: Use only vector search - **Keyword**: Use only keyword search - **Hybrid** (default): Combine vector and keyword search - - **Semantic Hybrid**: Combine vector, keyword, and semantic ranking (requires semantic configuration) -- **Semantic Configuration**: Enter the name of the semantic configuration (required when using Semantic Hybrid query mode). + - **Semantic Hybrid**: Combine vector, keyword, and semantic ranking (optional semantic configuration can enhance results) +- **Semantic Configuration**: (Optional) Enter the name of the semantic configuration if you want to use semantic ranking with Semantic Hybrid query mode. ## Templates and examples @@ -168,9 +169,9 @@ The [connections flow](https://n8n.io/workflows/2465-building-your-first-whatsap Refer to: -- [Azure AI Search Vector Search documentation](https://learn.microsoft.com/en-us/azure/search/vector-search-overview) for more information about the service. +- [Azure AI Search Vector Search documentation](https://learn.microsoft.com/azure/search/vector-search-overview) for more information about the service. - [LangChain's Azure AI Search documentation](https://js.langchain.com/docs/integrations/vectorstores/azure_aisearch) for more information about the integration. -- [Azure AI Search REST API reference](https://learn.microsoft.com/en-us/rest/api/searchservice/) for detailed API information. +- [Azure AI Search REST API reference](https://learn.microsoft.com/rest/api/searchservice/) for detailed API information. --8<-- "_snippets/integrations/builtin/cluster-nodes/langchain-overview-link.md" diff --git a/docs/integrations/builtin/credentials/azureaisearch.md b/docs/integrations/builtin/credentials/azureaisearch.md index 6de2a04d1ae..9a2862b9430 100644 --- a/docs/integrations/builtin/credentials/azureaisearch.md +++ b/docs/integrations/builtin/credentials/azureaisearch.md @@ -25,7 +25,7 @@ You can use these credentials to authenticate the following nodes: ## Related resources -Refer to [Azure AI Search documentation](https://learn.microsoft.com/en-us/azure/search/) for more information about the service. +Refer to [Azure AI Search documentation](https://learn.microsoft.com/azure/search/) for more information about the service. ## Using API key From ea5b37266fe2a4c10fe8425c2492cbcffa849804 Mon Sep 17 00:00:00 2001 From: farzad528 Date: Sun, 9 Nov 2025 23:57:08 +0000 Subject: [PATCH 4/5] post-pr comments docs update --- ...odes-langchain.vectorstoreazureaisearch.md | 273 +++++++++++------- .../builtin/credentials/azureaisearch.md | 144 +++++---- nav.yml | 2 + 3 files changed, 259 insertions(+), 160 deletions(-) diff --git a/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md b/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md index b0e4fff946e..06f6d512f4e 100644 --- a/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md +++ b/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md @@ -7,7 +7,7 @@ priority: medium # Azure AI Search Vector Store node -Azure AI Search (formerly Azure Cognitive Search) is a cloud search service that provides vector search capabilities through its Vector Search feature. Use this node to interact with Vector Search indexes in your Azure AI Search service. You can insert documents, retrieve documents, and use the vector store in chains or as a tool for agents. +Azure AI Search (formerly Azure Cognitive Search) is a cloud search service with vector search capabilities for RAG and semantic search applications. Use this node to store, retrieve, and query vector embeddings alongside their content and metadata. On this page, you'll find the node parameters for the Azure AI Search Vector Store node, and links to more resources. @@ -19,94 +19,108 @@ You can find authentication information for this node [here](/integrations/built ## Prerequisites -Before using this node, create a [Vector Search index](https://learn.microsoft.com/azure/search/vector-search-overview) in your Azure AI Search service. Follow these steps to create one: - -1. Log in to the [Azure Portal](https://portal.azure.com/). - -2. Navigate to your Azure AI Search service or create a new one. -3. Select "Indexes" from the left navigation menu. -4. Click "Add Index" and create a new index with vector fields. -5. Configure your index schema with: - - A vector field for embeddings with appropriate dimensions - - Metadata fields for filtering and content - - Configure the vector search profile with the similarity metric (cosine, euclidean, or dotProduct) - - Example index JSON configuration: - ```json - { - "fields": [ - { - "name": "content_vector", - "type": "Collection(Edm.Single)", - "searchable": true, - "retrievable": true, - "dimensions": 1536, - "vectorSearchProfile": "vector-profile" - }, - { - "name": "content", - "type": "Edm.String", - "searchable": true, - "retrievable": true - } - ], - "vectorSearch": { - "profiles": [ - { - "name": "vector-profile", - "algorithm": "hnsw-algorithm" - } - ], - "algorithms": [ - { - "name": "hnsw-algorithm", - "kind": "hnsw", - "parameters": { - "metric": "cosine" - } - } - ] - } - } - ``` - -6. Note down your service endpoint URL and index name for configuration. - -7. (Optional) If using managed identity authentication, ensure your Microsoft Entra ID (formerly Azure AD) tenant is properly configured with the necessary role assignments for your managed identities. - -Make sure to note the following values which are required when configuring the node: - -- Azure AI Search endpoint URL -- Index name -- Authentication method (API key, system-assigned managed identity, or user-assigned managed identity) +Before using this node, you need: + +1. An [Azure subscription](https://azure.microsoft.com) +2. An [Azure AI Search service](https://learn.microsoft.com/azure/search/search-create-service-portal) +3. Authentication configured—choose based on your deployment: + - **API key**: Simple setup, works anywhere + - **Managed identity**: Recommended for Azure-hosted production deployments + + See [credentials documentation](/integrations/builtin/credentials/azureaisearch.md) for detailed setup instructions. + +### Index configuration + +The node automatically creates indexes if they don't exist. When auto-creating, the node configures: + +- Vector fields with appropriate dimensions based on your embeddings model +- HNSW algorithm for efficient similarity search with cosine metric +- Content and metadata fields for filtering and retrieval + +You can also pre-create indexes in Azure Portal for custom configurations. Example schema: + +```json +{ + "name": "n8n-vectorstore", + "fields": [ + { + "name": "id", + "type": "Edm.String", + "key": true, + "filterable": true + }, + { + "name": "content", + "type": "Edm.String", + "searchable": true + }, + { + "name": "content_vector", + "type": "Collection(Edm.Single)", + "searchable": true, + "vectorSearchDimensions": 1536, + "vectorSearchProfileName": "n8n-vector-profile" + }, + { + "name": "metadata", + "type": "Edm.String", + "filterable": true + } + ], + "vectorSearch": { + "profiles": [ + { + "name": "n8n-vector-profile", + "algorithm": "n8n-vector-algorithm" + } + ], + "algorithms": [ + { + "name": "n8n-vector-algorithm", + "kind": "hnsw", + "hnswParameters": { + "metric": "cosine", + "m": 4, + "efConstruction": 400, + "efSearch": 500 + } + } + ] + } +} +``` + +/// note | Vector dimensions +The `vectorSearchDimensions` value must match your embeddings model output. +/// ## Node usage patterns -You can use the Azure AI Search Vector Store node in the following patterns: - ### Use as a regular node to insert and retrieve documents -You can use the Azure AI Search Vector Store as a regular node to insert or get documents. This pattern places the Azure AI Search Vector Store in the regular connection flow without using an agent. - -You can see an example of this in scenario 1 of [this template](https://n8n.io/workflows/2621-ai-agent-to-chat-with-files-in-supabase-storage/) (the template uses the Supabase Vector Store, but the pattern is the same). +Use the node directly in workflows to insert or retrieve documents without an agent. See [this template](https://n8n.io/workflows/2621-ai-agent-to-chat-with-files-in-supabase-storage/) for an example pattern (uses Supabase, but the pattern is identical). ### Connect directly to an AI agent as a tool -You can connect the Azure AI Search Vector Store node directly to the tool connector of an [AI agent](/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/index.md) to use the vector store as a resource when answering queries. +Connect to an [AI agent's](/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/index.md) tool connector to use the vector store as a searchable knowledge base: -Here, the connection would be: AI agent (tools connector) -> Azure AI Search Vector Store node. +AI agent (tools connector) → Azure AI Search Vector Store node ### Use a retriever to fetch documents -You can use the [Vector Store Retriever](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.retrievervectorstore.md) node with the Azure AI Search Vector Store node to fetch documents from the Azure AI Search Vector Store node. This is often used with the [Question and Answer Chain](/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.chainretrievalqa/index.md) node to fetch documents from the vector store that match the given chat input. +Use with [Vector Store Retriever](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.retrievervectorstore.md) and [Question and Answer Chain](/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.chainretrievalqa/index.md) for retrieval-augmented generation: + +Question and Answer Chain (Retriever) → Vector Store Retriever (Vector Store) → Azure AI Search Vector Store -An [example of the connection flow](https://n8n.io/workflows/1960-ask-questions-about-a-pdf-using-ai/) (the linked example uses Pinecone, but the pattern is the same) would be: Question and Answer Chain (Retriever connector) -> Vector Store Retriever (Vector Store connector) -> Azure AI Search Vector Store. +See [this example workflow](https://n8n.io/workflows/1960-ask-questions-about-a-pdf-using-ai/). -### Use the Vector Store Question Answer Tool to answer questions +### Use the Vector Store Question Answer Tool -Another pattern uses the [Vector Store Question Answer Tool](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolvectorstore.md) to summarize results and answer questions from the Azure AI Search Vector Store node. Rather than connecting the Azure AI Search Vector Store directly as a tool, this pattern uses a tool specifically designed to summarize data in the vector store. +Use [Vector Store Question Answer Tool](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolvectorstore.md) to summarize and answer questions: -The [connections flow](https://n8n.io/workflows/2465-building-your-first-whatsapp-chatbot/) (the linked example uses the In-Memory Vector Store, but the pattern is the same) in this case would look like this: AI agent (tools connector) -> Vector Store Question Answer Tool (Vector Store connector) -> Azure AI Search Vector Store. +AI agent (tools) → Vector Store Question Answer Tool (Vector Store) → Azure AI Search Vector Store + +See [this example](https://n8n.io/workflows/2465-building-your-first-whatsapp-chatbot/). ## Node parameters @@ -116,49 +130,108 @@ The [connections flow](https://n8n.io/workflows/2465-building-your-first-whatsap --8<-- "_snippets/integrations/builtin/cluster-nodes/vector-store-rerank-results.md" +/// note | Azure AI Search semantic reranking +Azure AI Search has built-in [semantic reranking](https://learn.microsoft.com/azure/search/semantic-search-overview) available when you use **Semantic Hybrid** query mode with a semantic configuration. To use it: + +1. Set **Query Mode** to **Semantic Hybrid** in Options +2. Set **Semantic Configuration** to your configuration name (defaults to `semantic-search-config` if not specified) + +The built-in semantic reranker uses machine learning models to improve relevance. You can chain an additional reranking node after semantic reranking for further refinement. + +[Semantic reranking](https://learn.microsoft.com/azure/search/semantic-search-overview) is only available if your index has a semantic configuration defined. +/// + ### Get Many parameters -- **Endpoint**: Enter the Azure AI Search endpoint URL (e.g., `https://your-service.search.windows.net`). -- **Index Name**: Enter the name of the Azure AI Search index to use. -- **Results Count**: Enter the maximum number of documents to return (default: 50). +- **Endpoint**: Your Azure AI Search endpoint (format: `https://your-service.search.windows.net`) +- **Index Name**: The index to query +- **Results Count**: Maximum documents to return (default: 50) ### Insert Documents parameters -- **Endpoint**: Enter the Azure AI Search endpoint URL (e.g., `https://your-service.search.windows.net`). -- **Index Name**: Enter the name of the Azure AI Search index to use. -- **Batch Size**: Controls the number of documents uploaded to Azure AI Search in each indexing batch. This parameter manages document upload batching to the search service, not embedding generation batching (which is configured in upstream embedding nodes). +- **Endpoint**: Your Azure AI Search endpoint +- **Index Name**: The index to use (created automatically if it doesn't exist) +- **Batch Size**: Number of documents uploaded per batch to Azure AI Search. Adjust based on document size and your service tier limits. This controls upload batching only—embedding generation batching is configured in embedding nodes. ### Update Documents parameters -- **Endpoint**: Enter the Azure AI Search endpoint URL (e.g., `https://your-service.search.windows.net`). -- **Index Name**: Enter the name of the Azure AI Search index to use. +- **Endpoint**: Your Azure AI Search endpoint +- **Index Name**: The index to update ### Retrieve Documents parameters (As Vector Store for Chain/Tool) -- **Endpoint**: Enter the Azure AI Search endpoint URL (e.g., `https://your-service.search.windows.net`). -- **Index Name**: Enter the name of the Azure AI Search index to use. +- **Endpoint**: Your Azure AI Search endpoint +- **Index Name**: The index to query ### Retrieve Documents (As Tool for AI Agent) parameters -- **Name**: The name of the vector store. -- **Description**: Explain to the LLM what this tool does. A good, specific description allows LLMs to produce expected results more often. -- **Endpoint**: Enter the Azure AI Search endpoint URL (e.g., `https://your-service.search.windows.net`). -- **Index Name**: Enter the name of the Azure AI Search index to use. -- **Limit**: Enter how many results to retrieve from the vector store. For example, set this to `10` to get the ten best results. +- **Name**: Tool name shown to the LLM +- **Description**: Explain to the LLM what this tool does. Be specific to help the LLM choose when to use this tool. +- **Endpoint**: Your Azure AI Search endpoint +- **Index Name**: The index to query +- **Limit**: Maximum results to retrieve (e.g., `10` for ten best matches) ## Node options ### Options -- **Filter**: Use [OData filter expressions](https://learn.microsoft.com/azure/search/search-query-odata-filter) to filter results based on metadata fields. -- **Query Mode**: Choose how to search the index: - - **Vector**: Use only vector search - - **Keyword**: Use only keyword search - - **Hybrid** (default): Combine vector and keyword search - - **Semantic Hybrid**: Combine vector, keyword, and semantic ranking (optional semantic configuration can enhance results) -- **Semantic Configuration**: (Optional) Enter the name of the semantic configuration if you want to use semantic ranking with Semantic Hybrid query mode. +- **Filter**: [OData filter expression](https://learn.microsoft.com/azure/search/search-query-odata-filter) to filter results by metadata (e.g., `metadata/source eq 'manual.pdf'`) +- **Query Mode**: Search strategy to use: + - **Vector**: Similarity search using embeddings only + - **Keyword**: Full-text search using BM25 ranking + - **Hybrid** (default): Combines vector and keyword search with Reciprocal Rank Fusion (RRF) + - **Semantic Hybrid**: Hybrid search with [semantic reranking](https://learn.microsoft.com/azure/search/semantic-search-overview) for improved relevance +- **Semantic Configuration**: Name of the semantic configuration to use for [semantic ranking](https://learn.microsoft.com/azure/search/semantic-search-overview). Defaults to `semantic-search-config` if not specified. Only required if you pre-created an index with a custom semantic configuration name. + +/// note | Query mode selection +Use **Vector** for semantic similarity, **Keyword** for exact term matching, **Hybrid** for balanced results, or **Semantic Hybrid** when you've configured semantic search in your index for maximum relevance. +/// + +## Azure AI Search specific features + +### Hybrid search with RRF + +Azure AI Search's hybrid search uses Reciprocal Rank Fusion to merge vector and keyword results, providing better accuracy than either method alone. + +### [Semantic ranking](https://learn.microsoft.com/azure/search/semantic-search-overview) + +Semantic Hybrid mode applies machine learning models to rerank results based on semantic understanding of your query. This requires a semantic configuration in your index. + +### OData filters + +Use OData syntax to filter by metadata fields before vector search executes. This improves performance and precision when you need results from specific sources or with certain attributes. + +### HNSW algorithm + +Azure AI Search uses Hierarchical Navigable Small World (HNSW) graphs for approximate nearest neighbor search, providing fast retrieval at scale with configurable accuracy/speed tradeoffs. + +## Troubleshooting + +### Index issues + +**Index not found**: Verify the index name is correct (case-sensitive) and exists in your Azure AI Search service. If using auto-creation, check that the index was created successfully. + +**Vector dimension mismatch**: Ensure your embedding model dimensions match the index vector field dimensions. Check the index schema to confirm the `vectorSearchDimensions` setting. + +**Document insert failures**: +- Verify write permissions (admin API key or Search Index Data Contributor role) +- Check document fields match your index schema +- Ensure required fields are provided in documents +- Review batch size settings if experiencing timeouts with large document sets + +### Connection issues + +**Unable to connect**: +- Verify endpoint URL format: `https://your-service.search.windows.net` +- Confirm your Azure AI Search service is running and accessible +- Check network security groups, firewall rules, and private endpoint configurations +- For Azure-hosted n8n, verify virtual network peering or service endpoint configuration if using private endpoints + +### Authentication issues + +For authentication troubleshooting including credential test failures, API key errors, and managed identity issues, refer to the [credentials documentation troubleshooting section](/integrations/builtin/credentials/azureaisearch.md#troubleshooting). ## Templates and examples @@ -167,12 +240,10 @@ The [connections flow](https://n8n.io/workflows/2465-building-your-first-whatsap ## Related resources -Refer to: - -- [Azure AI Search Vector Search documentation](https://learn.microsoft.com/azure/search/vector-search-overview) for more information about the service. -- [LangChain's Azure AI Search documentation](https://js.langchain.com/docs/integrations/vectorstores/azure_aisearch) for more information about the integration. -- [Azure AI Search REST API reference](https://learn.microsoft.com/rest/api/searchservice/) for detailed API information. +- [Azure AI Search Vector Search documentation](https://learn.microsoft.com/azure/search/vector-search-overview) +- [LangChain Azure AI Search integration](https://js.langchain.com/docs/integrations/vectorstores/azure_aisearch) +- [Azure AI Search REST API reference](https://learn.microsoft.com/rest/api/searchservice/) --8<-- "_snippets/integrations/builtin/cluster-nodes/langchain-overview-link.md" ---8<-- "_snippets/self-hosting/starter-kits/self-hosted-ai-starter-kit.md" \ No newline at end of file +--8<-- "_snippets/self-hosting/starter-kits/self-hosted-ai-starter-kit.md" diff --git a/docs/integrations/builtin/credentials/azureaisearch.md b/docs/integrations/builtin/credentials/azureaisearch.md index 9a2862b9430..60d7e456999 100644 --- a/docs/integrations/builtin/credentials/azureaisearch.md +++ b/docs/integrations/builtin/credentials/azureaisearch.md @@ -13,9 +13,9 @@ You can use these credentials to authenticate the following nodes: ## Prerequisites -- Create an [Azure](https://azure.microsoft.com) subscription. -- Create an Azure AI Search service in the [Azure Portal](https://portal.azure.com/). -- Configure appropriate access to your search service (API key or managed identity). +- An [Azure subscription](https://azure.microsoft.com) +- An Azure AI Search service created in the [Azure Portal](https://portal.azure.com/) +- Appropriate authentication configured (API key or managed identity) ## Supported authentication methods @@ -31,93 +31,119 @@ Refer to [Azure AI Search documentation](https://learn.microsoft.com/azure/searc To configure this credential, you'll need: -- An **Endpoint**: The URL of your Azure AI Search service (e.g., `https://your-service.search.windows.net`) -- An **API Key**: The admin or query key for your service +- **Endpoint**: Your Azure AI Search service URL (format: `https://your-service.search.windows.net`) +- **API Key**: Admin key (read-write) or query key (read-only) -To get the information above: +To get these values: -1. Navigate to your Azure AI Search service in the [Azure Portal](https://portal.azure.com/). -2. In the **Overview** section, copy the **URL** for your endpoint. -3. In the **Settings** > **Keys** section, copy either: - - **Admin key** (for read-write access) - - **Query key** (for read-only access) -4. Enter these values into the corresponding fields in n8n. +1. Navigate to your Azure AI Search service in the [Azure Portal](https://portal.azure.com/) +2. Copy the **URL** from the **Overview** section +3. Go to **Settings** > **Keys** and copy: + - **Admin key** for full read-write access, or + - **Query key** for read-only querying +4. Enter these values in n8n /// note | API key permissions -Admin keys provide full access to the search service, including the ability to create and delete indexes. Query keys provide read-only access for querying data. Choose the appropriate key based on your workflow requirements. +Admin keys provide full access including index creation and deletion. Query keys provide read-only access. Choose based on your workflow requirements. /// ## Using Managed Identity (System-Assigned) -System-assigned managed identity (SAMI) is automatically created and managed by Azure for your specific resource. This identity is tied directly to the Azure resource lifecycle and is recommended for single-resource scenarios. To configure: +System-assigned managed identity (SAMI) is automatically created with your Azure resource and follows its lifecycle. Use this for single-resource scenarios. -1. Enable system-assigned managed identity on your Azure resource (e.g., Azure VM, App Service, Function App). +To configure: + +1. Enable system-assigned managed identity on your Azure resource (VM, App Service, Container Instance, etc.) 2. In your Azure AI Search service: - 1. Navigate to **Settings** > **Keys**. - 2. Select **Role-based access control** as the authentication method. - 3. Go to **Access control (IAM)** > **Add role assignment**. - 4. Assign the appropriate role to your system-assigned managed identity: - - **Search Index Data Contributor** for read-write access - - **Search Index Data Reader** for read-only access -3. In n8n, enter only the **Endpoint** URL. -4. Select **Managed Identity (System-Assigned)** as the authentication method. - -/// note | When to use System-Assigned Managed Identity -Use SAMI when your n8n instance runs on a single Azure resource and you want the identity to be automatically managed with the resource lifecycle. The identity is automatically deleted when the resource is deleted. + 1. Go to **Settings** > **Keys** + 2. Enable **Role-based access control** + 3. Go to **Access control (IAM)** > **Add role assignment** + 4. Assign one of these roles to your system-assigned managed identity: + - **Search Index Data Contributor** (read-write) + - **Search Index Data Reader** (read-only) +3. In n8n: + 1. Enter the **Endpoint** URL + 2. Select **Managed Identity (System-Assigned)** + +/// note | Credential test behavior +The managed identity credential test will fail in n8n's credential interface, but this is expected. The test uses HTTP requests that cannot authenticate with Azure's SDK-based token credential. The credentials will work correctly when the node executes. +/// + +/// note | When to use SAMI +Use SAMI when n8n runs on a single Azure resource and you want automatic identity lifecycle management. The identity is deleted when the resource is deleted. /// ## Using Managed Identity (User-Assigned) -User-assigned managed identity (UAMI) allows you to create and manage the identity separately from Azure resources. This identity can be shared across multiple resources and persists independently of resource lifecycles. To configure: +User-assigned managed identity (UAMI) is created independently and can be shared across multiple resources. Use this for multi-resource deployments or when you need identity persistence beyond resource lifecycles. -1. Create a user-assigned managed identity in the [Azure Portal](https://portal.azure.com/): - 1. Search for "Managed Identities" and select **Create**. - 2. Provide a name and select your subscription and resource group. - 3. After creation, copy the **Client ID** from the identity's overview page. -2. Assign the identity to your Azure resource (e.g., Azure VM, App Service, Function App). +To configure: + +1. Create a user-assigned managed identity: + 1. In [Azure Portal](https://portal.azure.com/), search for "Managed Identities" + 2. Click **Create** + 3. Provide name, subscription, and resource group + 4. After creation, copy the **Client ID** +2. Assign the identity to your Azure resource 3. In your Azure AI Search service: - 1. Navigate to **Settings** > **Keys**. - 2. Select **Role-based access control** as the authentication method. - 3. Go to **Access control (IAM)** > **Add role assignment**. - 4. Assign the appropriate role to your user-assigned managed identity: - - **Search Index Data Contributor** for read-write access - - **Search Index Data Reader** for read-only access + 1. Go to **Settings** > **Keys** + 2. Enable **Role-based access control** + 3. Go to **Access control (IAM)** > **Add role assignment** + 4. Assign one of these roles to your user-assigned managed identity: + - **Search Index Data Contributor** (read-write) + - **Search Index Data Reader** (read-only) 4. In n8n: - 1. Enter the **Endpoint** URL. - 2. Select **Managed Identity (User-Assigned)** as the authentication method. - 3. Enter the **Client ID** of your user-assigned managed identity. + 1. Enter the **Endpoint** URL + 2. Select **Managed Identity (User-Assigned)** + 3. Enter the **Client ID** + +/// note | Credential test behavior +Like system-assigned, the credential test will fail for user-assigned managed identity. This is expected—the credentials work correctly at runtime when the node executes. +/// -/// note | When to use User-Assigned Managed Identity -Use UAMI when you need to share the same identity across multiple Azure resources, when you want the identity to persist beyond the lifecycle of individual resources, or when you need more granular control over identity management. This is ideal for enterprise scenarios with multiple n8n instances or complex multi-resource deployments. +/// note | When to use UAMI +Use UAMI for multi-instance deployments, when identity should persist independently of resources, or when you need centralized identity management across multiple Azure resources. /// -/// note | Managed Identity availability -Managed identity authentication is only available when n8n is running on Azure infrastructure (Azure VM, App Service, Container Instances, etc.). It won't work for local development or non-Azure deployments. +/// note | Managed identity availability +Managed identity authentication requires n8n to run on Azure infrastructure (VM, App Service, Container Instances, Functions, etc.). It won't work for local development or non-Azure environments. + +For local testing, use `az login` to authenticate via Azure CLI—the Azure SDK will use CLI credentials as a fallback. /// ## Understanding Microsoft Entra ID Integration -Managed identity authentication uses Microsoft Entra ID (formerly Azure Active Directory) as the underlying identity platform. When you configure managed identity for Azure AI Search: +Managed identity authentication uses Microsoft Entra ID (formerly Azure Active Directory) for identity and access management: -- The identity is registered in your Microsoft Entra ID tenant -- Role assignments are managed through Entra ID's Role-Based Access Control (RBAC) -- Authentication tokens are issued by the Microsoft Entra ID token service -- This provides enterprise-grade security with centralized identity management +- Identities are registered in your Entra ID tenant +- Role assignments use Entra ID Role-Based Access Control (RBAC) +- Authentication tokens are issued by the Entra ID token service +- Centralized identity governance with enterprise security policies -This integration ensures that your n8n workflows benefit from the same identity and access management policies that govern your organization's other Azure resources. +This provides the same identity and access management for n8n workflows as your other Azure resources. ## Troubleshooting -### Authentication errors +### Credential test failures -If you encounter authentication errors: +**Managed identity credential tests fail**: This is expected behavior. The test uses HTTP requests that cannot authenticate with Azure SDK token credentials. The credentials work correctly when nodes execute. + +### Authentication errors -- **API key**: Verify the key is correct and hasn't been regenerated in Azure Portal. -- **System-Assigned Managed Identity**: Ensure the identity is enabled on your Azure resource and has the correct role assignments in both Azure AI Search and Microsoft Entra ID. -- **User-Assigned Managed Identity**: Verify the Client ID is correct, the identity is assigned to your Azure resource, and has proper role assignments. Check that the identity exists in your Microsoft Entra ID tenant. +- **API key**: Verify the key is correct and hasn't been regenerated +- **System-Assigned Managed Identity**: + - Confirm identity is enabled on your Azure resource + - Verify correct role assignments in Azure AI Search IAM + - Check that the Azure resource has network access to the search service +- **User-Assigned Managed Identity**: + - Verify the Client ID is correct + - Confirm identity is assigned to your Azure resource + - Check role assignments in both Azure AI Search and Entra ID + - Ensure the identity exists in your Entra ID tenant ### Connection issues -- Verify the endpoint URL is correct and includes the protocol (https://). -- Check that your Azure AI Search service is running and accessible. -- Ensure network security rules allow access from your n8n instance. \ No newline at end of file +- Verify endpoint URL format: `https://your-service.search.windows.net` +- Confirm Azure AI Search service is running +- Check network security rules and firewall settings allow access from your n8n instance +- For managed identity, verify the Azure resource can reach Azure services diff --git a/nav.yml b/nav.yml index 460520d8d1b..cf75e4ef170 100644 --- a/nav.yml +++ b/nav.yml @@ -717,6 +717,7 @@ nav: - Text Classifier: integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.text-classifier.md - Sentiment Analysis: integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.sentimentanalysis.md - LangChain Code: integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.code.md + - Azure AI Search Vector Store: integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md - Simple Vector Store: integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreinmemory.md - Milvus Vector Store: integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoremilvus.md - MongoDB Atlas Vector Store: integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoremongodbatlas.md @@ -819,6 +820,7 @@ nav: - integrations/builtin/credentials/aws.md - integrations/builtin/credentials/azureopenai.md - integrations/builtin/credentials/azurecosmosdb.md + - integrations/builtin/credentials/azureaisearch.md - integrations/builtin/credentials/azurestorage.md - integrations/builtin/credentials/bamboohr.md - integrations/builtin/credentials/bannerbear.md From ed3e451db1a9b63393c6a0edfe2a40f4fa133397 Mon Sep 17 00:00:00 2001 From: farzad528 Date: Fri, 14 Nov 2025 16:16:10 +0000 Subject: [PATCH 5/5] latest docs --- ...odes-langchain.vectorstoreazureaisearch.md | 74 +++++++++++-- .../builtin/credentials/azureaisearch.md | 101 ++---------------- 2 files changed, 71 insertions(+), 104 deletions(-) diff --git a/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md b/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md index 06f6d512f4e..ebf9f87a90a 100644 --- a/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md +++ b/docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md @@ -23,11 +23,9 @@ Before using this node, you need: 1. An [Azure subscription](https://azure.microsoft.com) 2. An [Azure AI Search service](https://learn.microsoft.com/azure/search/search-create-service-portal) -3. Authentication configured—choose based on your deployment: - - **API key**: Simple setup, works anywhere - - **Managed identity**: Recommended for Azure-hosted production deployments +3. API key authentication configured (admin key for write operations, query key for read-only) - See [credentials documentation](/integrations/builtin/credentials/azureaisearch.md) for detailed setup instructions. + See [credentials documentation](/integrations/builtin/credentials/azureaisearch.md) for setup instructions. ### Index configuration @@ -147,7 +145,7 @@ The built-in semantic reranker uses machine learning models to improve relevance - **Endpoint**: Your Azure AI Search endpoint (format: `https://your-service.search.windows.net`) - **Index Name**: The index to query -- **Results Count**: Maximum documents to return (default: 50) +- **Limit**: Maximum documents to return (default: 4) ### Insert Documents parameters @@ -177,7 +175,7 @@ The built-in semantic reranker uses machine learning models to improve relevance ### Options -- **Filter**: [OData filter expression](https://learn.microsoft.com/azure/search/search-query-odata-filter) to filter results by metadata (e.g., `metadata/source eq 'manual.pdf'`) +- **Filter**: [OData filter expression](https://learn.microsoft.com/azure/search/search-query-odata-filter) to filter results by document fields or metadata. See filter examples below. - **Query Mode**: Search strategy to use: - **Vector**: Similarity search using embeddings only - **Keyword**: Full-text search using BM25 ranking @@ -189,6 +187,50 @@ The built-in semantic reranker uses machine learning models to improve relevance Use **Vector** for semantic similarity, **Keyword** for exact term matching, **Hybrid** for balanced results, or **Semantic Hybrid** when you've configured semantic search in your index for maximum relevance. /// +### OData filter examples + +Azure AI Search uses [OData syntax](https://learn.microsoft.com/azure/search/search-query-odata-filter) for filtering. Metadata fields are accessed using `metadata/fieldName` format. + +**Filter by document ID:** +``` +id eq '3da6491a-f930-4a4e-9471-c05dcd450ba0' +``` + +**Filter by metadata field:** +``` +metadata/source eq 'user-guide' +``` + +**Complex AND filter:** +``` +metadata/category eq 'technology' and metadata/author eq 'John' +``` + +**Complex OR filter:** +``` +metadata/source eq 'user-guide' or metadata/rating ge 4 +``` + +**Numeric comparison:** +``` +metadata/rating ge 4 and metadata/rating lt 10 +``` + +**String matching with NOT:** +``` +metadata/category eq 'technology' and metadata/title ne 'Deprecated' +``` + +**Supported OData operators:** +- Comparison: `eq`, `ne`, `gt`, `ge`, `lt`, `le` +- Logical: `and`, `or`, `not` +- String functions: `startswith()`, `endswith()`, `contains()` +- Collection functions: `any()`, `all()` + +/// note | Filter format +Filters work across all query modes (Vector, Keyword, Hybrid, Semantic Hybrid) and all operation modes (retrieve, load, retrieve-as-tool). +/// + ## Azure AI Search specific features ### Hybrid search with RRF @@ -201,7 +243,7 @@ Semantic Hybrid mode applies machine learning models to rerank results based on ### OData filters -Use OData syntax to filter by metadata fields before vector search executes. This improves performance and precision when you need results from specific sources or with certain attributes. +Use OData syntax to filter by document fields or metadata before vector search executes. This improves performance and precision when you need results from specific sources or with certain attributes. ### HNSW algorithm @@ -216,11 +258,24 @@ Azure AI Search uses Hierarchical Navigable Small World (HNSW) graphs for approx **Vector dimension mismatch**: Ensure your embedding model dimensions match the index vector field dimensions. Check the index schema to confirm the `vectorSearchDimensions` setting. **Document insert failures**: -- Verify write permissions (admin API key or Search Index Data Contributor role) +- Verify write permissions (admin API key required) - Check document fields match your index schema - Ensure required fields are provided in documents - Review batch size settings if experiencing timeouts with large document sets +### Filter issues + +**Filter not working**: +- Verify OData syntax is correct +- Ensure metadata fields use `metadata/` prefix: `metadata/source eq 'value'` +- Check that filtered fields are marked as `filterable` in your index schema +- Test with simple filters first (`id eq 'value'`) before complex expressions + +**Invalid OData syntax**: +- Use single quotes for string values: `metadata/source eq 'value'` +- Use proper operators: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `and`, `or`, `not` +- Refer to [OData filter documentation](https://learn.microsoft.com/azure/search/search-query-odata-filter) for syntax details + ### Connection issues **Unable to connect**: @@ -231,7 +286,7 @@ Azure AI Search uses Hierarchical Navigable Small World (HNSW) graphs for approx ### Authentication issues -For authentication troubleshooting including credential test failures, API key errors, and managed identity issues, refer to the [credentials documentation troubleshooting section](/integrations/builtin/credentials/azureaisearch.md#troubleshooting). +For authentication troubleshooting including API key errors, refer to the [credentials documentation troubleshooting section](/integrations/builtin/credentials/azureaisearch.md#troubleshooting). ## Templates and examples @@ -243,6 +298,7 @@ For authentication troubleshooting including credential test failures, API key e - [Azure AI Search Vector Search documentation](https://learn.microsoft.com/azure/search/vector-search-overview) - [LangChain Azure AI Search integration](https://js.langchain.com/docs/integrations/vectorstores/azure_aisearch) - [Azure AI Search REST API reference](https://learn.microsoft.com/rest/api/searchservice/) +- [OData filter syntax for Azure AI Search](https://learn.microsoft.com/azure/search/search-query-odata-filter) --8<-- "_snippets/integrations/builtin/cluster-nodes/langchain-overview-link.md" diff --git a/docs/integrations/builtin/credentials/azureaisearch.md b/docs/integrations/builtin/credentials/azureaisearch.md index 60d7e456999..34922dfcf65 100644 --- a/docs/integrations/builtin/credentials/azureaisearch.md +++ b/docs/integrations/builtin/credentials/azureaisearch.md @@ -15,13 +15,10 @@ You can use these credentials to authenticate the following nodes: - An [Azure subscription](https://azure.microsoft.com) - An Azure AI Search service created in the [Azure Portal](https://portal.azure.com/) -- Appropriate authentication configured (API key or managed identity) ## Supported authentication methods -- API key -- Managed identity (system-assigned) -- Managed identity (user-assigned) +This node uses API key authentication. ## Related resources @@ -47,103 +44,17 @@ To get these values: Admin keys provide full access including index creation and deletion. Query keys provide read-only access. Choose based on your workflow requirements. /// -## Using Managed Identity (System-Assigned) - -System-assigned managed identity (SAMI) is automatically created with your Azure resource and follows its lifecycle. Use this for single-resource scenarios. - -To configure: - -1. Enable system-assigned managed identity on your Azure resource (VM, App Service, Container Instance, etc.) -2. In your Azure AI Search service: - 1. Go to **Settings** > **Keys** - 2. Enable **Role-based access control** - 3. Go to **Access control (IAM)** > **Add role assignment** - 4. Assign one of these roles to your system-assigned managed identity: - - **Search Index Data Contributor** (read-write) - - **Search Index Data Reader** (read-only) -3. In n8n: - 1. Enter the **Endpoint** URL - 2. Select **Managed Identity (System-Assigned)** - -/// note | Credential test behavior -The managed identity credential test will fail in n8n's credential interface, but this is expected. The test uses HTTP requests that cannot authenticate with Azure's SDK-based token credential. The credentials will work correctly when the node executes. -/// - -/// note | When to use SAMI -Use SAMI when n8n runs on a single Azure resource and you want automatic identity lifecycle management. The identity is deleted when the resource is deleted. -/// - -## Using Managed Identity (User-Assigned) - -User-assigned managed identity (UAMI) is created independently and can be shared across multiple resources. Use this for multi-resource deployments or when you need identity persistence beyond resource lifecycles. - -To configure: - -1. Create a user-assigned managed identity: - 1. In [Azure Portal](https://portal.azure.com/), search for "Managed Identities" - 2. Click **Create** - 3. Provide name, subscription, and resource group - 4. After creation, copy the **Client ID** -2. Assign the identity to your Azure resource -3. In your Azure AI Search service: - 1. Go to **Settings** > **Keys** - 2. Enable **Role-based access control** - 3. Go to **Access control (IAM)** > **Add role assignment** - 4. Assign one of these roles to your user-assigned managed identity: - - **Search Index Data Contributor** (read-write) - - **Search Index Data Reader** (read-only) -4. In n8n: - 1. Enter the **Endpoint** URL - 2. Select **Managed Identity (User-Assigned)** - 3. Enter the **Client ID** - -/// note | Credential test behavior -Like system-assigned, the credential test will fail for user-assigned managed identity. This is expected—the credentials work correctly at runtime when the node executes. -/// - -/// note | When to use UAMI -Use UAMI for multi-instance deployments, when identity should persist independently of resources, or when you need centralized identity management across multiple Azure resources. -/// - -/// note | Managed identity availability -Managed identity authentication requires n8n to run on Azure infrastructure (VM, App Service, Container Instances, Functions, etc.). It won't work for local development or non-Azure environments. - -For local testing, use `az login` to authenticate via Azure CLI—the Azure SDK will use CLI credentials as a fallback. -/// - -## Understanding Microsoft Entra ID Integration - -Managed identity authentication uses Microsoft Entra ID (formerly Azure Active Directory) for identity and access management: - -- Identities are registered in your Entra ID tenant -- Role assignments use Entra ID Role-Based Access Control (RBAC) -- Authentication tokens are issued by the Entra ID token service -- Centralized identity governance with enterprise security policies - -This provides the same identity and access management for n8n workflows as your other Azure resources. - ## Troubleshooting -### Credential test failures - -**Managed identity credential tests fail**: This is expected behavior. The test uses HTTP requests that cannot authenticate with Azure SDK token credentials. The credentials work correctly when nodes execute. - ### Authentication errors -- **API key**: Verify the key is correct and hasn't been regenerated -- **System-Assigned Managed Identity**: - - Confirm identity is enabled on your Azure resource - - Verify correct role assignments in Azure AI Search IAM - - Check that the Azure resource has network access to the search service -- **User-Assigned Managed Identity**: - - Verify the Client ID is correct - - Confirm identity is assigned to your Azure resource - - Check role assignments in both Azure AI Search and Entra ID - - Ensure the identity exists in your Entra ID tenant +**API key authentication fails**: +- Verify the API key is correct and hasn't been regenerated in Azure Portal +- Confirm you're using an admin key for write operations (insert/update) +- Check that the key hasn't expired or been rotated ### Connection issues - Verify endpoint URL format: `https://your-service.search.windows.net` -- Confirm Azure AI Search service is running +- Confirm your Azure AI Search service is running - Check network security rules and firewall settings allow access from your n8n instance -- For managed identity, verify the Azure resource can reach Azure services