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

# Weaviate

> Auto-trace Weaviate near_vector query and data insert calls with zespan.autopatch() — retrieval spans and RAG context capture with no code changes to your Weaviate v4/v3 client calls.

<Note>
  Available for: **Python** and **TypeScript**.
</Note>

Calling Weaviate directly (no LangChain/LlamaIndex retriever abstraction in between) previously got zero automatic tracing — only the manual `recordRetrieval`/`record_retrieval` helper. Zespan now patches the v4 collections client (Python) / `weaviate-client` v3 (Node) so every `near_vector` query and `data.insert()` call is captured automatically, the same way LLM provider calls already are.

<Note>
  Patched automatically as part of `zespan.autopatch()`, which both SDKs run on `init()` unless you pass `autopatch: false` (`autopatch=False` in Python). There's no separate opt-in call for vector-DB tracing.
</Note>

## What gets traced

* **Reads** — `collection.query.near_vector()` (Python) / `collection.query.nearVector()` (Node) emits a `retriever` span. This is the v4-style, method-based collections API (gRPC transport) — the older GraphQL builder chain (`.withNearVector().withLimit().do()`) is not patched
* **Writes** — `collection.data.insert()` (single object, REST transport) emits an `embedding` span. Batch insert methods are not patched

<Tabs>
  <Tab title="Python">
    ### Installation

    ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    pip install zespan weaviate-client
    ```

    ### Usage

    ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    import zespan

    zespan.init(api_key="zsp_your_api_key_here")  # patches Weaviate automatically

    import weaviate

    client = weaviate.connect_to_local()
    collection = client.collections.get("Docs")

    # Traced automatically -- emits an "embedding" span
    collection.data.insert(properties={"text": "chunk text", "source": "handbook.pdf"})

    # Traced automatically -- emits a "retriever" span
    results = collection.query.near_vector(near_vector=query_embedding, limit=5)
    ```

    <Note>
      Only the **sync** Weaviate client is auto-traced. `WeaviateAsyncClient` (the async client) is not yet covered — if you're on the async client, use the manual [`record_retrieval`/`record_vector_search`](/sdk/manual-spans) helpers instead.
    </Note>
  </Tab>

  <Tab title="TypeScript">
    ### Installation

    ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    npm install @zespan/sdk weaviate-client
    ```

    ### Usage

    ```typescript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    import { zespan } from "@zespan/sdk";

    zespan.init({ apiKey: process.env.ZESPAN_API_KEY! }); // patches Weaviate automatically

    import weaviate from "weaviate-client";

    const client = await weaviate.connectToLocal();
    const collection = client.collections.get("Docs");

    // Traced automatically -- emits an "embedding" span
    await collection.data.insert({ text: "chunk text", source: "handbook.pdf" });

    // Traced automatically -- emits a "retriever" span
    const results = await collection.query.nearVector(queryEmbedding, { limit: 5 });
    ```

    <Note>
      `weaviate-client`'s collection objects come from **plain factory functions**, not a class with a shared `prototype` — patching a prototype once (the pattern every other Node wrapper uses) would do nothing here. Zespan instead patches `client.collections.get()`/`.use()`/`.create()` (and the `connectToLocal`/`connectToWeaviateCloud`/`connectToCustom` entry points that produce the client) so that each returned collection's own `query.nearVector`/`data.insert` are patched directly. This is transparent to your code — every collection you obtain through `get()`, `use()`, or `create()` is traced.
    </Note>
  </Tab>
</Tabs>

## What gets captured

### Read span (`near_vector`) — `span_kind: "retriever"`, `operation: "vector_search"`

| Field                   | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`              | `"weaviate"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `latency_ms`            | Time spent in the real `near_vector`/`nearVector` call                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `status`                | `"success"` or `"error"` (with `error_message`, truncated to 500 characters)                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `rag_context_count`     | Number of objects returned                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `metadata.rag_contexts` | One entry per object: `{ content, document_id, score, source }` — `content` comes from the object's properties (its text field), `document_id` from the object's UUID, `score` from `metadata.score`, falling back to `certainty` then `distance` depending on which the query requested. Same shape [`recordRetrieval`/`record_retrieval`](/sdk/manual-spans#recording-retrieved-documents) produces, so the trace-detail **Retrieval** panel and the [RAG evaluators](/dashboard/evaluations#evaluating-rag-pipelines) work with no extra setup |
| `metadata.top_k`        | Requested result count, read from the call's `limit` option — only present when you actually pass one, since `limit` is optional in Weaviate's client. Not gated by `storePrompts` when present, since it's a count, not query content. Only observable nested under `metadata` — the ingest pipeline persists the `metadata` object verbatim but drops other unrecognized top-level fields                                                                                                                                                       |
| `metadata.filter`       | The query's `filters` option, redacted and stringified — only present when `storePrompts`/`store_prompts` is `true` (its default). Filter values commonly carry user IDs, emails, or other PII, so unlike `top_k` this is dropped entirely, not just redacted, when `storePrompts` is off. (Same `metadata`-only visibility as `top_k` above.)                                                                                                                                                                                                    |

`content` follows your `storePrompts`/`store_prompts` setting and the same redaction rules as prompt text — set `storePrompts: false` and object text is dropped while `document_id`/`source`/`score` are still kept.

### Write span (`data.insert()`) — `span_kind: "embedding"`, `operation: "vector_upsert"`

| Field                   | Details                                                                                                                                                                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`              | `"weaviate"`                                                                                                                                                                                                                              |
| `metadata.vector_count` | Always `1` — only the single-object `insert()` is patched, not a batch insert method. Only observable nested under `metadata` — the ingest pipeline persists the `metadata` object verbatim but drops other unrecognized top-level fields |
| `latency_ms`            | Time spent in the real `insert()` call                                                                                                                                                                                                    |
| `input_tokens`          | Always `0` — the wrapper doesn't generate embeddings, it only records that an object was written                                                                                                                                          |
| `status`                | `"success"` or `"error"` (with `error_message`)                                                                                                                                                                                           |

<Warning>
  **Linking a Weaviate query to a following LLM call.** Trace context (`trace_id`) is picked up from whatever `with_zespan_context()`/`withZespanContext()` scope is active when `near_vector`/`insert()` runs — the same rule every other Zespan wrapper follows. If your Weaviate call and your LLM call are two independent, unwrapped top-level calls, they land on **two different traces**, and RAG evaluators/the Retrieval panel won't see the connection between them. Wrap both in the same `with_zespan_context()`/`withZespanContext()` block, exactly like the [complete RAG pipeline example](/sdk/manual-spans#complete-rag-pipeline-example) in Manual spans.
</Warning>

## Next steps

* [Manual spans](/sdk/manual-spans) — the `record_vector_search()`/`recordVectorSearch()` helper for pgvector, and the full `with_zespan_context()`/`withZespanContext()` trace-linking pattern
* [Evaluating RAG pipelines](/dashboard/evaluations#evaluating-rag-pipelines) — score retrieval quality once `rag_contexts` is on the trace
* [Pinecone](/sdk/integrations/pinecone), [Chroma](/sdk/integrations/chroma), [Qdrant](/sdk/integrations/qdrant) — the other auto-traced vector DBs