Full Text Queries

Full-text queries search the cluster for documents matching certain terms or strings of texts. Unlike N1QL queries which are designed to be structured, i.e. ensuring that a given document field matches a given value, full-text queries are more free-form, allowing the ability to search multiple fields and to add variance in queries.

Couchbase offers full-text queries in version 4.5. To issue a query from the Python SDK, use the search() cluster method.

To perform an actual search, define a search index (via Couchbase web UI, or using the REST interface), create a Query object and then pass the index name and the query object to the search method:

query = ConjunctionQuery(TermQuery("couchbase"), MatchQuery("nosql"))
for hit in cluster.search('indexName', query):
    print(hit)

The above query searches for any document which has both nosql and couchbase in any of its fields. Note that PhraseQuery may be better suited for this kind of query

query = PhraseQuery('couchbase', 'nosql')
for hit in cluster.search('indexName', query):
    print(hit)

Query Types

You may issue simple match queries (MatchQuery) to inspect a user term; TermQuery to match a field exactly, PrefixQuery for type-ahead queries, or a compound query type such as ConjunctionQuery for more complex queries.

class couchbase.search.SearchQuery[source]

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

property boost

When specifying multiple queries, you can give this query a higher or lower weight in order to prioritize it among sibling queries. See ConjunctionQuery

property encodable

Returns an object suitable for serializing to JSON

json.dumps(query.encodable)
validate(self)[source]

Optional validation function. Invoked before encoding

Match Queries

class couchbase.search.MatchQuery(term, **kwargs)[source]

Query which checks one or more fields for a match

property analyzer

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

property field

Restrict searching to a given document field

property 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 a float

property match

String to search for

property 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.MatchPhraseQuery(term, **kwargs)[source]

Search documents which match a given phrase. The phrase is composed of one or more terms.

Example:

MatchPhraseQuery("Hello world!")
property analyzer

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

property field

Restrict searching to a given document field

property match_phrase

Phrase to search for

class couchbase.search.PrefixQuery(term, **kwargs)[source]

Search documents for fields beginning with a certain prefix. This is most useful for type-ahead or lookup queries.

property field

Restrict searching to a given document field

property prefix

The prefix to match

class couchbase.search.RegexQuery(term, **kwargs)[source]

Search documents for fields matching a given regular expression

property field

Restrict searching to a given document field

property regex

Regular expression to use

class couchbase.search.WildcardQuery(term, **kwargs)[source]

Query in which the characters * and ? have special meaning, where ? matches 1 occurrence and * will match 0 or more occurrences of the previous character

property field

Restrict searching to a given document field

property wildcard

Wildcard pattern to use

class couchbase.search.BooleanFieldQuery(term, **kwargs)[source]
property bool

Boolean value to search for

property field

Restrict searching to a given document field

class couchbase.search.QueryStringQuery(term, **kwargs)[source]

Query which allows users to describe a query in a query language. The server will then execute the appropriate query based on the contents of the query string:

See also

Query Language

Example:

QueryStringQuery('description:water and stuff')
property query

Actual query string

class couchbase.search.DocIdQuery(term, **kwargs)[source]

Matches document IDs. This is must useful in a compound query (for example, BooleanQuery). When used as a criteria, only documents with the specified IDs will be searched.

property ids

List of document IDs to use

validate(self)[source]

Optional validation function. Invoked before encoding

Range Queries

class couchbase.search.NumericRangeQuery(min=None, max=None, **kwargs)[source]

Search documents for fields containing a value within a given numerical range.

At least one of min or max must be specified.

Parameters
  • min (float) – See min

  • max (float) – See max

property field

Restrict searching to a given document field

property max

Upper bound of range. See max_inclusive

property max_inclusive

Whether matches are inclusive of upper bound

property min

Lower bound of range. See min_inclusive

property min_inclusive

Whether matches are inclusive of lower bound

class couchbase.search.DateRangeQuery(start=None, end=None, **kwargs)[source]

Search documents for fields containing a value within a given date range.

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>_.

The start and end parameters should be specified in the constructor. Note that either start or end (but not both!) may be omitted.

DateRangeQuery(start='2014-12-25', end='2016-01-01')
Parameters
  • start (str) – Start of date range

  • end (str) – End of date range

  • kwargs – Additional options: field, boost

property datetime_parser

Parser to use when analyzing the start and end fields on the server.

If not specified, the RFC 3339 parser is used. Ensure to specify start and end in a format suitable for the given parser.

property end

Upper bound datetime

property end_inclusive

If end is inclusive

property field

Restrict searching to a given document field

property start

Lower bound datetime

property start_inclusive

If start is inclusive

Compound Queries

class couchbase.search.ConjunctionQuery(*queries)[source]

Compound query in which all sub-queries passed must be satisfied

validate(self)[source]

Optional validation function. Invoked before encoding

class couchbase.search.DisjunctionQuery(*queries, **kwargs)[source]

Compound query in which at least min or more queries must be satisfied

property min

Number of queries which must be satisfied

validate(self)[source]

Optional validation function. Invoked before encoding

class couchbase.search.BooleanQuery(must=None, should=None, must_not=None)[source]
property encodable

Returns an object suitable for serializing to JSON

json.dumps(query.encodable)
property must

Queries which must be satisfied. When setting this attribute, the SDK will convert value to a ConjunctionQuery if the value is a list of queries.

property must_not

Queries which must not be satisfied. Documents found which satisfy the queries in this clause are not returned in the match.

When setting this attribute in the SDK, it will be converted to a DisjunctionQuery if the value is a list of queries.

property should

Specify additional queries which should be satisfied. As opposed to must, you can specify the number of queries in this field which must be satisfied.

The type of this attribute is DisjunctionQuery, and you can set the minimum number of queries to satisfy using:

boolquery.should.min = 1
validate(self)[source]

Optional validation function. Invoked before encoding

Debugging Queries

class couchbase.search.MatchAllQuery(**kwargs)[source]

Special query which matches all documents

class couchbase.search.MatchNoneQuery(**kwargs)[source]

Special query which matches no documents

class couchbase.search.TermQuery(term, **kwargs)[source]

Searches for a given term in documents. Unlike MatchQuery, the term is not analyzed.

Example:

TermQuery('lcb_cntl_string')
property field

Restrict searching to a given document field

property 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 a float

property 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

Exact term to search for

class couchbase.search.PhraseQuery(*phrases, **kwargs)[source]
property field

Restrict searching to a given document field

property terms

List of terms to search for

validate(self)[source]

Optional validation function. Invoked before encoding

Parameters

Query parameters may be passed as the options keyword argument to search().

class couchbase.search.SearchOptions() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)[source]

Search Options

These options apply to a Full Text Search query.

Parameters
  • timeout (timedelta) – Timeout to use for this query. If not set, the default cluster-wide timeout is used search_timeout()

  • limit (int) – Limit the results returned.

  • skip (int) – Skip the first N results.

  • explain (bool) – Include an explaination of the search result scores.

  • fields (Iterable[str]) – List of fields to return, if they exist on the document.

  • highlight_style (HighlightStyle) – Style to render the highlights. See HighlighStyle for details.

  • highlight_fields (Iterable[str]) – Fields to highlight. If this is not specified, all fields returned are highlighted.

  • scan_consistency (QueryScanConsistency) – Scan Consistency to use for this query. See QueryScanConsistency for details.

  • consistent_with (MutationState) – Specify a consistency using MutationState.

  • facets (Iterable[str,Facet]) – Specify a set of Facet objects that aggregate the result data.

  • raw (dict[str,JSON]) – A way to support unknown commands, and be future-compatible.

  • sort (Iterable[Sort]) – List of various Sort objects to sort the results.

class SearchParamsInternal(iterargs, itercls, params)

Create new instance of SearchParamsInternal(iterargs, itercls, params)

iterargs

Alias for field number 0

itercls

Alias for field number 1

params

Alias for field number 2

Facets

Facets allow additional aggregate information to be returned in the results. You can count how many documents match specific criteria based on ranges and matches.

class couchbase.search.TermFacet(field, limit=0)[source]

Facet aggregating the most frequent terms used.

property limit

Maximum number of terms/count pairs to return

class couchbase.search.DateFacet(field)[source]

Facet to aggregate results based on a date range. This facet must have at least one invocation of add_range() before it is added to facets.

add_range(self, name, start=None, end=None)[source]

Adds a date range to the given facet.

Parameters
  • name (str) – The name by which the results within the range can be accessed

  • start (str) – Lower date range. Should be in RFC 3339 format

  • end (str) – Upper date range.

Returns

The DateFacet object, so calls to this method may be chained

class couchbase.search.NumericFacet(field)[source]

Facet to aggregate results based on a numeric range. This facet must have at least one invocation of add_range() before it is added to Params.facets

add_range(self, name, min=None, max=None)[source]

Add a numeric range.

Parameters
  • name (str) – the name by which the range is accessed in the results

  • | float min (int) – Lower range bound

  • | float max (int) – Upper range bound

Returns

This object; suitable for method chaining