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