<!-- BusyBot node reference — https://busybot.net/tools/embedding-similarity/ -->

> Node: Embedding Similarity (`embedding_similarity`) · Action · v1
> Category: AI · Credentials: none
> Updated: 2026-08-16

# 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.

```json
{
  "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`:

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

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

```json
{
  "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`:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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 |