Couchbase Python Client Library
4.7.0

Guide

  • Using the Python SDK
  • Migration
  • Logging and Telemetry
  • Transactions
  • Parallelism
  • Environment Variables

Reference

  • Synchronous API
  • asyncio API
  • Twisted API
  • Common reference
    • Authentication
    • Options
    • Management options
    • Exceptions
    • Warnings
    • Durability
    • Sub-document operations
    • Range scan
    • Replica reads
    • Query (SQL++)
    • Analytics
    • Search
    • Vector search
      • VectorQuery
        • VectorQuery.boost
        • VectorQuery.create()
        • VectorQuery.field_name
        • VectorQuery.num_candidates
        • VectorQuery.prefilter
        • VectorQuery.vector
        • VectorQuery.vector_base64
      • VectorQueryCombination
        • VectorQueryCombination.AND
        • VectorQueryCombination.OR
      • VectorSearch
        • VectorSearch.from_vector_query()
    • Search scoring
    • Views
    • Mutation state
    • Transactions
    • Transcoders and serializers
    • Field-level encryption
    • Diagnostics
    • Observability
Couchbase Python Client Library
  • Common reference
  • Vector search
  • View page source

Vector search

class couchbase.vector_search.VectorQuery(field_name: str, vector: list[float] | str, num_candidates: int | None = None, boost: float | None = None, prefilter: SearchQuery | None = None)

A query for the documents whose vectors are nearest a given vector.

Parameters:
  • field_name (str) – The index field that holds the vectors.

  • vector (list[float] | str) – The vector to search near, as floats or as a str of its little-endian 32-bit floats, base64 encoded.

  • num_candidates (int, optional) – How many nearest neighbours the query returns. Must be 1 or more. Defaults to None, which returns 3.

  • boost (float, optional) – A multiplier on the query’s part of a hit’s score.

  • prefilter (SearchQuery, optional) – A query a document must match to be a candidate.

Raises:
  • InvalidArgumentException – If the field name is empty, or the vector is empty, not a list of floats or a str.

  • InvalidArgumentException – If num_candidates is not an int of 1 or more, boost is not a float, or prefilter is not a search query.

property boost: float | None

A multiplier on the query’s part of a hit’s score, or None if not set.

classmethod create(field_name: str, vector: list[float] | str, num_candidates: int | None = None, boost: float | None = None, prefilter: SearchQuery | None = None) → VectorQuery

Creates a VectorQuery.

Parameters:
  • field_name (str) – The index field that holds the vectors.

  • vector (list[float] | str) – The vector to search near, as floats or as a str of its little-endian 32-bit floats, base64 encoded.

  • num_candidates (int, optional) – How many nearest neighbours the query returns. Must be 1 or more. Defaults to None, which returns 3.

  • boost (float, optional) – A multiplier on the query’s part of a hit’s score.

  • prefilter (SearchQuery, optional) – A query a document must match to be a candidate.

Raises:
  • InvalidArgumentException – If the field name is empty, or the vector is empty, not a list of floats or a str.

  • InvalidArgumentException – If num_candidates is not an int of 1 or more, boost is not a float, or prefilter is not a search query.

Returns:

The query.

Return type:

VectorQuery

property field_name: str

The index field that holds the vectors.

property num_candidates: int | None

How many nearest neighbours the query returns, or None for the default of 3.

property prefilter: SearchQuery | None

A query a document must match to be a candidate, or None if not set.

property vector: list[float] | None

The vector as floats, or None if it was given base64 encoded.

property vector_base64: str | None

The vector base64 encoded, or None if it was given as floats.

class couchbase.vector_search.VectorQueryCombination(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

How a vector search combines its queries’ results.

AND keeps the documents every query returns, and OR the documents any of them returns.

AND = 'and'
OR = 'or'
class couchbase.vector_search.VectorSearch(queries: list[VectorQuery], options: VectorSearchOptions | None = None)

One or more vector queries, sent together as a search request’s vector search.

Parameters:
  • queries (list[VectorQuery]) – The queries.

  • options (VectorSearchOptions, optional) – How the queries’ results are combined.

Raises:

InvalidArgumentException – If queries is empty or holds anything but vector queries.

classmethod from_vector_query(query: VectorQuery) → VectorSearch

Creates a VectorSearch of one query.

Parameters:

query (VectorQuery) – The query.

Raises:

InvalidArgumentException – If query is not a vector query.

Returns:

The vector search.

Return type:

VectorSearch

Previous Next

© Copyright 2013-2026, Couchbase, Inc..

Built with Sphinx using a theme provided by Read the Docs.