Query String Query

A query string can be used, to express a given query by means of a special syntax.

{ "query": "+nice +view" }

A demonstration of a query string Query using the Java SDK can be found in Searching from the SDK.

The Full Text Searches conducted with the Couchbase Web Console themselves use query strings. (See Searching from the UI.)

Certain queries supported by FTS are not yet supported by the query string syntax. These include wildcards and regular expressions.

Query strings enable you to describe complex queries using a simple syntax. Following subsections provide the ways in which a user can modify the query string to represent a query with complex logic.

Boosting

When you specify multiple query-clauses, you can specify the relative importance to a given clause by suffixing it with the ^ operator, followed by a number or by specifying the boost parameter with the number to boost the search.

Example

description:pool name:pool^5

The above syntax performs Match Queries for pool in both the name and description fields, but documents having the term in the name field score higher.

"query": {
    "disjuncts": [
         {
      "match": "glossop",
      "field": "city",
      "boost": 10
    },
         {
      "match": "glossop",
      "field": "title"
    }
  ]
}

The above syntax performs Match Queries for a city glossop in both the city and title fields, but documents having the term in the city field score higher.

Date Range

You can perform date range searches by using the >, >=, <, and <= operators, followed by a date value in quotes.

For example, created:>"2016-09-21" will perform a date range query on the created field for values after September 21, 2016.

Escaping

The following quoted-string enumerates the characters which may be escaped:

"+-=&|><!(){}[]^\"~*?:\\/ "

This list contains the space character.

In order to escape these characters, they are prefixed with the \ (backslash) character. In all cases, using the escaped version produces the character itself and is not interpreted by the lexer.

For example:

my\ name is interpreted as a single argument to a match query with the value "my name".
"contains a\" character" is interpreted as a single argument to a phrase query with the value contains a " character.

Field Scoping

You can specify the field in which a search needs to be performed by prefixing the term with a field-name, separated by a colon.

The field-name may be a path to a field, using dot notation. The path must use Search syntax rather than N1QL syntax; in other words, you cannot specify array locations such as [*] or [3] in the path.

Required, Optional, and Exclusion

When a query string includes multiple items, by default these are placed into the SHOULD clause of a Boolean Query. You can adjust this by prefixing items with + or -.

Prefixing with + places that item in the MUST portion of the boolean query.
Prefixing with - places that item in the MUST NOT portion of the boolean query.

Example

For example, description:pool performs a match query for the term pool, in the description field.

For example, +description:pool -continental breakfast performs a boolean query that MUST satisfy the match query for the term pool in the description field, MUST NOT satisfy the match query for the term continental in the default field, and SHOULD satisfy the match query for the term breakfast in the default field. Result documents satisfying the SHOULD clause score higher than those that do not.

Match Phrase

Placing the search terms in quotes performs a match phrase query.

This query searches for terms in the target that occur in the positions and offsets indicated by the input: this depends on term_vectors, which must have been included in the creation of the index used for the search.

Example

"continental breakfast" performs a match phrase query for the phrase continental breakfast.

Match Query Syntax

A term without any other syntax is interpreted as a match query for the term in the default field.

The default field is _all.

For example, pool performs a match query for the term pool.

Example

The following JSON object demonstrates specification of a match query:

{
 "match": "location hostel",
 "field": "reviews.content",
 "analyzer": "standard",
 "fuzziness": 2,
 "prefix_length": 4,
 "operator": "and"
}

Numeric Ranges

You can specify numeric ranges with the >, >=, <, and <= operators, each followed by a numeric value.

Example

reviews.ratings.Cleanliness:>4 performs a numeric range query on the reviews.ratings.Cleanliness field, for values greater than 4.