Full Text Search

Note

Further updates to the search docs will come with future 4.x releases.

Enumerations

enum couchbase.search.SearchScanConsistency(value)

SearchScanConsistency

This can be:

NOT_BOUNDED

Which means we just return what is currently in the indexes.

Valid values are as follows:

NOT_BOUNDED = <SearchScanConsistency.NOT_BOUNDED: 'not_bounded'>

REQUEST_PLUS = <SearchScanConsistency.REQUEST_PLUS: 'request_plus'>

AT_PLUS = <SearchScanConsistency.AT_PLUS: 'at_plus'>

Options

class couchbase.options.SearchOptions(timeout=None, limit=None, skip=None, explain=None, fields=None, highlight_style=None, highlight_fields=None, scan_consistency=None, consistent_with=None, facets=None, raw=None, sort=None, disable_scoring=None, scope_name=None, collections=None, include_locations=None, client_context_id=None, serializer=None, show_request=None, log_request=None, log_response=None)

Available options to for a search (FTS) query.

Warning

Importing options from couchbase.search is deprecated. All options should be imported from couchbase.options.

Parameters:

• timeout (timedelta, optional) – The timeout for this operation. Defaults to global search query operation timeout.

• limit (int, optional) – Specifies the limit to the number of results that should be returned. Defaults to None.

• skip (int, optional) – Specifies the number of results to skip from the index before returning results. Defaults to None.

• explain (bool, optional) – Configures whether the result should contain the execution plan for the search query. Defaults to False.

• fields (List[str], optional) – Specifies the list of fields which should be searched. Defaults to None.

• highlight_style (HighlightStyle, optional) – Specifies the mode used for highlighting. Defaults to None.

• highlight_fields (List[str], optional) – Specifies the list of fields that should be highlighted. Defaults to None.

• scan_consistency (SearchScanConsistency, optional) – Specifies the consistency requirements when executing the search query.

• facets (Dict[str, Facet], optional) – Specifies any facets that should be included in the search query. Defaults to None.

• client_context_id (str, optional) – The returned client context id for this query. Defaults to None.

• disable_scoring (bool, optional) – Specifies that scoring should be disabled. This improves performance but makes it impossible to sort based on how well a particular result scored. Defaults to False.

• include_locations (bool optional) – If set to True, will include the locations in the search result. Defaults to False.

• sort (Union[List[str],List[Sort]], optional) – Specifies a list of fields or search Sort’s to use when sorting the result sets. Defaults to None.

• scope_name (string, optional) – Specifies the scope which should be searched as part of the search query. Defaults to None.

• collections (List[str], optional) – Specifies the collections which should be searched as part of the search query. Defaults to None.

• consistent_with (MutationState, optional) – Specifies a MutationState which the search query should be consistent with. Defaults to None.

• serializer (Serializer, optional) – Specifies an explicit serializer to use for this specific search query. Defaults to DefaultJsonSerializer.

• raw (Dict[str, Any], optional) – Specifies any additional parameters which should be passed to the search query engine when executing the search query. Defaults to None.

• show_request (bool, optional) – Specifies if the search response should contain the request for the search query. Defaults to False.

• log_request (bool, optional) – UNCOMMITTED Specifies if search request body should appear the log. Defaults to False.

• log_response (bool, optional) – UNCOMMITTED Specifies if search response should appear in the log. Defaults to False.

SearchRequest

class couchbase.search.SearchRequest(query)

Represents a search query and/or vector search to execute via the Couchbase Full Text Search (FTS) service.

Parameters:

query (Union[SearchQuery, VectorSearch]) – A SearchQuery or VectorSearch to initialize the search request.

Raises:

InvalidArgumentException – If neither a SearchQuery or VectorSearch is provided.

Returns:

The created search request.

Return type:

SearchRequest

classmethod create(query) → SearchRequest

Creates a SearchRequest.

Parameters:

query (Union[SearchQuery, VectorSearch]) – A SearchQuery or VectorSearch to initialize the search request.

Raises:

InvalidArgumentException – If neither a SearchQuery or VectorSearch is provided.

Returns:

The created search request.

Return type:

SearchRequest

property search_query: SearchQuery | None

Returns the search request’s SearchQuery, if it exists.

Type:

Optional[SearchQuery]

property vector_search: VectorSearch | None

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

Optional[VectorSearch]: Returns the search request’s VectorSearch, if it exists.

with_search_query(query) → SearchRequest

Add a SearchQuery to the search request.

Parameters:

query (SearchQuery) – The SearchQuery to add to the search request.

Raises:

• InvalidArgumentException – If the search request already contains a SearchQuery.

• InvalidArgumentException – If the provided query is not an instance of a SearchQuery.

Returns:

The search request in order to allow method chaining.

Return type:

SearchRequest

with_vector_search(vector_search) → SearchRequest

Add a VectorSearch to the search request.

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

Parameters:

vector_search (VectorSearch) – The VectorSearch to add to the search request.

Raises:

• InvalidArgumentException – If the search request already contains a VectorSearch.

• InvalidArgumentException – If the provided query is not an instance of a VectorSearch.

Returns:

The search request in order to allow method chaining.

Return type:

SearchRequest

Results

SearchMetaData

class couchbase.search.SearchMetaData(raw)

Represents the meta-data returned along with a search query result.

SearchMetrics

class couchbase.search.SearchMetrics(raw)

SearchResult

class couchbase.result.SearchResult

rows()

The rows which have been returned by the search query.

Note

If using the acouchbase API be sure to use async for when looping over rows.

Returns:

Either an iterable or async iterable.

Return type:

Iterable

metadata()

The meta-data which has been returned by the search query.

Returns:

An instance of SearchMetaData.

Return type:

SearchMetaData

Vector Search

class couchbase.vector_search.VectorQuery(field_name, vector, num_candidates=None, boost=None)

Represents a vector query.

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

Parameters:

• field_name (str) – The name of the field in the search index that stores the vector.

• vector (List[float]) – The vector to use in the query.

• num_candidates (int, optional) – Specifies the number of results returned. If provided, must be greater or equal to 1.

• boost (float, optional) – Add boost to query.

Raises:

• InvalidArgumentException – If the vector is not provided.

• InvalidArgumentException – If all values of the provided vector are not instances of float.

Returns:

The created vector query.

Return type:

VectorQuery

property boost: float | None

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

Optional[float]: Returns vector query’s boost value, if it exists.

classmethod create(field_name, vector, num_candidates=None, boost=None) → VectorQuery

Creates a VectorQuery.

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

Parameters:

• field_name (str) – The name of the field in the search index that stores the vector.

• vector (List[float]) – The vector to use in the query.

• num_candidates (int, optional) – Specifies the number of results returned. If provided, must be greater or equal to 1.

• boost (float, optional) – Add boost to query.

Raises:

• InvalidArgumentException – If the vector is not provided.

• InvalidArgumentException – If all values of the provided vector are not instances of float.

Returns:

The created vector query.

Return type:

VectorQuery

property field_name: str

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

str: Returns vector query’s field name

property num_candidates: int | None

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

Optional[int]: Returns vector query’s num candidates value, if it exists.

property vector: List[float]

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

List[float]: Returns the vector query’s vector.

class couchbase.vector_search.VectorSearch(queries, options=None)

Represents a vector search.

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

Parameters:

• queries (List[VectorQuery]) – The list of VectorQuery’s to use for the vector search.

• options (VectorSearchOptions, optional) – Options to set for the vector search.

Raises:

• InvalidArgumentException – If a list of VectorQuery is not provided.

• InvalidArgumentException – If all values of the provided queries are not instances of VectorQuery.

Returns:

The created vector search.

Return type:

VectorSearch

classmethod from_vector_query(query) → VectorSearch

Creates a VectorSearch from a single VectorQuery.

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

Parameters:

query (VectorQuery) – A VectorQuery’s to use for the vector search.

Raises:

InvalidArgumentException – If the provided query is not an instance of VectorQuery.

Returns:

The created vector search.

Return type:

VectorSearch

property options: VectorSearchOptions | None

INTERNAL

property queries: List[VectorQuery]

INTERNAL

Enumerations

enum couchbase.vector_search.VectorQueryCombination(value)

Specifies how multiple vector searches are combined.

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

This can be one of:

AND: Indicates that multiple vector queries should be combined with logical AND.

OR: Indicates that multiple vector queries should be combined with logical OR.

Valid values are as follows:

AND = <VectorQueryCombination.AND: 'and'>

OR = <VectorQueryCombination.OR: 'or'>

Options

class couchbase.options.VectorSearchOptions(vector_query_combination=None)

UNCOMMITTED This API is unlikely to change, but may still change as final consensus on its behavior has not yet been reached.

Available options to for a FTS vector search.

Parameters:

vector_query_combination (VectorQueryCombination, optional) – Specifies logical operation to use with multiple vector queries.