Queries

You can use queries to be selective about data returned by OCAPI, which reduces network bandwidth.

query

A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

match_all_query - returns all records.
term_query - matches records where a field (or fields) exactly match some simple value (including null).
text_query - matches records where a field (or fields) contain a search phrase.
boolean_query - formulates a complex boolean expression using query objects as criteria.
filtered_query - allows for filtering of records based on both a query and a filter.

Queries can also contain nested queries.

match_all_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

Example:

1"query":{
2   "match_all_query":{}
3}

term_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator “is” can only take one value, while “one_of” can take multiple values. If multiple fields are specified, they are combined using the OR operator. The less and greater operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query.

Elastic only: If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

Example: (id=“my_id”)

1"query":{
2   "term_query":{
3      "fields":["id"],
4      "operator":"is",
5      "values":["my_id"]
6   }
7}

Example: (id IN (“my_id”,“other_id”))

1"query":{
2   "term_query":{
3      "fields":["id"],
4      "operator":"one_of",
5      "values":[
6         "my_id",
7         "other_id"
8      ]
9   }
10}

Example: (id=null)

1"query":{
2   "term_query":{
3      "fields":[
4         "description"
5      ],
6      "operator":"is_null"
7   }
8}

Example: ((id IN (‘generic’, ‘keyword’)) OR (description IN (‘generic’, ‘keyword’))

1"query":{
2   "term_query":{
3      "fields":[
4         "id",
5         "description"
6      ],
7      "operator":"one_of",
8      "values":[
9         "generic",
10         "keyword"
11      ]
12   }
13}

Property	Type	Constraints	Description
fields	[String]	mandatory=true, minItems=1, nullable=false	The document field(s), the value(s) are matched against, combined with the operator.
operator	Enum {is, one_of, is_null, is_not_null, less, greater, not_in, neq}	mandatory=true, nullable=false	Returns the operator to use for the term query.
values	[Object]		The values, the field(s) are compared against, combined with the operator.

text_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

Example: (coupon_id contains “xmas” )

1"query":{
2   "text_query":{
3      "fields":[
4         "coupon_id"
5      ],
6      "search_phrase":"xmas"
7   }
8}

Example: (coupon_id contains “xmas” OR description contains “xmas”)

1"query":{
2   "text_query":{
3      "fields":[
4         "description",
5         "coupon_id"
6      ],
7      "search_phrase":"xmas"
8   }
9}

Example: (description contains “holiday” AND description contains “bojo”)

1"query":{
2   "text_query":{
3      "fields":[
4         "description"
5      ],
6      "search_phrase":"holiday bogo"
7   }
8}

Property	Type	Constraints	Description
fields	[String]	mandatory=true, minItems=1, nullable=false	The document fields the search phrase has to match against.
search_phrase	String	mandatory=true, nullable=false	A search phrase, which may consist of multiple terms.

boolean_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that ‘must’, ‘should’ and / or ‘must not’ match. If ‘must’, ‘must_not’, or ‘should’ appear in the same boolean query, they are combined logically using the AND operator. Example: (id = ‘foo’ AND description LIKE ‘bar’)

1"query":{
2   "bool_query":{
3      "must":[
4         {
5            "term_query":{
6               "fields":[
7                  "id"
8               ],
9               "operator":"is",
10               "values":[
11                  "foo"
12               ]
13            }
14         },
15         {
16            "text_query":{
17               "fields":[
18                  "description"
19               ],
20               "search_phrase":"bar"
21            }
22         }
23      ]
24   }
25}

Example: (id = ‘foo’ OR description LIKE ‘bar’)

1"query":{
2   "bool_query":{
3      "should":[
4         {
5            "term_query":{
6               "fields":[
7                  "id"
8               ],
9               "operator":"is",
10               "values":[
11                  "foo"
12               ]
13            }
14         },
15         {
16            "text_query":{
17               "fields":[
18                  "description"
19               ],
20               "search_phrase":"bar"
21            }
22         }
23      ]
24   }
25}

Example: (NOT (id = ‘foo’ OR description LIKE ‘bar’))

1"query":{
2   "bool_query":{
3      "must_not":[
4         {
5            "term_query":{
6               "fields":[
7                  "id"
8               ],
9               "operator":"is",
10               "values":[
11                  "foo"
12               ]
13            }
14         },
15         {
16            "text_query":{
17               "fields":[
18                  "description"
19               ],
20               "search_phrase":"bar"
21            }
22         }
23      ]
24   }
25}

Example: ((coupon_id LIKE “limit” AND description LIKE “limit per customer”) AND NOT (enabled=false))

1"query":{
2   "bool_query":{
3      "must":[
4         {
5            "text_query":{
6               "fields":[
7                  "coupon_id"
8               ],
9               "search_phrase":"limit"
10            }
11         },
12         {
13            "text_query":{
14               "fields":[
15                  "description"
16               ],
17               "search_phrase":"limit per customer"
18            }
19         }
20      ],
21      "must_not":[
22         {
23            "term_query":{
24               "fields":[
25                  "enabled"
26               ],
27               "operator":"is",
28               "values":[
29                  false
30               ]
31            }
32         }
33      ]
34   }
35}

Property	Type	Description
must	[query {boolean_query, match_all_query, filtered_query, nested_query, term_query, text_query}]	List of queries that must match.
must_not	[query {boolean_query, match_all_query, filtered_query, nested_query, term_query, text_query}]	List of queries that must not match.
should	[query {boolean_query, match_all_query, filtered_query, nested_query, term_query, text_query}]	List of queries that should match.

Queries can be nested.

filtered_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter. Example:

1"query":{
2   "filtered_query":{
3      "query":{
4         "text_query":{
5            "fields":[
6               "coupon_id"
7            ],
8            "search_phrase":"disabled"
9         }
10      },
11      "filter":{
12         "term_filter":{
13            "field":"enabled",
14            "operator":"is",
15            "values":[
16               false
17            ]
18         }
19      }
20   }
21}

Property	Type	Constraints	Description
filter	Filter {BoolFilter, QueryFilter, Range2Filter, RangeFilter, TermFilter}	mandatory=true, nullable=false	The (possibly complex) filter object.
query	[query {boolean_query, match_all_query, filtered_query, nested_query, term_query, text_query}]	mandatory=true, nullable=false	The query object.

nested_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types.

Example: finds all the documents that has firstname = “John” and lastname = “Doe”

1{
2  "query": {
3    "bool_query": {
4      "must": [
5        {
6          "nested_query": {
7            "path": "order.shipping_addresses",
8            "query": {
9              "bool_query": {
10                "must": [
11                  {
12                    "bool_query": {
13                      "must": [
14                        {
15                          "term_query": {
16                            "fields": [
17                              "order.shipping_addresses.first_name"
18                            ],
19                            "operator": "is",
20                            "values": [
21                              "John"
22                            ]
23                          }
24                        }
25                      ]
26                    }
27                  },
28                  {
29                    "bool_query": {
30                      "must": [
31                        {
32                          "term_query": {
33                            "fields": [
34                              "order.shipping_addresses.last_name"
35                            ],
36                            "operator": "is",
37                            "values": [
38                              "Doe"
39                            ]
40                          }
41                        }
42                      ]
43                    }
44                  }
45                ]
46              }
47            },
48            "score_mode": "avg"
49          }
50        }
51      ]
52    }
53  }
54}

Property	Type	Constraints
path	[String]
query	[query {boolean_query, match_all_query, filtered_query, nested_query, term_query, text_query}]	mandatory=true, nullable=false
score_mode	Enum {avg, total, max, none}

Attention!

The Open Commerce API (OCAPI) is now deprecated. The provisions described in our versioning and deprecation policy fully apply. For all new projects and major refactoring work, use B2C Commerce API (SCAPI) as the default REST API. For additional details, refer to Why Use SCAPI Instead of OCAPI.

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!