MarkLogic 9 Product Documentation
cts:registered-query

cts:registered-query(
   $ids as xs:unsignedLong*,
   [$options as xs:string*],
   [$weight as xs:double?]
) as cts:registered-query

Summary

Returns a query matching fragments specified by previously registered queries (see cts:register). If the database is not empty and a registered query with the specified ID(s) is not found, then a cts:search operation with an invalid cts:registered-query throws an XDMP-UNREGISTERED exception.

Parameters

ids Some registered query identifiers.

Parameters
ids	Some registered query identifiers.
options	Options to this query. The default is (). Options include: "filtered" A filtered query (the default). Filtered queries eliminate any false-positive results and properly resolve cases where there are multiple candidate matches within the same fragment, thereby guaranteeing that the results fully satisfy the original `cts:query` item that was registered. This option is not currently available. "unfiltered" An unfiltered query. Unfiltered registered queries select fragments from the indexes that are candidates to satisfy the `cts:query`. Depending on the original `cts:query`, the structure of the documents in the database, and the configuration of the database, unfiltered registered queries may result in false-positive results or in incorrect matches when there are multiple candidate matches within the same fragment. To avoid these problems, you should only use unfiltered queries on top-level XPath expressions (for example, document nodes, collections, directories) or on fragment roots. Using unfiltered queries on complex XPath expressions or on XPath expressions that traverse below a fragment root can result in unexpected results. This option is required in the current release.
weight	A weight for this query. Higher weights move search results up in the relevance order. The default is 1.0. The weight should be between 64 and -16. Weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.

options

Options to this query. The default is ().

Options include:

"filtered"

A filtered query (the default). Filtered queries eliminate any false-positive results and properly resolve cases where there are multiple candidate matches within the same fragment, thereby guaranteeing that the results fully satisfy the original cts:query item that was registered. This option is not currently available.

"unfiltered"

An unfiltered query. Unfiltered registered queries select fragments from the indexes that are candidates to satisfy the cts:query. Depending on the original cts:query, the structure of the documents in the database, and the configuration of the database, unfiltered registered queries may result in false-positive results or in incorrect matches when there are multiple candidate matches within the same fragment. To avoid these problems, you should only use unfiltered queries on top-level XPath expressions (for example, document nodes, collections, directories) or on fragment roots. Using unfiltered queries on complex XPath expressions or on XPath expressions that traverse below a fragment root can result in unexpected results. This option is required in the current release.

weight A weight for this query. Higher weights move search results up in the relevance order. The default is 1.0. The weight should be between 64 and -16. Weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.

Usage Notes

Searches that use registered queries will generate results with different scores than the equivalent searches using non-registered queries. This is because registered queries are treated as a single term in relevance calculations.

If the options parameter does not contain "unfiltered", then an error is returned, as the "unfiltered" option is required.

Registered queries are persisted as a soft state only; they can become unregistered through an explicit direction (using cts:deregister), as a result of the cache growing too large, or because of a server restart. Consequently, either your XQuery code or your middleware layer should handle the case when an XDMP-UNREGISTERED exception occurs (for example, you can wrap your cts:registered-query code in a try/catch block or your Java or .NET code can catch and handle the exception).

Unfiltered queries, including registered queries, do not match in cts:walk or cts:highlight.

Example

  cts:search(//function,
    cts:registered-query(1234567890123456,"unfiltered"))

  => .. relevance-ordered sequence of 'function' elements
  in any document that also matches the registered query

Example

(: wrap the registered query in a try/catch :)
try {
cts:search(fn:doc(),cts:registered-query(995175721241192518,"unfiltered"))
} catch ($e) {
  if ($e/err:code = "XDMP-UNREGISTERED")
  then ("Retry this query with the following registered query ID: ",
        cts:register(cts:word-query("hello*world","wildcarded")))
  else $e }
}

MarkLogic 9 Product Documentationcts:registered-query

Summary

Usage Notes

Example

Example

MarkLogic 9 Product Documentation
cts:registered-query