Similar Items
Find documents similar to a given document using embedding cosine similarity. Uses the same BGE-small embeddings computed at index time — no additional configuration required beyond enabling semantic search.
Find documents similar to a source document by embedding cosine similarity.
Request body
| Parameter | Type | Description |
|---|---|---|
| document_id required | string | Primary key of the source document to find similar items for. |
| limit optional | number | Maximum number of similar documents to return. Max 200. Default: 10 |
| offset optional | number | Number of results to skip for pagination. Default: 0 |
| filter optional | string | Filter expression to scope candidates. Same syntax as search filters. |
| attributes_to_retrieve optional | string[] | Restrict which fields are returned in each hit. Returns all fields if omitted. |
| show_ranking_score optional | boolean | Include _similarityScore (cosine similarity) on each hit. Default: false |
Example
curl -X POST https://search.example.com/v1/indices/products/similar \ -H "Authorization: Bearer sk_search_live_..." \ -H "Content-Type: application/json" \ -d '{ "document_id": "prod_abc123", "limit": 5, "show_ranking_score": true }'
SDK
const results = await idx.similar('prod_abc123', { limit: 5, show_ranking_score: true, });
Response 200 OK
{
"hits": [
{
"id": "prod_xyz789",
"title": "14K Gold Curved Barbell 8mm",
"price": 24.99,
"_similarityScore": 0.9342
},
{
"id": "prod_def456",
"title": "Rose Gold Curved Barbell 6mm",
"price": 22.50,
"_similarityScore": 0.9187
}
],
"total_hits": 2,
"processing_time_ms": 12,
"limit": 5,
"offset": 0,
"document_id": "prod_abc123"
}Response fields
| Parameter | Type | Description |
|---|---|---|
| hits required | object[] | Array of similar documents, sorted by cosine similarity descending. |
| total_hits required | number | Total number of similar documents found (before limit/offset). |
| processing_time_ms required | number | Server-side processing time in milliseconds. |
| limit required | number | The limit that was applied. |
| offset required | number | The offset that was applied. |
| document_id required | string | The source document ID that was queried. |
With filters
Use the filter parameter to scope candidates. For example, find similar
products only within the same category:
const results = await idx.similar('prod_abc123', { limit: 10, filter: 'category = "earrings"', show_ranking_score: true, });
Prerequisites
Similar items requires semantic search to be enabled on the index. The endpoint uses the same BGE-small-en-v1.5 embeddings that are computed automatically when documents are indexed with semantic search enabled.
// Enable semantic search in index settings await idx.updateSettings({ semantic: { enabled: true }, });
400 error.
Enable it via settings, then re-index your documents so embeddings are computed.How it works
When you call the similar endpoint, Skirre:
- Looks up the source document by primary key and extracts its embedding vector.
- Scans candidate documents (respecting any filter you provide).
- Computes cosine similarity between the source embedding and each candidate.
- Excludes the source document from results.
- Returns candidates sorted by similarity score, with limit/offset applied.
The source document is always excluded from the results. If the source document has no
embedding (e.g. it was indexed before semantic search was enabled), the endpoint returns a 400 error.