XQuery enhancements in MarkLogic Server

MarkLogic Server implements its own XQuery dialect called XQuery 1.0-ml. It's not hard to guess that this is the same XQuery 1.0 with some additions from MarkLogic, designed to make a developer's life better. The specification states that these changes make XQuery more suitable for programming an application. Look at the XQuery add-ons described in the MarkLogic Server 6.0 specification (http://docs.marklogic.com/6.0/guide/xquery.pdf)
The dialect used is declared by the following directive.

xquery version "1.0-ml"; 

It is the default that is used, but it is also possible to use XQuery 1.0 by placing the following directive at the beginning of the module
')

 xquery version "1.0"; 

List of XQuery 1.0-ml improvements according to MarkLogic
1. try / catch expressions
2. Function Mapping
3. Semicolon as Transaction Separator
4. Private functions and variables
5. Functions with side effect “Side effect”
6. Abbreviated Positioning Predicate
7. Designer of binary objects
8. expression validate as
9. Serialization options
10. Importing XSLT Styles into XQuery Models
11. Semantics defined by implementation

Consider a little more detail each item

1. try / catch expressions
This expression makes it possible to catch exceptions during the execution of XQuery and react adequately to them.

 try {    } catch ($exception) {    } 

The $ exception variable, like everything in MarkLogic Server, is XML that describes the exception that you can set on, for example XPath, and pull out the data of interest, or you can do everything that can be done with XML inside the MarkLogic Server.
And only three "special" exceptions cannot be caught in this way - XDMP-CANCELED, SVC-CENCELER XDMP-DISABLED .

2. Function Mapping
"Function Mapping" is an expression that allows you to pass a sequence of elements as a function parameter, BUT! each element in the sequence is processed separately. This means that a handler function will be called for each element of the sequence, and one element will be passed to it as a parameter.
"Function Mapping" is an analogue of the iterative processing of an array of elements in a for loop. Naturally with some exceptions.

 xquery version "1.0-ml"; declare function local:print-word ($word as xs:string) { $word }; local:print-word( ("hello", "world") ) 

This code will print the text “helloworld”. The local: print-word function will be called twice for each element.
In the following expression, we get an interesting result.

 xquery version "1.0-ml"; (1,2) * (3,4) 

the result (3, 4, 6, 8). In this case, “Function Mapping” also works, and the result is the result of successively multiplying numbers.
Particular attention should be paid to the results of calling such functions, which becomes the sequence of the results of calling the function for each element. It is worth noting that when calling a function with an empty sequence

 local:print-word( () ) 

the result of the function will be - (), which was to be expected, but at the same time, the function itself will not be called once. This is worth remembering.
"Function Mapping" is available in MarkLogic server by default, but it is possible to forcibly disable or enable it. This is done as follows.
Turning on:

 declare namespace xdmp="http://marklogic.com/xdmp"; declare option xdmp:mapping "true"; 

Shutdown:

 declare namespace xdmp="http://marklogic.com/xdmp"; declare option xdmp:mapping "false"; 

3. Semicolon - as a transaction separator
In Xquery 1.0-ml you can add the character ";" after one or several XQuery expressions, and this will mean that the code located before this character will be executed in one transaction, and all instructions located after this character will be executed in another (next) transaction. By default, the entire request to MarkLogic Server is executed in a single transaction, and if it is rolled back, all the data modified in this request is restored. The transaction separator allows you to split the request to the MarkLogic Server into parts, in case it is very complex.
It should also be remembered that the new version of the document is not available from the transaction from which it was modified.

4. Private functions and variable definitions.
When implementing libraries, you can lock up some functions or variables inside the module, making them private and not accessible from other libraries. This is done as follows.

 declare private function .... declare private variable .... 

It is worth noting that, by definition, functions and variables from the “main” module are private, therefore “private” is valid only for library modules.

5. Functions with side effect “Side effect”
The XQuery specification says that functions can only return a value instead of a call, and no side changes are allowed from the function body to the data. MarkLogic Server has many enhancements that contradict the XQuery specification and cause data changes in addition to the result of functions. An example of such an effect is a change in a document in the database, which not only returns the result, but also changes the data.
The “Side Effect” is very often used when creating applications, which is why the MarkLogic Server has many functions that create the “Side Effect”.
Example of such functions
• xdmp: set
• Update functions (xdmp: document-load, xdmp: node-insert, etc.)
• Management functions (xdmp: merge, admin library, xdmp: shutdown, etc.)

6. Abbreviated Positioning Predicate
MarkLogic Server has a reduced predicate for positioning elements in a sequence. So, to get the first three elements of a sequence in XQuery 1.0-ml you need to run

 xquery version "1.0-ml"; (1, 2, 3, 4, 5, 5)[1 to 3] 

and in XQuery 1.0

 xquery version "1.0"; (1, 2, 3, 4, 5, 5)[fn:position() = (1 to 3)] 

7. Designer of binary objects
XQuery 1.0-ml expands extends XQuery 1.0 by entering the type of binary data that is used to save binary documents. To support the new type, the binary data constructor and the binary () type check function are introduced, which can be used in typeswitch type constructs.

8. expression validate as
Another innovation is the expression "validate as", which can be used to specify the type in the expression "validate".

 xquery version "1.0-ml"; validate as xs:boolean { <foo>{fn:true()}</foo> } 

In principle, this is not such an innovation XQuery 1.0-ml. A similar check in XQuery 1.0 can be done as follows.

 xquery version "1.0"; declare namespace xdmp="http://marklogic.com/xdmp"; (# xdmp:validate-type xs:boolean #) { <foo>{fn:true()}</foo> } 

9. Serialization options
Serialization options can be specified in XQuery using the "declare option" directive.

10. Importing XSLT Styles into XQuery Models
In XQuery 1.0-ml, you can import XSLT styles in an XQuery module, and at the same time get access to all functions and variables declared in the XSLT module.
Importing XSLT

 xquery version "1.0-ml"; import stylesheet at "/path-to-stylesheet.xsl"; 

11. Semantics defined by implementation
The XQuery specification contains a set of clauses that can be implemented differently in different XQuery implementations.

1. Predefined namespaces.
Each XQuery implementation contains its own set of namespaces that you can use without importing it explicitly. For example, "fn:" is one of these spaces.

2. External variables
External variables are variables that can be used from an external module. Example of declaring such a variable

 xquery version "1.0-ml"; declare namespace my="myNamespace"; declare variable $my:variable as xs:string* external; fn:concat("The value of $my:variable is: ", $my:variable) 

The xdmp: invoke, xdmp: eval, xdmp: spawn or XCC functions can set the value of such a variable.

 >xquery version "1.0-ml"; declare namespace my="myNamespace"; xdmp:invoke("/extvar.xqy", (xs:QName("my:variable"), "my value")) 

Use of such variables

 The value of $my:variable is: my value 

3. Sorting options
Names, collations, and default parameters for each XQuery implementation are individual. For more information, see the Search Developer's Guide.

4. XQuery implementation-defined types
MarkLogic Server extends XQuery with additional types and functions to interact with them. These types are not mandatory in the XQuery specification, but life becomes better with them, and therefore they are present in the MarkLogic Server.
Some new types
• cts: query (with a variety of subtypes such as cts: word-query, cts: element-query, etc.)
• map: map
• cts: region (with subtypes cts: box, cts: circle, cts: polygon, and cts: point)
• json: object
• json: array
• json: unquotedString

5. Accuracy of decimals
MarkLogic Server has no settings to limit the accuracy of decimal fractions. Decimal numbers have an accuracy of 18 decimal digits.

6. The namespace of a module is its default function space.
The default namespace for a module is the default namespace for all functions inside this module. This means that you can declare functions within a module without explicitly specifying their prefix (namespace).