Search Developer's Guide (PDF)

MarkLogic 9 Product Documentation
Search Developer's Guide — Chapter 4

« Previous chapter
Next chapter »

Searching Using Structured Queries

This chapter describes how to perform searches using structured queries expressed in XML or JSON. The annotated cts:query that is generated by default from search:parse or search:search works well for cases where you do not need to perform extensive modification to the query. If you want to generate your own query, or if you want to parse your query using different rules from the Search API grammar rules, there is an alternate query style called structured query.

This chapter includes the following topics:

Structured Query Overview

A structured query is an Abstract Syntax Tree representation of a search expression, expressed in XML or JSON. For example, the following is a structured query in XML that is equivalent to the string query cat AND dog.

<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:and-query>
    <search:term-query>
      <search:text>cat</search:text>
    </search:term-query>
    <search:term-query>
      <search:text>dog</search:text>
    </search:term-query>
  </search:and-query>
</search:query>

Any time you want to intercept a query and either augment or manipulate it in some way, consider using a structured query. The following use cases are good candidates for structured queries:

  • Queries that do not work well in a string query. For example, constraints such as a geospatial constraint of a complex polygon are designed to be machine generated.
  • Search strings that include complex sets of rules, or a set of rules that do not map well to the string query grammar.
  • Combining a pre-parsed structured query with a user-generated or dynamically constructed string query.
  • Converting a non-MarkLogic query representation such as an in-house query format into a form consumable by MarkLogic Server.
  • String queries that require application-specific validation.

You can generate a structured query using the XQuery function search:parse or by writing your own code that returns a structured query. You can use structured queries to search contents and metadata with the following MarkLogic Server APIs:

Structured Query Concepts

The concepts covered in this section should help you understand the purpose and scope of the various structured query building blocks. For detailed information about a particular sub-query, see Syntax Reference.

The following topics are covered:

Major Query Categories

A query encapsulates your search criteria. You can combine search criteria into complex search expressions using many different types of query combinations. The many sub-query components of structured query fall into one of the categories described in this section.

The query categories in the following table are leaf queries that never contain other queries. These type of query are the basic search building blocks that describe what content you want to match.

Query Type Description
value Match an entire value in a specific place, such as a phrase or number in a JSON property or XML element. Value queries on JSON property values must use properly typed criteria; if you do not specify a type, string is assumed. For example, to match the value of a property with number type, you must explicitly set the criteria value type to number in your query. For details, see value-query.
word Match a word or phrase in a specific place, such as in a specific JSON property, XML element or attribute, or field. A word query will match a subset of a text value. A word query only matches text, so it will never match JSON property values that have number, boolean, or null type. For details, see word-query.
term Match a word or phrase anywhere it appears in a document or container. A term query will match a subset of a text value. A term query only matches text, so it will never match JSON property values that have number, boolean, or null type. For details, see term-query.
range Match values that satisfy a relational expression applied to a typed value. You can express conditions such as less than 5 or not equal to true. A range query must either be backed by a range index or used in a filtered search operation. For details, see range-query.

Additional sub-queries enable you to combine the basic content queries with each other and with additional criteria and constraints. The additional query types fall into the following general categories.

  • Logical Composers: Express logical relationships between criteria. You can build up compound logical expressions such as x AND (y OR z).
  • Document Selectors: Select documents based on collection, directory, or URI. For example, you can express criteria such as x only when it matches in documents in collection y.
  • Location Qualifiers: Further limit a criteria based on where the match appears. For example, x only when contained in JSON property z, or x only when it matches within n words of y, or x only when it matches in a document property.

Understanding the Difference Between Term and Word Queries

Term queries and word queries differ primarily in how they handle containment. A term query finds matches anywhere within its context container, while a word query matches only immediate children. For example, suppose your JSON or XML document has the following structure:

JSON XML 
{ "a": {
  "b": "value",
  "c": { "d": "value" }
} }
 
<a>
  <b>value</b>
  <c>
    <d>value</d>
  </c>
</a>

A term query for value in a finds 2 matches: The occurrence in b, and the one in d. However, a word query for value in a finds no matches because value does not occur as an immediate child of a.

To locate occurrences of value using a word query, you must constrain the word query to the scope of b or d. For example, the following sub-queries match value in b in the JSON and XML documents, respectively:

JSON XML 
"word-query": {
  "json-property": "b",
  "text": "value"
}
 
<search:word-query>
  <search:element name="b">
  <search:text>value</search:text>
</search:word-query>

Understanding Containment

Many sub-query types constrain matches to the context of a particular container. A container is a JSON property, XML element, or XML element attribute.

A query such as a word or value query that includes the name of a container only matches occurrences within that container. However, the container can appear at any level within the enclosing document or container. That is, it does not have to be an immediate child.

For example, the following word queries only matches occurrences of value when appears in the value of a JSON property or XML element named a. (The examples use json-property in the JSON version and element in the XML version, but you can use these specifiers independent of query format.)

JSON XML 
"word-query": {
  "json-property": "b",
  "text": "value"
}
 
<search:word-query>
  <search:element name="b">
  <search:text>value</search:text>
</search:word-query>

However, in the absence of other restrictions, the container named b can occur anywhere. For example, the following documents each contain two matches because there are 2 JSON properties (or XML elements) containing value.

JSON XML 
{"a": {
  "b": "value",
  "c": { "b": "value" }
} }
 
<a>
  <b>value</b>
  <c>
    <b>value</b>
  </c>
</a>

You can wrap a query in a container-query to further limit the scope of the matches. For example, the following sub-queries only match value in b when b occurs inside c:

JSON XML 
"container-query": {
  "json-property": "c",
  "word-query": {
    "json-property": "b",
    "text": "value"
  }
}
 
<search:container-query>
  <search:element name="c" />
  <search:word-query>
    <search:element name="b">
    <search:text>value</search:text>
  </search:word-query>
</search:container-query>

You can limit the scope of matches in other ways, such as collection, database directory, or property fragment scope. For details, see Location Qualifiers and Document Selectors.

Text Match Semantics

Whether a value, term, or word query on text content is case-sensitive, diacritic-sensitive, whitespace-sensitive, or punctuation-sensitive depends on database configuration, query options, and the input criteria text. Whether stemming and wildcarding are active similar depends on options and database configuration.

The defaults for text matches are as follows:

  • Case: If the criteria text is all lower-case, then the match is case-insenstive. If the criteria contains any upper-case letters, then the match is case sensitive.
  • Diacritics: If the criteria text contains no diacritics, then the match is diacritic-insenstive. If the criteria contains any diacritics, then the match is diacritic-sensitive.
  • Whitespace: Whitespace insenstive. (Whitespace is still used to tokenize words.)
  • Punctuation: If the criteria text contains no punctuation, then the match is punctuation-insenstive. If the criteria contains any punctuation, then the match is punctuation sensitive.
  • Stemming: Depends on the database configuration. Stemmed search is disabled on a database by default.
  • Wildcarding: Depends on the database configuration and the criteria text. Wildcard searches are disabled on a database by default. If any wildcard search is enabled and the criteria text contains wildcard characters (...Äò?' or '*'), then wildcarding is applied.

For example, a word query for purple matches both purple elephants and Purple Elephants, but a word query for Purple only matches Purple Elephants.

Similarly, a word query for purple elephants matches both purple elephants and purple, elephants, but a word query for purple,elephants will only match purple, elephants.

You can override some of these behaviors with query options and database configuration. For example, if wildcard searches are not enabled on the database, then a word query for thom* will not match Thomas. Similarly, you can set term options local to a particular word-query or value-query, or more widely through the term-options query option.

For more details, see Term Options and Understanding the Text Index Settings in the Administrator's Guide.

Structured Query Sub-Query Taxonomy

Structured query explicitly exposes all the query types described in Major Query Categories. This section is a quick reference for locating the kind of sub-query you need, based on this categorization.

You can use most kinds of sub-query in combination with each other to build up complex queries. For details, see Syntax Reference.

Basic Content Queries

Basic content queries express search criteria about your content, such as JSON property A contains value B or any document containing the phrase 'dog'. These queries function as leaves in the structure of a complex, compound query because they do not contain sub-queries.

Logical Expression Composers

Logical composers are queries that join one or more sub-queries into a logical expression. For example, documents which match both query1 and query2 or documents which match either query1 or query2 or query3.

Location Qualifiers

Location qualifiers limit results based on where subquery matches occur, such as only in content, only in metadata, or only when contained by a specified JSON property or XML element. For example, matches for this sub-query that occur in metadata or matches for this sub-query that are contained in JSON Property P.

Document Selectors

Document selectors are queries that match a group of documents by database attributes such as collection membership, directory, or URI, rather than by contents. For example, all documents in collections A and B or all documents in directory D.

Constructing a Structured Query

You can construct a structured query in multiple ways:

  • Manually, using the syntax described in Syntax Reference.
  • In XQuery, by calling the XQuery function search:parse and supplying "search:query" as the 3rd parameter to see the XML representation.
  • In Java, using the class com.marklogic.client.query.StructuredQueryBuilder. or com.marklogic.client.pojo.PojoQueryBuilder, or an equivalent interface.

The XQuery Search API only accepts structured queries in XML. The REST and Java APIs accept XML and JSON representations.

For XML, you can use the search:parse technique with Query Console to explore how a string query or serialized cts:query maps to a structured query, and then modify it according to your needs. For example:

xquery version "1.0-ml";
import module namespace search = 
  "http://marklogic.com/appservices/search"
  at "/MarkLogic/appservices/search/search.xqy";

return search:parse("cat AND dog", (), "search:query")

If you run the above query in Query Console and display the results as XML, you get the XML representation of cat AND dog when parsed with the default search options in effect:

<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:and-query>
    <search:term-query>
      <search:text>cat</search:text>
    </search:term-query>
    <search:term-query>
      <search:text>dog</search:text>
    </search:term-query>
  </search:and-query>
</search:query>

Syntax Summary

This section gives a brief summary of structure of a structured query. For details, see Syntax Reference

A structured query is a search:query XML element with children representing cts:query composers, cts:query scoping constructors, and abstractions for Search API components such as constraints and operators. When using the XQuery Search API, you must use the XML representation. In REST and Java, you can choose between the XML or JSON representations.

Like cts:query constructors in XQuery, structured queries are composable to make a complex search query. A structured query expressed as XML must have a <search:query> wrapper node. For example:

<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:and-query>...</search:and-query>
</search:query>

Similarly, the JSON representation of a structured query has a query wrapper object. Within this wrapper, the sub-queries are enclosed in a queries array. The queries wrapper is used wherever multiple sub-queries can occur. For example:

{
  "query": {
    "queries": [
      { "and-query": ... }
    ]
  }
}

You can compose complex queries consisting of and-queries, or-queries, and so on, and they can contain any number of term-queries with terms to search for. You can constrain queries to an element, attribute, JSON property, or field; use range-queries; and so on. For background on how cts:query expressions work in MarkLogic Server, see Composing cts:query Expressions.

The REST API and the Java API support XML and JSON representations of structured queries. The REST and Java APIs internally use the JSON conversion features in MarkLogic to convert between JSON and XML. For details on this conversion, see Working With JSON in the Application Developer's Guide.

Examples of Structured Queries

This section includes the following examples of Structured Search, with an XML example as well as the corresponding JSON example for each:

For additional examples, see Syntax Reference.

Example: Simple Structured Search

The following is a structured query XML node equivalent to a string query for the phrase "imagine a complex search":

<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:term-query>
    <search:text>imagine a complex search</search:text>
  </search:term-query>
</search:query>

The following is the JSON representation of the same query (for use in the REST API or the Java API):

{
  "query": {
    "queries": [{
      "term-query": {
        "text": [ "imagine a complex search" ]
      }
    }]
}}

With XQuery, you can generate the XML structured query from a string query using search:parse, and perform a search with the structured query using search:resolve, as shown in the following code:

xquery version "1.0-ml";
import module namespace search =
     "http://marklogic.com/appservices/search"
     at "/MarkLogic/appservices/search/search.xqy";

let $complex-search :=
  search:parse('"imagine a complex search"', 
      (), "search:query")
return      
search:resolve($complex-search)

=> a search:response element

The REST API and Java API include interfaces for searching directly with structured queries. For details, see Searching With Structured Queries in REST Application Developer's Guide and Search Documents Using Structured Query Definition in Java Application Developer's Guide.

Example: Structured Search With Constraint References as Text

The following is a slightly more complicated Structured Search query. It has an and-query to combine terms, and has references to a constraint defined in a search options node, as it would be if parsed using the default query grammar (for example, decade:1940s represents the decade constraint with the value 1940s).

<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:and-query>
    <search:term-query>
      <search:text>hepburn</search:text>
    </search:term-query>
    <search:term-query>
      <search:text>decade:1940s</search:text>
    </search:term-query>
  </search:and-query>
</search:query>

The following is the corresponding JSON representation:

{
  "query": {
    "queries": [{
      "and-query": {
        "queries": [
          { "term-query": { "text": [ "hepburn" ] } },
          { "term-query": { "text": [ "decade:1940s" ] } }
        ]
      }
    }]
}}

Example: Structured Search With Constraint References

The following example demonstrates a query that includes an explicit reference to a constraint defined in query options.

Assume the query options include a decade bucketed constraint definition, and one of the buckets is named 1940s:

<!-- for complete options, see Buckets Example -->
<search:constraint name="decade">
    <search:range type="xs:gYear" facet="true">
      ...more buckets...
      <search:bucket lt="1950" ge="1940"
         name="1940s">1940s</search:bucket>
      <search:bucket lt="1940" ge="1930"
         name="1930s">1930s</search:bucket>
      ...more buckets...
      <search:facet-option>limit=10</search:facet-option>
      <search:attribute ns="" name="year"/>
      <search:element ns="http://marklogic.com/wikipedia"
         name="nominee"/>
    </search:range>
  </search:constraint>
</search:options>

When evaluated with the above options, the string query "hepburn AND decade:1940s" expresses a range constraint (decade:1940s) that limits matches to those that meet the criteria for the 1940s bucket of the decade constraint. The following is the equivalent structured query, expressed in XML:

<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:and-query>
    <search:term-query>
      <search:text>hepburn</search:text>
    </search:term-query>
    <search:range-constraint-query>
      <search:constraint-name>decade</search:constraint-name>
      <search:value>1940s</search:value>
    </search:range-constraint-query>
  </search:and-query>
</search:query>

The following is the corresponding JSON representation:

{
  "query": {
    "queries": [{
      "and-query": {
        "queries": [
          { "term-query": { "text": [ "hepburn" ] } },
          {
            "range-constraint-query": {
              "value": [ "1940s" ],
              "constraint-name": "decade"
            }
          }
        ]
      }
    }]
}}

Example: Structured Search on Key-Value Metadata Fields

A metadata field is a field over key-value document metadata. To make key-value metadata searchable, you must define a metadata field on the key, as described in Configuring a New Metadata Field in the Administrator's Guide. You might also need to enable field value searches on your database or configure a field range index, depending on the type of query you want to perform.

Once you define a field over a metadata key, you can include that key-value pair in searches using any of the field query capabilities.

For example, the following query matches the word twain when it occurs in the value of the metadata key author:

<word-query>
    <field name="author"/>
    <text>twain</text>
  </word-query>
</query>

The following is the equivalent query expressed as JSON:

{ "query": {
    "queries": [{
      "word-query": {
        "field": {"name": "mkey"},
        "text": "flubber"
      }
    }]
}}

Syntax Reference

This section provides detailed syntax information on structured queries. There is a subsection for each top level element in a structured query. Each section includes detailed syntax, an explanation of the child elements, and an example. Begin with the top level query wrapper.

query

A query is the top level wrapper around a structured query definition. It can contain one or more subquery children. See the subsections on each child for details.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <!-- word or phrase query -->
  <term-query />
  <!-- cts:query composers -->
  <and-query />
  <or-query />
  <and-not-query />
  <not-query />
  <not-in-query />
  <near-query />
  <boost-query />
  <!-- cts:query scoping ctors -->
  <properties-fragment-query />
  <directory-query />
  <collection-query />
  <container-query />
  <document-query />
  <document-fragment-query />
  <locks-fragment-query />
  <range-query />
  <value-query />
  <word-query />
  <geo-elem-query />
  <geo-elem-pair-query />
  <geo-attr-pair-query />
  <geo-path-query />
  <geo-json-property-query />
  <geo-json-property-pair-query />
  <lsqt-query />
  <before-query>
  <after-query>
  <period-compare-query />
  <period-range-query />
  <!-- Search API abstractions -->
  <range-constraint-query />
  <value-constraint-query />
  <word-constraint-query />
  <collection-constraint-query />
  <container-constraint-query />
  <element-constraint-query />
  <properties-constraint-query />
  <custom-constraint-query />
  <geospatial-constraint-query />
  <operator-state />
</query>

{
  "query": {
    "queries": [
      term-query,

      and-query,
      or-query,
      and-not-query,
      not-query,
      not-in-query,
      near-query,
      boost-query,

      properties-fragment-query,
      directory-query,
      collection-query,
      container-query,
      document-query,
      document-fragment-query,
      locks-fragment-query,
      range-query,
      value-query,
      word-query,
      geo-elem-query,
      geo-elem-pair-query,
      geo-attr-pair-query,
      geo-path-query,
      geo-json-property-query,
      geo-json-property-pair-query,
      lsqt-query,
      period-compare-query,
      period-range-query,

      range-constraint-query,
      value-constraint-query,
      word-constraint-query,
      collection-constraint-query,
      container-constraint-query,
      element-constraint-query,
      properties-constraint-query,
      custom-constraint-query,
      geospatial-constraint-query,
      operator-state    ]
  }
}

term-query

A query that matches one or more search terms or phrases. By default, a term-query is equivalent to cts:word-query. However, if you use the term query option to customize query term handling, this equivalence may not hold. For example, if your search includes a term option that specifies a field word constraint, then a term-query might be handled as a cts:field-word-query. For details, see term.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<term-query>
  <text>term-or-phrase</text>
  <weight>value</weight>
  <term-option>option</term-option>
</term-query>
 
"term-query": {
  "text": [ "term-or-phrase" ],
  "weight": "value",
  "term-option": [ option ]
}
Component Description

Element or JSON Property Name Req'd? Description 
text
 Y The term or phrase to search for. The query can contain multiple text children. When there are multiple terms, the query matches if any of the terms match. 
weight
 N A weight for this query. Default: 1.0. Higher weights move search results up in the relevance order. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64, inclusive). Weights greater than 64 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. 
term-option
 N

Term options to apply to the query. You can specify multiple term options. If the option has a value, the value of term-option is option=value. For example: <term-option>min-occurs=1</term-option> in XML, or "term-option": ["min-occurs=1"] in JSON.

For details, see the cts query corresponding to the query constraint type: cts:word-query, cts:element-word-query, cts:element-attribute-word-query, cts:field-word-query, or cts:json-property-word-query; and Term Options.
Examples

The following example searches for documents containing either of the terms dog or cat.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <term-query>
    <text>dog</text>
    <text>cat</text>
  </term-query>
</query>
 
{
  "query": {
    "queries": [{
      "term-query": {
        "text": [ "dog", "cat" ]
      }
    }]
}}

and-query

Find the intersection of matches specified by one or more sub-queries. For details, see cts:and-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<and-query>
  anyQueryType
  <ordered>bool</ordered>
</and-query>
 
"and-query": {
  "queries": [
    anyQueryType,
    "ordered": boolean
  ]
}
Component Description

Element or JSON Property Name Req'd? Description
anyQueryType N One or more sub-queries.
ordered N Whether or not the sub-query matches must occur in the order of the sub-queries. For example, if the sub-queries are "cat" and "dog", an ordered query will only match fragments where both "cat" and "dog" occur, and where "cat" comes before "dog" in the fragment. Default: false.
Examples

The following example searches for documents containing both of the terms dog and cat, with dog occurring before cat.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <and-query>
    <term-query>
      <text>dog</text>
    </term-query>
    <term-query>
      <text>cat</text>
    </term-query>
    <ordered>true</ordered>
  </and-query>
</query>
 
{
  "query": {
    "queries": [{
      "and-query": {
        "queries": [
          {
            "term-query": {
              "text": [ "dog" ]
            }
          },
          {
            "term-query": {
              "text": [ "cat" ]
            }
          },
          { "ordered": "true" }
        ]
      }
    }]
}}

or-query

Find the union of matches specified by one or more sub-queries. For details, see cts:or-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<or-query>
  anyQueryType
</or-query>
 
"or-query": {
  "queries": [ anyQueryType ]
}
Component Description

Element or JSON Property Name Req'd? Description
anyQueryType N One or more sub-queries.
Examples

The following example matches documents containing either the phrase dog bone or the term cat.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <or-query>
    <term-query>
      <text>dog bone</text>
    </term-query>
    <term-query>
      <text>cat</text>
    </term-query>
  </or-query>
</query>
 
{
  "query": {
    "queries": [{
      "or-query": {
        "queries": [
          {
            "term-query": {
              "text": ["dog bone"]
            }
          },
          {
            "term-query": {
              "text": [ "cat" ]
            }
          }
        ]}
    }]
}}

and-not-query

Find the set difference of the matches specified by two sub-queries. That is, return results that match the positive query, but which do not match the negative query. For details, see cts:and-not-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<and-not-query>
  <positive-query>
    anyQueryType
  </positive-query>
  <negative-query>
    anyQueryType
  </negative-query>
</and-not-query>

"and-not-query": {
  "positive-query": { anyQueryType },
  "negative-query" : { anyQueryType }
}
Component Description

Element or JSON Property Name Req'd? Description
positive-query Y A query specifying the results filtered in. All results will match this query.
negative-query Y A query specifying the results filtered out. None of the results will match this query.
Examples

The following example matches occurrences of dog, but only where cat does not occur in the same fragment.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <and-not-query>
    <positive-query>
      <term-query>
        <text>dog</text>
      </term-query>
    </positive-query>
    <negative-query>
      <term-query>
        <text>cat</text>
      </term-query>
    </negative-query>
  </and-not-query>
</query>
 
{
  "query": {
    "queries": [{
      "and-not-query": {
        "positive-query": {
          "term-query": {
            "text": [ "dog" ]
        }},
        "negative-query": {
          "term-query": {
            "text": [ "cat" ]
        }}
      }
    }]
}}

not-query

A query that filters out any results that match its sub-query. For details, see cts:not-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<not-query>
  anyQueryType
</not-query>

"not-query": {
  anyQueryType
}
Component Description

Element or JSON Property Name Req'd? Description
anyQueryType Y A negative query, specifying the search results to filter out.
Examples

The following only matches documents that do not include the term dog.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <not-query>
    <term-query>
      <text>dog</text>
    </term-query>
  </not-query>
</query>
 
{
  "query": {
    "queries": [{
      "not-query": {
        "term-query": {
          "text": [ "dog" ]
        }
      }
    }]
}}

not-in-query

A query that returns results matching a positive query only when those matches do not overlap positionally with matches to a negative query. For details, see cts:not-in-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<not-in-query>
  <positive-query>
    anyQueryType
  </positive-query>
  <negative-query>
    anyQueryType
  </negative-query>
</not-in-query>

"not-in-query": {
  "positive-query": { anyQueryType },
  "negative-query" : { anyQueryType }
}
Component Description

Element or JSON Property Name Req'd? Description
positive-query Y A positive query, specifying the search results to filter in.
negative-query Y A negative query, specifying the search results to filter out.
Examples

The example below matches fragments that contain at least one occurrence of dog outside of the phrase man bites dog.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <not-in-query>
    <positive-query>
      <term-query>
        <text>dog</text>
      </term-query>
    </positive-query>
    <negative-query>
      <term-query>
        <text>man bites dog</text>
      </term-query>
    </negative-query>
  </not-in-query>
</query>
 
{
  "query": {
    "queries": [{
      "not-in-query": {
        "positive-query": {
          "term-query": {
            "text": [ "dog" ]
        }},
        "negative-query": {
          "term-query": {
            "text": [
              "man bites dog"
            ]
        }}
      }
    }]
}}

true-query

A query that matches all documents (or fragments). For details, see cts:true-query.

Syntax Summary
XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<true-query/>
 
"true-query": null
Component Description

This query has no sub-components.

Examples

The following example matches all documents.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <true-query/>
</query>
 
{"query": {
    "queries": [{
      "true-query": null
    }]
}}

false-query

A query that matches no documents (or fragments). For details, see cts:false-query.

Syntax Summary
XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<false-query/>
 
"false-query": null
Component Description

This query has no sub-components.

Examples

The following example matches all documents.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <false-query/>
</query>
 
{"query": {
    "queries": [{
      "false-query": null
    }]
}}

near-query

A query that returns results matching all of the specified queries where the matches occur within a specified distance of each other. For details, see cts:near-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<near-query>
  anyQueryType
  <distance>integer</distance>
  <minimum-distance>integer<minimum-distance>
  <distance-weight>
    double
  </distance-weight>
  <ordered>boolean</ordered>
</near-query>
 
"near-query": {
  "queries": [
    anyQueryType,
    "distance": "number",
    "minimum-distance": "number",
    "distance-weight": "number",
    "ordered" : boolean
  ]
}
Component Description

Note that distance and minimum-distance apply to each near-query match. Therefore, if minimum-distance is greater than distance, there can be no matches.

Element or JSON Property Name Req'd? Description
anyQueryType Y One or more queries that must match within the specified proxmity to each other.
distance N A maximum distance, in number of words, between any two matching queries. Default: 10. The results match if two queries match and the minimum distance between the two matches is less than or equal to the specified distance. A distance of 0 matches when the text is the same text or when there is overlapping text. A negative distance is treated as 0.
minimum-distance N The minimum distance, in words, between any two matching queries. Default: 0. The results match if the two queries match and the minimum distance between the two matches is greater than or equal to the specified minimum distance. A negative distance is treated as 0.
distance-weight N A weight attributed to the distance for this query. Higher weights add to the importance of distance (as opposed to term matches) when the relevance order is calculated. Default: 1.0.
ordered N Whether or not the sub-query matches must occur in the order of the sub-queries. For example, if the sub-queries are "cat" and "dog", an ordered query will only match fragments where both "cat" and "dog" occur within the required distance and "cat" comes before "dog" in the fragment. Default: false.
Examples

The following example matches occurrences of dog occuring within in two terms of cat.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <near-query>
    <term-query>
      <text>dog</text>
    </term-query>
    <term-query>
      <text>cat</text>
    </term-query>
    <distance>2</distance>
  </near-query>
</query>
 
{
  "query": {
    "queries": [{
      "near-query": {
        "queries": [
          {
            "term-query": {
              "text": [ "dog" ]
            }
          },
          {
            "term-query": {
              "text": [ "cat" ]
            }
          },
          { "distance": "2" }
        ]
      }
    }]
}}

boost-query

Find all matches to a query. Boost the search relevance score of results that also match the boosting query. For details, see cts:boost-query and Boosting Relevance Score With a Secondary Query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<boost-query>
  <matching-query>
    anyQueryType
  </matching-query>
  <boosting-query>
    anyQueryType
  </boosting-query>
</boost-query>
 
"boost-query": {
  "matching-query": { anyQueryType },
  "boosting-query" : { anyQueryType }
}
Component Description

Element or JSON Property Name Req'd? Description
matching-query N The query to match. All search results matching this query are returned (modulo limitations imposed by search options). This element can occur multiple times; multiple occurrences are AND'd together. If there are no occurrences, the boosting query implicitly matches all documents.
boosting-query N The query to use for relevance score boosting. Those results which match both matching-query and boosting-query have their relevance scores modified proportional to the weight of boosting-query. The boosting-query is not evaluated if there are no matches to matching-query. This element can occur multiple times; multiple occurrences are AND'd together. If there are no occurrences, the boosting query implicitly matches all documents.
Examples

The following example searches for documents containing the term dog. Documents that also contain the term cat will return a search:result with a relevance score boosted proportional to the weight 10.0, giving them higher scores than documents that do not contain cat.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <boost-query>
    <matching-query>
    <term-query>
      <text>dog</text>
    </term-query>
    </matching-query>
    <boosting-query>
      <term-query>
        <text>cat</text>
        <weight>10.0</weight>
      </term-query>
    </boosting-query>
  </boost-query>
</query>
 
{
  "query": {
    "queries": [{
      "boost-query": {
        "matching-query": {
          "term-query": {
            "text": [ "dog" ]
        }},
        "boosting-query": {
          "term-query": {
            "text": [ "cat" ],
            "weight": "10.0"
        }}
      }
    }]
}}

properties-fragment-query

A query that matches all documents where the sub-query matches against document properties. For details, see cts:properties-fragment-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<properties-fragment-query>
  anyQueryType
</properties-fragment-query>
 
"properties-fragment-query": {
  anyQueryType
}
Component Description

Element or JSON Property Name Req'd? Description
anyQueryType Y A sub-query to run against document properties.
Examples

The following example matches all documents modified since 2012-12-31, assuming you define an element range index on the last-modified property and your query includes options defining the modified constraint.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="modified">
    <range type="xs:string">
      <element
        ns="http://marklogic.com/xdmp/property"
        name="last-modified"/>
      <fragment-scope>properties</fragment-scope>
    </range>
  </constraint>
</options>
<query xmlns="http://marklogic.com/appservices/search">
  <properties-fragment-query>
    <range-constraint-query>
      <constraint-name>modified</constraint-name>
      <value>2012-12-31</value>
      <range-operator>GT</range-operator>
    </range-constraint-query>
  </properties-fragment-query>
</query>
JSON 
{
  "options": {
    "constraint": [
      {
        "name": "modified",
        "range": {
          "type": "xs:string",
          "element": {
            "ns": "http://marklogic.com/xdmp/property",
            "name": "last-modified"
          },
          "fragment-scope": "properties"
    }]
}}
{
  "query": {
    "queries": [{
      "properties-fragment-query": {
        "range-constraint-query": {
          "value": [ "2012-12-31" ],
          "constraint-name": "modified",
          "range-operator": "GT"
        }
      }
    }]
}}

directory-query

A query matching documents in the directories with the given URIs. For details, see cts:directory-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<directory-query>
  <uri>directory-uri</uri>
  <infinite>boolean</infinite>
</directory-query>
 
"directory-query": {
  "uri": [ directory-uris ],
  "infinite": boolean
}
Component Description

Element or JSON Property Name Req'd? Description
uri Y One or more directory URIs. A directory URI must end with a forward slash (/).
infinite N Whether or not to recurse through all child directories. Default: true.
Examples

The following example matches documents in the database directories /documents/ or /images/, but does not look for matches in any sub-directories.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <directory-query>
    <uri>/documents/</uri>
    <uri>/images/</uri>
    <infinite>false</infinite>
  </directory-query>
</query>
 
{
  "query": {
    "queries": [{
      "directory-query": {
        "uri": [
          "/documents/",
          "/images/"
        ],
        "infinite": false
      }
    }]
}}

collection-query

A query matching documents in any of the collections with the given URIs. For details, see cts:collection-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<collection-query>
  <uri>collection-uri</uri>
</collection-query>
 
"collection-query": {
  uri": [ collection-uris ]
}
Component Description

Element or JSON Property Name Req'd? Description
uri Y One or more collection URIs. A document matches if it is in any one of the collections specified by uri.
Examples

The following example matches documents in the reports collection or the analysis collection.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <collection-query>
    <uri>reports</uri>
    <uri>analysis</uri>
  </collection-query>
</query>
 
{
  "query": {
    "queries": [{
      "collection-query": {
        "uri": ["reports","analysis"]
      }
    }]
}}

container-query

A query matching documents containing a specified XML element or JSON property whose contents match a specified sub-query.

Syntax Summary
XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<container-query>
  <element name=string ns=string />
  <json-property>name</json-property>
  <fragment-scope>scope</fragment-scope>
  anyQueryType
</container-query>
 
"container-query": {
  "element": {
    "name": elem-name,
    "ns": namespace
  },
  "json-property": prop-name,
  "fragment-scope": scope,
  anyQueryType
}
Component Description

Your query must include exactly one of element or json-property.

Element or JSON Property Name Req'd? Description 
element
 Y An XML element descriptor, identified by name and namespace (ns). Both name and ns are required. If you include element, you should not include a json-property. If you specify multiple elements, the query matches documents that satisfy any one of the element constraints. 
json-property
 Y A JSON property name. If you include json-property, you should not include an element. If you specify multiple properties, the query matches documents that satisfy any one of the property constraints. 
fragment-scope
 N Constrain matches to the specified fragment scope. Allowed values: documents (default) or properties. For more details, see the fragment-scope query option. 
anyQueryType
 Y A sub-query to run against the contents of matching containers (XML elements or JSON properties). An and-query will only match array items in the container if all the and-query criteria are met in the same array value.
Examples

The following XML example matches all documents containing a <pets/> element with descendants whose contents match the term dog. The JSON example matches all documents containing the property named pets with descendants whose contents match the term dog.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <container-query>
    <element name="pet" ns="" />
    <term-query>
      <text>dog</text>
    </term-query>
</query>

{
  "query": {
    "queries": [{
      "container-query": {
        "json-property": "pet",
        "term-query": {
          "text": [ "dog" ]
        }
      }
    }]
}}

document-query

A query matching documents with the given URIs.. For details, see cts:document-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<document-query>
  <uri>document-uri</uri>
</document-query>

"document-query": {
  "uri": [ document-uris ]
}
Component Description

Element or JSON Property Name Req'd? Description
uri Y One or more document URIs.
Examples

The following example matches either the document with URI /documents/reports.xml or the document with URI /documents/analysis.xml.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <document-query>
    <uri>/documents/reports.xml</uri>
    <uri>/documents/analysis.xml</uri>
  </document-query>
</query>

{
  "query": {
    "queries": [{
      "document-query": {
        "uri": [
          "/documents/reports.xml",
          "/documents/analysis.xml"
        ]
      }
    }]
}}

document-fragment-query

A query that matches all documents where a sub-query matches any document fragment. For details, see cts:document-fragment-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<document-fragment-query>
  anyQueryType
</document-fragment-query>

"document-fragment-query": {
  anyQueryType
}
Component Description

Element or JSON Property Name Req'd? Description
anyQueryType Y The query to be matched against any document fragment.
Examples

The following example matches any documents that include fragments that contain the term dog.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <document-fragment-query>
    <term-query>
      <text>dog</text>
    </term-query>
  </document-fragment-query>
</query>
 
{
  "query": {
    "queries": [{
      "document-fragment-query": {
        "term-query": {
          "text": [ "dog" ]
        }
      }
    }]
}}

locks-fragment-query

A query that matches all documents where a sub-query matches a document-locks fragment. For details, see cts:locks-fragment-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<locks-fragment-query>
  anyQueryType
</locks-fragment-query>

"locks-fragment-query": {
  anyQueryType
}
Component Description

Element or JSON Property Name Req'd? Description
anyQueryType Y The query to be matched against any document fragment.
Examples

The following example matches documents with document locks fragments that include the term write in lock:lock-type element. This example assumes the existence of an element range index on lock:lock-type and query options that include a constraint on that element with the name lock-type.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <locks-fragment-query>
    <container-constraint-query>
      <constraint-name>
        lock-type
      </constraint-name>
      <term-query>
        <text>write</text>
      </term-query>
    </container-constraint-query>
  </locks-fragment-query>
</query>
 
{
  "query": {
    "queries": [{
      "locks-fragment-query": {
        "container-constraint-query": {
         "constraint-name": "lock-type",
         "term-query": {
           "text": [ "write" ]
         }
      }}
    }]
}}

range-query

A query that applies a range constraint and compares the results to the specified value. For details, see Constraint Options and the XQuery functions cts:element-range-query, cts:element-attribute-range-query, cts:field-range-query, and cts:path-range-query.

A range-query is equivalent to string query expressions of the form constraint:value or constraint LE value. The constraint is defined in the query and must be backed by a range index.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<range-query type=index-type collation=uri>
  <element name=elem-name ns=namespace />
  <attribute name=attr-name ns=namespace />
  <json-property>name</json-property>
  <field name=field-name collation=uri />
  <path-index>path-expr</path-index>
  <fragment-scope>scope</fragment-scope>
  <value>value</value>
  <range-operator>operator</operator>
  <range-option>option</range-option>
</range-query>
 
"range-query": {
  "type": index-type,
  "collation": index-collation-uri,
  "element": {
    "name": elem-name,
    "ns": namespace
  },
  "attribute": {
    "name": attr-name,
    "ns": namespace
  },
  "json-property": prop-name,
  "field": {
    "name": field-name,
    "collation": uri
  },
  "path-index": {
    "text": path-expr,
    "namespaces": {
      prefix: namespace-uri
    }
  },
  "fragment-scope": scope,
  "value": value-as-string,
  "range-operator": operator,
  "range-option": option
}
Component Description

You must specify an element, json-property, field, or path-index, or an element and an attribute to define the range constraint to apply to the query. These components are mutually exclusive: Except for element and attribute, a query must include exactly one.

Element or JSON Property Name Req'd? Description 
element
 N An XML element descriptor, identified by element name and namespace (ns). Both name and ns are required. If you include element, you should not include a json-property, field, or path-index. 
attribute
 N An XML attribute descriptor, identifying the attribute by name and namespace (ns). Both name and ns are required. 
json-property
 N A JSON property name. If you include json-property, you should not include an element, field, or path-index. 
field
 N A field descriptor, identified by the field name (required) and optional collation. The database configuration must include a definition for this field. If you include field, you should not include an element, json-property, or path-index. 
path-index
 N

A path range expression. If the path expression includes namespace prefixes, you must define the namespace bindings on the path-index. If you include path-index, you should not include an element, json-property, or field.

The database configuration must include a matching path range index. The path expression and namespace URIs must match the index configuration; namespace prefixes do not have to match.

The path expression is limited to the subset of XPath that can be used to define a path range index. For details, see Path Field and Path-Based Range Index Configuration in the XQuery and XSLT Reference Guide.

 
fragment-scope
 N Constrain matches to the specified fragment scope. Allowed values: documents (default) or properties. For more details, see the fragment-scope query option. 
value
 N The value against which to match XML elements, XML element attributes, JSON properties, or fields that match the constraint identified by constraint-name. This element can occur 0 or more times. 
range-operator
 N One of LT, LE, GT, GE, EQ, NE. Default: EQ. The relationship that must be satisfied between constraint matches and value. 
range-option
 N One or more range query options. Allowed values depend on the type of range query (element, path, field, etc.). For details, see Including a Range or Geospatial Query in Scoring in Search Developer's Guide. For a list of options, see Range Options. 
type
 N The type of the range index. Required when you have multiple indexes over the same item with different datatypes. 
collation
 N A collation URI to use if the index type is string.
Examples

The following example matches documents containing a <body-color/> element with a value of black, assuming an element range index exists on <body-color/>.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <range-query type="xs:string">
    <element ns="" name="body-color"/>
    <value>black</value>
  </range-query>
</query>
 
{
  "query": {
    "queries": [{
      "range-query": {
        "type": "xs:string",
        "element": {
          "ns": "",
          "name": "body-color"
        },
        "value": [ "black" ]
      }
    }]
}}

value-query

A query that matches fragments where the value of an XML element, XML attribute, JSON property, or field matches value in the text XML element or JSON property of the query.

When searching JSON documents, the criteria value in the query text element or JSON property must be properly typed by setting the type element or property in the query. If you do not set type in the query, string is assumed, which will never match a number, boolean, or null value in a JSON document.

The match semantics depend on the text value, the database configuration, and the options in effect. For details, seeText Match Semantics or cts:element-value-query, cts:element-attribute-value-query, cts:json-property-value-query, or cts:field-value-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<value-query type=node-type>
  <element name=elem-name ns=namespace />
  <attribute name=attr-name ns=namespace />
  <json-property>name</json-property>
  <field name=field-name collation=uri />
  <fragment-scope>scope</fragment-scope>
  <text>name</text>
  <term-option>option/term-option>
  <weight>value</weight>
</value-query>

"value-query": {
  "type": node-type,
  "element": {
    "name": elem-name,
    "ns": namespace
  },
  "attribute": {
    "name": attr-name,
    "ns": namespace
  },
  "json-property": name,
  "field": {
    "name": field-name,
    "collation": uri
  },
  "fragment-scope": scope,
  "text": [ name ],
  "term-option": [ option ],
  "weight": number
}
Component Description

You must specify an element, json-property, field, or an element and an attribute to define the range constraint to apply to the query. These components are mutually exclusive: Except for element and attribute, a query must include exactly one.

Element, Attribute, or JSON Property Name Req'd? Description 
type
 N A JSON node type, one of string (default), boolean, null, number. Only meaningful for JSON content. Use type to constrain the matches to values in this node type. Non-JSON documents never contain boolean, null or number nodes. 
element
 N An XML element descriptor, identified by element name and namespace (ns). Both name and ns are required. If you include element, you should not include a json-property. 
attribute
 N An XML attribute descriptor, identifying the attribute by name and namespace (ns). Both name and ns are required. 
json-property
 N A JSON property name. If you include json-property, you should not include an element. 
field
 N A field descriptor, identified by the field name (required) and optional collation. The database configuration must include a definition for this field. 
fragment-scope
 N Constrain matches to the specified fragment scope. Allowed values: documents (default) or properties. For more details, see the fragment-scope query option. 
text
 N The value that must match in an XML element, XML element attribute, JSON property, or field value. Multiple values can be specified. If there is no type specifier, the values are treated as strings for matching purposes. The interpretation of the value is determined by the type setting in the query. 
term-option
 N

Term options to apply to the query when matching text. You can specify multiple term options. If the option has a value, the value of term-option is option=value. For example: <term-option>min-occurs=1</term-option>.

For details, see the cts query corresponding to the query constraint type: cts:element-value-query, cts:element-attribute-value-query, cts:json-property-value-query, or cts:field-value-query; and Term Options.

 
weight
 N A weight for this query. Default: 1.0. Higher weights move search results up in the relevance order. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64, inclusive). Weights greater than 64 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.
Examples

The following example matches documents where the field defined with the name myFieldName has the value Jane Doe. The example assumes the field myFieldName is defined in the database configuration and that field searches are enabled for the database.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <value-query>
    <field name="myFieldName" />
    <text>Jane Doe</text>
  </value-query>
</query>
 
{
  "query": {
    "queries": [{
      "value-query": {
        "field": {
          "name": "myFieldName",
        },
        "text": [ "Jane Doe" ]
      }
    }]
}}

The following example matches documents where the JSON property num contains the number value 42. Since type is set to number, the query matches a document such as { "num": 42 }, but it will not match a document such as { "num": "42" }. If you did not set type, then the type would be string and the query would match a document such as { "num": "42" } but would not match a document such as { "num": "42" }.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <value-query>
    <json-property>num</json-property>
    <text>42</text>
    <type>number</type>
  </value-query>
</query>
 
{
  "query": {
    "queries": [{
      "value-query": {
        "json-property": "num",
        "type": "number",
        "text": [ "42" ]
      }
    }]
}}

Note that in the JSON version of the query, the value of text can be either a string ("42") or a number (42). The interpretation of the value depends on the type setting in the query.

word-query

A query that matches fragments containing the specified terms or phrases in the XML element or attribute, JSON property, or field identified by the constraint defined in the query. This is similar to a string query of the form constraint:value, where the constraint is an element, element attribute, JSON property, or field constraint. For details, see the cts word query function that corresponds to your constraint type, such as cts:element-word-query or cts:field-word-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<word-query>
  <element name=elem-name ns=namespace />
  <attribute name=attr-name ns=namespace />
  <json-property>name</json-property>
  <field name=field-name collation=uri />
  <fragment-scope>scope</fragment-scope>
  <text>name</text>
  <term-option>option/term-option>
  <weight>value</weight>
</word-query>
 
"word-query": {
  "element": {
    "name": elem-name,
    "ns": namespace
  },
  "attribute": {
    "name": attr-name,
    "ns": namespace
  },
  "json-property": prop-name,
  "field": {
    "name": field-name,
    "collation": uri
  },
  "fragment-scope": scope,
  "text": [ name ],
  "term-option": [ option ],
  "weight": number
}
Component Description

You must specify at least one element, json-property, field, or an element and an attribute to define the range constraint to apply to the query. These components are mutually exclusive: Except for element and attribute pairs, a word-query must include exactly one type of constraint specifier.

Element or JSON Property Name Req'd? Description 
element
 N An XML element descriptor, identified by element name and namespace (ns). Both name and ns are required. You can specify multiple elements, in which case the query matches if a match is found in any of the elements. If you include element, you should not include a json-property or field. 
attribute
 N An XML attribute descriptor, identifying the attribute by name and namespace (ns). Both name and ns are required. You can specify multiple attributes, in which case the query matches if a match is found in any of the attributes. You cannot use this component in conjunction with json-property or field. 
json-property
 N A JSON property name. You can specify multiple properties, in which case the query matches if a match is found in any of the properties. If you include json-property, you should not include an element, attribute, or field. 
field
 N A field descriptor, identified by the field name (required) and optional collation. The database configuration must include a definition for the field. You can specify multiple fields, in which case the query matches if a match is found in any of the fields. If you include field, you should not include an element, attribute, or json-property. 
fragment-scope
 N Constrain matches to the specified fragment scope. Allowed values: documents (default) or properties. For more details, see the fragment-scope query option. 
text
 N Terms or phrases that must occur in documents matching the constraint defined by this query. Multiple values can be specified; if any one matches, the document matches the query. 
term-option
 N

Term options to apply to the query. You can specify multiple term options. If the option has a value, the value of term-option is option=value. For example: <term-option>min-occurs=1</term-option>.

For details, see the cts query corresponding to the query constraint type, such as: cts:element-word-query, cts:element-attribute-word-query, cts:json-property-word-query, or cts:field-word-query; and Term Options.

 
weight
 N A weight for this query. Default: 1.0. Higher weights move search results up in the relevance order. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64, inclusive). Weights greater than 64 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.
Examples

The following example matches documents containing a <body-color/> element that contains the word black.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<query>
  <word-query>
    <element name="body-color" ns="" />
    <text>black</text>
  </word-query>
</query>
 
{
  "query": {
    "queries": [{
      "word-query": {
        "element": {
          "name": "body-color",
          "ns": ""
        },
        "text": [ "black" ]
      }
    }]
}}

geo-elem-query

A query that returns documents that match the geospatial element constraint defined in the query. For details, see cts:element-geospatial-query, cts:element-child-geospatial-query, or Geospatial Search Applications.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-elem-query>
  <parent name=elem-name ns=uri />
  <element name=elem-name ns=uri />
  <geo-option>option</geo-option>
  <fragment-scope>scope</fragement-scope>
  <point>
    <latitude>float</latitude>
    <longitude>float</longitude>
  </point>
  <box>
    <south>float</south>
    <west>float</west>
    <north>float</north>
    <east>float</east>
  </box>
  <circle>
    <radius>float</radius>
    <point/>
  </circle>
  <polygon>
    <point/>
  </polygon>
</geo-elem-query>
 
"geo-elem-query": {
  "parent": {
    "name": elem-name
    "ns": uri
  },
  "element": {
    "name": elem-name
    "ns": uri
  },
  "geo-option": [ option ],
  "fragment-scope": scope,
  "point": [
    {
      "latitude": number,
      "longitude": number
    }
  ],
  "box": [
    {
      "south": number,
      "west": number,
      "north": number,
      "east": number
    }
  ],
  "circle": [
    {
      "radius": number,
      point
    }
  ],
  "polygon": [ point ]
}
Component Description

A geospatial query contains one or more points or regions, described by point, box, circle, and polygon XML child elements or JSON sub-objects. The element pair containing geospatial data are described by parent, lat, and lon. For details, see Geospatial Search Applications

Element or JSON Property Name Req'd? Description 
parent
 N Optional. The parent element of the element containing geospatial data, identified by element name and namespace (ns). Both name and ns are required. 
element
 Y The element containing geospatial data, identified by name and namespace (ns). Both name and ns are required. 
fragment-scope
 N Constrain matches to the specified fragment scope. Allowed values: documents (default) or properties. For more details, see the fragment-scope query option. 
geo-option
 N Geospatial options to apply to the query. You can specify multiple options. If an option has a value, the value of geo-option is of the form option=value. For example: <geo-option>units=miles</geo-option>. For details, see cts:element-geospatial-query or cts:element-child-geospatial-query. 
point
 N Zero or more geographic points, each defined by a latitude and a longitude. The query can contain 0 or more points. 
box
 N Zero or more rectangular regions, each defined by 4 points: north, south, east, and west. 
circle
 N Zero or more circles, each defined by radius and a center point. 
polygon
 N Zero or more polygons, each series of point's.
Examples

The following example matches points contained in either of two polygons. The constraint defined in the query by parent and element defines how to construct the points to match against the regions defined in the query.

Format Query
XML 
<query xmlns="http://marklogic.com/appservices/search">
  <geo-elem-query>
    <parent ns="ns1" name="elem1"/> 
    <element ns="ns1" name="elem2"/> 
    <polygon>
      <point> <latitude>1</latitude> <longitude>2</longitude> </point>
      <point> <latitude>3</latitude> <longitude>4</longitude> </point>
      <point> <latitude>5</latitude> <longitude>6</longitude> </point>
      <point> <latitude>7</latitude> <longitude>8</longitude> </point>
    </polygon>
    <polygon>
      <point> <latitude>2</latitude> <longitude>6</longitude> </point>
      <point> <latitude>3</latitude> <longitude>7</longitude> </point>
      <point> <latitude>4</latitude> <longitude>8</longitude> </point>
      <point> <latitude>5</latitude> <longitude>9</longitude> </point>
    </polygon>
  </geo-elem-query>
</query>
JSON 
{
  "query": {
    "queries": [{
      "geo-elem-query": {
        "parent": { "ns": "ns1", "name": "elem1" },
        "element": { "ns": "ns1", "name": "elem2" },
        "polygon": [
          {
            "point": [
              { "latitude": 1, "longitude": 2 },
              { "latitude": 3, "longitude": 4 },
              { "latitude": 5, "longitude": 6 },
              { "latitude": 7, "longitude": 8 }
            ] 
          }, 
          {
            "point": [
              { "latitude": 2, "longitude": 6 },
              { "latitude": 3, "longitude": 7 },
              { "latitude": 4, "longitude": 8 },
              { "latitude": 5, "longitude": 9 }
            ]
          } 
        ]
      }
    }] 
}}

geo-elem-pair-query

A query that returns documents that match the geospatial XML element constraint defined in the query. For details, see cts:element-pair-geospatial-query and Geospatial Search Applications.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-elem-pair-query>
  <parent name=elem-name ns=uri />
  <lat name=elem-name ns=uri />
  <lon name=elem-name ns=uri />
  <geo-option>option</geo-option>
  <fragment-scope>scope</fragement-scope>
  <point>
    <latitude>float</latitude>
    <longitude>float</longitude>
  </point>
  <box>
    <south>float</south>
    <west>float</west>
    <north>float</north>
    <east>float</east>
  </box>
  <circle>
    <radius>float</radius>
    <point/>
  </circle>
  <polygon>
    <point/>
  </polygon>
</geo-elem-pair-query>
 
"geo-elem-pair-query": {
  "parent": {
    "name": elem-name
    "ns": uri
  },
  "lat": {
    "name": elem-name
    "ns": uri
  },
  "lon": {
    "name": elem-name
    "ns": uri
  },
  "geo-option": [ option ],
  "fragment-scope": scope,
  "point": [
    {
      "latitude": number,
      "longitude": number
    }
  ],
  "box": [
    {
      "south": number,
      "west": number,
      "north": number,
      "east": number
    }
  ],
  "circle": [
    {
      "radius": number,
      point
    }
  ],
  "polygon": [ point ]
}
Component Description

A geospatial query contains one or more points or regions, described by point, box, circle, and polygon XML child elements or JSON sub-objects. The element pair containing geospatial data are described by parent, lat, and lon.

Element or JSON Property Name Req'd? Description 
parent
 N The element containing geospatial data, identified by element name and namespace (ns). Both name and ns are required. 
lat
 Y The XML element containing latitude data, identified by name and namespace (ns). Both name and ns are required. 
lon
 Y The XML element containing longitude data, identified by name and namespace (ns). Both name and ns are required. 
fragment-scope
 N Constrain matches to the specified fragment scope. Allowed values: documents (default) or properties. For more details, see the fragment-scope query option. 
geo-option
 N Geospatial options to apply to the query. You can specify multiple options. If an option has a value, the value of geo-option is of the form option=value. For example: <geo-option>units=miles</geo-option>. For details, see cts:element-pair-geospatial-query. 
point
 N Zero or more geographic points, each defined by a latitude and a longitude. The query can contain 0 or more points. 
box
 N Zero or more rectangular regions, each defined by 4 points: north, south, east, and west. 
circle
 N Zero or more circles, each defined by radius and a center point. 
polygon
 N Zero or more polygons, each series of point's.
Examples

The following example matches points contained in either of two polygons. The constraint defined in the query by parent, lat, and lon defines how to construct the points to match against the regions defined in the query.

Format Query
XML 
<query xmlns="http://marklogic.com/appservices/search">
  <geo-elem-pair-query>
    <parent ns="ns1" name="elem2"/> 
    <lat ns="ns2" name="attr2"/> 
    <lon ns="ns3" name="attr3"/>
    <polygon>
      <point> <latitude>1</latitude> <longitude>2</longitude> </point>
      <point> <latitude>3</latitude> <longitude>4</longitude> </point>
      <point> <latitude>5</latitude> <longitude>6</longitude> </point>
      <point> <latitude>7</latitude> <longitude>8</longitude> </point>
    </polygon>
    <polygon>
      <point> <latitude>2</latitude> <longitude>6</longitude> </point>
      <point> <latitude>3</latitude> <longitude>7</longitude> </point>
      <point> <latitude>4</latitude> <longitude>8</longitude> </point>
      <point> <latitude>5</latitude> <longitude>9</longitude> </point>
    </polygon>
  </geo-elem-pair-query>
</query>
JSON 
{"query": {
    "queries": [{
      "geo-elem-pair-query": {
        "parent": { "ns": "ns1", "name": "elem2" },
        "lat": { "ns": "ns2", "name": "attr2" },
        "lon": { "ns": "ns3", "name": "attr3" }
        "polygon": [
          {
            "point": [
              { "latitude": 1, "longitude": 2 },
              { "latitude": 3, "longitude": 4 },
              { "latitude": 5, "longitude": 6 },
              { "latitude": 7, "longitude": 8 }
            ] 
          }, 
          {
            "point": [
              { "latitude": 2, "longitude": 6 },
              { "latitude": 3, "longitude": 7 },
              { "latitude": 4, "longitude": 8 },
              { "latitude": 5, "longitude": 9 }
            ]
          } 
        ]
      }
    }] 
}}

geo-attr-pair-query

A query that returns documents that match the geospatial element constraint defined in the query. For details, see cts:element-attribute-pair-geospatial-query or Geospatial Search Applications.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-attr-pair-query>
  <parent name=elem-name ns=uri />
  <lat name=attr-name ns=uri />
  <lon name=attr-name ns=uri />
  <geo-option>option</geo-option>
  <fragment-scope>scope</fragement-scope>
  <point>
    <latitude>float</latitude>
    <longitude>float</longitude>
  </point>
  <box>
    <south>float</south>
    <west>float</west>
    <north>float</north>
    <east>float</east>
  </box>
  <circle>
    <radius>float</radius>
    <point/>
  </circle>
  <polygon>
    <point/>
  </polygon>
</geo-attr-pair-query>
 
"geo-attr-pair-query": {
  "parent": {
    "name": elem-name
    "ns": uri
  },
  "lat": {
    "name": attr-name
    "ns": uri
  },
  "lon": {
    "name": attr-name
    "ns": uri
  },
  "geo-option": [ option ],
  "fragment-scope": scope,
  "point": [
    {
      "latitude": number,
      "longitude": number
    }
  ],
  "box": [
    {
      "south": number,
      "west": number,
      "north": number,
      "east": number
    }
  ],
  "circle": [
    {
      "radius": number,
      point
    }
  ],
  "polygon": [ point ]
}
Component Description

A geospatial query contains one or more points or regions, described by point, box, circle, and polygon XML child elements or JSON sub-objects. The element pair containing geospatial data are described by parent, lat, and lon. For details, see Geospatial Search Applications

Element or JSON Property Name Req'd? Description 
parent
 Y The element containing the lat and lon attributes that hold geospatial data, identified by element name and namespace (ns). Both name and ns are required. 
lat
 Y The name of the attribute that contains latitude data, identified by name and namespace (ns). Both name and ns are required. 
lon
 Y The name of the attribute that contains longitude data, identified by name and namespace (ns). Both name and ns are required. 
fragment-scope
 N Constrain matches to the specified fragment scope. Allowed values: documents (default) or properties. For more details, see the fragment-scope query option. 
geo-option
 N Geospatial options to apply to the query. You can specify multiple options. If an option has a value, the value of geo-option is of the form option=value. For example: <geo-option>units=miles</geo-option>. For details, see cts:element-attribute-pair-geospatial-query. 
point
 N Zero or more geographic points, each defined by a latitude and a longitude. The query can contain 0 or more points. 
box
 N Zero or more rectangular regions, each defined by 4 points: north, south, east, and west. 
circle
 N Zero or more circles, each defined by radius and a center point. 
polygon
 N Zero or more polygons, each series of point's.
Examples

The following example matches points contained in either of two polygons. The constraint defined in the query by parent, lat, and lon defines how to construct the points to match against the regions defined in the query.

Format Query
XML 
<query xmlns="http://marklogic.com/appservices/search">
  <geo-attr-pair-query>
    <parent ns="ns1" name="elem"/> 
    <lat ns="ns1" name="attr1"/> 
    <lon ns="ns1" name="attr2" />
    <polygon>
      <point> <latitude>1</latitude> <longitude>2</longitude> </point>
      <point> <latitude>3</latitude> <longitude>4</longitude> </point>
      <point> <latitude>5</latitude> <longitude>6</longitude> </point>
      <point> <latitude>7</latitude> <longitude>8</longitude> </point>
    </polygon>
    <polygon>
      <point> <latitude>2</latitude> <longitude>6</longitude> </point>
      <point> <latitude>3</latitude> <longitude>7</longitude> </point>
      <point> <latitude>4</latitude> <longitude>8</longitude> </point>
      <point> <latitude>5</latitude> <longitude>9</longitude> </point>
    </polygon>
  </geo-attr-pair-query>
</query>
JSON 
{
  "query": {
    "queries": [{
      "geo-elem-query": {
        "parent": { "ns": "ns1", "name": "elem1" },
        "element": { "ns": "ns1", "name": "elem2" },
        "polygon": [
          {
            "point": [
              { "latitude": 1, "longitude": 2 },
              { "latitude": 3, "longitude": 4 },
              { "latitude": 5, "longitude": 6 },
              { "latitude": 7, "longitude": 8 }
            ] 
          }, 
          {
            "point": [
              { "latitude": 2, "longitude": 6 },
              { "latitude": 3, "longitude": 7 },
              { "latitude": 4, "longitude": 8 },
              { "latitude": 5, "longitude": 9 }
            ]
          } 
        ]
      }
    }] 
}}

geo-path-query

A query that returns documents that match the geospatial constraint defined in the query only when it occurs in an XML element, XML attribute, or JSON property that matches a specified XPath expression. For details, see cts:path-geospatial-query or Geospatial Search Applications.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-path-query>
  <path-index>path-expr</path-index>
  <geo-option>option</geo-option>
  <fragment-scope>scope</fragement-scope>
  <point>
    <latitude>float</latitude>
    <longitude>float</longitude>
  </point>
  <box>
    <south>float</south>
    <west>float</west>
    <north>float</north>
    <east>float</east>
  </box>
  <circle>
    <radius>float</radius>
    <point/>
  </circle>
  <polygon>
    <point/>
  </polygon>
</geo-path-query>
 
"geo-path-query": {
  "path-index": {
    "text": path-expr,
    "namespaces": [{
      prefix: namespace-uri
    }]
  },
  "geo-option": [ option ],
  "fragment-scope": scope,
  "point": [
    {
      "latitude": number,
      "longitude": number
    }
  ],
  "box": [
    {
      "south": number,
      "west": number,
      "north": number,
      "east": number
    }
  ],
  "circle": [
    {
      "radius": number,
      point
    }
  ],
  "polygon": [ point ]
}
Component Description

A geospatial query contains one or more points or regions, described by point, box, circle, and polygon XML child elements or JSON sub-objects. The element or attribute containing geospatial data are described by path-index. For details, see Geospatial Search Applications

Element or JSON Property Name Req'd? Description 
path-index
 Y

A path range expression matching an element or attribute whose contents represent a point contained within the given geographic region(s). If the path expression includes namespace prefixes, you must define the namespace bindings on the path-index.

The database configuration must include a matching path range index. The path expression and namespace URIs must match the index configuration; namespace prefixes do not have to match.

The path expression is limited to the subset of XPath that can be used to define a path range index. For details, see Path Field and Path-Based Range Index Configuration in the XQuery and XSLT Reference Guide.

 
fragment-scope
 N Constrain matches to the specified fragment scope. Allowed values: documents (default) or properties. For more details, see the fragment-scope query option. 
geo-option
 N Geospatial options to apply to the query. You can specify multiple options. If an option has a value, the value of geo-option is of the form option=value. For example: <geo-option>units=miles</geo-option>. For details, see cts:element-attribute-pair-geospatial-query. 
point
 N Zero or more geographic points, each defined by a latitude and a longitude. The query can contain 0 or more points. 
box
 N Zero or more rectangular regions, each defined by 4 points: north, south, east, and west. 
circle
 N Zero or more circles, each defined by radius and a center point. 
polygon
 N Zero or more polygons, each series of point's.
Examples

The following example matches points contained in either of two polygons. The constraint defined in the query by path-index defines how to construct the points to match against the regions defined in the query.

Format Query
XML 
<query xmlns="http://marklogic.com/appservices/search">
  <geo-path-query>
    <path-index xmlns:ns1="/my/ns">/ns:a/ns:b</path-index>
    <polygon>
      <point> <latitude>1</latitude> <longitude>2</longitude> </point>
      <point> <latitude>3</latitude> <longitude>4</longitude> </point>
      <point> <latitude>5</latitude> <longitude>6</longitude> </point>
      <point> <latitude>7</latitude> <longitude>8</longitude> </point>
    </polygon>
    <polygon>
      <point> <latitude>2</latitude> <longitude>6</longitude> </point>
      <point> <latitude>3</latitude> <longitude>7</longitude> </point>
      <point> <latitude>4</latitude> <longitude>8</longitude> </point>
      <point> <latitude>5</latitude> <longitude>9</longitude> </point>
    </polygon>
  </geo-path-query>
</query>
JSON 
{"query":{
  "geo-path-query":{
    "path-index": {
      "text": "/ns1:a/ns2:b",
      "namespaces": [ {"ns1": "/my/ns1"}, {"ns2": "my/ns2"}]
    },
    "polygon": [
      {"point": [
        { "latitude": 1, "longitude": 2 },
        { "latitude": 3, "longitude": 4 },
        { "latitude": 5, "longitude": 6 },
        { "latitude": 7, "longitude": 8 }
      ] },
      {"point": [
        { "latitude": 2, "longitude": 6 },
        { "latitude": 3, "longitude": 7 },
        { "latitude": 4, "longitude": 8 },
        { "latitude": 5, "longitude": 9 }
      ] }
    ]
  }
}}

geo-json-property-query

A query that returns documents that match the geospatial constraint defined in the query only when it occurs a specified JSON property. For details, see cts:json-property-geospatial-query, cts:json-property-child-geospatial-query, or Geospatial Search Applications.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-json-property-query>
  <parent-property>name</parent-property>
  <json-property>name</json-property>
  <geo-option>option</geo-option>
  <fragment-scope>scope</fragement-scope>
  <point>
    <latitude>float</latitude>
    <longitude>float</longitude>
  </point>
  <box>
    <south>float</south>
    <west>float</west>
    <north>float</north>
    <east>float</east>
  </box>
  <circle>
    <radius>float</radius>
    <point/>
  </circle>
  <polygon>
    <point/>
  </polygon>
</geo-json-property-query>
 
"geo-json-property-query": {
  "parent-property": name,
  "json-property": name,
  "geo-option": [ option ],
  "fragment-scope": scope,
  "point": [
    {
      "latitude": number,
      "longitude": number
    }
  ],
  "box": [
    {
      "south": number,
      "west": number,
      "north": number,
      "east": number
    }
  ],
  "circle": [
    {
      "radius": number,
      point
    }
  ],
  "polygon": [ point ]
}
Component Description

A geospatial query contains one or more points or regions, described by point, box, circle, and polygon XML child elements or JSON sub-objects. The element pair containing geospatial data are described by parent, lat, and lon. For details, see Geospatial Search Applications

Element or JSON Property Name Req'd? Description 
parent-property
 N Optional. The parent property of the property containing geospatial data, identified by name. 
json-property
 Y The name of the property containing geospatial data. 
fragment-scope
 N Constrain matches to the specified fragment scope. Allowed values: documents (default) or properties. For more details, see the fragment-scope query option. 
geo-option
 N Geospatial options to apply to the query. You can specify multiple options. If an option has a value, the value of geo-option is of the form option=value. For example: <geo-option>units=miles</geo-option>. For details, see cts:json-property-geospatial-query or cts:json-property-child-geospatial-query. 
point
 N Zero or more geographic points, each defined by a latitude and a longitude. The query can contain 0 or more points. 
box
 N Zero or more rectangular regions, each defined by 4 points: north, south, east, and west. 
circle
 N Zero or more circles, each defined by radius and a center point. 
polygon
 N Zero or more polygons, each series of point's.
Examples

The following example matches points contained in either of two polygons. The JSON property defined in the query by parent-property and json-property defines how to construct the points to match against the regions defined in the query.

Format Query
XML 
<query xmlns="http://marklogic.com/appservices/search">
  <geo-json-property-query>
    <parent-property>myParent</parent>
    <json-property>loc</json-property>
    <polygon>
      <point> <latitude>1</latitude> <longitude>2</longitude> </point>
      <point> <latitude>3</latitude> <longitude>4</longitude> </point>
      <point> <latitude>5</latitude> <longitude>6</longitude> </point>
      <point> <latitude>7</latitude> <longitude>8</longitude> </point>
    </polygon>
    <polygon>
      <point> <latitude>2</latitude> <longitude>6</longitude> </point>
      <point> <latitude>3</latitude> <longitude>7</longitude> </point>
      <point> <latitude>4</latitude> <longitude>8</longitude> </point>
      <point> <latitude>5</latitude> <longitude>9</longitude> </point>
    </polygon>
  </geo-json-property-query>
</query>
JSON 
{
  "query": {
    "queries": [{
      "geo-json-property-query": {
        "parent-property": "myParent",
        "json-property": "loc",
        "polygon": [
          {
            "point": [
              { "latitude": 1, "longitude": 2 },
              { "latitude": 3, "longitude": 4 },
              { "latitude": 5, "longitude": 6 },
              { "latitude": 7, "longitude": 8 }
            ] 
          }, 
          {
            "point": [
              { "latitude": 2, "longitude": 6 },
              { "latitude": 3, "longitude": 7 },
              { "latitude": 4, "longitude": 8 },
              { "latitude": 5, "longitude": 9 }
            ]
          } 
        ]
      }
    }] 
}}

geo-json-property-pair-query

A query that returns documents that match the geospatial constraint defined in the query only when it occurs a JSON property that matches a specified XPath expression. For details, see cts:json-property-pair-geospatial-query or Geospatial Search Applications.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-json-property-pair-query>
  <parent-property>name</parent-property>
  <lat-property>name</lat-property>
  <lon-property>name</lon-property>
  <geo-option>option</geo-option>
  <fragment-scope>scope</fragement-scope>
  <point>
    <latitude>float</latitude>
    <longitude>float</longitude>
  </point>
  <box>
    <south>float</south>
    <west>float</west>
    <north>float</north>
    <east>float</east>
  </box>
  <circle>
    <radius>float</radius>
    <point/>
  </circle>
  <polygon>
    <point/>
  </polygon>
</geo-json-property-pair-query>
 
"geo-json-property-pair-query": {
  "parent-property": name,
  "lat-property": name,
  "lon-property": name,
  "geo-option": [ option ],
  "fragment-scope": scope,
  "point": [
    {
      "latitude": number,
      "longitude": number
    }
  ],
  "box": [
    {
      "south": number,
      "west": number,
      "north": number,
      "east": number
    }
  ],
  "circle": [
    {
      "radius": number,
      point
    }
  ],
  "polygon": [ point ]
}
Component Description

A geospatial query contains one or more points or regions, described by point, box, circle, and polygon XML child elements or JSON sub-objects. The element pair containing geospatial data are described by parent-property, lat-property, and lon-property. For details, see Geospatial Search Applications

Element or JSON Property Name Req'd? Description 
parent-property
 Y The name of JSON property containing lat-property and lon-property. 
lat-property
 Y The name of the JSON property that contains latitude data. 
lon-property
 Y The name of the JSON property that contains longitude data. 
fragment-scope
 N Constrain matches to the specified fragment scope. Allowed values: documents (default) or properties. For more details, see the fragment-scope query option. 
geo-option
 N Geospatial options to apply to the query. You can specify multiple options. If an option has a value, the value of geo-option is of the form option=value. For example: <geo-option>units=miles</geo-option>. For details, see cts:json-property-pair-geospatial-query. 
point
 N Zero or more geographic points, each defined by a latitude and a longitude. The query can contain 0 or more points. 
box
 N Zero or more rectangular regions, each defined by 4 points: north, south, east, and west. 
circle
 N Zero or more circles, each defined by radius and a center point. 
polygon
 N Zero or more polygons, each series of point's.
Examples

The following example matches points contained in either of two polygons. The constraint defined in the query by parent, lat, and lon defines how to construct the points to match against the regions defined in the query.

Format Query
XML 
<query xmlns="http://marklogic.com/appservices/search">
  <geo-json-property-pair-query>
    <parent-property>myParent</parent>
    <lat-property>loc</lat-property>
    <lon-property>lon</lon-property>
    <polygon>
      <point> <latitude>1</latitude> <longitude>2</longitude> </point>
      <point> <latitude>3</latitude> <longitude>4</longitude> </point>
      <point> <latitude>5</latitude> <longitude>6</longitude> </point>
      <point> <latitude>7</latitude> <longitude>8</longitude> </point>
    </polygon>
    <polygon>
      <point> <latitude>2</latitude> <longitude>6</longitude> </point>
      <point> <latitude>3</latitude> <longitude>7</longitude> </point>
      <point> <latitude>4</latitude> <longitude>8</longitude> </point>
      <point> <latitude>5</latitude> <longitude>9</longitude> </point>
    </polygon>
  </geo-json-property-pair-query>
</query>
JSON 
{
  "query": {
    "queries": [{
      "geo-json-property-pair-query": {
        "parent-property": "myParent",
        "lat-property": "lat",
        "lon-property": "lon",
        "polygon": [
          {
            "point": [
              { "latitude": 1, "longitude": 2 },
              { "latitude": 3, "longitude": 4 },
              { "latitude": 5, "longitude": 6 },
              { "latitude": 7, "longitude": 8 }
            ] 
          }, 
          {
            "point": [
              { "latitude": 2, "longitude": 6 },
              { "latitude": 3, "longitude": 7 },
              { "latitude": 4, "longitude": 8 },
              { "latitude": 5, "longitude": 9 }
            ]
          } 
        ]
      }
    }] 
}}

geo-region-path-query

A query that returns documents containing at least one region R1 that satisfies the requirement R1 op R2, for some topological operator op and criteria region R2. For example, R1 contains R2 or R1 intersects R2. The regions in the documents are identified by a reference to a geospatial region path index. The criteria regions are defined in the query. For details, see cts:geospatial-region-query, cts.geospatialRegionQuery, or Searching for Matching Regions.

If the query defines multiple criteria regions, a document matches the query if R1 op R2 is true for any one (R1, R2) pair. That is, specifying multiple criteria regions is like an implicit OR query.

Syntax Summary
XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-region-path-query coord="coord-sys">
  <path-index>path-expr</path-index>
  <geospatial-operator>op</geospatial-operator>
  <geo-option>option</geo-option>
  <fragment-scope>scope</fragement-scope>
  <weight>value</weight>
  <point>
    <latitude>float</latitude>
    <longitude>float</longitude>
  </point>
  <box>
    <south>float</south>
    <west>float</west>
    <north>float</north>
    <east>float</east>
  </box>
  <circle>
    <radius>float</radius>
    <point/>
  </circle>
  <polygon>
    <point/>
  </polygon>
</geo-region-path-query>
 
"geo-region path-query": {
  "path-index": {
    "text": path-expr,
    "namespaces": [{
      prefix: namespace-uri
    }]
  },
  "geospatial-operator": op,
  "coord": coord-sys-name,
  "geo-option": [ option ],
  "weight": number,
  "fragment-scope": scope,
  "point": [
    {
      "latitude": number,
      "longitude": number
    }
  ],
  "box": [
    {
      "south": number,
      "west": number,
      "north": number,
      "east": number
    }
  ],
  "circle": [
    {
      "radius": number,
      point
    }
  ],
  "polygon": [ point ]
}
Component Description

A geospatial region query contains one or more point or region criteria, described by point, box, circle, and polygon XML child elements or JSON sub-objects. The XML element or JSON property defining a region in your documents is identified by path-index. For details, see Geospatial Region Queries and Indexes.

Element or JSON Property Name Req'd? Description 
path-index
 Y

A path range expression matching an XML element or JSON property whose contents represent a region. If the path expression includes namespace prefixes, you must define the namespace bindings on the path-index in XML or using path-index/namespaces in JSON; for details, see the Examples, below.

The database configuration must include a matching geospatial region path index. The path expression and namespace URIs must match the index configuration; namespace prefixes do not have to match.

The path expression is limited to the subset of XPath that can be used to define a path range index. For details, see Path Field and Path-Based Range Index Configuration in the XQuery and XSLT Reference Guide.

 
geospatial-operator
 N A topological operator. One of contains, covered-by, covers, disjoint, intersects, overlaps, within. Default: contains. For a region R1 in the specified region index and a search criteria region R2, a document matches if R1 op R2 is true. 
coord
 N Specify the coordinate system and precision of the region index associated with the path in path-index. Allowed values: wgs84, wgs84/double, etrs89, etrs89/double, raw, raw/double. You must specify this value if path-index is not sufficient to unambiguously identify the target region index. 
geo-option
 N Geospatial options to apply to the query. You can specify multiple options. If an option has a value, the value of geo-option is of the form option=value. For example: <geo-option>units=miles</geo-option> in XML, or "units=miles" in JSON. For details, see cts:geospatial-region-query or cts.geospatialRegionQuery. 
fragment-scope
 N Constrain matches to the specified fragment scope. Allowed values: documents (default) or properties. For more details, see the fragment-scope query option.
weight N A weight for this query. Default: 1.0. Higher weights move search results up in the relevance order. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64, inclusive). Weights greater than 64 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. 
point
 N Zero or more geographic points, each defined by a latitude and a longitude. The query can contain 0 or more points. 
box
 N Zero or more rectangular regions, each defined by 4 points: north, south, east, and west. 
circle
 N Zero or more circles, each defined by radius and a center point. 
polygon
 N Zero or more polygons, each series of point's.
Examples

The following example matches regions in documents that intersect either of the two criteria polygons. A geospatial region index matching path-index and coord must exist.

Format Query
XML 
<query xmlns="http://marklogic.com/appservices/search">
  <geo-region-path-query coord="wgs84/double">
    <path-index xmlns:ns="/my/ns">/ns:a/ns:b</path-index>
    <geospatial-operator>intersects</geospatial-operator>
    <polygon>
      <point> <latitude>1</latitude> <longitude>2</longitude> </point>
      <point> <latitude>3</latitude> <longitude>4</longitude> </point>
      <point> <latitude>5</latitude> <longitude>6</longitude> </point>
      <point> <latitude>7</latitude> <longitude>8</longitude> </point>
    </polygon>
    <polygon>
      <point> <latitude>2</latitude> <longitude>6</longitude> </point>
      <point> <latitude>3</latitude> <longitude>7</longitude> </point>
      <point> <latitude>4</latitude> <longitude>8</longitude> </point>
      <point> <latitude>5</latitude> <longitude>9</longitude> </point>
    </polygon>
  </geo-region-path-query>
</query>
JSON 
{"query":{
  "geo-region-path-query":{
    "path-index": {
      "text": "/ns1:a/ns2:b",
      "namespaces": [ {"ns1": "/my/ns1"}, {"ns2": "my/ns2"}]
    },
    "coord": "wgs84/double",
    "geospatial-operator": "intersects",
    "polygon": [
      {"point": [
        { "latitude": 1, "longitude": 2 },
        { "latitude": 3, "longitude": 4 },
        { "latitude": 5, "longitude": 6 },
        { "latitude": 7, "longitude": 8 }
      ] },
      {"point": [
        { "latitude": 2, "longitude": 6 },
        { "latitude": 3, "longitude": 7 },
        { "latitude": 4, "longitude": 8 },
        { "latitude": 5, "longitude": 9 }
      ] }
    ]
  }
}}

range-constraint-query

A query that applies a pre-defined range constraint and compares the results to the specified value. For details, see Constraint Options and the XQuery functions cts:element-range-query, cts:element-attribute-range-query, cts:field-range-query, and cts:path-range-query.

A range-constraint-query is equivalent to string query expressions of the form constraint:value or constraint LE value. The named constraint must be backed by a range index.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<range-constraint-query>
  <constraint-name>name</constraint-name>
  <value>value-to-match</value>
  <range-operator>operator</range-operator>
  <range-option>option</range-option>
</range-constraint-query>
 
"range-constraint-query": {
  "constraint-name": "name",
  "value": [ value-to-match ],
  "range-operator": "operator",
  "range-option": [ option ]
}
Component Description

Element or JSON Property Name Req'd? Description 
constraint-name
 Y The name of a constraint defined in the global or query-specific query options. 
value
 Y The value against which to match XML elements, XML element attributes, JSON properties, or fields that match the constraint identified by constraint-name. This element can occur 0 or more times. 
range-operator
 N One of LT, LE, GT, GE, EQ, NE. Default: EQ. The match relationship that must be satisfied between constraint-name matches and value. 
range-option
 N One or more range query options. Allowed values depend on the type of range query (element, path, field, etc.). For details, see Including a Range or Geospatial Query in Scoring in Search Developer's Guide. For a list of options, see Range Options.
Examples

The following example matches documents containing a <body-color/> element with a value of black, assuming an element range index exists on <body-color/>.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="color">
    <range type="xs:string">
      <element ns="" name="body-color"/>
    </range>
 </constraint>
</options>
<query xmlns="http://marklogic.com/appservices/search">
  <range-constraint-query>
    <constraint-name>color</constraint-name>
    <value>black</value>
  </range-constraint-query>
</query>
JSON 
{
  "options": {
    "constraint": [
      {
        "name": "color",
        "range": {
          "type": "xs:string",
          "element": {
            "ns": "",
            "name": "body-color"
          }
        }}]}}
{
  "query": {
    "queries": [{
      "range-constraint-query": {
        "constraint-name": "color",
        "value": [ "black" ]
      }
    }]
}}

value-constraint-query

A query that matches fragments where the value of the content of an XML element, XML attribute, JSON property, or field exactly matches the text, number, boolean, or null value in the query. The match semantics depend on the value, the database configuration, and the options in effect. The element, attribute, property, or field is identified by a value constraint defined in query options. This is similar to a string query term of the form constraint:value. For details, see cts:element-value-query, cts:element-attribute-value-query, cts:field-value-query, cts:json-property-value-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<value-constraint-query>
  <constraint-name>name</constraint-name>
  <text>value-to-match</text>
  <weight>value</weight>
</value-constraint-query>

"value-constraint-query": {
  "constraint-name": "name",
  "text": [ string ],
  "weight": number
}
Component Description

Element or JSON Property Name Req'd? Description
constraint-name Y The name of a values constraint defined in the global or query-specific query options.
text N A value to match. Multiple values can be specified. If there is no text, number, boolean, or null component, all values matching the constraint are returned.
number N A numeric value to match. Applicable to only to JSON documents. Multiple values can be specified. If there is no text, number, boolean, or null component, all values matching the constraint are returned.
boolean N A boolean value to match. Applicable to only to JSON documents. Multiple values can be specified. If there is no text, number, boolean, or null component, all values matching the constraint are returned.
null N Match a null value. Applicable to only to JSON documents. Multiple values can be specified. If there is no text, number, boolean, or null component, all values matching the constraint are returned.
weight N A weight for this query. Default: 1.0. Higher weights move search results up in the relevance order. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64, inclusive). Weights greater than 64 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.
Examples

The following example matches documents where the field defined with the name myFieldName has the value Jane Doe. The example assumes the field myFieldName is defined in the database configuration and that field searches are enabled for the database.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="full-name">
   <value>
     <field name="myFieldName"/>
   </value>
 </constraint>
</options>
<query xmlns="http://marklogic.com/appservices/search">
  <value-constraint-query>
    <constraint-name>full-name</constraint-name>
    <text>Jane Doe</text>
  </value-constraint-query>
</query>
JSON 
{
  "options": {
    "constraint": [
      {
        "name": "full-name",
        "value": {
          "field": {
            "name": "myFieldName"
          }}}]}}
{
  "query": {
    "queries": [{
      "value-constraint-query": {
        "text": [ "Jane Doe" ],
        "constraint-name": "full-name"
      }
    }]
}}

word-constraint-query

A query that matches fragments containing the specified terms or phrases in the XML element or attribute, JSON property, or field identified by a specified constraint. This is similar to a string query of the form constraint:value, where the constraint is a word constraint. For details, see cts:word-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<word-constraint-query>
  <constraint-name>name</constraint-name>
  <text>text-to-match</text>
  <weight>value</weight>
</word-constraint-query>
 
"word-constraint-query": {
  "constraint-name": "name",
  "text": [ string ],
  "weight": number
}
Component Description

Element or JSON Property Name Req'd? Description
constraint-name Y The name of a word constraint defined in the global or query-specific query options. If you include multiple constraint names, the query matches if any of the constraints are met.
text N Terms or phrases that must occur in documents matching the constraint defined by constraint-name. Multiple values can be specified; if any one matches, the document matches the query.
weight N A weight for this query. Default: 1.0. Higher weights move search results up in the relevance order. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64, inclusive). Weights greater than 64 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.
Examples

The following example matches documents containing a <body-color/> element that contains the word black.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="color">
   <word>
     <element name="body-color"/>
   </word>
 </constraint>
</options>
<query xmlns="http://marklogic.com/appservices/search">
  <word-constraint-query>
    <constraint-name>color</constraint-name>
    <text>black</text>
  </word-constraint-query>
</query>
JSON 
{
  "query": {
    "queries": [{
      "word-constraint-query": {
        "text": [ "black" ],
        "constraint-name": "color"
      }
    }]
}}

collection-constraint-query

A query that applies a pre-defined constraint and compares the results to the specified value. For details, see cts:collection-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<collection-constraint-query>
  <constraint-name>name</constraint-name>
  <uri>collection-uri</value>
</collection-constraint-query>

"collection-constraint-query": {
  "constraint-name": "name",
  "uri": [ collection-uri ]
}
Component Description

Element or JSON Property Name Req'd? Description
constraint-name Y The name of a collection constraint defined in the global or query-specific query options.
uri N One or more collection URIs to match against.
Examples

The following example matches documents in the collection reports or the collection analysis.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="biz">
    <collection prefix="my-coll-prefix"/>
  </constraint>
</options>
<query xmlns="http://marklogic.com/appservices/search">
  <collection-constraint-query>
    <constraint-name>biz</constraint-name>
    <uri>reports</uri>
    <uri>analysis</uri>
  </collection-constraint-query>
</query>
JSON 
{
  "options": {
    "constraint": [{
        "name": "biz",
        "collection": {
          "prefix": "my-coll-prefix"
        }
    }]
}}
{
  "query": {
    "queries": [{
      "collection-constraint-query": {
        "uri": [ "reports", "analysis" ],
        "constraint-name": "biz"
      }
    }]
}}

container-constraint-query

A query that matches XML elements or JSON properties meeting a specified constraint, with contained elements, attributes or properties that match a specified sub-query(s). The matching container and all of its descendants are considered by the sub-queries. For details, see cts:element-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<container-constraint-query>
  <constraint-name>name</constraint-name>
  anyQueryType
</element-constraint-query>
 
"container-constraint-query": {
  "constraint-name": "name",
  anyQueryType
}
Component Description

Element or JSON Property Name Req'd? Description
constraint-name Y The name of a constraint defined in the global or query-specific query options. If you specify multiple constraints, the query matches documents that satisfy any one of the constraints.
anyQueryType Y A query to run against containers matching the constraint identified by constraint-name.
Examples

The following example matches occurrences of a <body-color/> element that contains the term black.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="body-color">
    <container>
      <element name="color" ns="" />
    </container>
  </constraint>
</options>
<query xmlns="http://marklogic.com/appservices/search">
  <container-constraint-query>
    <constraint-name>body-color</constraint-name>
    <term-query>
      <text>black</text>
    </term-query>
  </container-constraint-query>
</query>
JSON 
{
  "options": {
    "constraint": [{
      "name": "body-color",
      "container": {
        "element": {
          "name": "color",
          "ns": ""
        }
      }
    }]
}}
{
  "query": {
    "queries": [{
      "container-constraint-query": {
        "constraint-name": "body-color",
        "term-query": {
          "text": [ "black" ]
        
      }
    }]
}}

element-constraint-query

A query that matches elements meeting a specified element constraint, with sub-elements and/or attribute that match a specified sub-query(s). The matching element and all of its descendants are considered by the sub-queries. For details, see cts:element-query.

Use of this query type is deprecated. Use container-constraint-query instead.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<element-constraint-query>
  <constraint-name>name</constraint-name>
  anyQueryType
</element-constraint-query>
 
"element-constraint-query": {
  "constraint-name": "name",
  anyQueryType
}
Component Description

Element or JSON Property Name Req'd? Description
constraint-name Y The name of a container constraint defined in the global or query-specific query options. If you specify multiple constraints, the query matches documents that satisfy any one of the constraints.
anyQueryType Y A query to run against elements matching the constraint identified by constraint-name.
Examples

The following example matches occurrences of a <body-color/> element that contains the term black.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="body-color">
    <element-query name="color" ns="" />
  </constraint>
</options>
<query xmlns="http://marklogic.com/appservices/search">
  <element-constraint-query>
    <constraint-name>body-color</constraint-name>
    <term-query>
      <text>black</text>
    </term-query>
  </element-constraint-query>
</query>
JSON 
{
  "options": {
    "constraint": [{
      "name": "body-color",
      "element": {
        "name": "color",
        "ns": ""
      }
    }]
}}
{
  "query": {
    "queries": [{
      "element-constraint-query": {
        "constraint-name": "body-color",
        "term-query": {
          "text": [ "black" ]
        
      }
    }]
}}

properties-constraint-query

A query that matches documents with properties that match the specified property constraint, where the matching properties also match the specified query. For details, see cts:properties-fragment-query.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<properties-constraint-query>
  <constraint-name>name</constraint-name>
  anyQueryType
</properties-constraint-query>
 
"properties-constraint-query": {
  "constraint-name": "name",
  anyQueryType
}
Component Description

Element or JSON Property Name Req'd? Description
constraint-name Y The name of a properties constraint defined in the global or query-specific query options.
anyQueryType Y A query to run against properties matching the constraint identified by constraint-name.
Examples

The following example matches documents that have properties fragments containing the term dog.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="prop-only">
    <properties />
  </constraint>
</options>
<query xmlns="http://marklogic.com/appservices/search">
  <properties-constraint-query>
    <constraint-name>prop-only</constraint-name>
    <term-query>
      <text>dog</text>
    </term-query>
  </properties-constraint-query>
</query>
JSON 
{
  "options": {
    "constraint": [{
      "name": "prop-only",
      "properties": null
    }]
}}
{
  "query": {
    "queries": [{
      "properties-constraint-query": {
        "constraint-name": "prop-only",
        "term-query": {
          "text": [ "dog" ]
        }
      }
    }]
}}

custom-constraint-query

A query constructed by a custom XQuery extension function, using the supplied criteria. For details, see Creating a Custom Constraint.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<custom-constraint-query>
  <constraint-name>name</constraint-name>
  <text>term</text>
</custom-constraint-query>
 
"custom-constraint-query": {
  "constraint-name": "name",
  "text": [ term ]
}
Component Description

Element or JSON Property Name Req'd? Description
constraint-name Y The name of a custom constraint defined in the global or query-specific query options.
text N A query to run against fragments matching the constraint identified by constraint-name.
Examples

The following example is equivalent to the string query part:book where part is the name of a custom constraint defined in the query options.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="part">
    <custom facet="false">
      <parse apply="part" ns="my-namespace" at="/my-module.xqy"/>
    </custom>
  </constraint>
</options>
<query xmlns="http://marklogic.com/appservices/search">
  <custom-constraint-query>
    <constraint-name>part</constraint-name>
    <text>book</text>
  </custom-constraint-query>
</query>
JSON 
{
  "options": {
    "constraint": [{
      "name": "part",
      "custom": {
        "facet": false,
        "parse": {
          "apply": "part",
          "ns": "my-namespace",
          "at": "/my-module.xqy"
        }
      }
    }]
}}
{
  "query": {
    "queries": [{
      "custom-constraint-query": {
        "text": [ "book" ],
        "constraint-name": "part"
      }
    }]
}}

geospatial-constraint-query

A query that returns documents that match the specified geospatial constraint and the matching fragments also match the geospatial queries. For details, see Geospatial Search Applications.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geospatial-constraint-query>
  <constraint-name>name</constraint-name>
  <point>
    <latitude>float</latitude>
    <longitude>float</longitude>
  </point>
  <box>
    <south>float</south>
    <west>float</west>
    <north>float</north>
    <east>float</east>
  </box>
  <circle>
    <radius>float</radius>
    <point/>
  </circle>
  <polygon>
    <point/>
  </polygon>
  <text>term</text>
</geospatial-constraint-query>
 
"geospatial-constraint-query": {
  "constraint-name": "name",
  "point": [
    {
      "latitude": number,
      "longitude": number
    }
  ],
  "box": [
    {
      "south": number,
      "west": number,
      "north": number,
      "east": number
    }
  ],
  "circle": [
    {
      "radius": number,
      point
    }
  ],
  "polygon": [ point ]
}
Component Description

A geospatial constraint query contains one or more points or regions, described by point, box, circle, and polygon XML child elements or JSON sub-objects.

Element or JSON Property Name Req'd? Description
constraint-name Y The name of a custom constraint defined in the global or query-specific query options.
point N Zero or more geographic points, each defined by a latitude and a longitude. The query can contain 0 or more points.
box N Zero or more rectangular regions, each defined by 4 points: north, south, east, and west.
circle N Zero or more circles, each defined by radius and a center point.
polygon N Zero or more polygons, each series of point's.
Examples

The following example matches points contained in either of two polygons. The my-geo-elem-pair constraint in the query options defines how to construct the points.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-geo-elem-pair">
    <geo-elem-pair> 
      <parent ns="ns1" name="elem2"/> 
      <lat ns="ns2" name="attr2"/> 
      <lon ns="ns3" name="attr3"/>
    </geo-elem-pair>
  </constraint>
</options>
<query xmlns="http://marklogic.com/appservices/search">
  <geospatial-constraint-query>
    <constraint-name>name</constraint-name>
    <polygon>
      <point> <latitude>1</latitude> <longitude>2</longitude> </point>
      <point> <latitude>3</latitude> <longitude>4</longitude> </point>
      <point> <latitude>5</latitude> <longitude>6</longitude> </point>
      <point> <latitude>7</latitude> <longitude>8</longitude> </point>
    </polygon>
    <polygon>
      <point> <latitude>2</latitude> <longitude>6</longitude> </point>
      <point> <latitude>3</latitude> <longitude>7</longitude> </point>
      <point> <latitude>4</latitude> <longitude>8</longitude> </point>
      <point> <latitude>5</latitude> <longitude>9</longitude> </point>
    </polygon>
  </geospatial-constraint-query>
</query>
JSON 
{
  "options": {
    "constraint": [{
      "name": "my-geo-elem-pair",
      "geo-elem-pair": {
        "parent": { "ns": "ns1", "name": "elem2" },
        "lat": { "ns": "ns2", "name": "attr2" },
        "lon": { "ns": "ns3", "name": "attr3" }
      }
    }]
}}
{
  "query": {
    "queries": [{
      "geospatial-constraint-query": {
        "constraint-name": "name",
        "polygon": [
          {
            "point": [
              { "latitude": 1, "longitude": 2 },
              { "latitude": 3, "longitude": 4 },
              { "latitude": 5, "longitude": 6 },
              { "latitude": 7, "longitude": 8 }
            ] 
          }, 
          {
            "point": [
              { "latitude": 2, "longitude": 6 },
              { "latitude": 3, "longitude": 7 },
              { "latitude": 4, "longitude": 8 },
              { "latitude": 5, "longitude": 9 }
            ]
          } 
        ]
      }
    }] 
}}

geo-region-constraint-query

A query that returns documents that match the specified geospatial region constraint and the matching fragments also match the geospatial region queries. For details, see Geospatial Search Applications.

A query that returns documents containing at least one region R1 that satisfies the requirement R1 op R2, for some topological operator op and criteria region R2. For example, R1 contains R2 or R1 intersects R2. The regions in the documents are identified by a reference to a geospatial region path index. The criteria regions are defined in the query. For details, see cts:geospatial-region-query, cts.geospatialRegionQuery, or Searching for Matching Regions.

If the query defines multiple criteria regions, a document matches the query if R1 op R2 is true for any one (R1, R2) pair. That is, specifying multiple criteria regions is like an implicit OR query.

Syntax Summary
XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-region-path-query coord="coord-sys">
  <path-index>path-expr</path-index>
  <geospatial-operator>op</geospatial-operator>
  <geo-option>option</geo-option>
  <fragment-scope>scope</fragement-scope>
  <weight>value</weight>
  <point>
    <latitude>float</latitude>
    <longitude>float</longitude>
  </point>
  <box>
    <south>float</south>
    <west>float</west>
    <north>float</north>
    <east>float</east>
  </box>
  <circle>
    <radius>float</radius>
    <point/>
  </circle>
  <polygon>
    <point/>
  </polygon>
</geo-region-path-query>
 
"geo-region path-query": {
  "path-index": {
    "text": path-expr,
    "namespaces": [{
      prefix: namespace-uri
    }]
  },
  "geospatial-operator": op,
  "coord": coord-sys-name,
  "geo-option": [ option ],
  "weight": number,
  "fragment-scope": scope,
  "point": [
    {
      "latitude": number,
      "longitude": number
    }
  ],
  "box": [
    {
      "south": number,
      "west": number,
      "north": number,
      "east": number
    }
  ],
  "circle": [
    {
      "radius": number,
      point
    }
  ],
  "polygon": [ point ]
}
Component Description

A geospatial region query contains one or more point or region criteria, described by point, box, circle, and polygon XML child elements or JSON sub-objects. The XML element or JSON property defining a region in your documents is identified by path-index. For details, see Geospatial Region Queries and Indexes.

Element or JSON Property Name Req'd? Description
constraint-name Y The name of a geospatial region constraint defined in the global or query-specific query options. 
geospatial-operator
 N A topological operator. One of contains, covered-by, covers, disjoint, intersects, overlaps, within. Default: contains. For a region R1 in the specified region index and a search criteria region R2 specified in this query, a document matches if R1 op R2 is true.
weight N A weight for this query. Default: 1.0. Higher weights move search results up in the relevance order. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64, inclusive). Weights greater than 64 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. 
point
 N Zero or more geographic points, each defined by a latitude and a longitude. The query can contain 0 or more points. 
box
 N Zero or more rectangular regions, each defined by 4 points: north, south, east, and west. 
circle
 N Zero or more circles, each defined by radius and a center point. 
polygon
 N Zero or more polygons, each series of point's.
Examples

The following example matches regions in documents that intersect either of the two criteria polygons. A geospatial region index matching the constraint definition must exist.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-geo-region">
    <geo-region-path coord="wgs84"> 
      <path-index>/a/b</path-index>
      <geo-option>units=feet</geo-option>
    </geo-region-path>
  </constraint>
</options>

<query xmlns="http://marklogic.com/appservices/search">
  <geo-region-constraint-query>
    <constraint-name>my-geo-region</constraint-name>
    <geospatial-operator>intersects</geospatial-operator>
    <polygon>
      <point> <latitude>1</latitude> <longitude>2</longitude> </point>
      <point> <latitude>3</latitude> <longitude>4</longitude> </point>
      <point> <latitude>5</latitude> <longitude>6</longitude> </point>
      <point> <latitude>7</latitude> <longitude>8</longitude> </point>
    </polygon>
    <polygon>
      <point> <latitude>2</latitude> <longitude>6</longitude> </point>
      <point> <latitude>3</latitude> <longitude>7</longitude> </point>
      <point> <latitude>4</latitude> <longitude>8</longitude> </point>
      <point> <latitude>5</latitude> <longitude>9</longitude> </point>
    </polygon>
  </geo-region-path-query>
</query>
JSON 
{ "options": {
    "constraint": [{
      "name": "my-geo-region",
      "geo-region-path": {
        "path-index": "/a/b",
        "coord": "wgs84",
        "geo-option": ["units=feet"]
      }
    }]
}}

{ "query": {
  "queries": [{
    "geo-region-constraint-query":{
      "constraint-name": "my-geo-region",
      "geospatial-operator": "intersects",
      "polygon": [
        {"point": [
          { "latitude": 1, "longitude": 2 },
          { "latitude": 3, "longitude": 4 },
          { "latitude": 5, "longitude": 6 },
          { "latitude": 7, "longitude": 8 }
        ] },
        {"point": [
          { "latitude": 2, "longitude": 6 },
          { "latitude": 3, "longitude": 7 },
          { "latitude": 4, "longitude": 8 },
          { "latitude": 5, "longitude": 9 }
        ] }
      ]
    }
  }]
}}

lsqt-query

A query that returns documents before Last Stable Query Time (LSQT) or before a given timestamp that is before LSQT. For details, see cts:lsqt-query or Searching Temporal Documents in the Temporal Developer's Guide.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<lsqt-query>
  <temporal-collection>name</temporal-collection>
  <timestamp>dateTime</timestamp>
  <weight>value</weight>
  <temporal-option>option</temporal-option>
</lsqt-query>
 
"lsqt-query": {
  "temporal-collection": name,
  "timestamp": string,
  "weight": number,
  "temporal-option": [ string ]
} 
Component Description

Element or JSON Property Name Req'd? Description 
temporal-collection
 Y The name of a temporal collection. 
timestamp
 N Return only temporal documents with a system start time less than or equal to this value. Timestamps greater than LSQT are rejected. Default: LSQT for the named temporal collection. 
weight
 N A weight for this query. Default: 1.0. Higher weights move search results up in the relevance order. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64, inclusive). Weights greater than 64 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. 
temporal-option
 N Temporal options to apply to the query. You can specify multiple options. If the option has a value, the value of temporal-option is option=value. For example: <temporal-option>score-function=linear</temporal-option>. For available options, see cts:lsqt-query.
Examples

The following example returns documents in the temporal collection myTemporalCollection before LSQT.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">

</options>
<query xmlns:search="http://marklogic.com/appservices/search">
  <lsqt-query>
    <temporal-collection>myTemporalCollection</temporal-collection>
    <temporal-option>cached-incremental</temporal-option>
  </lsqt-query>
</query>
JSON 
{"query": {
  "queries": [{
    "lsqt-query": {
      "temporal-collection": "myTemporalCollection",
      "temporal-option": [ "cached-incremental" ]
    }
  }]
}}

before-query

Returns a query matching fragments committed before or at a specified timestamp. For details, see cts:before-query.

Fragment commit timestamps change not only by application transactions, but also by system transactions from the reindexer or the rebalancer. The query will also match fragments whose timestamps have been changed because of reindexing and rebalancing before the given timestamp.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<before-query>
  
  <timestamp>unsignedLong</timestamp>
  
</before-query>
 
"before-query": {
  
  "timestamp": string,
  
} 
Component Description

Element or JSON Property Name Req'd? Description
timestamp Y A commit timestamp. Database fragments committed after this timestamp are matched.
Examples

The following example matches document fragments committed before the specified timestamp.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">

</options>
<query xmlns:search="http://marklogic.com/appservices/search">
  <before-query>
    <timestamp>15956309638793350</timestamp>
  </before-query>
</query>
JSON 
{"query": {
  "queries": [{
    "before-query": {
      "timestamp: "15956309638793350"
    }
  }]
}}

after-query

Returns a query matching fragments committed after a specified timestamp. For details, see cts:after-query.

Fragment commit timestamps change not only by application transactions, but also by system transactions from the reindexer or the rebalancer. The query will also match fragments whose timestamps have been changed because of reindexing and rebalancing after the given timestamp.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<after-query>
  
  <timestamp>unsignedLong</timestamp>
  
</after-query>
 
"after-query": {
  
  "timestamp": string,
  
} 
Component Description

Element or JSON Property Name Req'd? Description
timestamp Y A commit timestamp. Database fragments committed after this timestamp are matched..
Examples

The following example matches document fragments committed after the specified timestamp.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">

</options>
<query xmlns:search="http://marklogic.com/appservices/search">
  <after-query>
    <timestamp>15956309638793350</timestamp>
  </after-query>
</query>
JSON 
{"query": {
  "queries": [{
    "after-query": {
      "timestamp:"15956309638793350"
    }
  }]
}}

period-compare-query

A query that matches documents for which the specified relationship holds between two temporal axes. For details, see cts:period-compare-query or Searching Temporal Documents in the Temporal Developer's Guide.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<period-compare-query>
  <axis1>axis-name</axis1>
  <temporal-operator>
    operator
  </temporal-operator>
  <axis2>axis-name</axis2>
  <temporal-option>option</temporal-option>
</period-compare-query>
 
"period-compare-query": {
  "axis1": name,
  "temporal-operator": string,
  "axis2": name,
  "temporal-option": [ string ]
} 
Component Description

Element or JSON Property Name Req'd? Description 
axis1
 Y The name of the first temporal axis. 
temporal-operator
 Y The comparison operation to apply to the two axes. For a list of operator names, see cts:period-compare-query and Period Comparison Operators in the Temporal Developer's Guide. 
axis2
 Y The name of the second temporal axis. 
temporal-option
 N Temporal options to apply to the query. You can specify multiple options. If the option has a value, the value of temporal-option is option=value. For example: <temporal-option>score-function=linear</temporal-option>. For available options, see cts:lsqt-query.
Examples

The following example matches documents that were in the database when the time period defined by the axis named valid is within the time period defined by the axis system.

Format Query
XML 
<query xmlns:search="http://marklogic.com/appservices/search">
  <period-compare-query>
    <axis1>system</axis1>
    <temporal-operator>iso_contains</temporal-operator>
    <axis2>valid</axis2>
  </period-compare-query>
</query>
JSON 
{"query": {
  "queries": [{
    "period-compare-query": {
      "axis1": "system",
      "temporal-operator": "iso_contains",
      "axis2": "valid"
    }
  }]
}}

period-range-query

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<period-range-query>
  <axis>axis-name</axis>
  <temporal-operator>
    operator
  </temporal-operator>
  <period>
    <period-start>dateTime</period-start>
    <period-end>period-end</period-end>
  </period>
  <temporal-option>option</temporal-option>
</period-range-query>
 
"period-range-query": {
  "axis": [ name ],
  "temporal-operator": string,
  "period": [
    {
      "period-start": string,
      "period-end": string
    }
  ],
  "temporal-option": [ string ]
} 
Component Description

Element or JSON Property Name Req'd? Description 
axis
 Y The name of a temporal axis. You can specify multiple axis names. 
temporal-operator
 Y The comparison operation to apply to the axis and period. For a list of operator names, see cts:period-range-query and Period Comparison Operators in the Temporal Developer's Guide. 
period
 Y One or more periods to match. When multiple periods are specified, the query matches if any value matches. 
temporal-option
 N Temporal options to apply to the query. You can specify multiple options. If the option has a value, the value of temporal-option is option=value. For example: <temporal-option>score-function=linear</temporal-option>. For available options, see cts:lsqt-query.
Examples

The following example matches temporal documents a valid end time before. 14:00.

Format Query
XML 
<query xmlns:search="http://marklogic.com/appservices/search">
  <period-range-query>
    <axis>valid</axis>
    <temporal-operator>aln_before</temporal-operator>
    <period>
      <period-start>2014-04-03T14:00:00</period-start>
      <period-end>9999-12-31T11:59:59Z</period-end>
    </period>
  </period-range-query>
</query>
JSON 
{"query": {
  "queries": [{
    "period-range-query": {
      "axis": [ "valid" ],
      "temporal-operator": "aln_before",
      "period": [
        {
          "period-start": "2014-04-03T14:00:00",
          "period-end": "9999-12-31T11:59:59Z"
        }
      ]
    }
  }]
}}

operator-state

This component of a structured query sets the state of a custom runtime configuration operator defined by your string query grammar. For details, see Operator Options.

Syntax Summary

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<operator-state>
  <operator-name>name</operator-name>
  <state-name>state</state-name>
</operator-state>
 
"operator-state": {
  "operator-name": "name",
  "state-name": "state"
}
Component Description

Element or JSON Property Name Req'd? Description
operator-state Y The name of a custom runtime configuration operator defined by the <operator/> query option.
state-name Y The name of a state recognized by this operator.
Examples

The following example illustrates use of a custom sort operator defined in the query options. The example structured query is equivalent to the string query sort:date. For details, see Operator Options.

Format Query
XML 
<options xmlns="http://marklogic.com/appservices/search">
  <operator name="sort">
   <state name="relevance">
      <sort-order>
         <score/>
      </sort-order>
   </state>
   <state name="date">
      <sort-order direction="descending" type="xs:dateTime">
         <element ns="my-ns" name="date"/>
      </sort-order>
      <sort-order>
         <score/>
      </sort-order>
   </state>
 </operator>
</options>
<query xmlns:search="http://marklogic.com/appservices/search">
  <operator-state>
    <operator-name>sort</operator-name>
    <state-name>date</state-name>
  </operator-state>
</query>
JSON 
{
  "options": {
    "operator": [{
      "name": "sort",
      "state": [
        {
          "name": "relevance",
          "sort-order": [ { "score": null } ]
        },
        {
          "name": "date",
          "sort-order": [
            {
              "direction": "descending",
              "type": "xs:dateTime",
              "element": { "ns": "my-ns", "name": "date" }
            },
            { "score": null }
          ]
      }]
    }]
}}
{
  "query": {
    "queries": [{
      "operator-state": {
        "operator-name": "sort",
        "state-name": "date"
      }
    }]
}}

« Previous chapter
Next chapter »
Powered by MarkLogic Server | Terms of Use | Privacy Policy