MarkLogic 9 Product Documentation

Search Developer's Guide — Chapter 3

Query Components and Operators

Use the following components and operators to form string queries with the default search grammar:

Operator Precedence

The precedence of operators in the default grammar, from highest to lowest, is shown in the following table. Each row in the table represents a precedence level. Where multiple operators have the same precedence, evaluation occurs from left to right. Query sub-expressions using operators higher in the table are evaluated before sub-expressions using operators lower in the table.

For example, AND has higher precedence than OR, so the following queries:

A AND B OR C
A OR B AND C

Evaluate as if written as follows:

(A AND B) OR C
A OR (B AND C)

Using Relational Operators on Constraints

The relational query operators :, LT, LE, GT, GE, and NE accept a constraint name on the left hand side and a value on the right hand side. That is, queries using these operators are of the following form:

constraint op value

These relational operators match fragments that meet the named constraint with a value that matches the relationship defined by the operator (equals, less than, greater than, etc.). For example, if your query options define an element word constraint named color, then color:red matches documents that contain elements meeting the color constraint with a value of red. For details and more examples, see Constraint Options.

The constraint name must be the name of a <constraint/> XML element or "constraint" JSON object defined by the query options governing the search. The constraint can be a word, value, range, or geospatial constraint. There must be a range index associated with the constraint.

If the constraint is unbucketed, the value on the right hand side of the operator must be convertible to the type of the constraint. For example, if the range index behind the constraint has type xs:date, then the value to match must represent an xs:date.

If the constraint is bucketed, then the value must be the name of a bucket defined by the constraint. For example, if searching using the decade bucketed constraint defined in Bucketed Range Constraint Example, then the value on the right hand side must be a bucket name such as 1920s or 2000s, such as decade:1920s.

String Query Examples

The default grammar provides a robust ability to generate complex queries. The following are some examples of queries that use the default grammar:

• (cat OR dog) NEAR vet

  at least one of the terms cat or dog within 10 terms (the default distance for cts:near-query) of the word vet

• dog NEAR/30 vet

  the word dog within 30 terms of the word vet

• cat -dog

the word cat where there is no word dog

starter

A starter defines a unary prefix operator or a pair of grouping symbols. For example, the default grammar defines the minus sign ( - ) as a starter for negation and parentheses ( () ) as a grouping starter.

A grammar query option can contain 0 or more starter elements, but must contain at least one starter or joiner.

Do the following to define a unary starter operator in your grammar:

1. Identify the XQuery parsing function using the apply, at, and ns, as described in Search Customization Via Options and Extensions.
2. Put the operator token in the XML <starter/> text node or the JSON label sub-object.
3. Set strength to reflect the evaluation precedence this operator should have relative to other operators in the same grammar.
4. Set element to the QName of the cts:query element returned by the parsing function. For example, the negation operator defined by the default grammar produces a cts:not-query element.
5. Optionally, set options to a space separated list of search options to pass to the parsing function.

For example, the default grammar defines a unary - operator as follows:

<starter strength="40" apply="prefix" 
  element="cts:not-query">-</starter>

"starter": [
  {
    "strength": 40,
    "apply": "prefix",
    "element": "cts:not-query",
    "label": "-"
  }
]

Do the following to define a grouping symbol in your grammar:

1. Identify the XQuery parsing function using the apply, at, and ns, as described in Search Customization Via Options and Extensions.
2. Put the grouping start token in the XML <starter/> text node or the JSON label sub-object.
3. Set delimiter to the grouping end token.
4. Set strength to reflect the evaluation precedence this operator should have relative to other operators in the same grammar.
5. Set element to the QName of the cts:query element returned by the parsing function. For example, the negation operator defined by the default grammar produces a cts:not-query element.
6. Optionally, set options to a space separated list of search options to pass to the parsing function.

For example, the default grammar defines ( ) as grouping tokens as follows:

<starter strength="30" apply="grouping" 
  delimiter=")">(</starter>

"starter": [
  {
    "strength": 30,
    "apply": "grouping",
    "delimiter": ")",
    "label": "("
  }
]

joiner

A joiner defines a binary operator that joins two string query expressions. Examples of joiners in the default grammar include AND, OR, LT, and colon ( : ).

A grammar query option can contain 0 or more joiners, but must contain at least one starter or joiner.

Do the following to define a joiner:

1. Identify the XQuery parsing function using the apply, at, and ns, as described in Search Customization Via Options and Extensions.
2. Put the operator token or symbol in the XML <joiner/> text node or the JSON label sub-object.
3. Set strength to reflect the evaluation precedence this operator should have relative to other operators in the same grammar.
4. Set element to the QName of the cts:query element returned by the parsing function. For example, the AND operator defined by the default grammar produces a cts:and-query element.
5. Optionally, set options to a space separated list of search options to pass to the parsing function.

To define a prefix operator, put the operator token in the XML <starter/> text node or the JSON label sub-object. For example, the default grammar defines a unary - operator as follows:

<starter strength="40" apply="prefix" 
  element="cts:not-query">-</starter>

"starter": [
  {
    "strength": 40,
    "apply": "prefix",
    "element": "cts:not-query",
    "label": "-"
  }
]

quotation

The quotation grammar element defines symbol used to demarcate phrases. The default grammar uses double quotes ( " ):

<quotation>"</quotation>

A grammar can contain at most one quotation definition.

In XML, place the symbol in the text node of the <quotation/> element. In JSON, place the symbol in the string value associated with the quotation key. For example, to use percent ( % ) instead of double quotes for phrases, include the following in your grammar:

<quotation>%</quotation>

"quotation": "%"

implicit

The implicit grammar element specifies how to handle adjacent terms that are are not separated by an explicit joiner operator. For example, how to interpret a string query such as cat dog. A grammar query option can contain at most one implicit rule.

Do the following to define an implicit operation:

1. Select a query type from the cts:query hierarchy defined in cts:query Hierarchy.
2. If you are building XML query options, add a child element of the appropriate type to the <implicit/> element. You can build this using the cts:query constructors. For example, you can construct an empty cts:and-query by evaluating cts:and-query((), ()).
3. If you are building JSON query options, set the value associated with the implicit key to the serialized representation of the cts:query element type selected in Step 1.

For example, the default grammar includes an implicit rule that specifies cts:and-query as the implicit operation, so cat dog is equivalent to cat AND dog:

<implicit>
  <cts:and-query
    xmlns:cts="http://marklogic.com/cts"/>
</implicit>

"implicit":
  "<cts:and-query xmlns='http://marklogic.com/cts'/>"