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.
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_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
-
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
-
property
-
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
-
property
-
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
-
property
-
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
-
property
-
class
couchbase_core.fulltext.
BooleanFieldQuery
(term, **kwargs)[source]¶ -
property
bool
¶ Boolean value to search for
-
property
field
¶ Restrict searching to a given document field
-
property
-
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
Example:
QueryStringQuery('description:water and stuff')
-
property
query
¶ Actual query string
-
property
-
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
-
property
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.
-
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_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
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_core.fulltext.
ConjunctionQuery
(*queries)[source]¶ Compound query in which all sub-queries passed must be satisfied
-
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
-
property
-
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
-
property
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
-
property
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
(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
(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
-
property
-
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 tofacets
.-
add_range
(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 toParams.facets