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_core.fulltext.Query[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_core.fulltext.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_core.fulltext.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_core.fulltext.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_core.fulltext.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_core.fulltext.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_core.fulltext.BooleanFieldQuery(term, **kwargs)[source]
property bool

Boolean value to search for

property field

Restrict searching to a given document field

class couchbase_core.fulltext.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_core.fulltext.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_core.fulltext.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_core.fulltext.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_core.fulltext.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_core.fulltext.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_core.fulltext.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_core.fulltext.MatchAllQuery(**kwargs)[source]

Special query which matches all documents

class couchbase_core.fulltext.MatchNoneQuery(**kwargs)[source]

Special query which matches no documents

class couchbase_core.fulltext.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_core.fulltext.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 params keyword argument to search().

class couchbase_core.fulltext.Params(**kwargs)[source]

Generic parameters and query modifiers. Keyword arguments may be used to initialize instance attributes. See individual attributes for more information.

facets

A dictionary of Facet objects. The dictionary uses the facet name for keys. You can retrieve the facet results by their name as well.

You can add facets like so:

params.facets['term_analysis'] = TermFacet('author', limit=10)
params.facets['view_count'] = NumericFacet().add_range('low', max=50)
as_encodable(self, index_name)[source]
Parameters

index_name – The name of the index for the query

Returns

A dict suitable for passing to json.dumps()

property consistency

Consistency for the query. Use this for ‘fixed’ consistency, or to clear consistency.

You might want to use consistent_with() for consistency that is bounded to specific mutations

consistent_with(self, ms)[source]

Ensure that this query is consistent with the given mutations. When set, this ensures that only document versions as or more recent than the provided mutations are used for the search. This is often helpful when attempting searches on newly inserted documents. :param ms: Mutation State :type ms: couchbase_core.mutation_state.MutationState

property explain

Whether to return the explanation of the search

property fields

Return these fields for each document

property highlight_fields

Highlight the results from these fields (list)

property highlight_style

Highlight the results using a given style. Can be either ansi or html

property limit

Maximum number of results to return

property skip

Seek by this number of results

property sort

Specify a list of fields by which to sort the results. Can also be a Sort class

property timeout

Timeout for the query, in seconds

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_core.fulltext.TermFacet(field, limit=0)[source]

Facet aggregating the most frequent terms used.

property limit

Maximum number of terms/count pairs to return

class couchbase_core.fulltext.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_core.fulltext.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