MarkLogic Server 11.0 Product Documentation

XQuery and XSLT Reference Guide — Chapter 4

Direct Element Constructors: Switching Between XQuery and XML Using Curly Braces

As described in the previous section, an XQuery expression by itself is a valid XQuery program. You can create XML nodes as XQuery expressions. Therefore, the following is valid XQuery:

<my-element>content goes here</my-element>

It simply returns the element. The XQuery syntax also allows you to embed XQuery between XML, effectively switching back and forth between an XML syntax and an XQuery syntax to populate parts of the XML content. The separator characters to switch back and forth between XML and XQuery are the open curly brace ( { ) and close curly brace ( } ) characters. For example, consider the following XQuery:

<my-element>{fn:current-date()}</my-element>

This expression returns an XML element named my-element with content that is the result of evaluating the expression between the curly braces. This expression returns the current date, so you get an element that looks like the following:

<my-element>2008-06-25-07:00</my-element>

You can create complex expressions that go back and forth between XML and XQuery as often as is needed. For example, the following is slightly more complex:

<my-element id="{xdmp:random()}">{fn:current-date()}</my-element>

This returns an element like the following:

<my-element id="9175848626240925436">2008-06-25-07:00</my-element>

This technique of constructing XML are called direct element constructors. There are many more rules for how to use these direct element constructors to create XML nodes. For more details, see the of the XQuery specification (http://www.w3.org/TR/xquery/#doc-xquery-DirCommentConstructor).

Computed Element and Attribute Constructors

You can also create XML nodes by using computed constructors. There are computed constructors for all types of XML nodes (element, attribute, document, text, comment, and processing instruction). The following is the basic syntax for computed constructors:

The following is an example of some XML that is created using computed constructors:

element hello { attribute myatt { "world" } , "hello world" }
(: 
   returns the following XML:
   <hello myatt="world">hello world</hello>
:)

In this example, the comma operator concatenates a constructed attribute (the myatt attribute on the hello element) and a literal expression (hello world, which becomes the element text node content) to create the content for the element node. The following example shows how you can compute the QName with an XQuery expression:

element {xs:QName("hello")} { 
  attribute myatt { "world" } , "hello world" }
(: 
   returns the following XML:
   <hello myatt="world">hello world</hello>
:)

Returning XML From an XQuery Program

Using the direct and computed constructors described above, it is natural to have the output of an XQuery program be XML. Besides computed and direct constructors, XML can be the result of an XPath expression, a cts:search expression, or any other expression that returns XML. The XML can be constructed as any well-formed XML.

When you construct XML in XQuery, the XQuery evaluator will always construct well-formed XML (assuming your XQuery is valid). Compared with other languages where you construct strings that represent XML, the fact that the XQuery rules ensure that an XML node is well formed tends to eliminate a whole class of bugs in your code that you might encounter using other languages.

XQuery Version Declaration

Every XQuery module (both main and library) can have an optional XQuery version declaration. The version declaration tells MarkLogic Server which dialect of XQuery to use. MarkLogic Server supports the following values for the XQuery version declaration: 1.0-ml, 1.0, and 0.9-ml.

XQuery dialect 0.9-ml has been deprecated. MarkLogic recommends that you use either 1.0-ml or 1.0.

For details on dialects 1.0 and 1.0-ml, including rules for the combining different dialects, see XQuery Dialects in MarkLogic Server.

The following is the basic syntax of the XQuery version declaration:

The following is an example of an XQuery version declaration:

xquery version "1.0-ml";

Main Modules

A main module contains an XQuery program to be evaluated. You can call a main module directly and it will return the results of the evaluation. A main module contains an optional XQuery version declaration, a prolog (the prolog can be empty, so it is in effect optional), and a body. The XQuery body can be any XQuery expression.

In 1.0-ml, you can construct programs that have multiple main modules separated by semi-colons, as described in Semi-Colon as Transaction Separator.

The following is an example of a very simple main module:

xquery version "1.0-ml";
"hello world"

For another example of a main module, see the example at the end of the Library Modules.

Library Modules

A library module contains function definitions and/or variable definitions. You cannot call a library module to directly evaluate it, and it cannot have a query body. To use a library module, it must be imported from another module (main or library). A library module contains a module declaration followed by a prolog. For details on the prolog, see XQuery Prolog. The following is the basic syntax of a library module:

The following is a very simple XQuery library module

xquery version "1.0-ml";
module namespace my-library="my.library.uri" ;

declare function hello() { "hello" };

If you stored this module under an App Server root as hello.xqy, you could call this function with the following very simple main module:

xquery version "1.0-ml";
import module namespace my-library="my.library.uri" at "hello.xqy";

my-library:hello()
     (: this returns the string "hello" :)

Importing Modules or Schemas

You can import modules and schemas in the XQuery prolog. The following are sample module and schema import declarations:

import module namespace my-library="my.library.uri" at "hello.xqy";
import schema namespace xhtml="http://www.w3.org/1999/xhtml" 
   at "xhtml1.1.xsd";

The library module location and the schema location are not technically required. The location must be supplied for module imports, however, as they are used to determine the location of the library module and the module will not be found without it. Also, all modules for a given namespace must be imported with a single import statement (with comma-separated locations). For schema imports, if the location is not supplied, MarkLogic Server resolves the schema URI using the in-scope schemas (schemas in the schemas database and the <marklogic-dir>/Config directory). If there are multiple schemas with the same URI, MarkLogic Server chooses one of them. Therefore, to ensure you are importing the correct schema, use the location for the schema import, too. For details on the rules for resolving the locations, see Importing XQuery Modules, XSLT Stylesheets, and Resolving Paths in the Application Developer's Guide.

For more details on imports, see the XQuery specification for schema imports (http://www.w3.org/TR/xquery/#id-schema-import) and for module imports (http://www.w3.org/TR/xquery/#id-module-import).

Declaring Namespaces

Namespace declarations are used to bind a namespace prefix to a namespace URI. The following is a sample namespace declaration:

declare namespace my-namespace="my.namespace.uri";

For more details on namespace declarations, see the XQuery specification (http://www.w3.org/TR/xquery/#id-namespace-declaration)

Declaring Options

XQuery provides vendor-specific options that are declared in the prolog. This section describes the MarkLogic Server options you can declare in the XQuery prolog, and includes the following prolog options:

• xdmp:mapping
• xdmp:update
• xdmp:commit
• xdmp:transaction-mode
• xdmp:copy-on-validate
• xdmp:output
• xdmp:coordinate-system

declare option xdmp:mapping "false";

declare option xdmp:update "true";

declare option xdmp:commit "explicit";

declare option xdmp:transaction-mode "auto";

declare option xdmp:copy-on-validate "true";

declare option xdmp:output "method = html";

attribute-name="value"

<xsl:output xdmp:default-attributes="no" xdmp:intent-untyped="yes" 
   xmlns:xdmp="http://marklogic.com/xdmp"/>

declare option xdmp:coordinate-system "wgs84/double";

Declaring Functions

Functions are a fundamental part of programming in XQuery. Functions provide more than a mechanism to modularize your code (although they certainly are that), as functions allow you to easily perform recursive actions. This is a powerful design pattern in XQuery.

Functions can optionally be typed, both for parameters to the function and for results of the function. The following is a very simple function declaration that takes a string as input and returns a sentence indicating the length of the string:

declare function simple($input as xs:string) as xs:string* {
   fn:concat('The string "', $input, '" is ', 
             (fn:string-length($input)), 
             ' characters in length.')
} ;

Declaring Variables

You can declare variables in a main or library module to reference elsewhere in your programs. If you put variable definitions in a library module, you can reference those variables from any module that imports the library module. Because the content of a variable can be any valid XQuery expression, you can create variables with dynamic content. The following is a variable declaration that returns a string indicating if it is January or not:

declare variable $is-it-january as xs:string :=
  if ( fn:month-from-date(fn:current-date()) eq 1 )
  then "it is January"
  else "it is not January" ;

If this variable were defined in a library module named mylib.xqy stored under your App Server root, and if you imported that library module bound to the namespace prefix mylib into a main module, then you can reference this variable in the main module as follows:

xquery version "1.0-ml";
import module namespace mylib="my.library.uri" at "mylib.xqy";

$mylib:is-it-january

Declaring a Default Collation

The default collation declaration defines the collation that is in effect for a query. In general, everything that uses a collation in a query with a default collation declaration will use the collation specified. The exceptions are for functions that have options which explicitly override the default collation, and for FLWOR expressions that explicitly state the collation in the order by clause. The following is a sample collation declaration:

declare default collation "http://marklogic.com/collation/";

For more details on collations, see the Encodings and Collations chapter of the Application Developer's Guide.

XPath Expressions

XPath expressions search for XML content. They can be combined with other XQuery expressions to form other arbitrarily complex expressions. For more details on XPath expressions, see XPath Quick Reference.

FLWOR Expressions

The FLWOR expression (for, let, where, order by, return) is used to generate items or sequences. A FLWOR expression binds variables, applies a predicate, orders the data set, and constructs a new result:

The following is the basic syntax of a FLWOR expression:

The following sections examine each of the five clauses in more detail:

• The for Clause
• The let Clause
• The where Clause
• The order by Clause
• The return Clause

for $x in (1, 2, 3, 4, 5)
return
$x * 2

(: returns the sequence (2, 4, 6, 8, 10) :)

for $x in (1,2,3)
for $y in (4,5,6)
return
$x * 2

(: returns the sequence (2, 2, 2, 4, 4, 4, 6, 6, 6) :)

for $x in (1,2,3)
for $y in (4,5,6)
return
($x * 2, $y * 3)

(: returns the sequence 
(2, 12, 2, 15, 2, 18, 4, 12, 4, 15, 4, 18, 6, 12, 6, 15, 6, 18) :)

for $x in (1,2,3), $y in (4,5,6)

let $seq := ("hello", "goodbye") return $seq

"hello", "goodbye"

let $x := (1 to 5)
for $y in $x
return 
$x * 2

(: returns the sequence (2, 4, 6, 8, 10) :)

for $x in ("a", "B", "c", "A", "apple")
where fn:starts-with(fn:lower-case($x), "a")
return
$x

(: returns the sequence ("a", "A", "apple") :)

for $x in ( "B", "c", "a", "d")
order by $x
return $x (: returns the sequence ("a", "B", "c", "d") :)

xquery version "1.0-ml";
for $x in ( <data><a>1</a><b>10</b></data>,
            <data><a>20</a><b>5</b></data>, 
            <data><a>20</a><b>25</b></data> )
order by $x/a descending, $x/b
return $x 

(: returns the following sequence
 :  <data><a>20</a><b>25</b></data>
 :  <data><a>20</a><b>5</b></data>
 :  <data><a>1</a><b>10</b></data>
 :)

The typeswitch Expression

The typeswitch expression allows conditional evaluation of a set of sub-expressions based on the type of a specified expression:

A typeswitch expression evaluates the first case_expr whose sequenceType matches the type of the specified expression. If there is no sequenceType match, expr_default is evaluated.

Typeswitch provides a powerful mechanism for processing node contents:

typeswitch ($address) 
  case $a as element(*, USAddress) return handleUS($a) 
  case $a as element(*, CanadaAddress) return handleCanada($a)  
  default return handleUnknown($address)

This code snippet determines the sequenceType of the variable $address, then evaluates one of three sub-expressions. In this case:

• If $address is of type USAddress, the function handleUS($a) is evaluated.
• If $address is of type CanadaAddress, the function handleCanada($a) is evaluated.
• If the type of variable $address matches none of the above, the function handleUnknown($a) is evaluated.

A sequenceType can also be a kind test (such as an element test). It is possible to construct case clauses in which a particular expression matches multiple sequenceTypes. In this case, the case_expr of only the first matching sequenceType is evaluated. You can also use the typeswitch expression in a recursive function to iterate through a document and perform transformation of the document. For details about using recursive typeswitches, see the Transforming XML Structures With a Recursive typeswitch Expression chapter of the Application Developer's Guide.

The if Expression

The if expression allows conditional evaluation of sub-expressions:

If expression expr_c1 evaluates to true, then the value of the if expression is the value of expression expr_r1, otherwise the value of the if expression is the value of expr_r2. The else clause is not optional; if no action is to be taken, use an empty sequence for expr_r2; there is no end if or similar construct in XQuery:

if (1 eq 2) 
then "this is strange" 
else ()

The extent of expr_r1 and expr_r2 is limited to a single expression. If a more complex set of actions are required, an element constructor, sequence, or function call must be used.

If expressions can be nested:

if ($year < 1994)
then
   <available>archive</available>
else if ($year = $current_year) then
   <available>current</available>
else
   <available>inventory</available>

Quantified Expressions (some/every ... satisfies ...)

XQuery provides predicates that simplify the evaluation of quantified expressions. The basic syntax for these expressions follows:

These expressions are particularly useful when trying to select a node based on a condition satisfied by at least one or alternatively all of a particular set of its children.

Imagine an XML document containing log messages. The document has the following structure:

<log>
   <event>
      <program>   .... </program>
      <message>   .... </message>
      <level>     .... </level>
      <error>
         <code>      .... </code>
         <severity>  .... </severity>
         <resolved>  .... </resolved>
      </error>
      <error>
         ....
      </error>
      ....
   </event>
   ....
</log>

Every <event> node has <program>, <message>, and <level> children. Some <event> nodes have one or more <error> children.

Consider a query to report on those events that have unresolved errors:

for $event in /log/event
where some $error in $event/error satisfies $error/resolved = "false"
return
   $event

This query returns only those <event> nodes in which there is an <error> node with a <resolved> element whose value is false.

Validate Expression

The validate expression is used to validate element and document nodes against in-scope schemas (schemas that are in the schemas database). The following is the basic syntax of the validate expression:

The expression to validate must be a node referencing an in-scope schema. The node can reference a schema. The default validation mode is strict. When performing lax validation, the validate expression first tries to validate the node using an in-scope schema, and then if no schema is found and none is referenced in the node, the validation occurs without a schema. If a node is not valid, an exception is thrown. If a node is valid, then the node is returned. For more details, see the XQuery specification (http://www.w3.org/TR/xquery/#id-validate).

You can also set a prolog option to determine if the node returned is a copy of the original node (losing its context) or the original node (keeping its context). The XQuery specification calls for the node to be a copy, but it is often useful for the node to retain its original context (for example, so you can look at its ancestor elements). The following is the prolog option:

declare option xdmp:copy-on-validate "true";

You can specify true or false. This option is true by default in the 1.0 dialect, and false by default in the 1.0-ml dialect.

The following is a simple validate expression:

xquery version "1.0-ml";
validate { <p xmlns="http://www.w3.org/1999/xhtml">hello there</p> }

(: 
validates against the in-scope xhtml schema and returns the element:
<p xmlns="http://www.w3.org/1999/xhtml">hello there</p> 
:)

The as XML_type validation mode allows you to specify the type to validate as (rather than use the in-scope schema definitions for the type). This mode is an extension to the XQuery 1.0 syntax and is only available in the 1.0-ml dialect.

xquery version "1.0-ml";

validate as xs:boolean { <foo>{fn:true()}</foo> }

In the 1.0 dialect (or also in the 1.0-ml dialect), you can specify the an xdmp:validate-type pragma before an expression to perform the same as XML_type validation, but without the validate as syntax, as in the following example:

xquery version "1.0";
declare namespace xdmp="http://marklogic.com/xdmp";

(# xdmp:validate-type xs:boolean #) { <foo>{fn:true()}</foo> }

Node Comparison Operators

You can specify node comparisons to test if two nodes are before or after each other (in document order), or if the nodes are the exact same node. These tests return true or false. The following are the node comparison operators:

<<

let $x := <foo>
            <bar>hello</bar>
            <baz>goodbye</baz>
          </foo>
return
($x/baz << $x/bar, $x/bar << $x/baz)
(: returns false, true :)

>>

let $x := <foo>
            <bar>hello</bar>
            <baz>goodbye</baz>
          </foo>
return
($x/baz >> $x/bar, $x/bar >> $x/baz)
(: returns true, false :)

is

let $x := <foo>
            <bar>hello</bar>
            <baz>goodbye</baz>
          </foo>
return
($x/baz is $x/bar, $x/bar is $x/bar)
(: returns false, true :)

Node comparison tests are useful when creating logic that relies on document order. For example, if you wanted to verify if a particular node came before another node, you can test as follows:

$x << $y

If this test returns true, you know that the node bound to $x comes before the node bound to $y, based on document order.

Sequence and Item Operators

XQuery has separate operators for to compare sequences and items. The following table lists XQuery operators for sequences and for items, along with a description and example for each operator. These operators are used to form expressions that compare values, and those expressions return a boolean value. This section consists of the following parts:

• Sequence Operators
• Item Operators

=

1 = 1 => true
1 = (1, 2) => true
(0, 3) = (1, 2) => false

>

1 > 1 => false
1 > (0, 1) => true
(0, 1) > (0, 1) => true

>=

1 >= 1 => true
1 >= (1, 2) => true
(1, 2) >= (1, 2) => true

<

1 < 1 => false
1 < (1, 2) => true
(1, 2) < (1, 2) => true

<=

1 <= 1 => true
1 <= (1, 2) => true
(1, 2) <= (1, 2) => true

!=

1 != 1 => false
1 != (1, 2) => true
(1, 2) != (1, 2) => true

eq

1 eq 1 => true
1 eq (1, 2) => error

gt

1 gt 1 => false

ge

1 ge 1 => true

lt

1 lt 1 => false

le

1 le 1 => true

ne

1 ne 1 => false