> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# similarity_search_by_vector

Returns documents most similar to an embedding vector.

<Tabs>
  <Tab title="Embedded">
    ```python theme={null}
    similarity_search_by_vector(
        embedding: Union[List[float], np.ndarray],
        k: int = 4,
        filter: Optional[Dict[str, Any]] = None,
        **kwargs
    ) -> List[Document]
    ```

    ### Parameters

    | Parameter | Type | Description |
    | - | - | - |
    | `embedding` | `Union[List[float], np.ndarray]` | Embedding vector to search with |
    | `k` | `int` | Number of documents to return (default: 4) |
    | `filter` | `Optional[Dict[str, Any]]` | *(Optional)* Metadata filters to apply |
    | `**kwargs` | `Any` | Additional keyword arguments (currently unused) |

    ### Returns

    `List[Document]`: List of most similar Document objects

    ### Example Usage

    ```python theme={null}
    # Get embedding for a query
    query_embedding = store.get_embeddings("data science concepts")

    # Search using the embedding
    results = store.similarity_search_by_vector(query_embedding, k=5)

    # Search with custom embedding
    custom_embedding = np.random.rand(384)  # Example 384-dim embedding
    results = store.similarity_search_by_vector(custom_embedding, k=3)
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    similarity_search_by_vector(
        embedding: Union[List[float], np.ndarray],
        k: Optional[int] = None,
        filter: Optional[Dict[str, Any]] = None,
        **kwargs
    ) -> List[Document]
    ```

    ### Parameters

    | Parameter | Type | Description |
    | - | - | - |
    | `embedding` | `Union[List[float], np.ndarray]` | Embedding vector to search with |
    | `k` | `Optional[int]` | *(Optional)* Number of documents to return (default: `None`, uses server default) |
    | `filter` | `Optional[Dict[str, Any]]` | *(Optional)* Metadata filters to apply |
    | `**kwargs` | `Any` | Additional keyword arguments |

    ### Returns

    `List[Document]`: List of most similar Document objects

    ### Example Usage

    ```python theme={null}
    query_embedding = store.get_embeddings("data science concepts")
    results = store.similarity_search_by_vector(query_embedding, k=5)
    ```
  </Tab>

  <Tab title="JS/TS">
    ```typescript theme={null}
    similaritySearchVectorWithScore(
        query: number[],
        k: number,
        filter?: Record<string, any>
    ): Promise<[Document, number][]>
    ```

    ### Parameters

    | Parameter | Type | Description |
    | - | - | - |
    | `query` | `number[]` | Embedding vector to search with |
    | `k` | `number` | Number of documents to return |
    | `filter` | `Record<string, any>` | *(Optional)* Metadata filters to apply |

    ### Returns

    `Promise<[Document, number][]>`: Array of \[Document, score] tuples

    <Warning>The JS/TS method name is `similaritySearchVectorWithScore` (not `similaritySearchByVector`), and it returns score tuples unlike the Python SDKs which return documents only.</Warning>

    ### Example Usage

    ```typescript theme={null}
    const queryEmbedding = [0.1, 0.2, 0.3, /* ... */];
    const results = await store.similaritySearchVectorWithScore(queryEmbedding, 5);

    for (const [doc, score] of results) {
        console.log(`Score: ${score.toFixed(4)} - ${doc.pageContent.slice(0, 100)}...`);
    }
    ```
  </Tab>
</Tabs>

### Async

<Accordion title="Python async variants">
  The Embedded and Python SDK provide async versions of this method prefixed with `a`:

  ```python theme={null}
  # asimilarity_search_by_vector — async variant
  docs = await store.asimilarity_search_by_vector(embedding, k=5)
  ```
</Accordion>

<Note>
  JS/TS methods are natively async — all signatures above already return `Promise<...>`. No separate async variant is needed.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.