> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Weaviate (vector search)

Connect Weaviate, an external vector database, to search your Weaviate collections
from Runtype. Agents search Weaviate with the **Semantic Search** built-in tool.
Flows search Weaviate with the **Vector Search** step and write to it with the
**Store Vector** step. Weaviate is a provider option for these tools, not a separate
search tool.

## Choose a vector provider

Choose a provider based on where you store the vectors:

* **Choose Platform Records (pgvector)** when you store searchable data in Runtype Records.
* **Choose Weaviate** when you store searchable data in a Weaviate collection.
* **Choose Cloudflare Vectorize** when you store searchable data in a Vectorize index.

## Before you begin

Make sure that you have the following:

* A Weaviate Cloud cluster or a self-hosted Weaviate instance, with its URL and API key.
  Runtype must be able to reach the instance over the public internet.
* A Weaviate collection. Runtype embeds search queries with the OpenAI
  `text-embedding-3-small` model by default. Index your collection with the same model,
  or searches return no matches or fail.
* Access to OpenAI for query embeddings. Runtype uses the platform OpenAI key unless
  you add your own key in **Settings > Models**. For details, see
  [Platform keys vs. BYOK](/user-guide/getting-started/platform-keys-vs-byok).

## Set up Weaviate

To connect a Weaviate instance to Runtype, follow these steps:

1. Copy the cluster URL and API key from Weaviate.
2. In Runtype, click **Settings > Integrations**.
3. In **Vector Databases**, click **Add Configuration** for **Weaviate**.
4. In **Configuration Name**, enter a name for the connection.
5. In **Weaviate Instance URL**, enter the cluster URL. For a self-hosted instance,
   include the protocol, for example `https://weaviate.example.com`.
6. In **API Key**, enter the Weaviate API key.
7. Optional: To make this connection the default, turn on **Set as default Weaviate
   configuration**. Your first Weaviate configuration becomes the default automatically.
8. Optional: To send extra headers with every request to Weaviate, on the **Advanced**
   tab, enter them in **Custom Headers (JSON)**.
9. On the **Test Connection** tab, click **Test Connection**. Confirm that the
   connection succeeds.
10. Click **Save Configuration**.

Searches always use your default Weaviate configuration. To search a different
Weaviate instance, set its configuration as the default.

## Configure Semantic Search

To connect **Semantic Search** to a Weaviate collection, follow these steps:

1. Add the **Semantic Search** tool to an Agent.
2. In **Display name**, enter the name that the model sees for this search instance.
3. In **Provider**, select **Weaviate**.
4. In **Class name**, enter the Weaviate collection name. The name is case-sensitive.
5. In **Similarity threshold**, enter a value from `0` to `1`. Lower values return
   more results. The default is `0.3`.

In a Flow Prompt step, the same field is labeled **Collection Name**.

When the Agent calls **Semantic Search**, it can set `limit` from `1` to `20` to
control the maximum number of results. The default is `5`.

You can add more than one **Semantic Search** instance to the same Agent. Point each
instance to a different Weaviate collection.

With the Weaviate provider, **Semantic Search** returns each match's ID and similarity
scores, but not the document text. To retrieve document content from Weaviate, use
the **Vector Search** step in a Flow and set **Return Properties**.

## Search Weaviate in a Flow

To search a Weaviate collection from a Flow, follow these steps:

1. Add a **Vector Search** step to the Flow.
2. In **Search for**, enter the query text or a variable, for example `{{userMessage}}`.
3. In the provider list, select **Weaviate**.
4. In **collection**, enter the collection name. The name is case-sensitive.
5. Set how many results to return and the minimum similarity. The defaults are `5`
   results and a similarity of `0.7`.
6. In the embedding model list, select the model that you used to index the
   collection.
7. Expand **Search Mode**. In **Return Properties**, enter the collection properties
   to return, for example `title, content`.

List every property that you need in the next step. If you leave **Return Properties**
empty, results don't include your document text.

The step also shows a **connection** list. When you choose a connection there,
**collection** lists that connection's collections. The search itself ignores the
selection and always uses your default Weaviate configuration.

The step saves its results to its output variable. The default name is
`search_results`. The variable holds an array of matches, and each match has the
following shape:

**`One Weaviate search result`**

```json title="One Weaviate search result"
{
  "id": "4f1c2a9e-8d3b-4c55-9a1e-2b7d6f0c1a23",
  "properties": {
    "title": "Refund policy",
    "content": "Customers can request a refund within 30 days of purchase.",
    "_additional": {
      "id": "4f1c2a9e-8d3b-4c55-9a1e-2b7d6f0c1a23",
      "certainty": 0.86,
      "distance": 0.28
    }
  },
  "rank": 1,
  "score": 0.86,
  "distance": 0.28,
  "certainty": 0.86,
  "source": {
    "provider": "weaviate",
    "className": "Documents",
    "weaviateId": "4f1c2a9e-8d3b-4c55-9a1e-2b7d6f0c1a23"
  },
  "weaviateMetadata": {
    "certainty": 0.86,
    "distance": 0.28,
    "weaviateId": "4f1c2a9e-8d3b-4c55-9a1e-2b7d6f0c1a23",
    "className": "Documents"
  }
}
```

The returned properties are under `properties`, not `metadata`. The `score` value is
the match's certainty. To pass the matches
to the step that generates the answer, reference `{{search_results}}` in its prompt.

If you set `metadataFilters` on a **Vector Search** step through the API or an SDK,
Weaviate applies only the first entry.

### Use hybrid search

Use hybrid search when your queries include exact identifiers, error codes, or other
terms that vector similarity might miss. To use hybrid search, expand **Search Mode**
and turn on **Enable hybrid search (vector + keyword)**. In **Alpha**, enter a value
from `0.1` to `1`. Lower values weight keyword search, and higher values weight vector
search. The default is `0.5`. The dashboard replaces an **Alpha** of `0` with `0.5`.

Hybrid results have no similarity score, so any similarity value greater than `0` removes
every hybrid result. The dashboard doesn't accept a similarity of `0`, so a hybrid
search that you configure in the dashboard returns no results. To use hybrid search,
save the step through the API with `threshold` set to `0`.

## Index content into Weaviate from a Flow

To write vectors into a Weaviate collection from a Flow, follow these steps:

1. Add a **Store Vector** step after the step that generates the embeddings.
2. In **Store vectors from**, enter the variable that holds the embeddings.
3. In the destination list, select **Weaviate**.
4. In the connection list, select the Weaviate connection.
5. In **collection**, enter the collection name.
6. Expand **Metadata** and add the fields to store with each vector, for example
   `content` set to the source text.

Weaviate assigns each object's ID. The step ignores **with ID template** for Weaviate.
The **Metadata** fields become the object's properties in Weaviate. To get them back
in a search, list the same names in **Return Properties**. To search the collection
with **Semantic Search**, generate the embeddings with `text-embedding-3-small`.

## Verify the setup

To confirm that the connection works, run the Flow or Agent with a query that
matches a document you know is in the collection. The results include that
document's ID, and in a **Vector Search** step, the properties that you listed.

## Troubleshoot Weaviate search

The following table lists common errors and how to fix them:

| Error or symptom                                                                     | Fix                                                                                                                                                 |
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Weaviate collection 'X' does not exist`                                             | Check the collection name. It is case-sensitive and must match exactly.                                                                             |
| `Failed to connect to Weaviate instance` or `Unable to connect to Weaviate instance` | Check the URL and API key in **Settings > Integrations**, then click **Test Connection**.                                                           |
| `Weaviate configuration not found`                                                   | Add a Weaviate configuration, or set an existing one as the default.                                                                                |
| `OpenAI API key not configured` (**Semantic Search**)                                | Add an OpenAI key in **Settings > Models**, or check that your organization can use platform keys.                                                  |
| Searches return no matches                                                           | Check that the query embedding model matches the model used to index the collection. Then lower the similarity value.                               |
| Hybrid search returns no matches                                                     | Hybrid results have no similarity score, so a similarity value filters them out. Set `threshold` to `0` through the API, or turn off hybrid search. |

## Next steps

Use these pages to continue:

* [Built-in tools](/user-guide/tools/built-in-tools): configure **Semantic Search** and other built-in tools
* [Flow step types overview](/user-guide/flows/flow-step-types-overview): add **Vector Search** and **Store Vector** steps to a Flow
* [Building retrieval that works](/user-guide/records/building-retrieval-that-works): choose retrieval strategies and tune hybrid search
* [Integrations (PostHog, Weaviate, Daytona)](/user-guide/settings/integrations-posthog-weaviate-daytona): edit or delete Weaviate connections
* [API reference](/api-reference): manage Weaviate connections with the `/v1/integrations/weaviate` endpoints
* [Cloudflare (Vectorize and Browser Rendering)](/user-guide/integrations/cloudflare-integration): connect Cloudflare Vectorize and Browser Rendering
* [Using vector steps](/user-guide/flows/using-vector-steps): generate embeddings, store vectors, and run vector search in a Flow

## BYOK-only organizations

With **Require your own model keys** enabled, Weaviate hybrid search and `text2vec-*`
server-side vectorization are unavailable. Disable hybrid search and select an explicit
embedding model backed by a selected organization connection. Setting `threshold` to `0`
does not make server-side vectorization eligible.