Loading TOC...
Search Developer's Guide (PDF)

Search Developer's Guide — Chapter 3

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:

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.

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 key, 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 "pretend this is a complex search":

<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:term-query>
    <search:text>pretend this is 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": [ "pretend this is 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('"pretend this is a complex search"', 
      (), "search:query")
return      
search:resolve($complex-search)

=> a search:response element

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"
            }
          }
        ]
      }
    }]
}}

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> />
  <!-- cts:query scoping ctors -->
  <properties-query />
  <directory-query />
  <collection-query />
  <document-query />
  <document-fragment-query />
  <locks-query />
  <!-- Search API abstractions -->
  <range-constraint-query />
  <value-constraint-query />
  <word-constraint-query />
  <collection-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,

      properties-query,
      directory-query,
      collection-query,
      document-query,
      document-fragment-query,
      locks-query,

      range-constraint-query,
      value-constraint-query,
      word-constraint-query,
      collection-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.

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-query>
"term-query": {
  "text": [ "term-or-phrase" ]
  "weight": "value"
}
Component Description

Element Name or JSON Key Req'd? Description
text Y The term or phrase to search for. The query can contain multiple text children.
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 the absolute value of 16 (between -16 and 16, inclusive). Weights greater than 16 have the same effect as a weight of 16. 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 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 Name or JSON Key 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 Name or JSON Key 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 Name or JSON Key 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 Name or JSON Key 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 Name or JSON Key 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"
            ]
        }}
      }
    }]
}}

near-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:near-query.

Syntax Summary

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

Element Name or JSON Key Req'd? Description
anyQueryType Y One or more queries that must match within the specified proxmity to each other.
distance N A distance, in number of words, between any two matching queries. Default: 10
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" }
        ]
      }
    }]
}}

properties-query

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

Syntax Summary

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

Element Name or JSON Key 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-query>
    <range-constraint-query>
      <constraint-name>modified</constraint-name>
      <value>2012-12-31</value>
      <range-operator>GT</range-operator>
    </range-constraint-query>
  </properties-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-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 Name or JSON Key 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 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 Name or JSON Key Req'd? Description
uri Y One or more collection URIs.
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"]
      }
    }]
}}

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 Name or JSON Key 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 Name or JSON Key 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-query

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

Syntax Summary

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

Element Name or JSON Key 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-query>
    <element-query>
      <constraint-name>
        lock-type
      </constraint-name>
      <term-query>
        <text>write</text>
      </term-query>
    </element-query>
  </locks-query>
</query>
{
  "query": {
    "queries": [{
      "locks-query": {
        "element-query": {
        "constraint-name": "lock-type",
        "term-query": {
          "text": [ "write" ]
        }
      }}
    }]
}}

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-constraint-query>
"range-constraint-query": {
  "constraint-name": "name",
  "value": [ value-to-match ],
  "range-operator": "operator"
}
Component Description

Element Name or JSON Key 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 elements, element attributes, JSON keys, 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.
Examples

The following example matches documents containing a <body-color/> element with a value of black.

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">
  <element-query>
    <range-constraint-query>
      <constraint-name>color</constraint-name>
      <value>black</value>
    </range-constraint-query>
  </element-query>
</query>
JSON
{
  "options": {
    "constraint": [
      {
        "name": "color",
        "range": {
          "type": "xs:string",
          "element": {
            "ns": "",
            "name": "body-color"
          }
        }}]}}
{ "query": { "queries": [{       "element-query": {         "range-constraint-query": {         "value": [ "black" ],         "constraint-name": "color"       }} }] }}

value-constraint-query

A query that matches fragments where the value of the text content of an XML element, XML attribute, JSON key-value pair, or field exactly matches the text phrase in the query. The match semantics depend on the text value, the database configuration, and the options in effect. The element, attribute, key, 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.

Syntax Summary

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

Element Name or JSON Key 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 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 the absolute value of 16 (between -16 and 16, inclusive). Weights greater than 16 have the same effect as a weight of 16. 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 key, 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>name</text>
  <weight>value</weight>
</word-constraint-query>
"word-constraint-query": {
  "constraint-name": "name",
  "text": [ name ],
  "weight": number
}
Component Description

Element Name or JSON Key Req'd? Description
constraint-name Y The name of a word constraint defined in the global or query-specific query options.
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 the absolute value of 16 (between -16 and 16, inclusive). Weights greater than 16 have the same effect as a weight of 16. 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 Name or JSON Key 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"
      }
    }]
}}

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.

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 Name or JSON Key Req'd? Description
constraint-name Y The name of an constraint defined in the global or query-specific query options.
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 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-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 Name or JSON Key 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 Name or JSON Key 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 Name or JSON Key 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 }
            ]
          } 
        ]
      }
    }] 
}}

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 Name or JSON Key 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 »