@timyeung/n8n-nodes-azure-cosmos-sdk

This is an n8n community node for Azure Cosmos DB. It provides complete SQL query freedom using the official Azure Cosmos DB SDK, enabling advanced features like hybrid search, vector similarity search, and Microsoft Entra ID authentication.

Why Use This Node?

Unlike the native n8n Cosmos DB node (which uses REST API), this implementation:

• ✅ Uses Azure Cosmos DB SDK (not REST API) for full feature support
• ✅ Complete query freedom - write any SQL query including hybrid search
• ✅ Vector similarity search - supports VectorDistance() and hybrid search queries
• ✅ Vector field exclusion - optionally exclude large embedding fields to reduce payload
• ✅ Modern SDK features - access to latest Cosmos DB capabilities

Azure Cosmos DB is a fully managed NoSQL and relational database for modern app development with vector database support.

n8n is a fair-code licensed workflow automation platform.

• Installation
• Operations
• Credentials
• Compatibility
• Usage
• Resources

Installation

Follow the installation guide in the n8n community nodes documentation.

Development

# Install dependencies
npm install

# Build the node
npm run build

# Run in development mode
npm run dev

Operations

This node supports multiple operations against Azure Cosmos DB containers:

Select (Query Documents)

Execute full SQL queries with complete freedom:

• Any SQL Query: Write any Cosmos DB SQL query
• Hybrid Search: Combine vector similarity search with traditional filters
• Vector Similarity: Use VectorDistance() function for semantic search
• Vector Field Exclusion: Option to exclude vector/embedding fields from results to reduce payload size

Example Queries:

Basic Query:

SELECT * FROM c WHERE c.status = "active"

Vector Similarity Search:

SELECT TOP 10 c.id, c.title, VectorDistance(c.embedding, [0.1, 0.2, ...]) AS similarity
FROM c
ORDER BY VectorDistance(c.embedding, [0.1, 0.2, ...])

Hybrid Search (Vector + Filters):

SELECT TOP 10 c.id, c.title, VectorDistance(c.embedding, [0.1, 0.2, ...]) AS similarity
FROM c
WHERE c.category = "research" AND c.year >= 2023
ORDER BY VectorDistance(c.embedding, [0.1, 0.2, ...])

Insert (Create Document)

Insert new documents into a container:

• JSON Input: Provide document as JSON
• Auto-generated Metadata: Returns document with Cosmos DB metadata (_rid, _self, _etag, etc.)
• Partition Key Support: Automatically handles partition keys

Example:

{
  "id": "unique-id-123",
  "name": "John Doe",
  "email": "[email protected]",
  "status": "active"
}

Credentials

This node supports two authentication methods:

Option 1: Master Key Authentication (Default)

1. Azure Cosmos DB Account: Sign up at Azure Portal
2. Endpoint URL: Your Cosmos DB account endpoint (e.g., https://your-account.documents.azure.com:443/)
3. Access Key: Primary or secondary key from Azure Portal → Your Cosmos DB Account → Keys

The credential test uses HMAC-SHA256 signature authentication with master keys to verify your connection by listing databases.

Option 2: Microsoft Entra ID (Azure AD) Authentication

For enhanced security using OAuth2 and role-based access control (RBAC):

1. Azure Cosmos DB Account: Your Cosmos DB endpoint URL
2. Client ID: Application (client) ID from Azure App Registration
3. Client Secret: Client secret from Azure App Registration
4. Tenant ID: Directory (tenant) ID from Azure App Registration

Setup Steps:

1. Create an App Registration in Azure Portal → Microsoft Entra ID
2. Create a client secret for the app
3. Assign the app appropriate Cosmos DB RBAC roles (e.g., "Cosmos DB Built-in Data Contributor")
4. Use the app credentials in n8n

Scopes Used: https://cosmos.azure.com/.default with offline_access

The node uses the Azure Cosmos DB SDK (@azure/cosmos) with OAuth2 token authentication.

Compatibility

• Minimum n8n version: 1.0.0
• Node.js version: >=20.0.0
• Azure Cosmos DB SDK: @azure/cosmos ^4.2.1

Usage

Select Operation

1. Add the Azure Cosmos DB (SDK) node to your workflow
2. Select or create credentials with your Cosmos DB endpoint and access key
3. Choose Select operation
4. Enter:
   • Database Name: Your Cosmos DB database name
   • Container Name: Your container name
   • SQL Query: Your SQL query (e.g., SELECT * FROM c WHERE c.status = "active")

Excluding Vector Fields:

When working with vector embeddings, you can reduce payload size:

1. Expand the Options section
2. Enable Exclude Vector Fields
3. Optionally customize Vector Field Names (default: vector,embedding,embeddings)

This is useful when vector data isn't needed in downstream nodes.

Insert Operation

1. Add the Azure Cosmos DB (SDK) node to your workflow
2. Select or create credentials
3. Choose Insert operation
4. Enter:
   • Database Name: Your Cosmos DB database name
   • Container Name: Your container name
   • Document: JSON document to insert

Tips:

• The id field is required and must be unique
• Partition key must be included if your container uses one
• You can use expressions to dynamically generate documents from previous nodes

Resources

• n8n community nodes documentation
• Azure Cosmos DB documentation
• Cosmos DB SQL query reference
• Vector search in Cosmos DB
• Azure Cosmos DB SDK for JavaScript