Search

Requests

HighlightStyle(value[, names, module, ...])

How a search marks the matched terms in the fragments it returns: with ANSI escape codes, or HTML.

MatchOperator(value[, names, module, ...])

How a match query combines the terms it analyzes its text into.

SearchQuery(*[, boost])

Base query object.

SearchRequest(query)

A search query, a vector search, or both, to run on the Search service.

SearchScanConsistency(value[, names, ...])

How current the search index must be when a search reads it.

class couchbase.search.HighlightStyle(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

How a search marks the matched terms in the fragments it returns: with ANSI escape codes, or HTML.

Ansi = 'ansi'
Html = 'html'
class couchbase.search.MatchOperator(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

How a match query combines the terms it analyzes its text into.

UNCOMMITTED This API may change in the future.

OR, the default, matches a document with any of the terms; AND, one with all of them.

AND = 'and'
OR = 'or'
class couchbase.search.SearchQuery(*, boost: float | None = None)

Base query object. You probably want to use one of the subclasses.

property boost: float | None

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

property encodable: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any]

The query as the Search service’s JSON query language, validated first.

The result is ready to serialize to JSON, and each read builds a new one.

json.dumps(query.encodable)
set_prop(key: str, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any]) → None

Sets key in the query’s JSON to value, sent as given and without validation.

The key is written over whatever the query’s own fields encode under it, and is not read back by any of the query’s properties. Use this for a query parameter the class does not expose.

validate() → None

Check that the query’s required fields are set, before it is encoded.

The base class checks nothing. A subclass raises if a field it needs is missing or empty.

class couchbase.search.SearchRequest(query: SearchQuery | VectorSearch)

A search query, a vector search, or both, to run on the Search service.

A request holding both is a hybrid search, and the request’s scoring option sets how their results are combined.

Parameters:

query (SearchQuery | VectorSearch) – The search query or vector search to start with. Add the other with with_search_query() or with_vector_search().

Raises:

InvalidArgumentException – If query is neither.

classmethod create(query: SearchQuery | VectorSearch) → SearchRequest

Creates a SearchRequest.

Parameters:

query (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

The request’s search query, or None if it has none.

The request’s vector search, or None if it has none.

with_search_query(query: SearchQuery) → SearchRequest

Add a SearchQuery to the search request.

Parameters:

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

Raises:
Returns:

The search request in order to allow method chaining.

Return type:

SearchRequest

Add a VectorSearch to the search request.

Parameters:

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

Raises:
Returns:

The search request in order to allow method chaining.

Return type:

SearchRequest

class couchbase.search.SearchScanConsistency(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

How current the search index must be when a search reads it.

NOT_BOUNDED reads the index as it is. REQUEST_PLUS waits until the index holds every mutation made before the search. AT_PLUS waits until it holds the mutations given as the consistent_with option.

AT_PLUS = 'at_plus'
NOT_BOUNDED = 'not_bounded'
REQUEST_PLUS = 'request_plus'

Queries

BooleanFieldQuery([bool, field, boost])

A query for documents whose field holds a boolean value.

BooleanQuery([must, should, must_not])

A compound query that specifies multiple child queries.

ConjunctionQuery(*queries[, boost])

A compound query that specifies multiple child queries.

DateRangeQuery([start, end, ...])

A query for documents whose field holds a date in a range.

DisjunctionQuery(*queries[, min, boost])

A compound query that specifies multiple child queries.

DocIdQuery([ids, boost])

A query for the documents with the given IDs.

GeoBoundingBoxQuery([top_left, ...])

A query for documents with a location inside a rectangle.

GeoDistanceQuery([distance, location, ...])

A query for documents with a location within a distance of a point.

GeoPolygonQuery([polygon_points, field, boost])

A query for documents with a location inside a polygon.

MatchAllQuery(*[, boost])

A query that matches every document.

MatchNoneQuery(*[, boost])

A query that matches no document.

MatchPhraseQuery([match_phrase, field, ...])

A query for documents holding a phrase, which the server analyzes into terms first.

MatchQuery([match, match_operator, field, ...])

A query for documents matching a text, which the server analyzes into terms first.

NumericRangeQuery([min, max, inclusive_min, ...])

A query for documents whose field holds a number in a range.

PhraseQuery(*phrases[, terms, field, boost])

A query for documents holding terms together and in order, in one field.

PrefixQuery([prefix, field, boost])

A query for documents holding a term that starts with a prefix.

QueryStringQuery([query, boost])

Query that specifies the Search Service should search for a match to the specified query string.

RawQuery(obj)

A query given as its JSON, for parameters or query types the other classes do not cover.

RegexQuery([regexp, regex, field, boost])

A query for documents holding a term that matches a regular expression.

TermQuery([term, field, fuzziness, ...])

Query that specifies the Search Service should search for an exact match to the specified term.

TermRangeQuery([start, end, min, max, ...])

A query for documents holding a term in a range, in lexical order.

WildcardQuery([wildcard, field, boost])

Query that specifies the Search Service should search for a match to the specified wildcard string.

class couchbase.search.BooleanFieldQuery(bool: bool | None = None, *, field: str | None = None, boost: float | None = None)

A query for documents whose field holds a boolean value.

Examples

Basic search using BooleanFieldQuery:

from couchbase.search import BooleanFieldQuery, SearchRequest

# ... other code ...

query = BooleanFieldQuery(True, field='perfect_rating')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using BooleanFieldQuery with kwargs:

from couchbase.search import BooleanFieldQuery, SearchRequest

# ... other code ...

query = BooleanFieldQuery(bool=True, field='perfect_rating')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using BooleanFieldQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import BooleanFieldQuery, SearchRequest

# ... other code ...

query = BooleanFieldQuery(True, field='perfect_rating')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
property bool: bool | None

The boolean value to match.

field

Restrict searching to a given document field

class couchbase.search.BooleanQuery(must: SearchQuery | ConjunctionQuery | DisjunctionQuery | list[SearchQuery] | None = None, should: SearchQuery | ConjunctionQuery | DisjunctionQuery | list[SearchQuery] | None = None, must_not: SearchQuery | ConjunctionQuery | DisjunctionQuery | list[SearchQuery] | None = None)

A compound query that specifies multiple child queries.

For a BooleanQuery, a document must match the combination of queries to be included in the search results.

Examples

Basic search using BooleanQuery:

from couchbase.search import (BooleanQuery,
                              DateRangeQuery,
                              TermQuery,
                              PrefixQuery,
                              WildcardQuery,
                              SearchRequest)

# ... other code ...

must = [DateRangeQuery('2024-10-01',
                       '2024-12-31',
                       inclusive_start=True,
                       inclusive_end=True,
                       field='last_rated'),
        WildcardQuery('ff????', field='color_hex')]
must_not = [TermQuery('smoke', field='description'),
            PrefixQuery('rain', field='description')]
query = BooleanQuery(must, None, must_not)
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using BooleanQuery with kwargs:

from couchbase.search import (BooleanQuery,
                              DateRangeQuery,
                              TermQuery,
                              PrefixQuery,
                              WildcardQuery,
                              SearchRequest)

# ... other code ...

must = [DateRangeQuery('2024-10-01',
                       '2024-12-31',
                       inclusive_start=True,
                       inclusive_end=True,
                       field='last_rated'),
        WildcardQuery('ff????', field='color_hex')]
must_not = [TermQuery('smoke', field='description'),
            PrefixQuery('rain', field='description')]
query = BooleanQuery(must=must, must_not=must_not)
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using BooleanQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import (BooleanQuery,
                              DateRangeQuery,
                              TermQuery,
                              PrefixQuery,
                              WildcardQuery,
                              SearchRequest)

# ... other code ...

must = [DateRangeQuery('2024-10-01',
                       '2024-12-31',
                       inclusive_start=True,
                       inclusive_end=True,
                       field='last_rated'),
        WildcardQuery('ff????', field='color_hex')]
must_not = [TermQuery('smoke', field='description'),
            PrefixQuery('rain', field='description')]
query = BooleanQuery(must, None, must_not)
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
property must: ConjunctionQuery | None

The queries a document must all match, or None if not set.

property must_not: DisjunctionQuery | None

The queries a document must match none of, or None if not set.

property should: DisjunctionQuery | None

The queries a document must match the disjunction’s min of, or None if not set.

validate() → None

Check that at least one of must, should and must_not is set.

Raises:

ValueError – If none of them is.

class couchbase.search.ConjunctionQuery(*queries: SearchQuery | list[SearchQuery], boost: float | None = None)

A compound query that specifies multiple child queries.

For a ConjunctionQuery, every query object in the array must have a match in a document to include the document in search results.

Examples

Basic search using ConjunctionQuery:

from couchbase.search import ConjunctionQuery, DateRangeQuery, TermQuery, SearchRequest

# ... other code ...

queries = [DateRangeQuery('2024-01-01',
                          '2024-02-15',
                          inclusive_start=False,
                          inclusive_end=False,
                          field='last_rated'),
            TermQuery('sand', field='description')]
query = ConjunctionQuery(*queries)
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using ConjunctionQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import ConjunctionQuery, DateRangeQuery, TermQuery, SearchRequest

# ... other code ...

queries = [DateRangeQuery('2024-01-01',
                          '2024-02-15',
                          inclusive_start=False,
                          inclusive_end=False,
                          field='last_rated'),
            TermQuery('sand', field='description')]
query = ConjunctionQuery(*queries)
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
property conjuncts: list[SearchQuery]

The queries a document must all match.

validate() → None

Check that the query has at least one child query.

Raises:

NoChildrenException – If conjuncts is empty.

class couchbase.search.DateRangeQuery(start: str | None = None, end: str | None = None, *, inclusive_start: bool | None = None, inclusive_end: bool | None = None, datetime_parser: str | None = None, field: str | None = None, boost: float | None = None, start_inclusive: bool | None = None, end_inclusive: bool | None = None)

A query for documents whose field holds a date in a range.

Note

At least one of start or end must be specified.

The date ranges are parsed according to a given datetime_parser. If no parser is specified, the RFC 3339 parser is used. See Generating an RFC 3339 Timestamp <http://goo.gl/LIkV7G>_.

Examples

Basic search using DateRangeQuery:

from couchbase.search import DateRangeQuery, SearchRequest

# ... other code ...

query = DateRangeQuery('2024-01-01',
                       '2024-01-05',
                       inclusive_start=True,
                       inclusive_end=True,
                       field='last_rated')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using DateRangeQuery with kwargs:

from couchbase.search import DateRangeQuery, SearchRequest

# ... other code ...

query = DateRangeQuery(start='2024-01-01',
                       end='2024-01-05',
                       inclusive_start=True,
                       inclusive_end=True,
                       field='last_rated')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using DateRangeQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import DateRangeQuery, SearchRequest

# ... other code ...

query = DateRangeQuery('2024-01-01',
                       '2024-01-05',
                       inclusive_start=True,
                       inclusive_end=True,
                       field='last_rated')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
property datetime_parser: str | None

The name of the index’s date parser that reads the dates, or None for the index’s default.

property end: str | None

The latest date, or None for no upper bound.

property end_inclusive: bool | None

DEPRECATED The same as inclusive_end.

Deprecated since version 4.4.0: Use inclusive_end instead.

field

Restrict searching to a given document field

property inclusive_end: bool | None

Whether the end date is in the range, or None if not set.

property inclusive_start: bool | None

Whether the start date is in the range, or None if not set.

property start: str | None

The earliest date, or None for no lower bound.

property start_inclusive: bool | None

DEPRECATED The same as inclusive_start.

Deprecated since version 4.4.0: Use inclusive_start instead.

class couchbase.search.DisjunctionQuery(*queries: SearchQuery | list[SearchQuery], min: int | None = None, boost: float | None = None)

A compound query that specifies multiple child queries.

For a DisjunctionQuery, the min property sets the number of query objects from the disjuncts array that must have a match in a document. If a document does not match the min number of query objects, the Search Service does not include the document in search results.

Examples

Basic search using DisjunctionQuery:

from couchbase.search import DisjunctionQuery, NumericRangeQuery, TermQuery, SearchRequest

# ... other code ...

queries = [NumericRangeQuery(3.0,
                             3.1,
                             inclusive_min=True,
                             inclusive_max=True,
                             field='rating'),
            TermQuery('smoke', field='description')]
query = DisjunctionQuery(*queries)
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using DisjunctionQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import DisjunctionQuery, NumericRangeQuery, TermQuery, SearchRequest

# ... other code ...

queries = [NumericRangeQuery(3.0,
                             3.1,
                             inclusive_min=True,
                             inclusive_max=True,
                             field='rating'),
            TermQuery('smoke', field='description')]
query = DisjunctionQuery(*queries)
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
property disjuncts: list[SearchQuery]

The queries a document must match min of.

property min: int

How many of the queries a document must match. Defaults to 1.

validate() → None

Check that the query has child queries, and at least min of them.

Raises:
class couchbase.search.DocIdQuery(ids: Sequence[str] | None = None, *, boost: float | None = None)

A query for the documents with the given IDs.

Examples

Basic search using DocIdQuery:

from couchbase.search import DocIdQuery, SearchRequest

# ... other code ...

query = DocIdQuery(['34','43','61'])
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using DocIdQuery with kwargs:

from couchbase.search import DocIdQuery, SearchRequest

# ... other code ...

query = DocIdQuery(ids=['34','43','61'])
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using DocIdQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import DocIdQuery, SearchRequest

# ... other code ...

query = DocIdQuery(['34','43','61','72'])
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
property ids: Sequence[str] | None

The IDs of the documents to match.

validate() → None

Check that the query has at least one ID.

Raises:

NoChildrenException – If ids is empty.

class couchbase.search.GeoBoundingBoxQuery(top_left: Sequence[float] | dict[str, float] | None = None, bottom_right: Sequence[float] | dict[str, float] | None = None, *, field: str | None = None, boost: float | None = None)

A query for documents with a location inside a rectangle.

If you use location as an array, your array must contain a longitude value followed by a latitude value.

Examples

Basic search using GeoBoundingBoxQuery:

from couchbase.search import GeoBoundingBoxQuery, SearchRequest

# ... other code ...

query = GeoBoundingBoxQuery((-0.489, 51.686), (0.236, 51.28), field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using GeoBoundingBoxQuery with bounding box points as list:

from couchbase.search import GeoBoundingBoxQuery, SearchRequest

# ... other code ...

query = GeoBoundingBoxQuery([-0.489, 51.686], [0.236, 51.28], field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using GeoBoundingBoxQuery with location as dict:

from couchbase.search import GeoBoundingBoxQuery, SearchRequest

# ... other code ...

query = GeoBoundingBoxQuery({'lon': -0.489, 'lat': 51.686},
                            {'lon': 0.236, 'lat': 51.28},
                            field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using GeoBoundingBoxQuery with kwargs:

from couchbase.search import GeoBoundingBoxQuery, SearchRequest

# ... other code ...

query = GeoBoundingBoxQuery(top_left=(-0.489, 51.686), bottom_right=(0.236, 51.28), field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using GeoBoundingBoxQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import GeoBoundingBoxQuery, SearchRequest

# ... other code ...

query = GeoBoundingBoxQuery((-0.489, 51.686), (0.236, 51.28), field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
property bottom_right: list[float] | None

The rectangle’s bottom right corner, as [longitude, latitude].

field

Restrict searching to a given document field

property top_left: list[float] | None

The rectangle’s top left corner, as [longitude, latitude].

class couchbase.search.GeoDistanceQuery(distance: str | None = None, location: Sequence[float] | dict[str, float] | None = None, *, field: str | None = None, boost: float | None = None)

A query for documents with a location within a distance of a point.

If you use location as an array, your array must contain a longitude value followed by a latitude value.

The following distance units:
  • mm: Millimeters

  • cm: Centimeters

  • in: Inches

  • yd: Yards

  • ft: Feet

  • m: Meters

  • km: Kilometers

  • mi: Miles

  • nm: Nautical miles

Examples

Basic search using GeoDistanceQuery:

from couchbase.search import GeoDistanceQuery, SearchRequest

# ... other code ...

query = GeoDistanceQuery('130mi', (-115.1391, 36.1716), field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using GeoDistanceQuery with location as dict:

from couchbase.search import GeoDistanceQuery, SearchRequest

# ... other code ...

query = GeoDistanceQuery('130mi', {'lon': -115.1391, 'lat': 36.1716}, field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using GeoDistanceQuery with kwargs:

from couchbase.search import GeoDistanceQuery, SearchRequest

# ... other code ...

query = GeoDistanceQuery(distance='130mi', location=(-115.1391, 36.1716), field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using GeoDistanceQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import GeoDistanceQuery, SearchRequest

# ... other code ...

query = GeoDistanceQuery('130mi', (-115.1391, 36.1716), field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
property distance: str | None

The distance, with its unit, as in 10mi.

field

Restrict searching to a given document field

property location: list[float] | None

The point the distance is measured from, as [longitude, latitude].

class couchbase.search.GeoPolygonQuery(polygon_points: Sequence[Sequence[float] | dict[str, float]] | None = None, *, field: str | None = None, boost: float | None = None)

A query for documents with a location inside a polygon.

The point tuple must contain a longitude value followed by a latitude value.

Examples

Basic search using GeoPolygonQuery:

from couchbase.search import GeoPolygonQuery, SearchRequest

# ... other code ...

query = GeoPolygonQuery([(-122.44234633404847, 37.79393211306212),
                         (-122.43977141339417, 37.77995881733997),
                         (-122.42925715405579, 37.788031092020155),
                         (-122.41149020154114, 37.79026946582319),
                         (-122.40735054016113, 37.79571192027403),
                         (-122.44234633404847, 37.79393211306212)],
                         field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using GeoPolygonQuery with kwargs:

from couchbase.search import GeoPolygonQuery, SearchRequest

# ... other code ...

pts = [(-122.44234633404847, 37.79393211306212),
       (-122.43977141339417, 37.77995881733997),
       (-122.42925715405579, 37.788031092020155),
       (-122.41149020154114, 37.79026946582319),
       (-122.40735054016113, 37.79571192027403),
       (-122.44234633404847, 37.79393211306212)]
query = GeoPolygonQuery(polygon_points=pts, field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using GeoPolygonQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import GeoPolygonQuery, SearchRequest

# ... other code ...

query = GeoPolygonQuery([(-122.44234633404847, 37.79393211306212),
                         (-122.43977141339417, 37.77995881733997),
                         (-122.42925715405579, 37.788031092020155),
                         (-122.41149020154114, 37.79026946582319),
                         (-122.40735054016113, 37.79571192027403),
                         (-122.44234633404847, 37.79393211306212)],
                         field='geo_location')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
field

Restrict searching to a given document field

property polygon_points: list[list[float]] | None

The polygon’s corners, each as [longitude, latitude].

class couchbase.search.MatchAllQuery(*, boost: float | None = None)

A query that matches every document.

Examples

Basic search using MatchAllQuery:

from couchbase.search import MatchAllQuery, SearchRequest

# ... other code ...

query = MatchAllQuery()
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
class couchbase.search.MatchNoneQuery(*, boost: float | None = None)

A query that matches no document.

Examples

Basic search using MatchNoneQuery:

from couchbase.search import MatchNoneQuery, SearchRequest

# ... other code ...

query = MatchNoneQuery()
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
class couchbase.search.MatchPhraseQuery(match_phrase: str | None = None, *, field: str | None = None, analyzer: str | None = None, boost: float | None = None)

A query for documents holding a phrase, which the server analyzes into terms first.

The terms must appear together and in order.

Examples

Basic search using MatchPhraseQuery:

from couchbase.search import MatchPhraseQuery, SearchRequest

# ... other code ...

query = MatchPhraseQuery('white sands', field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using MatchPhraseQuery with kwargs:

from couchbase.search import MatchPhraseQuery, SearchRequest

# ... other code ...

query = MatchPhraseQuery(match_phrase='white sands', field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using MatchPhraseQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import MatchPhraseQuery, SearchRequest

# ... other code ...

query = MatchPhraseQuery('white sands', field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
analyzer

Use a defined server-side analyzer to process the input term prior to executing the search

field

Restrict searching to a given document field

property match_phrase: str | None

The phrase to match, which the server analyzes into terms.

class couchbase.search.MatchQuery(match: str | None = None, *, match_operator: MatchOperator | str | None = None, field: str | None = None, analyzer: str | None = None, fuzziness: int | None = None, prefix_length: int | None = None, boost: float | None = None)

A query for documents matching a text, which the server analyzes into terms first.

Without a field it searches the index’s default field.

Examples

Basic search using MatchQuery:

from couchbase.search import MatchQuery, SearchRequest

# ... other code ...

query = MatchQuery('secondary', field='color_wheel_pos')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using MatchQuery with kwargs:

from couchbase.search import MatchQuery, SearchRequest

# ... other code ...

query = MatchQuery(match='secondary', field='color_wheel_pos')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using MatchQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import MatchQuery, SearchRequest

# ... other code ...

query = MatchQuery('secondary', field='color_wheel_pos')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
analyzer

Use a defined server-side analyzer to process the input term prior to executing the search

field

Restrict searching to a given document field

fuzziness

Allow a given degree of fuzz in the match. Matches which are closer to the original term will be scored higher.

You can apply the fuzziness to only a portion of the string by specifying prefix_length - indicating that only the part of the field after the prefix length should be checked with fuzziness.

This value is specified as an int

property match: str | None

The text to match, which the server analyzes into terms.

property match_operator: MatchOperator | None

Whether a document must match all the text’s terms or any one of them, or None if not set.

It can be set with the str or or and.

prefix_length

When using fuzziness, this controls how much of the term or phrase is excluded from fuzziness. This may help improve performance at the expense of omitting potential fuzzy matches at the beginning of the string.

class couchbase.search.NumericRangeQuery(min: float | None = None, max: float | None = None, *, inclusive_min: bool | None = None, inclusive_max: bool | None = None, field: str | None = None, boost: float | None = None, min_inclusive: bool | None = None, max_inclusive: bool | None = None)

A query for documents whose field holds a number in a range.

Note

At least one of min or max must be specified.

Examples

Basic search using NumericRangeQuery:

from couchbase.search import NumericRangeQuery, SearchRequest

# ... other code ...

query = NumericRangeQuery(3.0,
                          3.2,
                          inclusive_min=True,
                          inclusive_max=False,
                          field='rating')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using NumericRangeQuery with kwargs:

from couchbase.search import NumericRangeQuery, SearchRequest

# ... other code ...

query = NumericRangeQuery(min=3.0,
                          max=3.2,
                          inclusive_min=True,
                          inclusive_max=False,
                          field='rating')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using NumericRangeQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import NumericRangeQuery, SearchRequest

# ... other code ...

query = NumericRangeQuery(3.0,
                          3.2,
                          inclusive_min=True,
                          inclusive_max=False,
                          field='rating')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
field

Restrict searching to a given document field

property inclusive_max: bool | None

Whether the upper bound is in the range, or None if not set.

property inclusive_min: bool | None

Whether the lower bound is in the range, or None if not set.

property max: float | None

The upper bound, or None for no upper bound.

property max_inclusive: bool | None

DEPRECATED The same as inclusive_max.

Deprecated since version 4.4.0: Use inclusive_max instead.

property min: float | None

The lower bound, or None for no lower bound.

property min_inclusive: bool | None

DEPRECATED The same as inclusive_min.

Deprecated since version 4.4.0: Use inclusive_min instead.

class couchbase.search.PhraseQuery(*phrases: str, terms: str | list[str] | tuple[str, ...] | None = None, field: str | None = None, boost: float | None = None)

A query for documents holding terms together and in order, in one field.

The field property must be set.

The terms are matched as given, without analysis, so each must be a term as the index holds it. Pass each term as its own argument, or as a list with terms=; a single string is split on whitespace. For a phrase the server should analyze first, use MatchPhraseQuery.

Examples

Basic search using PhraseQuery:

from couchbase.search import PhraseQuery, SearchRequest

# ... other code ...

query = PhraseQuery('white', 'sand', field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using PhraseQuery with kwargs:

from couchbase.search import PhraseQuery, SearchRequest

# ... other code ...

query = PhraseQuery(terms=['white', 'sand'], field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using PhraseQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import PhraseQuery, SearchRequest

# ... other code ...

query = PhraseQuery('white', 'sand', field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
field

Restrict searching to a given document field

property terms: list[str] | None

The terms to match, in order, without analysis.

validate() → None

Check that the query has at least one term.

Raises:

NoChildrenException – If terms is empty.

class couchbase.search.PrefixQuery(prefix: str | None = None, *, field: str | None = None, boost: float | None = None)

A query for documents holding a term that starts with a prefix.

Examples

Basic search using PrefixQuery:

from couchbase.search import PrefixQuery, SearchRequest

# ... other code ...

query = PrefixQuery('yellow', field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using PrefixQuery with kwargs:

from couchbase.search import PrefixQuery, SearchRequest

# ... other code ...

query = PrefixQuery(prefix='yellow', field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using PrefixQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import PrefixQuery, SearchRequest

# ... other code ...

query = PrefixQuery('yellow', field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
field

Restrict searching to a given document field

property prefix: str | None

The prefix a matching term starts with.

class couchbase.search.QueryStringQuery(query: str | None = None, *, boost: float | None = None)

Query that specifies the Search Service should search for a match to the specified query string.

See also

Query Language

Examples

Basic search using QueryStringQuery:

from couchbase.search import QueryStringQuery, SearchRequest

# ... other code ...

query = QueryStringQuery('+description:sea -color_hex:fff5ee')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using QueryStringQuery with kwargs:

from couchbase.search import QueryStringQuery, SearchRequest

# ... other code ...

query = QueryStringQuery(query='+description:sea -color_hex:fff5ee')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using QueryStringQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import QueryStringQuery, SearchRequest

# ... other code ...

query = QueryStringQuery('+description:sea -color_hex:fff5ee')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
property query: str | None

The query, in the query string syntax.

class couchbase.search.RawQuery(obj: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any])

A query given as its JSON, for parameters or query types the other classes do not cover.

The payload is read when the query is encoded, and never written: boost and set_prop() are added to a copy.

class couchbase.search.RegexQuery(regexp: str | None = None, *, regex: str | None = None, field: str | None = None, boost: float | None = None)

A query for documents holding a term that matches a regular expression.

Examples

Basic search using RegexQuery:

from couchbase.search import RegexQuery, SearchRequest

# ... other code ...

query = RegexQuery('f[58]f.*', field='color_hex')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using RegexQuery with kwargs:

from couchbase.search import RegexQuery, SearchRequest

# ... other code ...

query = RegexQuery(regexp='f[58]f.*', field='color_hex')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using RegexQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import RegexQuery, SearchRequest

# ... other code ...

query = RegexQuery('f[58]f.*', field='color_hex')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
field

Restrict searching to a given document field

property regex: str | None

The regular expression a matching term matches.

property regexp: str | None

Another name for regex.

class couchbase.search.TermQuery(term: str | None = None, *, field: str | None = None, fuzziness: int | None = None, prefix_length: int | None = None, boost: float | None = None)

Query that specifies the Search Service should search for an exact match to the specified term.

Examples

Basic search using TermQuery:

from couchbase.search import TermQuery, SearchRequest

# ... other code ...

query = TermQuery('park', field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using TermQuery with kwargs:

from couchbase.search import TermQuery, SearchRequest

# ... other code ...

query = TermQuery(term='park', field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using TermQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import TermQuery, SearchRequest

# ... other code ...

query = TermQuery('park', field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
field

Restrict searching to a given document field

fuzziness

Allow a given degree of fuzz in the match. Matches which are closer to the original term will be scored higher.

You can apply the fuzziness to only a portion of the string by specifying prefix_length - indicating that only the part of the field after the prefix length should be checked with fuzziness.

This value is specified as an int

prefix_length

When using fuzziness, this controls how much of the term or phrase is excluded from fuzziness. This may help improve performance at the expense of omitting potential fuzzy matches at the beginning of the string.

property term: str | None

The term to match exactly, without analysis.

class couchbase.search.TermRangeQuery(start: str | None = None, end: str | None = None, min: str | None = None, max: str | None = None, *, inclusive_min: bool | None = None, inclusive_max: bool | None = None, field: str | None = None, boost: float | None = None, start_inclusive: bool | None = None, end_inclusive: bool | None = None)

A query for documents holding a term in a range, in lexical order.

Note

At least one of min or max must be specified.

The first two positional arguments are the deprecated start and end, so pass the bounds by keyword.

Examples

Basic search using TermRangeQuery:

from couchbase.search import TermRangeQuery, SearchRequest

# ... other code ...

query = TermRangeQuery(min='mist',
                       max='misty',
                       inclusive_min=True,
                       inclusive_max=True,
                       field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using TermRangeQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import TermRangeQuery, SearchRequest

# ... other code ...

query = TermRangeQuery(min='mist',
                       max='misty',
                       inclusive_min=True,
                       inclusive_max=True,
                       field='description')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
property end: str | None

DEPRECATED The same as max.

Deprecated since version 4.4.0: Use max instead.

property end_inclusive: bool | None

DEPRECATED The same as inclusive_max.

Deprecated since version 4.4.0: Use inclusive_max instead.

field

Restrict searching to a given document field

property inclusive_max: bool | None

Whether the upper bound is in the range, or None if not set.

property inclusive_min: bool | None

Whether the lower bound is in the range, or None if not set.

property max: str | None

The upper bound, or None for no upper bound.

property min: str | None

The lower bound, or None for no lower bound.

property start: str | None

DEPRECATED The same as min.

Deprecated since version 4.4.0: Use min instead.

property start_inclusive: bool | None

DEPRECATED The same as inclusive_min.

Deprecated since version 4.4.0: Use inclusive_min instead.

class couchbase.search.WildcardQuery(wildcard: str | None = None, *, field: str | None = None, boost: float | None = None)

Query that specifies the Search Service should search for a match to the specified wildcard string.

Use ? to allow a match to any single character. Use * to allow a match to zero or many characters.

Examples

Basic search using WildcardQuery:

from couchbase.search import WildcardQuery, SearchRequest

# ... other code ...

query = WildcardQuery('f0f???', field='color_hex')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using WildcardQuery with kwargs:

from couchbase.search import WildcardQuery, SearchRequest

# ... other code ...

query = WildcardQuery(wildcard='f0f???', field='color_hex')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req)
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')

Basic search using WildcardQuery with SearchOptions:

from couchbase.options import SearchOptions
from couchbase.search import WildcardQuery, SearchRequest

# ... other code ...

query = WildcardQuery('f0f???', field='color_hex')
req = SearchRequest.create(query)
search_res = scope.search(scope_index_name, req, SearchOptions(limit=3, fields=['*']))
for r in search_res.rows():
    print(f'Found search result: {r}')
print(f'metadata={search_res.metadata()}')
field

Restrict searching to a given document field

property wildcard: str | None

The term to match, where ? matches any one character and * any run of them.

Facets

DateFacet(field[, limit])

Counts the matches whose field falls in each of a set of date ranges.

Facet(field[, limit])

The base of the facets, each of which counts the values of one field across the matches.

NumericFacet(field[, limit])

Counts the matches whose field falls in each of a set of numeric ranges.

TermFacet(field[, limit])

Counts the most frequent terms of a field across the matches.

class couchbase.search.DateFacet(field: str, limit: int | None = None)

Counts the matches whose field falls in each of a set of date ranges.

Add at least one range with add_range() before the facet is used.

add_range(name: str, start: str | None = None, end: str | None = None) → DateFacet

Add a date range.

Parameters:
  • name – The name the range’s count is returned under.

  • start – The range’s start, in RFC 3339 format.

  • end – The range’s end, in RFC 3339 format.

Returns:

This facet, so calls can be chained.

Raises:

InvalidArgumentException – If neither start nor end is given.

property date_ranges: list[dict[str, str | int | float | bool | None | Mapping[str, Any] | Sequence[Any]]]

The ranges, each a dict of name and at least one of start and end.

class couchbase.search.Facet(field: str, limit: int | None = None)

The base of the facets, each of which counts the values of one field across the matches.

property encodable: dict[str, str | int | float | bool | None | Mapping[str, Any] | Sequence[Any]]

The facet as the Search service’s JSON, ready to serialize to JSON.

Each read builds a new object.

property field: str

The field the facet counts.

limit: _OptionalField[int]

Maximum number of facet results to return

set_prop(key: str, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any]) → None

Sets key in the facet’s JSON to value, sent as given and without validation.

The key is written over whatever the facet’s own fields encode under it, and is not read back by any of the facet’s properties.

class couchbase.search.NumericFacet(field: str, limit: int | None = None)

Counts the matches whose field falls in each of a set of numeric ranges.

Add at least one range with add_range() before the facet is used.

add_range(name: str, min: int | float | None = None, max: int | float | None = None) → NumericFacet

Add a numeric range.

Parameters:
  • name – The name the range’s count is returned under.

  • min – The range’s lower bound.

  • max – The range’s upper bound.

Returns:

This facet, so calls can be chained.

Raises:

InvalidArgumentException – If neither min nor max is given.

property numeric_ranges: list[dict[str, str | int | float | bool | None | Mapping[str, Any] | Sequence[Any]]]

The ranges, each a dict of name and at least one of min and max.

class couchbase.search.TermFacet(field: str, limit: int | None = None)

Counts the most frequent terms of a field across the matches.

Sorting

Sort(by, *[, desc, descending])

Sorts search results by by, the Search service's name for what to sort on.

SortField(field, *[, type, mode, missing, ...])

Sorts by the value of a field.

SortGeoDistance(location, field, *[, unit, ...])

Sorts by each match's distance from a point.

SortID(*[, desc, descending])

Sorts lexically by the document ID of each match.

SortScore(*[, desc, descending])

Sorts by the score of each match.

class couchbase.search.Sort(by: str, *, desc: bool | None = None, descending: bool | None = None)

Sorts search results by by, the Search service’s name for what to sort on.

You probably want one of the subclasses.

as_encodable() → str | int | float | bool | None | Mapping[str, Any] | Sequence[Any]

Get the sort as the Search service’s JSON.

Returns:

The sort, ready to serialize to JSON. Each call builds a new object.

desc: _OptionalField[bool]

Sort in descending order

property descending: bool | None

The same as desc.

set_prop(key: str, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any]) → None

Sets key in the sort’s JSON to value, sent as given and without validation.

The key is written over whatever the sort’s own fields encode under it, and is not read back by any of the sort’s properties.

class couchbase.search.SortField(field: str, *, type: str | None = None, mode: str | None = None, missing: str | None = None, desc: bool | None = None, descending: bool | None = None)

Sorts by the value of a field.

property field: str

The field to sort by.

missing: _OptionalField[str]

Where a match without the field sorts, either first or last.

mode: _OptionalField[str]

Which value of a multi-valued field to sort by, one of default, min or max.

type: _OptionalField[str]

The type to coerce the field to, one of auto, string, number or date.

class couchbase.search.SortGeoDistance(location: Sequence[float] | dict[str, float], field: str, *, unit: str | None = None, desc: bool | None = None, descending: bool | None = None)

Sorts by each match’s distance from a point.

property field: str

The field that holds each document’s location.

property location: list[float]

The point to measure from.

Set as (lon, lat) or {'lon': lon, 'lat': lat}, and read back as [lon, lat].

unit: _OptionalField[str]

Distance unit used for measuring, such as m, km or mi

class couchbase.search.SortID(*, desc: bool | None = None, descending: bool | None = None)

Sorts lexically by the document ID of each match.

class couchbase.search.SortScore(*, desc: bool | None = None, descending: bool | None = None)

Sorts by the score of each match.

Results

SearchDateRangeFacet(name, count[, start, end])

One range of a date range facet's result.

SearchFacetResult(name, field, total, ...)

The result of one facet of a search.

SearchMetaData(record)

The metadata the search service returned with a search's rows.

SearchMetrics(record)

The metrics the search service reported for a search.

SearchNumericRangeFacet(name, count[, min, max])

One range of a numeric range facet's result.

SearchRow(index, id, score, fields, ...)

One document a search matched, which the server calls a hit.

SearchRowFields(**kwargs)

The stored fields a search returned for a row, by name.

SearchRowLocation([field, term, position, ...])

One place a term of the search matched in a row.

SearchRowLocations([locations])

Every place a term of the query matched in one row, in the order the server listed them.

SearchTermFacet(term, count)

One term of a term facet's result.

class couchbase.search.SearchDateRangeFacet(name: str, count: int, start: str | None = None, end: str | None = None)

One range of a date range facet’s result.

name

The range’s name, as the facet named it.

Type:

str

count

The number of matching documents in the range.

Type:

int

start

The range’s start, if it has one.

Type:

str | None

end

The range’s end, if it has one.

Type:

str | None

class couchbase.search.SearchFacetResult(name: str, field: str, total: int, missing: int, other: int, terms: list[SearchTermFacet] | None, numeric_ranges: list[SearchNumericRangeFacet] | None, date_ranges: list[SearchDateRangeFacet] | None)

The result of one facet of a search.

name

The facet’s name, as the search named it.

Type:

str

field

The field the facet counted.

Type:

str

total

The number of values the facet counted.

Type:

int

missing

The number of matching documents without the field.

Type:

int

other

The number of values counted that fall in none of the returned terms or ranges.

Type:

int

terms

The terms of a term facet.

Type:

list[couchbase.common.search.SearchTermFacet] | None

numeric_ranges

The ranges of a numeric range facet.

Type:

list[couchbase.common.search.SearchNumericRangeFacet] | None

date_ranges

The ranges of a date range facet.

Type:

list[couchbase.common.search.SearchDateRangeFacet] | None

Each of the three lists is None for a facet of another kind, and for one the server returned without its details.

class couchbase.search.SearchMetaData(record: _SearchMetaDataRecord)

The metadata the search service returned with a search’s rows.

client_context_id() → str | None

Get the client context ID which is associated with the search.

Returns:

The client context ID, if the service sent it.

Return type:

str | None

errors() → dict[str, str]

Get the errors the index partitions that failed reported.

Returns:

Each error, by the partition that reported it.

Return type:

dict[str, str]

metrics() → SearchMetrics | None

Get the metrics the search service reported for the search.

Returns:

The search’s metrics, if the service sent them.

Return type:

SearchMetrics | None

class couchbase.search.SearchMetrics(record: _SearchMetricsRecord)

The metrics the search service reported for a search.

error_partition_count() → int

Get the number of index partitions that failed to answer the search.

Returns:

The number of partitions that failed.

Return type:

int

max_score() → float

Get the highest score of any matching document.

Returns:

The highest score.

Return type:

float

success_partition_count() → int

Get the number of index partitions that answered the search.

Returns:

The number of partitions that answered.

Return type:

int

took() → timedelta

Get the time the search took.

Returns:

The time the search took.

Return type:

timedelta

total_partition_count() → int

Get the number of index partitions the search was sent to.

Returns:

The number of partitions.

Return type:

int

total_rows() → int

Get the number of documents that matched, which can be more than the rows returned.

Returns:

The number of documents that matched.

Return type:

int

class couchbase.search.SearchNumericRangeFacet(name: str, count: int, min: int | float | None = None, max: int | float | None = None)

One range of a numeric range facet’s result.

name

The range’s name, as the facet named it.

Type:

str

count

The number of matching documents in the range.

Type:

int

min

The range’s lower bound, if it has one.

Type:

int | float | None

max

The range’s upper bound, if it has one.

Type:

int | float | None

class couchbase.search.SearchRow(index: str, id: str, score: float, fields: ~typing.Any = <factory>, locations: ~couchbase.common.search.SearchRowLocations | None = <factory>, fragments: dict = <factory>, explanation: dict = <factory>)

One document a search matched, which the server calls a hit.

index

The index partition that matched the document.

Type:

str

id

The document’s ID.

Type:

str

score

How well the document matched.

Type:

float

fields

The stored fields the search asked for.

Type:

Any

locations

Where the search’s terms matched, if the search asked for them.

Type:

couchbase.common.search.SearchRowLocations | None

fragments

Highlighted fragments of each field, if the search asked for them.

Type:

dict

explanation

How the score was computed, if the search asked for it.

Type:

dict

property sort: list

Always empty. A search row does not carry a hit’s sort values.

Deprecated since version 4.7.0.

class couchbase.search.SearchRowFields(**kwargs: Any)

The stored fields a search returned for a row, by name.

class couchbase.search.SearchRowLocation(field: str | None = None, term: str | None = None, position: int | None = None, start: int | None = None, end: int | None = None, array_positions: list[int] | None = None)

One place a term of the search matched in a row.

field

The field the term was found in.

Type:

str | None

term

The term.

Type:

str | None

position

The term’s position in the field, counted in terms.

Type:

int | None

start

The offset of the term’s first byte in the field.

Type:

int | None

end

The offset of the byte after the term’s last.

Type:

int | None

array_positions

Where the field sits in the arrays that hold it, if any do.

Type:

list[int] | None

class couchbase.search.SearchRowLocations(locations: Iterable[SearchRowLocation] | None = None)

Every place a term of the query matched in one row, in the order the server listed them.

fields() → list[str]

Get the fields with a location, in the order they first appear.

Returns:

The fields.

Return type:

list[str]

get(field: str, term: str) → list[SearchRowLocation]

Get the locations of a term in a field.

Parameters:
  • field – The field.

  • term – The term.

Returns:

The locations.

Return type:

list[SearchRowLocation]

Raises:

InvalidArgumentException – If the term has no location in the field.

get_all() → list[SearchRowLocation]

Get every location, in any field, of any term.

Returns:

The locations.

Return type:

list[SearchRowLocation]

terms() → set[str]

Get the terms with a location, in any field.

Returns:

The terms.

Return type:

set[str]

terms_for(field: str) → list[str]

Get the terms with a location in a field, in the order they first appear.

Parameters:

field – The field.

Returns:

The terms.

Return type:

list[str]

Raises:

InvalidArgumentException – If the field has no location.

class couchbase.search.SearchTermFacet(term: str, count: int)

One term of a term facet’s result.

term

The term.

Type:

str

count

The number of matching documents with the term.

Type:

int