n8n-nodes-qdrant-hybrid

An n8n community node for Qdrant 1.15.x collections that use named dense vectors, client-side BM25 sparse vectors, and hybrid Reciprocal Rank Fusion (RRF).

Compatibility

• Self-hosted n8n with Node.js 20.15 or newer
• Qdrant 1.15.x; integration tests pin qdrant/qdrant:v1.15.2
• Dense embeddings supplied as arrays, including Gemini embeddings with 3072 dimensions

The node uses Qdrant's REST API directly and does not depend on a Qdrant client library.

Installation

From the repository root:

npm install
npm run build --workspace n8n-nodes-qdrant-hybrid

For a packed local installation:

cd apps/n8n-nodes-qdrant-hybrid
npm pack

Install the generated package in the custom-node directory of your self-hosted n8n instance and restart n8n.

Credentials

Select n8n's existing built-in Qdrant API credential. This package does not register a duplicate credential type.

• Qdrant URL: for example http://qdrant:6333
• API key: sent in the api-key header; leave empty only for an unsecured local server

The built-in credential test calls GET /collections. The n8n installation must include the built-in AI/LangChain Qdrant integration that provides the global qdrantApi credential type.

Because n8n's community-package security rules do not permit cross-package credential reuse in cloud-compatible strict mode, this package targets self-hosted n8n and declares strict: false.

Local Qdrant

docker compose -f test/integration/docker-compose.yml up -d

This starts Qdrant 1.15.2 on port 6333.

Node connections

The node follows n8n's default vector-store pattern:

• Embedding is a required ai_embedding connection in every mode.
• Document is a required ai_document connection in Insert Documents mode.
• A normal main input triggers execution and a normal main output returns insertion status or search results.

Connect an Embeddings node such as Google Gemini Embeddings. In Insert Documents mode, also connect Default Data Loader or another compatible Data Loader.

Modes

Insert Documents

The connected Data Loader supplies document content and metadata. The connected Embeddings model generates dense vectors; users do not enter dense arrays or dimensions manually.

If the collection does not exist, the node embeds the documents first and creates a named hybrid collection using the actual embedding dimension:

{
  "vectors": {
    "dense": {
      "size": 3072,
      "distance": "Cosine"
    }
  },
  "sparse_vectors": {
    "bm25": {
      "modifier": "idf"
    }
  }
}

For existing collections, the node detects named versus legacy unnamed dense vectors and validates the model output against the collection dimension. A Data Loader metadata field named id or pointId is used as the Qdrant point ID; otherwise the node generates a numeric ID.

Retrieve Documents

The node passes Query to the connected Embeddings model and performs dense search. No vector-array field is shown. For legacy unnamed collections, the request automatically omits using.

Hybrid Retrieve

The node embeds Query for dense retrieval and generates its BM25 sparse query vector locally. Dense and sparse prefetch results are fused with RRF.

Retrieve Documents (As Tool for AI Agent)

This mode replaces the main output with an ai_tool output that connects to an AI Agent's Tool input. Configure:

• Tool Name: the function name exposed to the agent
• Tool Description: guidance describing when the agent should search Qdrant
• Tool Retrieval Strategy: dense or hybrid RRF

The agent calls the tool with { "query": "..." }. The tool embeds that query using the connected Embeddings model and returns the matching Qdrant documents as JSON.

Hybrid requests use:

POST /collections/{collection_name}/points/query

with this shape:

{
  "prefetch": [
    {
      "query": [0.012, -0.035],
      "using": "dense",
      "limit": 20
    },
    {
      "query": {
        "indices": [9462544, 12815137, 178996241],
        "values": [1, 1, 1]
      },
      "using": "bm25",
      "limit": 20
    }
  ],
  "query": {
    "fusion": "rrf"
  },
  "limit": 10,
  "with_payload": true
}

Gemini embedding setup

Connect Google Gemini Embeddings to the node's Embedding socket. Configure Gemini for 3072 dimensions if that is the dimension used by an existing collection. New collection dimensions are inferred automatically from the first generated embedding.

BM25

Insert Documents and Hybrid Retrieve generate sparse vectors inside the node and send standard Qdrant sparse-vector data:

{
  "indices": [9462544, 12815137],
  "values": [1.5714, 0.9981]
}

Document vectors use BM25 term-frequency normalization. Query vectors use the same token hashing with unit weights, while Qdrant's sparse-vector idf modifier supplies collection-level inverse document frequency. This works with the stock self-hosted Qdrant image and does not require Qdrant Inference.

Filters

Retrieval options accept a raw Qdrant filter object. It supports must, must_not, should, match-value, match-any, and range conditions supported by Qdrant 1.15.

{
  "must": [
    {
      "key": "category",
      "match": {
        "value": "policy"
      }
    }
  ]
}

Returned data

Query points are mapped to n8n items containing id, score, content, metadata, and payload. Enable vector inclusion when the raw vectors are needed.

Examples

Import workflows from examples/workflows/:

• document-ingestion.json
• hybrid-search.json
• dense-compatibility.json
• agent-tool.json

The workflows use placeholder collection names and contain no credentials.

Development and tests

npm run build
npm run typecheck
npm run lint
npm test

Run the Docker integration test:

docker compose -f test/integration/docker-compose.yml up -d
set QDRANT_URL=http://localhost:6333
node --test test/integration/qdrant.integration.test.cjs

In PowerShell, set the environment variable with $env:QDRANT_URL = "http://localhost:6333".

Migration from n8n's Qdrant Vector Store

1. Connect the same Embeddings model previously used by the default Qdrant node.
2. Connect a Data Loader in Insert Documents mode.
3. Enter the existing collection name; named and legacy unnamed dense schemas are detected automatically.
4. Use Retrieve Documents for dense compatibility or Hybrid Retrieve for dense plus BM25 RRF.

Existing points are not renamed automatically. Migrating an unnamed vector to a named vector requires re-upserting or transforming those points.

Troubleshooting

Vector dimension error: expected dim: 3072, got 0

The connected Embeddings model returned an empty vector. Check its credentials, model, and output dimensionality. This node rejects the request before it reaches Qdrant.

Not existing vector name

Named collections store vectors under names such as dense; legacy collections use one unnamed vector. The node detects the collection shape automatically. If a named collection uses a non-default name, set Dense Vector Name in Options.

Existing collection returns a missing sparse-vector error

The collection must contain the sparse vector configured under Sparse Vector Name with the idf modifier. New collections are configured automatically. Existing dense-only collections need the sparse vector added or must be recreated before hybrid retrieval.

Invalid API key or timeout

Test the credential. Confirm the api-key, container hostname, port, TLS settings, and timeout.

Known limitations

• This is a self-hosted-only community node. Reusing n8n's built-in qdrantApi credential and providing a LangChain AI tool are not allowed by n8n Cloud's strict community-node rules.
• Structured filter builders are not yet exposed; filters use validated raw JSON.
• Docker integration tests require a local Docker engine and are not run by the default unit-test command.