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.
See also
MatchQuery
,BooleanQuery
,RegexQuery
,PrefixQuery
,NumericRangeQuery
,DateRangeQuery
,ConjunctionQuery
,DisjunctionQuery
, and others in this module.-
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)
-
property
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
-
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
-
property
-
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
-
property
-
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
-
property
-
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
-
property
-
class
couchbase.search.
BooleanFieldQuery
(term, **kwargs)[source]¶ -
property
bool
¶ Boolean value to search for
-
property
field
¶ Restrict searching to a given document field
-
property
-
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
Example:
QueryStringQuery('description:water and stuff')
-
property
query
¶ Actual query string
-
property
-
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
-
property
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.
-
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
-
property
-
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
andend
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
andend
fields on the server.If not specified, the RFC 3339 parser is used. Ensure to specify
start
andend
in a format suitable for the given parser.
-
property
end
¶ Upper bound datetime
-
property
field
¶ Restrict searching to a given document field
-
property
start
¶ Lower bound datetime
Compound Queries¶
-
class
couchbase.search.
ConjunctionQuery
(*queries)[source]¶ Compound query in which all sub-queries passed must be satisfied
-
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
-
property
-
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
-
property
Debugging Queries¶
-
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
-
property
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.
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
-
property
-
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 tofacets
.-
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 toParams.facets