Embedding Similarity

Calculate similarity between text embeddings from any provider.

Overview

Computes similarity between two embedding vectors using cosine similarity, Euclidean distance, or dot product. Accepts embedding arrays as JSON strings or arrays from any embedding provider (OpenAI, Claude, Gemini, etc.). Pure local computation — no API calls. Each input item produces one similarity score stored in a configurable output field (default: “similarity”) along with the metric used and vector dimensions.

Category: AI
Tool Name: embedding_similarity
Version: 1

Appearance: Icon: brain | Color: #6366f1

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool does not require any credentials.

Parameters

Parameter	Type	Required	Default	Description
Embedding A	string	Yes	—	First embedding vector as a JSON array of numbers. Falls back to item.embeddingA or item.embedding if empty. Supports expressions.
Embedding B	string	Yes	—	Second embedding vector as a JSON array of numbers. Falls back to item.embeddingB if empty. Supports expressions.
Metric	options	No	cosine	The similarity metric to use for comparing the two embedding vectors.
				Options: cosine (-1 to 1; 1 means identical direction, 0 means orthogonal, -1 means opposite), euclidean (distance from 0 up; 0 means identical, higher values mean more different), dotProduct (higher values indicate more similarity for normalized vectors)
Options	collection	No	{}	Optional output settings.
— Response Field Name	string	No	similarity	The output field name where the similarity score will be stored.
Include Input	boolean	No	false	Whether to include the original input item fields in the output alongside the similarity result.
Max Concurrency	number	No	20	Maximum number of items to process concurrently. Higher values are safe since this is pure computation.

Output Data

One output item per input item. The score is written to the field named by Response Field Name (similarity by default), alongside metric and dimensions. With Include Input off — the default — those three fields are the entire output item; turn it on to merge the original item fields underneath. Binary data is forwarded either way.

{
  "similarity": 0.9412,
  "metric": "cosine",
  "dimensions": 1536
}

• metric echoes the metric that produced the score, so a downstream node can interpret the number without re-reading the node configuration.
• dimensions is the length of the compared vectors. Both vectors must have the same length; mismatched or empty vectors are an item error.
• The score range depends on the metric: cosine runs from -1 to 1 (higher is more similar), euclidean starts at 0 and grows as the vectors diverge (lower is more similar), and dotProduct is unbounded.

Reference the result downstream by expression, e.g. {{ $json.similarity }}.

Usage Examples

• Compare two OpenAI text embeddings using cosine similarity
• Calculate Euclidean distance between document embeddings
• Score semantic similarity between search query and result embeddings
• Rank items by dot product similarity to a reference embedding
• Find the most similar items in a batch by comparing embedding pairs

Example Configuration

Minimal configuration — compare two embeddings already on the item, using all defaults. embeddingA and embeddingB are empty, so the node falls back to item.embeddingA / item.embedding and item.embeddingB respectively, and the result is written to item.similarity:

{
  "type": "embedding_similarity",
  "parameters": {
    "embeddingA": "",
    "embeddingB": ""
  }
}

Explicit vectors with the cosine metric — provide embedding arrays directly as JSON strings:

{
  "type": "embedding_similarity",
  "parameters": {
    "embeddingA": "[0.12, -0.45, 0.78, 0.03]",
    "embeddingB": "[0.10, -0.42, 0.80, 0.01]",
    "metric": "cosine"
  }
}

Euclidean distance with input passthrough — keep the original fields in the output and write the score to a field named distance:

{
  "type": "embedding_similarity",
  "parameters": {
    "embeddingA": "",
    "embeddingB": "",
    "metric": "euclidean",
    "includeInput": true,
    "options": {
      "responseFieldName": "distance"
    }
  }
}

High-throughput dot product comparison — process a large batch of pre-normalized embedding pairs concurrently:

{
  "type": "embedding_similarity",
  "parameters": {
    "embeddingA": "",
    "embeddingB": "",
    "metric": "dotProduct",
    "includeInput": false,
    "maxConcurrency": 50,
    "options": {
      "responseFieldName": "dotScore"
    }
  }
}

Semantic search ranking — after generating an embedding for a query and a set of document embeddings, pipe each document item through this node alongside the query embedding to get a cosine score for ranking:

{
  "type": "embedding_similarity",
  "parameters": {
    "embeddingA": "{{ $json.queryEmbedding }}",
    "embeddingB": "{{ $json.docEmbedding }}",
    "metric": "cosine",
    "includeInput": true,
    "options": {
      "responseFieldName": "relevanceScore"
    }
  }
}

Deduplication threshold check — compute the Euclidean distance between two candidate texts’ embeddings. A score near 0 indicates near-duplicate content:

{
  "type": "embedding_similarity",
  "parameters": {
    "embeddingA": "",
    "embeddingB": "",
    "metric": "euclidean",
    "includeInput": true,
    "maxConcurrency": 20,
    "options": {
      "responseFieldName": "euclideanDistance"
    }
  }
}

Normalized vector dot product — when vectors from your embedding provider are already L2-normalized, dot product is mathematically equivalent to cosine similarity and can be faster to reason about in downstream filtering:

{
  "type": "embedding_similarity",
  "parameters": {
    "embeddingA": "",
    "embeddingB": "",
    "metric": "dotProduct",
    "includeInput": false,
    "options": {
      "responseFieldName": "similarity"
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Embedding Similarity calculates closeness between two embedding vectors using cosine similarity, Euclidean distance, or dot product through pure local computation with no API calls. Use it when you have pre-generated embeddings from any provider such as OpenAI, Claude, or Gemini and need to rank, deduplicate, or filter content semantically. Each input item produces a numeric similarity score in a configurable output field, the metric name used, and the detected vector dimensions.

Key Reminders

Rule	Detail
options fields are nested	responseFieldName lives inside "options": { }, never at the top level
Fallback chain for embeddingA	explicit value → item.embeddingA → item.embedding
Fallback chain for embeddingB	explicit value → item.embeddingB
Metric output ranges differ	cosine → [-1, 1]; euclidean → [0, ∞); dotProduct → unbounded
maxConcurrency is safe to raise	No external I/O — CPU-only computation