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.

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:

{
  "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:

Next steps

Use these pages to continue:

• Built-in tools: configure Semantic Search and other built-in tools
• Flow step types overview: add Vector Search and Store Vector steps to a Flow
• Building retrieval that works: choose retrieval strategies and tune hybrid search
• Integrations (PostHog, Weaviate, Daytona): edit or delete Weaviate connections
• API reference: manage Weaviate connections with the /v1/integrations/weaviate endpoints
• Cloudflare (Vectorize and Browser Rendering): connect Cloudflare Vectorize and Browser Rendering
• 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.