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:
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 and does not use exact match semantics by default. 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'.
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> |
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.
Whether a value, term, or word query on text content is case-sensitive, diacritic-sensitive, whitespace-sensitive, or punctuation-sensitive depends on the query options in scope during the search. 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 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 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 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 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 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'.
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>
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.
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.
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.
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" ] } }
]
}
}]
}}
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"
}
}
]
}
}]
}}
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.
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 />
<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 ]
}
} |
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.
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 ]
} |
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. |
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" ]
}
}]
}} |
Find the intersection of matches specified by one or more sub-queries. For details, see cts:and-query.
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
]
} |
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. |
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" }
]
}
}]
}} |
Find the union of matches specified by one or more sub-queries. For details, see cts:or-query.
XML |
JSON |
All elements are in the namespace http://marklogic.com/appservices/search .<or-query>
anyQueryType
</or-query> |
"or-query": {
"queries": [ anyQueryType ]
} |
Element or JSON Property Name |
Req'd? |
Description |
anyQueryType |
N |
One or more sub-queries. |
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" ]
}
}
]}
}]
}} |
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.
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 }
} |
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. |
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" ]
}}
}
}]
}} |
A query that filters out any results that match its sub-query. For details, see cts:not-query.
XML |
JSON |
All elements are in the namespace http://marklogic.com/appservices/search .<not-query>
anyQueryType
</not-query>
|
"not-query": {
anyQueryType
} |
Element or JSON Property Name |
Req'd? |
Description |
anyQueryType |
Y |
A negative query, specifying the search results to filter out. |
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" ]
}
}
}]
}} |
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.
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 }
} |
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. |
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"
]
}}
}
}]
}} |
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.
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
]
} |
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 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. |
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" }
]
}
}]
}} |
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.
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>
</and-query> |
"boost-query": {
"matching-query": { anyQueryType },
"boosting-query" : { anyQueryType }
} |
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. |
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"
}}
}
}]
}} |
A query that matches all documents where the sub-query matches against document properties. For details, see cts:properties-fragment-query.
XML |
JSON |
All elements are in the namespace http://marklogic.com/appservices/search .<properties-fragment-query>
anyQueryType
</properties-fragment-query> |
"properties-fragment-query": {
anyQueryType
} |
Element or JSON Property Name |
Req'd? |
Description |
anyQueryType |
Y |
A sub-query to run against document properties. |
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"
}
}
}]
}} |
A query matching documents in the directories with the given URIs. For details, see cts:directory-query.
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
} |
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. |
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
}
}]
}} |
A query matching documents in any of the collections with the given URIs. For details, see cts:collection-query.
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 ]
} |
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 . |
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"]
}
}]
}} |
A query matching documents containing a specified XML element or JSON property whose contents match a specified sub-query.
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
} |
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). |
Your query must include exactly one of element
or json-property
.
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" ]
}
}
}]
}} |
A query matching documents with the given URIs.. For details, see cts:document-query.
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 ]
} |
Element or JSON Property Name |
Req'd? |
Description |
uri |
Y |
One or more document URIs. |
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"
]
}
}]
}} |
A query that matches all documents where a sub-query matches any document fragment. For details, see cts:document-fragment-query.
XML |
JSON |
All elements are in the namespace http://marklogic.com/appservices/search .<document-fragment-query>
anyQueryType
</document-fragment-query>
|
"document-fragment-query": {
anyQueryType
} |
Element or JSON Property Name |
Req'd? |
Description |
anyQueryType |
Y |
The query to be matched against any document fragment. |
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" ]
}
}
}]
}} |
A query that matches all documents where a sub-query matches a document-locks
fragment. For details, see cts:locks-fragment-query.
XML |
JSON |
All elements are in the namespace http://marklogic.com/appservices/search .<locks-fragment-query>
anyQueryType
</locks-fragment-query>
|
"locks-fragment-query": {
anyQueryType
} |
Element or JSON Property Name |
Req'd? |
Description |
anyQueryType |
Y |
The query to be matched against any document fragment. |
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" ]
}
}}
}]
}} |
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.
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
} |
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 Understanding Path Range Indexes in Administrator's 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. |
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" ]
}
}]
}} |
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, see Text Match Semantics or cts:element-value-query, cts:element-attribute-value-query, cts:json-property-value-query, or cts:field-value-query.
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
} |
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. |
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.
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.
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
} |
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. |
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" ],
}
}]
}}
|
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.
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 ]
} |
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. |
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 }
]
}
]
}
}]
}} |
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.
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 ]
} |
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. |
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 }
]
}
]
}
}]
}} |
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.
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 ]
} |
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. |
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 }
]
}
]
}
}]
}} |
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.
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 ]
} |
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 Understanding Path Range Indexes in Administrator's 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. |
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 }
] }
]
}
}} |
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.
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 ]
} |
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. |
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 }
]
}
]
}
}]
}} |
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.
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 ]
} |
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-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. |
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 }
]
}
]
}
}]
}} |
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.
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 ]
} |
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. |
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" ]
}
}]
}} |
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.
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
} |
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. |
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"
}
}]
}} |
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.
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
} |
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. |
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"
}
}]
}} |
A query that applies a pre-defined constraint and compares the results to the specified value. For details, see cts:collection-query.
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 ]
} |
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. |
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"
}
}]
}} |
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.
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
} |
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 . |
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" ]
}
}]
}} |
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.
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
} |
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 . |
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" ]
}
}]
}} |
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.
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
} |
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 . |
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" ]
}
}
}]
}} |
A query constructed by a custom XQuery extension function, using the supplied criteria. For details, see Creating a Custom Constraint.
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 ]
} |
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 . |
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"
}
}]
}} |
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.
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 ]
} |
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. |
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 }
]
}
]
}
}]
}} |
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.
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 ]
} |
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 . |
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" ]
}
}]
}} |
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.
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 ]
} |
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 . |
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"
}
}]
}} |
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 ]
} |
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 . |
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"
}
]
}
}]
}} |
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.
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"
} |
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. |
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"
}
}]
}} |