Search
Requests
|
How a search marks the matched terms in the fragments it returns: with ANSI escape codes, or HTML. |
|
How a match query combines the terms it analyzes its text into. |
|
Base query object. |
|
A search query, a vector search, or both, to run on the Search service. |
|
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.
See also
MatchQuery,BooleanQuery,RegexQuery,PrefixQuery,NumericRangeQuery,DateRangeQuery,ConjunctionQuery,DisjunctionQuery, and others in this module.- 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
keyin the query’s JSON tovalue, 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.
- 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 withwith_search_query()orwith_vector_search().- Raises:
InvalidArgumentException – If query is neither.
- classmethod create(query: SearchQuery | VectorSearch) SearchRequest
Creates a
SearchRequest.- Parameters:
query (
SearchQuery|VectorSearch) – ASearchQueryorVectorSearchto initialize the search request.- Raises:
InvalidArgumentException – If neither a
SearchQueryorVectorSearchis provided.- Returns:
The created search request.
- Return type:
- property search_query: SearchQuery | None
The request’s search query, or None if it has none.
- property vector_search: VectorSearch | None
The request’s vector search, or None if it has none.
- with_search_query(query: SearchQuery) SearchRequest
Add a
SearchQueryto the search request.- Parameters:
query (
SearchQuery) – TheSearchQueryto 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:
- with_vector_search(vector_search: VectorSearch) SearchRequest
Add a
VectorSearchto the search request.- Parameters:
vector_search (
VectorSearch) – TheVectorSearchto 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:
- 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_BOUNDEDreads the index as it is.REQUEST_PLUSwaits until the index holds every mutation made before the search.AT_PLUSwaits until it holds the mutations given as theconsistent_withoption.- AT_PLUS = 'at_plus'
- NOT_BOUNDED = 'not_bounded'
- REQUEST_PLUS = 'request_plus'
Queries
|
A query for documents whose field holds a boolean value. |
|
A compound query that specifies multiple child queries. |
|
A compound query that specifies multiple child queries. |
|
A query for documents whose field holds a date in a range. |
|
A compound query that specifies multiple child queries. |
|
A query for the documents with the given IDs. |
|
A query for documents with a location inside a rectangle. |
|
A query for documents with a location within a distance of a point. |
|
A query for documents with a location inside a polygon. |
|
A query that matches every document. |
|
A query that matches no document. |
|
A query for documents holding a phrase, which the server analyzes into terms first. |
|
A query for documents matching a text, which the server analyzes into terms first. |
|
A query for documents whose field holds a number in a range. |
|
A query for documents holding terms together and in order, in one field. |
|
A query for documents holding a term that starts with a prefix. |
|
Query that specifies the Search Service should search for a match to the specified query string. |
|
A query given as its JSON, for parameters or query types the other classes do not cover. |
|
A query for documents holding a term that matches a regular expression. |
|
Query that specifies the Search Service should search for an exact match to the specified term. |
|
A query for documents holding a term in a range, in lexical order. |
|
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()}')
- 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
minof, or None if not set.
- 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
conjunctsis 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_inclusive: bool | None
DEPRECATED The same as
inclusive_end.Deprecated since version 4.4.0: Use
inclusive_endinstead.
- field
Restrict searching to a given document field
- property start_inclusive: bool | None
DEPRECATED The same as
inclusive_start.Deprecated since version 4.4.0: Use
inclusive_startinstead.
- 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
minproperty 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
minof.
- validate() None
Check that the query has child queries, and at least
minof them.- Raises:
NoChildrenException – If
disjunctsis empty.InvalidArgumentException – If
minis more than the number of queries.
- 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()}')
- validate() None
Check that the query has at least one ID.
- Raises:
NoChildrenException – If
idsis 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
- 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()}')
- field
Restrict searching to a given document field
- 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
- 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
- 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_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
ororand.
- 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 max_inclusive: bool | None
DEPRECATED The same as
inclusive_max.Deprecated since version 4.4.0: Use
inclusive_maxinstead.
- property min_inclusive: bool | None
DEPRECATED The same as
inclusive_min.Deprecated since version 4.4.0: Use
inclusive_mininstead.
- 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
fieldproperty 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, useMatchPhraseQuery.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
- validate() None
Check that the query has at least one term.
- Raises:
NoChildrenException – If
termsis 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
- 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
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()}')
- 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:
boostandset_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
- 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
- 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
maxinstead.
- property end_inclusive: bool | None
DEPRECATED The same as
inclusive_max.Deprecated since version 4.4.0: Use
inclusive_maxinstead.
- field
Restrict searching to a given document field
- property start: str | None
DEPRECATED The same as
min.Deprecated since version 4.4.0: Use
mininstead.
- property start_inclusive: bool | None
DEPRECATED The same as
inclusive_min.Deprecated since version 4.4.0: Use
inclusive_mininstead.
- 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
Facets
|
Counts the matches whose field falls in each of a set of date ranges. |
|
The base of the facets, each of which counts the values of one field across the matches. |
|
Counts the matches whose field falls in each of a set of numeric ranges. |
|
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
startnorendis given.
- 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.
- set_prop(key: str, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any]) None
Sets
keyin the facet’s JSON tovalue, 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
minnormaxis given.
Sorting
|
Sorts search results by |
|
Sorts by the value of a field. |
|
Sorts by each match's distance from a point. |
|
Sorts lexically by the document ID of each match. |
|
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.
See also
SortScore,SortID,SortFieldandSortGeoDistance.- 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.
- set_prop(key: str, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any]) None
Sets
keyin the sort’s JSON tovalue, 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.
- 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.
Results
|
One range of a date range facet's result. |
|
The result of one facet of a search. |
|
The metadata the search service returned with a search's rows. |
|
The metrics the search service reported for a search. |
|
One range of a numeric range facet's result. |
|
One document a search matched, which the server calls a hit. |
|
The stored fields a search returned for a row, by name. |
|
One place a term of the search matched in a row. |
|
Every place a term of the query matched in one row, in the order the server listed them. |
|
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.
- 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.
- terms
The terms of a term facet.
- Type:
- 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:
Each of the three lists is
Nonefor 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
- 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:
- max_score() float
Get the highest score of any matching document.
- Returns:
The highest score.
- Return type:
- success_partition_count() int
Get the number of index partitions that answered the search.
- Returns:
The number of partitions that answered.
- Return type:
- 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.
- 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.
- fields
The stored fields the search asked for.
- Type:
Any
- locations
Where the search’s terms matched, if the search asked for them.
- Type:
- 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.
- 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.
- 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]