Turbopuffer vector store

The TurbopufferVector class provides vector search using Turbopuffer, a high-performance vector database optimized for RAG applications. Turbopuffer offers fast vector similarity search with advanced filtering capabilities and efficient storage management.

Constructor options

apiKey:

string

The API key to authenticate with Turbopuffer

baseUrl?:

string

= https://api.turbopuffer.com

The base URL for the Turbopuffer API

connectTimeout?:

number

= 10000

The timeout to establish a connection, in ms. Only applicable in Node and Deno.

connectionIdleTimeout?:

number

= 60000

The socket idle timeout, in ms. Only applicable in Node and Deno.

warmConnections?:

number

= 0

The number of connections to open initially when creating a new client.

compression?:

boolean

= true

Whether to compress requests and accept compressed responses.

consistency?:

'strong' | 'eventual'

= strong

The default consistency level for queries. Can be overridden per query. "strong" guarantees queries see all data written before the query started, at the cost of higher latency. "eventual" offers lower latency, but recently written data may not be visible yet.

schemaConfigForIndex?:

function

A callback function that takes an index name and returns a config object for that index. You can define explicit schemas per index.

Methods

createIndex()

Turbopuffer has no explicit create-index operation. createIndex() validates the arguments and records the dimension and metric locally; the namespace is created in Turbopuffer on the first upsert().

indexName:

string

Name of the index to create

dimension:

number

Vector dimension (must match your embedding model)

metric?:

'cosine' | 'euclidean'

= cosine

Distance metric for similarity search. 'dotproduct' isn't supported and throws an error.

upsert()

vectors:

number[][]

Array of embedding vectors

metadata?:

Record<string, any>[]

Metadata for each vector

ids?:

string[]

Optional vector IDs (auto-generated if not provided)

query()

indexName:

string

Name of the index to query

queryVector:

number[]

Query vector to find similar vectors

topK?:

number

= 10

Number of results to return

filter?:

Record<string, any>

Metadata filters for the query

includeVector?:

boolean

= false

Whether to include vectors in the results

consistency?:

'strong' | 'eventual'

The consistency level for this query. Overrides the consistency level set in the constructor. Defaults to "strong".

listIndexes()

Returns an array of index names as strings.

describeIndex()

indexName:

string

Name of the index to describe

Returns:

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}

deleteIndex()

indexName:

string

Name of the index to delete

updateVector()

Update a single vector by ID, or every vector that matches a metadata filter. Either id or filter must be provided, but not both.

indexName:

string

Name of the index containing the vector

id?:

string

ID of the vector to update (mutually exclusive with filter)

filter?:

Record<string, any>

Metadata filter to identify vector(s) to update (mutually exclusive with id)

update:

{ vector?: number[]; metadata?: Record<string, any>; }

Object containing the vector and/or metadata to update

deleteVector()

indexName:

string

Name of the index containing the vector

id:

string

ID of the vector to delete

deleteVectors()

Delete multiple vectors by IDs or by metadata filter. Either ids or filter must be provided, but not both.

indexName:

string

Name of the index containing the vectors to delete

ids?:

string[]

Array of vector IDs to delete (mutually exclusive with filter)

filter?:

Record<string, any>

Metadata filter to identify vectors to delete (mutually exclusive with ids)

Response types

Query results are returned in this format:

interface QueryResult {
  id: string
  score: number
  metadata?: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}

Schema configuration

The schemaConfigForIndex option allows you to define explicit schemas for different indexes:

schemaConfigForIndex: (indexName: string) => {
  // Mastra's default embedding model and index for memory messages:
  if (indexName === 'memory_messages_384') {
    return {
      dimensions: 384,
      schema: {
        thread_id: {
          type: 'string',
          filterable: true,
        },
      },
    }
  } else {
    throw new Error(`TODO: add schema for index: ${indexName}`)
  }
}

Error handling

The store throws MastraError instances from @mastra/core/error:

import { MastraError } from '@mastra/core/error'

try {
  await store.query({
    indexName: 'index_name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof MastraError) {
    console.log(error.id) // 'MASTRA_VECTOR_TURBOPUFFER_QUERY_FAILED'
    console.log(error.domain) // 'STORAGE'
    console.log(error.category) // 'USER' | 'THIRD_PARTY'
    console.log(error.details) // Additional error context
  }
}

Related

• Metadata Filters