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() bucket method.

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

query = ConjunctionQuery(TermQuery("couchbase"), MatchQuery("nosql"))
for hit in bucket.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 bucket.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.fulltext.SearchQuery

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.

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

encodable

Returns an object suitable for serializing to JSON

json.dumps(query.encodable)

validate()

Optional validation function. Invoked before encoding

Match Queries

class couchbase.fulltext.MatchQuery(term, **kwargs)

Query which checks one or more fields for a match

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

match

String to search for

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.fulltext.MatchPhraseQuery(term, **kwargs)

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

Example:

MatchPhraseQuery("Hello world!")

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

match_phrase

Phrase to search for

class couchbase.fulltext.PrefixQuery(term, **kwargs)

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

field

Restrict searching to a given document field

prefix

The prefix to match

class couchbase.fulltext.RegexQuery(term, **kwargs)

Search documents for fields matching a given regular expression

field

Restrict searching to a given document field

regex

Regular expression to use

class couchbase.fulltext.WildcardQuery(term, **kwargs)

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

field

Restrict searching to a given document field

wildcard

Wildcard pattern to use

class couchbase.fulltext.BooleanFieldQuery(term, **kwargs)

bool

Boolean value to search for

field

Restrict searching to a given document field

class couchbase.fulltext.StringQuery(term, **kwargs)

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:

StringQuery('description:water and stuff')

query

Actual query string

class couchbase.fulltext.DocIdQuery(term, **kwargs)

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.

ids

List of document IDs to use

Range Queries

class couchbase.fulltext.NumericRangeQuery(min=None, max=None, **kwargs)

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

field

Restrict searching to a given document field

max

Upper bound of range. See max_inclusive

max_inclusive

Whether matches are inclusive of upper bound

min

Lower bound of range. See min_inclusive

min_inclusive

Whether matches are inclusive of lower bound

class couchbase.fulltext.DateRangeQuery(start=None, end=None, **kwargs)

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

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.

end

Upper bound datetime

end_inclusive

If end is inclusive

field

Restrict searching to a given document field

start

Lower bound datetime

start_inclusive

If start is inclusive

Compound Queries

class couchbase.fulltext.ConjunctionQuery(*queries)

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

class couchbase.fulltext.DisjunctionQuery(*queries, **kwargs)

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

min

Number of queries which must be satisfied

class couchbase.fulltext.BooleanQuery(must=None, should=None, must_not=None)

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.

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.

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

Debugging Queries

class couchbase.fulltext.MatchAllQuery(**kwargs)

Special query which matches all documents

class couchbase.fulltext.MatchNoneQuery(**kwargs)

Special query which matches no documents

class couchbase.fulltext.TermQuery(term, **kwargs)

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

Example:

TermQuery('lcb_cntl_string')

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

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.

term

Exact term to search for

class couchbase.fulltext.PhraseQuery(*phrases, **kwargs)

field

Restrict searching to a given document field

terms

List of terms to search for

Parameters

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

class couchbase.fulltext.Params(**kwargs)

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)

explain

Whether to return the explanation of the search

fields

Return these fields for each document

highlight_fields

Highlight the results from these fields (list)

highlight_style

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

limit

Maximum number of results to return

skip

Seek by this number of results

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

Facet aggregating the most frequent terms used.

limit

Maximum number of terms/count pairs to return

class couchbase.fulltext.DateFacet(field)

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(name, start=None, end=None)

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.fulltext.NumericFacet(field)

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(name, min=None, max=None)

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