Qdrant vector store

The QdrantVector class provides vector search using Qdrant, a vector similarity search engine. It provides a production-ready service with a convenient API to store, search, and manage vectors with additional payload and extended filtering support.

Constructor options

<PropertiesTable content={[ { name: 'url', type: 'string', description: 'REST URL of the Qdrant instance. Eg. https://xyz-example.eu-central.aws.cloud.qdrant.io:6333', }, { name: 'apiKey', type: 'string', description: 'Optional Qdrant API key', }, { name: 'https', type: 'boolean', description: 'Whether to use TLS when setting up the connection. Recommended.', }, ]} />

Methods

createIndex()

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to create', }, { name: 'dimension', type: 'number', description: 'Vector dimension (must match your embedding model). Required for single-vector collections.', }, { name: 'metric', type: "'cosine' | 'euclidean' | 'dotproduct'", isOptional: true, defaultValue: 'cosine', description: 'Distance metric for similarity search', }, { name: 'namedVectors', type: "Record<string, { size: number; distance: 'cosine' | 'euclidean' | 'dotproduct' }>", isOptional: true, description: 'Configuration for named vector spaces. When provided, creates a collection with multiple named vector fields.', }, ]} />

Creating a Named Vectors Collection

// Create a collection with multiple named vector spaces
await store.createIndex({
  indexName: 'multi_modal',
  dimension: 768, // fallback
  namedVectors: {
    text: { size: 768, distance: 'cosine' },
    image: { size: 512, distance: 'euclidean' },
  },
})

upsert()

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to upsert into', }, { name: 'vectors', type: 'number[][]', description: 'Array of embedding vectors', }, { name: 'metadata', type: 'Record<string, any>[]', isOptional: true, description: 'Metadata for each vector', }, { name: 'ids', type: 'string[]', isOptional: true, description: 'Optional vector IDs (auto-generated if not provided)', }, { name: 'vectorName', type: 'string', isOptional: true, description: 'Name of the vector space to upsert into when using named vectors.', }, ]} />

Upserting into Named Vector Spaces

// Upsert into the "text" vector space
await store.upsert({
  indexName: 'multi_modal',
  vectors: textEmbeddings,
  metadata: textMetadata,
  vectorName: 'text',
})

// Upsert into the "image" vector space
await store.upsert({
  indexName: 'multi_modal',
  vectors: imageEmbeddings,
  metadata: imageMetadata,
  vectorName: 'image',
})

query()

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to query', }, { name: 'queryVector', type: 'number[]', description: 'Query vector to find similar vectors', }, { name: 'topK', type: 'number', isOptional: true, defaultValue: '10', description: 'Number of results to return', }, { name: 'filter', type: 'Record<string, any>', isOptional: true, description: 'Metadata filters for the query', }, { name: 'includeVector', type: 'boolean', isOptional: true, defaultValue: 'false', description: 'Whether to include vectors in the results', }, { name: 'using', type: 'string', isOptional: true, description: 'Name of the vector field to query when using named vectors. Use this when your collection has multiple named vector fields.', }, ]} />

Named Vectors

Qdrant supports named vectors, allowing multiple vector fields per collection. Use the using parameter to specify which named vector to query against:

const results = await store.query({
  indexName: 'my_index',
  queryVector: embedding,
  topK: 10,
  using: 'title_embedding', // Query against a specific named vector
})

listIndexes()

Returns an array of index names as strings.

describeIndex()

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to describe', }, ]} />

Returns:

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

deleteIndex()

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to delete', }, ]} />

updateVector()

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

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to update', }, { name: 'id', type: 'string', isOptional: true, description: 'ID of the vector to update (mutually exclusive with filter)', }, { name: 'filter', type: 'Record<string, any>', isOptional: true, description: 'Metadata filter to identify vector(s) to update (mutually exclusive with id)', }, { name: 'update', type: '{ vector?: number[]; metadata?: Record<string, any>; }', description: 'Object containing the vector and/or metadata to update', }, ]} />

Updates a vector and/or its metadata in the specified index. If both vector and metadata are provided, both will be updated. If only one is provided, only that will be updated.

deleteVector()

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index from which to delete the vector', }, { name: 'id', type: 'string', description: 'ID of the vector to delete', }, ]} />

Deletes a vector from the specified index by its ID.

deleteVectors()

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

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index containing the vectors to delete', }, { name: 'ids', type: 'string[]', isOptional: true, description: 'Array of vector IDs to delete (mutually exclusive with filter)', }, { name: 'filter', type: 'Record<string, any>', isOptional: true, description: 'Metadata filter to identify vectors to delete (mutually exclusive with ids)', }, ]} />

createPayloadIndex()

Creates a payload (metadata) index on a collection field to enable efficient filtering. This is required for Qdrant Cloud and any Qdrant instance with strict_mode_config = true.

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the collection to create the payload index on', }, { name: 'fieldName', type: 'string', description: 'Name of the payload field to index', }, { name: 'fieldSchema', type: "'keyword' | 'integer' | 'float' | 'geo' | 'text' | 'bool' | 'datetime' | 'uuid'", description: 'The schema type for the payload field', }, { name: 'wait', type: 'boolean', isOptional: true, defaultValue: 'true', description: 'Whether to wait for the operation to complete', }, ]} />

// Create a keyword index for filtering by source
await store.createPayloadIndex({
  indexName: 'my_index',
  fieldName: 'source',
  fieldSchema: 'keyword',
})

const results = await store.query({
  indexName: 'my_index',
  queryVector: queryVector,
  filter: { source: 'document-a' },
})

deletePayloadIndex()

Removes a payload index from a collection field.

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the collection to delete the payload index from', }, { name: 'fieldName', type: 'string', description: 'Name of the payload field index to delete', }, { name: 'wait', type: 'boolean', isOptional: true, defaultValue: 'true', description: 'Whether to wait for the operation to complete', }, ]} />

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
}

Error handling

The store throws typed errors that can be caught:

try {
  await store.query({
    indexName: 'index_name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}

Related

• Metadata Filters