Metadata-Version: 2.4
Name: langchain-clickhouse
Version: 0.1.0
Summary: Langchain vector store for ClickHouse.
Project-URL: Homepage, https://github.com/amany9000/langchain-vectorstore
Project-URL: Repository, https://github.com/amany9000/langchain-vectorstore
Project-URL: Issues, https://github.com/amany9000/langchain-vectorstore/issues
License: MIT
Requires-Python: <4.0.0,>=3.10.0
Requires-Dist: clickhouse-connect<2.0.0,>=1.0.0
Requires-Dist: langchain-core<2.0.0,>=1.2.0
Description-Content-Type: text/markdown

# ClickHouse

Langchain Vector store for [ClickHouse](https://clickhouse.com/).

## Install

```bash
pip install langchain-clickhouse
```

or

```bash
uv add langchain-clickhouse
```

Requires a running ClickHouse server (default: `localhost:8123`).

## API Reference

### `__init__`

```python
def __init__(
    self,
    embedding_function: Embeddings | None = None,
    host: str = "localhost",
    port: int = 8123,
    database: str = "default",
    username: str = "default",
    password: str = "",
    table_name: str = "langchain_documents",
    **kwargs,
)
```

| Parameter | Type | Description |
|---|---|---|
| `embedding_function` | `Embeddings \| None` | Embedding function used to embed queries and texts (e.g., `FastEmbedEmbeddings`). |
| `host` | `str` | ClickHouse server host. Default `"localhost"`. |
| `port` | `int` | ClickHouse HTTP interface port. Default `8123`. |
| `database` | `str` | Database name. Default `"default"`. |
| `username` | `str` | ClickHouse username. Default `"default"`. |
| `password` | `str` | ClickHouse password. Default `""`. |
| `table_name` | `str` | Table name for storing documents. Default `"langchain_documents"`. Created as a `MergeTree` if it doesn't exist. |

---

### `from_texts`

```python
def from_texts(
    cls,
    texts: list[str],
    embedding: Embeddings | None = None,
    metadatas: list[dict] | None = None,
    ids: list[str] | None = None,
    host: str | None = None,
    port: int | None = None,
    database: str | None = None,
    username: str | None = None,
    password: str | None = None,
    table_name: str | None = None,
    **kwargs,
) -> ClickHouse
```

| Parameter | Type | Description |
|---|---|---|
| `texts` | `list[str]` | Texts to index. |
| `embedding` | `Embeddings \| None` | Embedding function. |
| `metadatas` | `list[dict] \| None` | Optional metadata dicts, one per text. |
| `ids` | `list[str] \| None` | Optional document IDs. Auto-generated via SHA-256 if not provided. |
| `host` | `str \| None` | ClickHouse host (default: `CLICKHOUSE_HOST` env var or `"localhost"`). |
| `port` | `int \| None` | ClickHouse HTTP port (default: `CLICKHOUSE_PORT` env var or `8123`). |
| `database` | `str \| None` | Database name (default: `CLICKHOUSE_DATABASE` env var or `"default"`). |
| `username` | `str \| None` | ClickHouse username (default: `CLICKHOUSE_USERNAME` env var or `"default"`). |
| `password` | `str \| None` | ClickHouse password (default: `CLICKHOUSE_PASSWORD` env var or `""`). |
| `table_name` | `str \| None` | Table name. Default `"langchain_documents"`. |

**Returns:** `ClickHouse` — a new vector store with the texts indexed.

---

### `add_texts`

```python
def add_texts(
    self,
    texts: list[str],
    metadatas: list[dict] | None = None,
    ids: list[str] | None = None,
    **kwargs,
) -> list[str]
```

| Parameter | Type | Description |
|---|---|---|
| `texts` | `list[str]` | Texts to add. |
| `metadatas` | `list[dict] \| None` | Optional metadata dicts, one per text. Defaults to `{}`. |
| `ids` | `list[str] \| None` | Optional document IDs. Auto-generated via SHA-256 if not provided. |

**Returns:** `list[str]` — the IDs of the added texts.

---

### `delete`

```python
def delete(
    self,
    ids: list[str] | None = None,
    **kwargs,
) -> bool | None
```

| Parameter | Type | Description |
|---|---|---|
| `ids` | `list[str] \| None` | List of document IDs to remove. |

**Returns:** `bool` — `True` if deletion succeeded. Raises `ValueError` if `ids` is `None`.

---

### `similarity_search`

```python
def similarity_search(
    self,
    query: str,
    k: int = 4,
    **kwargs,
) -> list[Document]
```

| Parameter | Type | Description |
|---|---|---|
| `query` | `str` | Query text. |
| `k` | `int` | Number of documents to return. Default `4`. |

**Returns:** `list[Document]` — documents most similar to the query, ordered by cosine similarity (descending).

---

### `similarity_search_with_score`

```python
def similarity_search_with_score(
    self,
    query: str,
    k: int = 4,
    **kwargs,
) -> list[tuple[Document, float]]
```

| Parameter | Type | Description |
|---|---|---|
| `query` | `str` | Query text. |
| `k` | `int` | Number of documents to return. Default `4`. |

**Returns:** `list[tuple[Document, float]]` — tuples of `(Document, cosine_similarity)`. Score range `[-1, 1]`. **Higher = more similar.** Uses ClickHouse's native `1 - cosineDistance()` for server-side ranking.