Azure AI Search Vector Store Documentation

docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.vectorstoreazureaisearch.md

@@ -0,0 +1,178 @@
+---
+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/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)
+
+## 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"
+
+<!-- vale off -->
+### Get Many parameters
+<!-- vale on -->
+
+- **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.
+- **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
+
+- **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/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.
+
+## Templates and examples
+
+<!-- see https://www.notion.so/n8n/Pull-in-templates-for-the-integrations-pages-37c716837b804d30a33b47475f6e3780 -->
+[[ templatesWidget(page.title, 'azure-ai-search-vector-store') ]]
+
+## 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.
+
+--8<-- "_snippets/integrations/builtin/cluster-nodes/langchain-overview-link.md"
+
+--8<-- "_snippets/self-hosting/starter-kits/self-hosted-ai-starter-kit.md"

docs/integrations/builtin/credentials/azureaisearch.md

@@ -0,0 +1,123 @@
+---
+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/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 (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:
+   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.
+///
+
+## 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:
+
+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 | 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
+
+If you encounter 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.
+
+### 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.