Search Developer's Guide — Chapter 6

cts:query Hierarchy

The cts:query type forms a hierarchy, allowing you to construct complex cts:query expressions by combining multiple expressions together. The hierarchy includes composable and non-composable cts:query constructors.

A composable constructor is one that is used to combine multiple cts:query constructors together. A leaf-level constructor is one that cannot be used to combine with other cts:query constructors (although it can be combined using a composable constructor).

The following diagram shows the leaf-level cts:query constructors, which are not composable, and the composable cts:query constructors, which you can use to combine both leaf-level and other composable cts:query constructors. The diagram shows most of the available constructors, but not necessarily all of them.

Equivalent constructors exist for Server-Side JavaScript. For example, the JavaScript built-in cts.andQuery is equivalent to the XQuery built-in cts:and-query in the diagram above.

The remainder of this chapter goes into more detail on combining constructors.

Use to Narrow the Search

The core search cts:query API is cts:word-query. The cts:word-query function returns true for words or phrases that match its $text parameter, thus narrowing the search to fragments containing terms that match the query. If needed, you can use other cts:query APIs to combine a cts:word-query expression into a more complex expression. Similarly, you can use the other leaf-level cts:query constructors to narrow the results of a search.

Understanding cts:element-query

The cts:element-query function searches through a specified element and all of its children. It is used to narrow the field of search to the specified element hierarchy, exploiting the XML structure in the data. Also, it is composable with other cts:element-query functions, allowing you to specify complex hierarchical conditions in the cts:query expressions.

For example, the following search against a Shakespeare database returns the title of any play that has SCENE elements that have SPEECH elements containing both the words 'room' and 'castle':

for $x in cts:search(fn:doc(), 
   cts:element-query(xs:QName("SCENE"), 
       cts:element-query(xs:QName("SPEECH"), 
           cts:and-query(("room", "castle")) ) ) ) 
return
($x//TITLE)[1]

This query returns the first TITLE element of the play. The TITLE element is used for both play and scene titles, and the first one in a play is the title of the play.

When you use cts:element-query and you have both the word positions and element word positions indexes enabled in the Admin Interface, it will speed the performance of many queries that have multiple term queries (for example, "the long sly fox") by eliminating some false positive results.

Understanding cts:element-word-query

While cts:element-query searches through an element and all of its children, cts:element-word-query searches only the immediate text node children of the specified element. For example, consider the following XML structure:

<root>
  <a>hello
    <b>goodbye</b>
  <a>
</root>

The following query returns false, because "goodbye" is not an immediate text node of the element named a:

cts:element-word-query(xs:QName("a"), "goodbye")

Understanding Field Word and Value Query Constructors

The cts:field-word-query and cts:field-value-query constructors search in fields for either words or values. A field value is defined as all of the text within a field, with a single space between text that comes from different elements. For example, consider the following XML structure:

<name>
  <first>Raymond</first>
  <middle>Clevie</middle>
  <last>Carver</last>
</name>

If you want to normalize names in the form firstname lastname, then you can create a field on this structure. The field might include the element name and exclude the element middle. The value of this instance of the field would then be Raymond Carver, with a space between the text from the two different element values from first and last. If your document contained other name elements with the same structure, their values would be derived similarly. If the field is named my-field, then a cts:field-value-query("my-field", "Raymond Carver") returns true for documents containing this XML. Similarly, a cts:field-word-query("my-field", "Raymond Carver") returns true.

For more information about fields, see Fields Database Settings in the Administrator's Guide. For information on lexicons on fields, see Field Value Lexicons.

Understanding the Range Query Constructors

The cts:element-range-query, cts:element-atribute-range-query, cts:path-range-query, and cts:field-range-query constructors allow you to specify constraints on a value in a cts:query expression. The range query constructors require a range index on the specified element or attribute. For details on range queries, see Using Range Queries in cts:query Expressions.

Understanding the Reverse Query Constructor

The cts:reverse-query constructor allows you to match queries stored in a database to nodes that would match those queries. Reverse queries are used as the basis for alert applications. For details, see Creating Alerting Applications.

Understanding the Geospatial Query Constructors

The geospatial query constructors are used to constrain cts:query expressions on geospatial data. Geospatial searches are used with documents that have been marked up with latitude and longitude data, and can be used to answer queries like 'show me all of the documents that mention places within 100 miles of New York City.' For details on gesospatial searches, see Geospatial Search Applications.

Specifying the Language in a cts:query

All leaf-level cts:query constructors are language-aware; you can either explicitly specify a language value as an option, or it will default to the database default language. The language option specifies the language in which the query is tokenized and, for stemmed searches, the language of the content to be searched.

To specify the language option in a cts:query, use the lang=language_code, where language_code is the two or three character ISO 639-1 or ISO 639-2 language code (http://www.loc.gov/standards/iso639-2/php/code_list.php). For example, the following query:

let $x := 
<root>
 <el xml:lang="en">hello</el>
 <el xml:lang="fr">hello</el>
</root>
return
$x//el[cts:contains(., 
         cts:word-query("hello", ("stemmed", "lang=fr")))]

returns only the French-language node:

<el xml:lang="fr">hello</el>

Depending on the language of the cts:query and on the language of the content, a string will tokenize differently, which will affect the search results. For details on how languages and the xml:lang attribute affect tokenization and searches, see Language Support in MarkLogic Server.

String Query Overview

A string query is a plain text search string ('query text') composed of terms, phrases, and operators that can be easily composed by end users typing into an application search box. For example, 'cat AND dog' is a string query for finding documents that contain both the term 'cat' and the term 'dog'.

You can use the cts:parse XQuery built-in function or the cts.parse Server-Side JavaScript built-in function to convert such a string query into a cts:query (XQuery) or cts.query (JavaScript). Use the resulting query in any interface that accepts a cts query, such as the cts:search XQuery function, the cts.search JavaScript function, and several JSearch API interfaces.

The following example uses cts:parse to match documents that contain the term 'cat' and the term 'dog'.

cts:search(cts:parse("cat AND dog"))

// with cts.search
cts.search(cts.parse('cat AND dog'))

// with JSearch
var jsearch = require('/MarkLogic/jsearch.sjs');
jsearch.documents()
  .where(cts.parse('cat AND dog'))
  .result()

The string query grammar supported by cts:parse enables users to compose complex queries. Adjacents terms, phrases and sub-expressions are implicitly AND'd together.

The following are some examples of queries that work with cts:parse 'out of the box':

• (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

You can also bind a tag name to an index reference, lexicon reference, or field name. When such a tag name appears in a query string, it parses to a word, value, or range query that is scoped to the bound entity.

For example, binding the tag 'color' to a cts:reference to a JSON property named bodyColor enables users to create query text like the following:

• color:red

  Match documents where the value of the bodyColor contains the word 'red'

• color NE blue

  Match documents where the value of bodyColor is not 'blue'

Without the binding, the above examples are just word queries that include the term 'color'. For example, without a binding, 'color NE blue' becomes a query for documents containing the words 'color', 'NE', and 'blue'.

You can also bind a tag name to a reference to a function that generates a query, giving you more control over the interpretation. For example, you can use a query generator function to scope a query to documents in a particular collection or directory.

For details, see Binding a Tag to a Reference, Field, or Query Generator.

Grammar Components and Operators

This section describes the components and operators you can use in query text passed to cts.parse. Some operators are only available in search terms that involve tags bound to query generators using the parse binding feature.

• Basic Components and Operators
• Operators Usable With Bound Tags
• Including Options and Weights in Query Text
• Query Text Parsing Examples

dog
dog tail
"dog tail" cat mouse
dog (cat OR mouse)

"dog tail"
"dog tail" "cat whisker"
dog "cat whisker"

(cat OR dog) zebra

-dog
-(dog OR cat)
cat -dog

dog AND cat
(cat OR dog) AND zebra

color:red
decade:1980s
birthday:1999-12-31

color:(red blue)
decade:(1980s 1990s)

color = red
decade = 1980s
birthday = 1999-12-31

color = (red blue)
decade = (1980s 1990s)

color EQ red

decade EQ 1980s
birthday EQ 1999-12-31

color EQ (red blue)
decade EQ (1980s 1990s)

color NE red
birthday NE 1999-12-31

color LT red
birthday LT 1999-12-31

color LE red
birthday LE 1999-12-31

color GT red
birthday GT 1999-12-31

color GE red
birthday GE 1999-12-31

query[option1, ..., optionN]

cat

cts:word-query("cat", ("lang=en"), 1)

cat[case-sensitive]

cts:word-query(
  "cat", ("case-sensitive","lang=en"), 1)

chat[stemmed,lang=fr]

cts:word-query("chat", ("stemmed","lang=fr"), 1)

cat AND dog

cts:and-query(
  (cts:word-query("cat", ("lang=en"), 1),
   cts:word-query("dog", ("lang=en"), 1)
  ),("unordered"))

cat[min-occurs=3] AND
  dog[weight=2]

cts:and-query(
  (cts:word-query("cat",
    ("lang=en","min-occurs=3"), 1),
   cts:word-query("dog", ("lang=en"), 2)
  ),("unordered"))

Binding a Tag to a Reference, Field, or Query Generator

This topic describes how to define parse bindings that enable the use of specially scoped relational and comparison operators in query text passed to the cts:parse XQuery function or cts.parse Server-Side JavaScript function. You can create bindings to XML elements, XML element attributes, JSON properties, fields, and paths, as well as to custom parsing functions.

The following topics are covered:

• Binding Overview
• Binding to a cts:reference
• Binding to a Field by Simple Name
• Binding to a Geospatial Index Reference
• Binding to an XQuery Query Generator Function
• Binding to a JavaScript Query Generator Function

let $bindings := map:map()
let $_ := map:put(
  $bindings, 
  "by", cts:element-reference(xs:QName("author"))

var bindings =
  { by: cts.jsonPropertyReference('author') };

by:"mark twain"

xquery version "1.0-ml";
let $bindings := map:map()
let $_ := map:put(
  $bindings, 
  "by", cts:element-reference(xs:QName("author")))
return cts:parse('by:"mark twain"', $bindings)

(: emits 
 : cts:element-word-query(fn:QName("","author"), "mark twain")
 :)

var bindings =
  { by: cts.jsonPropertyReference('author') };
cts.parse('by:"mark twain"', bindings)

// emits
// cts.jsonPropertyWordQuery("author", "mark twain")

by:(twain frost)

xquery version "1.0-ml";
let $bindings := map:map()
let $_ := map:put(
  $bindings, 
  "cost", cts:element-reference(xs:QName("price")))
return cts:parse('cost LT 15', $bindings)

(: cts:element-range-query(
     fn:QName("","price"), "<", xs:float("15"), (), 1) 
:)

var bindings =
  { by: cts.jsonPropertyReference('price') };
cts.parse('cost LT 15', bindings)

// cts.jsonPropertyRangeQuery(
//    "price", "<", xs.float("15"), [], 1)

cts:element-word-query(fn:QName("","price"), "15", ("lang=en"), 1)

cts.jsonPropertyWordQuery("price", "15", ["lang=en"], 1)

(: parse time XDMP-ELEMRIDXNOTFOUND if no range index exists:)
xquery version "1.0-ml";
let $bindings := map:map()
let $_ := map:put(
  $bindings, 
  "cost", cts:element-reference(xs:QName("price")))
return cts:parse('cost LT 15', $bindings);

(: search time XDMP-ELEMRIDXNOTFOUND :)
xquery version "1.0-ml";
let $bindings := map:map()
let $_ := map:put(
  $bindings, "cost", cts:element-reference(xs:QName("price"),
    ("type=float","unchecked")))
return cts:search(cts:parse('cost LT 15', $bindings))

// parse time XDMP-ELEMRIDXNOTFOUND if no range index exists
cts.parse('cost LT 15', {p: cts.jsonPropertyReference('price')})

// Suppress the parse time index check
var query = cts.parse('cost LT 15', 
  {cost: cts.jsonPropertyReference(
    'price',['type=float','unchecked'])})
// But will still get search time error if no range index found
cts.search(query)        // XDMP-ELEMRIDXNOTFOUND

xquery version "1.0-ml";
let $bindings := map:map()
let $_ := map:put(
  $bindings, 
  "name", "person")
return cts:parse('name:"jane doe"', $bindings)

(: cts:field-word-query("name", "jane doe", ("lang=en"), 1) :)

var bindings = { name: 'person' };
cts.parse('name:"jane doe"', bindings)

// cts.fieldWordQuery("name", "jane doe", ["lang=en"], 1)

loc:"@5 37.5,-122.4"

xquery version "1.0-ml";
let $bindings := map:map()
let $_ := map:put(
  $bindings, 
  "loc", cts:geospatial-element-reference(xs:QName("incidents")))
return cts:parse('loc:"@5 37.5,-122.4"', $bindings)

(: cts:element-geospatial-query(
 :   fn:QName("","incidents"), 
 :   cts:circle("@5 37.5,-122.4"),
 :   ("coordinate-system=wgs84"), 1) 
 :)

cts.parse('loc:"@5 37.5,-122.4"', 
  { loc: cts.geospatialJsonPropertyReference('incidents') })

// cts.jsonPropertyGeospatialQuery(
//    "incidents", 
//    cts.circle("@5 37.5,-122.4"),
//    ["coordinate-system=wgs84"], 1)

"0,0 0,10 10,10 10,0 0,0"

"POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))"

lat,lon

tag:"37.5, -122.4"

@radius lat,lon

tag:"@5 37.5,-122.4"

[sbound, wbound, nbound, ebound]

tag:"[45, -122, 78, 30]"

lat1,lon1 lat2,lon2 ...latN,lonN

tag:"100,0 101,0 101,1 100,1 100,0"

function (
  $operator as xs:string,
  $values as xs:string*,
  $options as xs:string*
) as cts:query?

xquery version "1.0-ml";

(: The query generator :)
declare function local:scope-to-coll(
  $operator as xs:string,
  $values as xs:string*,
  $options as xs:string*)
as cts:query?
{
  if ($operator = (":", "EQ")) then
    let $known := ("classics", "fiction", "poetry")
    return cts:collection-query(
      for $c in ($values) 
      return
        if ($c = $known)
        then $c
        else fn:error(
          xs:QName("ERROR"), 
          fn:concat("Unrecognized category: ", $c))
    )
  else ()       (: unsupported operator :)
};

(: how to use it :)
let $bindings := map:map()
let $_ := map:put($bindings, "cat", local:scope-to-coll#3)
return cts:parse('cat EQ classics california', $bindings)
(: matchs docs in the "classics" collection that contain califorina :)

cat:classics

cat EQ classics

cts:collection-query("classics")

cat:unrecognized

None - function reports an error

cat LT anything

(: interpreted as text :)
cts:and-query((
  (cts:word-query("cat", ("lang=en"), 1),
   cts:word-query("LT", ("lang=en"), 1),
   cts:word-query("anything", ("lang=en"), 1)   ),("unordered"))

function (operator, values, options)

function scopeToColl(operator, category, options) {
  if (operator === ':' || operator === 'EQ') {
    // normalize input, which can be one val or an iterator
    var categories = 
        (category instanceof ValueIterator) 
        ? category.toArray() : [category];
    var known = ['classics', 'fiction', 'poetry']
    var collections = [];
    categories.forEach(function (c) {
      if (known.indexOf(c) != -1) {
        collections.push(c);
      } else {
        fn.error('ERROR', 'Unrecognized category: ' + c);
      }
    });
    return cts.collectionQuery(collections);
  }
  // else, unsupported operator, so return nothing
};

var bindings = { cat: scopeToColl };
cts.parse('cat:(classics poetry) california', bindings)

cat:classics

cat EQ classics

cts.collectionQuery('classics')

cat:unrecognized

None - function reports an error

cat LT anything

// Function returns nothing, phrase interpreted as text
// by cts.parse
cts.andQuery(
  [cts.wordQuery("cat", ["lang=en"], 1),    cts.wordQuery("LT", ["lang=en"], 1),    cts.wordQuery("anything", ["lang=en"], 1)],
  ["unordered"])

tag LT value

operator: 'LT'
values: value
options: an empty ValueIterator

tag = (val1 val2)

operator: '='
values: ValueIterator over val1 and val2
options: an empty ValueIterator

tag:42

operator: ':'
values: 42 as a number
options: an empty ValueIterator

tag:true

operator: ':'
values: 'true' (string, not boolean)
options: an empty ValueIterator

tag:value[opt]

operator: ':'
values: value
options: 'opt'

tag LT value[opt1,opt2=42]

operator: 'NE'
values: value
options: a ValueIterator over 'opt1' and 'opt2=42'

Customizing Naked Term Handling With Bindings

You can use bindings to control the interpretation of terms in query text that are not qualified by a tag (naked terms). For example, in query text such as 'cat AND dog', 'cat' and 'dog' are naked terms. The default interpretation of this query text is a query that matches the terms 'cat' and 'dog' anywhere they appear, similar to the following

cts:and-query((cts:word-query('cat'), cts:word-query('dog')))

If you create a binding with the empty string as the tag, you can customize the handling of terms that have no tag qualifier in the same way you can customize the interpretation of a defined tag. For example, you can configure the parser to scope the terms 'cat' and 'dog' to a particular XML element or JSON property.

You can bind naked terms to a content reference, field name, or a query generator function, just as when using a tag.

The following examples constrain naked terms to occurrences in an XML element/JSON property named 'title'.

xquery version "1.0-ml";
let $bindings := map:map()
let $_ := map:put($bindings, "",
  cts:element-reference(xs:QName("title")))
return cts:parse('cat AND dog', $bindings)

(:
  cts:and-query((
    cts:element-word-query(fn:QName("","title"),"cat",("lang=en"),1),
    cts:element-word-query(fn:QName("","title"),"dog",("lang=en"), 1)),   ("unordered"))
:)

cts.parse(
  'cat AND dog',
  {'': cts.jsonPropertyReference('title')}
)

// cts.andQuery([
//    cts.jsonPropertyWordQuery("title", "cat", ["lang=en"], 1), //    cts.jsonPropertyWordQuery("title", "dog", ["lang=en"], 1)
//  ],
//  ["unordered"])

For more details on using bindings, see Binding a Tag to a Reference, Field, or Query Generator.

Query Text Parsing Examples

This section illustrates the output from the cts:parse XQuery function or cts.parse JavaScript function various inputs. For examples of queries that include option values, see Including Options and Weights in Query Text.

You can use a query similar to the following in Query Console to explore the parser output on your own. The bindings are only needed for the examples that use the 'color' or 'loc' tag. To parse some of the query text that uses the bound tags, you need to define an element range index on the 'body-color' XML element or 'bodyColor' JSON property, and a geospatial element ranage index on an XML element or JSON property named 'incidents'.

XML

xquery version "1.0-ml";
let $bindings := map:map()
let $_ := 
  map:put($bindings, 
    "color", cts:element-reference(xs:QName("body-color")))
return cts:parse(queryText, $bindings)

JavaScript

cts.parse(queryText, 
  { color: cts.jsonPropertyReference('bodyColor') })

The following table contains examples of input query text and the result returned by the parser.

cat

cts:word-query(
  "cat", ("lang=en"), 1)

cts.wordQuery(
  "cat", ["lang=en"], 1)

cat dog

cat AND dog

cts:and-query((
  cts:word-query(
    "cat", ("lang=en"), 1),
  cts:word-query(
    "dog", ("lang=en"), 1)
  ), ("unordered"))

cts.andQuery([
  cts.wordQuery(
    "cat", ["lang=en"], 1),
  cts.wordQuery(
    "dog", ["lang=en"], 1)
  ], ["unordered"])

cat dog OR mouse

cts:or-query((
  cts:and-query((
    cts:word-query(
      "cat",("lang=en"),1),
    cts:word-query(
      "dog",("lang=en"), 1)
    ), ("unordered")),   cts:word-query(
    "mouse",("lang=en"),1)
  ), ())

cts.orQuery([
  cts.andQuery([
    cts.wordQuery(
      "cat",["lang=en"],1),
    cts.wordQuery(
      "dog", ["lang=en"],1)
    ], ["unordered"]),
  cts.wordQuery(
    "mouse", ["lang=en"],1)
  ], [])

cat (dog OR mouse)

cts:and-query((
  cts:word-query(
    "cat", ("lang=en"), 1),
  cts:or-query((
    cts:word-query(
      "dog",("lang=en"),1),
    cts:word-query(
      "mouse",("lang=en"),
      1)
    ), ())
  ), ("unordered"))

cts.andQuery([
  cts.wordQuery(
    "cat", ["lang=en"], 1),
  cts.orQuery([
    cts.wordQuery(
      "dog",["lang=en"],1),
    cts.wordQuery(
     "mouse",["lang=en"],1)
    ], [])
  ], ["unordered"])

cat -dog

cts:and-query((
  cts:word-query(
    "cat", ("lang=en"), 1),
  cts:not-query(
    cts:word-query(
      "dog", ("lang=en"),
      1),
    1)
  ), ("unordered"))

cts.andQuery([
  cts.wordQuery(
    "cat", ["lang=en"], 1),
  cts.notQuery(
    cts.wordQuery(
     "dog", ["lang=en"],1),
    1)
  ], ["unordered"])

color:red

cts:element-word-query(
  fn:QName("","body-color"),
  "red", ("lang=en"), 1)

cts.jsonPropertyWordQuery(
  "bodyColor", "red",
  ["lang=en"], 1)

color = red

cts:element-value-query(
  fn:QName("","body-color"),
  "red", ("lang=en"), 1)

cts.jsonPropertyValueQuery(
  "bodyColor", "red",
  ["lang=en"], 1)

color EQ red

cts:element-range-query(
  fn:QName("","body-color"), 
  "=", "red",
  ("collation=..."), 1)

cts.jsonPropertyRangeQuery(
  "bodyColor", "=", "red",
  ["collation=..."], 1)

color:(red blue)

cts:element-word-query(
  fn:QName("","body-color"),
  ("red", "blue"),
  ("lang=en"), 1)

cts.jsonPropertyWordQuery(
  "color", ["red", "blue"],
  ["lang=en"], 1)

loc:"100.0,1.0"

cts:element-geospatial-query(
  fn:QName("","incidents"),
  cts:point("100,1"),
  ("coordinate-system=wgs84"),
  1)

cts.jsonPropertyGeospatialQuery(
  "incidents",
  cts.point("100,1"),
  ["coordinate-system=wgs84"],
  1)

loc:"[10,20,30,40]"

cts:element-geospatial-query(
  fn:QName("","incidents"),
  cts:box("[10, 20, 30, 40]"),
  ("coordinate-system=wgs84",
  1)

cts.jsonPropertyGeospatialQuery(
  "incidents", 
  cts.box("[10,20,30,40]"),
  ["coordinate-system=wgs84",
  1)

Using cts:and-query and cts:or-query

You can construct arbitrarily complex boolean logic by combining cts:and-query and cts:or-query constructors in a single cts:query expression.

For example, the following search with a relatively simple nested cts:query expression will return all fragments that contain either the word alfa or the word maserati, and also contain either the word saab or the word volvo.

cts:search(fn:doc(),
  cts:and-query( ( cts:or-query(("alfa", "maserati")), 
                   cts:or-query(("saab", "volvo") )
  ) )
)

Additionally, you can use cts:and-not-query and cts:not-query to add negation to your boolean logic.

Proximity Queries using cts:near-query

You can add tests for proximity to a cts:query expression using cts:near-query. Proximity queries use the word positions index in the database and, if you are using cts:element-query, the element word positions index. Proximity queries will still work without these indexes, but the indexes will speed performance of queries that use cts:near-query.

Proximity queries return true if the query matches occur within the specified distance from each other. For more details, see the MarkLogic XQuery and XSLT Function Reference for cts:near-query.

Using Bounded cts:query Expressions

The following cts:query constructors allow you to bound a cts:query expression to one or more documents, a directory, or one or more collections.

• cts:document-query
• cts:directory-query
• cts:collection-query

These bounding constructors allow you to narrow a set of search results as part of the second parameter to cts:search. Bounding the query in the cts:query expression is much more efficient than filtering results in a where clause, and is often more convenient than modifying the XPath in the first cts:search parameter. To combine a bounded cts:query constructor with another constructor, use a cts:and-query or a cts:or-query constructor.

For example, the following constrains a search to a particular directory, returning the URI of the document(s) that match the cts:query.

for $x in cts:search(fn:doc(), 
   cts:and-query((
     cts:directory-query("/shakespeare/plays/", "infinity"), 
         "all's well that"))
)
return xdmp:node-uri($x)

This query returns the URI of all documents under the specified directory that satisfy the query "all's well that".

In this query, the query "all's well that" is equivalent to a cts:word-query("all's well that").

Matching Nothing and Matching Everything

An empty cts:word-query will always match no fragments, and an empty cts:and-query will always match all fragments. Therefore the following are true:

cts:search(fn:doc(), cts:word-query("") )
=> returns the empty sequence
cts:search(fn:doc(), "" )
=> returns the empty sequence
cts:search(fn:doc(), cts:and-query( () ) )
=> returns every fragment in the database

You can also use cts:true-query and cts:false-query to match everything or nothing. For example:

cts:search(fn:doc(), cts:false-query())
==> returns the empty sequence

cts:search(fn:doc(), cts:true-query())
==> returns every fragment in the database

One use for an empty cts:word-query is when you have a search box that an end user enters terms to search for. If the user enters nothing and hits the submit button, then the corresponding cts:search will return no hits.

An empty cts:and-query or a cts-true-query that matches everything is sometimes useful when you need a cts:query to match everything.

Registered Query APIs

To register and reuse unfiltered searches for cts:query expressions, use the following XQuery APIs:

• cts:register
• cts:registered-query
• cts:deregister

For the syntax of these functions, see the MarkLogic XQuery and XSLT Function Reference.

Must Be Used Unfiltered

You can only use registered queries on unfiltered constructors; using a registered query as a filtered constructor throws the XDMP-REGFLT exception. To specify an unfiltered constructor, use the "unfiltered" option to cts:registered-query. For details about unfiltered searches, see 'Using Unfiltered Searches for Fast Pagination' in the Query Performance and Tuning Guide.

Registration Does Not Survive System Restart

Registered queries are only stored in the memory cache, and if the cache grows too big, some registered queries might be aged out of the cache. Also, if MarkLogic Server stops or restarts, any queries that were registered are lost and must be re-registered.

If you attempt to call cts:registered-query in a cts:search and the query is not currently registered, it throws an XDMP-UNREGISTERED exception. Because registered queries are not guaranteed to be registered every time they are used, it is good practice to use a try/catch around calls to cts:registered-query, and re-register the query in the catch if the it throws an XDMP-UNREGISTERED exception.

For example, the following sample code shows a cts:registered-query call used with a try/catch expression in XQuery:

(: wrap the registered query in a try/catch :)
try{
xdmp:estimate(cts:search(fn:doc(), 
  cts:registered-query(995175721241192518, "unfiltered")))
}
catch ($e) 
{
let $registered := 'cts:register(
		cts:word-query("hello*world", "wildcarded"))'
return
if ( fn:contains($e/*:code/text(), "XDMP-UNREGISTERED") )
then ( "retry this query with the following registered query ID: ",
       xdmp:eval($registered) )
else ( $e ) 
}

This code is somewhat simplified: it catches the XDMP-UNREGISTERED exception and simply reports what the new registered query ID is. In an application that uses registered queries, you probably would want to re-run the query with the new registered ID. Also, this example performs the try/catch in XQuery. If you are using XCC to issue queries against MarkLogic Server, you can instead perform the try/catch in the middleware Java or .NET layer.

Storing Registered Query IDs

When you register a cts:query expression, the cts:register function returns an integer, which is the ID for the registered query. After the cts:register call returns, there is no way to query the system to find the registered query IDs. Therefore, you might need to store the IDs somewhere. You can either store them in the middleware layer (if you are using XCC to issue queries against MarkLogic Server) or you can store them in a document in MarkLogic Server.

The registered query ID is generated based on a hash of the actual query, so registering the same query multiple times results in the same ID. The registered query ID is valid for all queries against the database across the entire cluster.

Registered Queries and Relevance Calculations

Searches that use registered queries will generate results having different scores from the equivalent searches using a non-registered queries. This is because registered queries are treated as a single term in the relevance calculation. For details on relevance calculations, see Relevance Scores: Understanding and Customizing.

Example: Registering and Using a cts:query Expression

To run a registered query, you first register the query and then run the registered query, specifying it by ID. This section describes some example steps for registering a query and then running the registered query.

1. First register the cts:query expression you want to run, as in the following example:

   cts:register(cts:word-query("hello*world", "wildcarded"))

2. The first step returns an integer. Keep track of the integer value (for example, store it in a document).
3. Use the integer value to run a search with the registered query (with the "unfiltered" option) as follows:

   cts:search(fn:doc(), 
             cts:registered-query(987654321012345678, "unfiltered") ) 

Serializing a cts:query to XML

A serialized cts:query has XML that conforms to the <marklogic-dir>/Config/cts.xsd schema, which is in the http://marklogic.com/cts namespace, which is bound to the cts prefix. You can either construct the XML directly or, if you use any cts:query expression within the context of an element, MarkLogic Server will automatically serialize that cts:query to XML. Consider the following example:

<some-element>{cts:word-query("hello world")}</some-element>

When you run the above expression, it serializes to the following XML:

<some-element>
  <cts:word-query xmlns:cts="http://marklogic.com/cts">
    <cts:text xml:lang="en">hello world</cts:text>
  </cts:word-query>
</some-element>

If you are using an alerting application, you might choose to store this XML in the database so you can match searches that include cts:reverse-query constructors. For details on alerts, see Creating Alerting Applications.

Add Arbitrary Annotations With cts:annotation

You can annotate your cts:query XML with cts:annotation elements. A cts:annotation element can be a child of any element in the cts:query XML, and it can consist of any valid XML content (for example, a single text node, a single element, multiple elements, complex elements, and so on). MarkLogic Server ignores these annotations when processing the query XML, but such annotations are often useful to the application. For example, you can store information about where the query came from, information about parts of the query to use or not in certain parts of the application, and so on. The following is some sample XML with cts:annotation elements:

<cts:and-query xmlns:cts="http://marklogic.com/cts">
  <cts:directory-query>
    <cts:annotation>private</cts:annotation>
    <cts:uri>/myprivate-dir/</cts:uri>
  </cts:directory-query>
  <cts:and-query>
    <cts:word-query><cts:text>hello</cts:text></cts:word-query>
    <cts:word-query><cts:text>world</cts:text></cts:word-query>
  </cts:and-query>
  <cts:annotation>
    <useful>something useful to the application here</useful>
  </cts:annotation>
</cts:and-query>

For another example that uses cts:annotation to store the original query string in a function that generates a cts:query from a string, see the last part of the example in XML Serializations of cts:query Constructors.

Function to Construct a cts:query From XML

You can turn an XML serialization of a cts:query back into an un-serialized cts:query with the cts:query function. For example, you can turn a serialized cts:query back into a cts:query as follows:

cts:query(
  <cts:word-query xmlns:cts="http://marklogic.com/cts">
    <cts:text>word</cts:text>
  </cts:word-query>
)
(: returns: cts:word-query("word", ("lang=en"), 1) :)