Weaviate vector store

The WeaviateVector class provides vector search using Weaviate, an open-source vector database. Collections are created with vectorizer: none, so Mastra supplies the embeddings, and Mastra manages ids, distance metrics, and metadata filtering on your behalf.

Constructor options

id:

string

Unique identifier for this vector store instance.

httpHost?:

string

= localhost

Hostname of the Weaviate HTTP server.

httpPort?:

number

= 8080

Port of the Weaviate HTTP server.

httpSecure?:

boolean

= false

Whether to use a secure (TLS) connection to the HTTP server.

grpcHost?:

string

Hostname of the Weaviate gRPC server. Defaults to the HTTP host.

grpcPort?:

number

= 50051

Port of the Weaviate gRPC server.

grpcSecure?:

boolean

= false

Whether to use a secure (TLS) connection to the gRPC server.

apiKey?:

string

API key for authenticating with Weaviate (e.g. Weaviate Cloud).

headers?:

Record<string, string>

Additional headers to include in requests (e.g. third-party vectorizer API keys).

Methods

createIndex()

indexName:

string

Name of the index to create.

dimension:

number

Vector dimension (must match your embedding model).

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

Distance metric for similarity search. Mapped to Weaviate distances (cosine, l2-squared, dot).

upsert()

indexName:

string

Name of the index to upsert into.

vectors:

number[][]

Array of embedding vectors.

metadata?:

Record<string, any>[]

Metadata for each vector.

ids?:

string[]

Optional vector ids. Auto-generated if not provided. Arbitrary ids are preserved via a deterministic UUIDv5 mapping.

query()

indexName:

string

Name of the index to query.

queryVector:

number[]

Query vector to find similar vectors for.

topK?:

number

= 10

Number of results to return.

filter?:

Record<string, any>

Metadata filters (see below).

includeVector?:

boolean

= false

Whether to include the stored vector in the results.

The store also implements listIndexes(), describeIndex(), deleteIndex(), updateVector(), deleteVector(), and deleteVectors().

Basic usage

import { WeaviateVector } from '@mastra/weaviate'

const store = new WeaviateVector({ id: 'my-store' })

await store.createIndex({ indexName: 'my_index', dimension: 1536, metric: 'cosine' })

await store.upsert({
  indexName: 'my_index',
  vectors: [[0.1, 0.2 /* ... */]],
  metadata: [{ text: 'sample', category: 'docs' }],
})

const results = await store.query({
  indexName: 'my_index',
  queryVector: [0.1, 0.2 /* ... */],
  topK: 5,
  filter: { category: 'docs' },
})

Connecting to Weaviate Cloud

const store = new WeaviateVector({
  id: 'my-store',
  httpHost: 'my-cluster.weaviate.network',
  httpPort: 443,
  httpSecure: true,
  grpcHost: 'grpc-my-cluster.weaviate.network',
  grpcPort: 443,
  grpcSecure: true,
  apiKey: process.env.WEAVIATE_API_KEY,
})

Metadata filtering

Filters use a MongoDB-style syntax and are translated to Weaviate's native filter API:

• Comparison: $eq, $ne, $gt, $gte, $lt, $lte
• Array: $in, $nin, $all
• Element: $exists
• Logical: $and, $or, $not

const results = await store.query({
  indexName: 'my_index',
  queryVector: [0.1, 0.2 /* ... */],
  filter: {
    $and: [{ category: { $in: ['docs', 'guides'] } }, { views: { $gt: 100 } }],
  },
})

Notes and limitations

• Weaviate doesn't distinguish an explicitly stored null from an absent field, so null round-tripping isn't supported.
• $regex, $size, $elemMatch, $nor, and $contains aren't supported.
• Collection names are capitalized by Weaviate. The original index name is preserved in the collection description and returned by listIndexes() and describeIndex().

Related

• Metadata Filters