MarkLogic 9 Product Documentation

XQuery and XSLT Reference Guide — Chapter 2

MarkLogic Server Enhanced (XQuery 1.0-ml)

For a module to use the MarkLogic Server enhanced dialect, use the following for the XQuery version declaration on the first line of the XQuery module:

xquery version "1.0-ml";

Note the semi-colon at the end of the declaration, which is required in 1.0-ml. The enhanced dialect has the XQuery 1.0 syntax and also includes various extensions to the language such as try/catch. This dialect is the default for new App Servers, and is considered the preferred dialect for new applications. For more details on the enhanced 1.0-ml dialect, see MarkLogic Server Enhanced XQuery Language.

XQuery 0.9-ml

For a module to use the XQuery 0.9-ml dialect, use the following for the XQuery version declaration on the first line of the XQuery module:

xquery version "0.9-ml"

Note there is no semi-colon at the end of the declaration for 0.9-ml. The 0.9-ml dialect allows you to write code that you can use with both 0.9-ml and 1.0-ml. Any code you have from releases where no version is mentioned is equivalent to 0.9-ml. To use 0.9-ml code in 1.0-ml, the best practice is to add the 0.9-ml XQuery declaration as the first line of each XQuery module.

The XQuery 0.9-ml dialect will soon be deprecated. MarkLogic recommends that you use either the 1.0-ml or 1.0 dialect.

Strict (XQuery 1.0)

For a module to use the MarkLogic Server strict dialect (1.0), use the following for the XQuery version declaration on the first line of the XQuery module:

xquery version "1.0";

Note the semi-colon at the end of the declaration, which is required in 1.0. The strict mode is for compatibility with other XQuery 1.0 processors; if you write a library in 1.0, you can use it with MarkLogic Server and you can also use it with other conforming processors. Similarly, you can use modules that are written in standard XQuery with MarkLogic Server.

To use the MarkLogic Server built-in functions in 1.0, you must bind a prefix (for example, xdmp) to the namespace for the MarkLogic Server functions; there is no need to import a library for these built-in functions, but you do need to bind the namespace to a prefix. To use the xdmp functions in 1.0, add prolog entries for the namespace bindings you are using in your query, as in the following example:

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

xdmp:version()

When To Migrate XQuery Code

Because of the flexibility of how you can interoperably use the various XQuery dialects, it is really up to you when and how you migrate your XQuery code. The differences between the dialects are mostly syntax changes in the prolog, but there are also some other differences that might cause subtle changes in behavior. For details on the differences between the XQuery dialects in 0.9-ml and 1.0-ml, see XQuery Changes From Previous MarkLogic Server Releases. When you decide to migrate XQuery code to 1.0-ml (or to 1.0), there are several ways you can go about it:

• Migrate an entire application all at once. This method gets everything over with at once, and therefore focuses the effort. If you have a relatively small amount of code to migrate, it might make sense to just go ahead and migrate it all at once.
• Migrate one module at a time. This method allows you to spread the migration work over a number of small tasks instead of one large task, and further allows you to test each module independently after migration. This technique is very flexible, as you can do a little bit at a time. A good first step for this one-by-one approach is to start by adding an XQuery 0.9-ml declaration to the first line of each XQuery file. Then, as you migrate a module, you can change the declaration to 1.0-ml and make any needed syntax changes to that module.

XQuery Changes From Previous MarkLogic Server Releases

While XQuery 1.0-ml 4.0 includes a compatibility dialect to run your 0.9-ml code without changes, the new enhanced mode offers several important improvements, so it is a good idea to migrate your code to the enhanced dialect (1.0-ml). Because you can mix modules in the old dialect with modules in the new, you can perform your migration one module at a time. This section highlights the major syntax and semantic changes between the XQuery used in 0.9-ml and enhanced XQuery dialect 1.0-ml. Additionally, see the Known Incompatibilities section of the Release Notes. The changes include:

• Semi-colons ( ; ) are now required at the end of each prolog declaration.
• Prolog declarations that previously used define now use declare.
• Variable declaration syntax is slightly different, and now uses the := syntax (for details and an example, see Declaring Variables).
• Library module declarations now require the namespace keyword and a prefix for the namespace, for example:

  module namespace my = "my-namespace";

• Function declarations that return the empty sequence now require the empty sequence to be specified as follows:

  empty-sequence()

  In 0.9-ml, you specify empty() for the empty sequence.

• Some of the effective boolean value rules have changed. Notably, the following returns true in 0.9-ml and returns false in 1.0-ml (and throws an exception in 1.0):

  (: returns true in 0.9-ml, false in 1.0-ml, and
     throws XDMP-EFFBOOLVALUE in 1.0 :)
  fn:boolean((fn:false(), fn:false()))

  This change might affect applications that have if/then/else statements where the if test returns a sequence of boolean values. In these cases, you might see the if statement evaluating to false in cases where it previously evaluated to true, causing the else statement to be evaluated intead of the then statement.

• The namespace used for durations now uses the xs namespace prefix; previously it was the xdt prefix. Any code you have that uses the xdt namespace prefix will require a change to the xs prefix. For example, if you have code that uses xdt:dayTimeDuration, change it to xs:dayTimeDuration.
• element() tests in 0.9-ml are equivalent to schema-element() test in 1.0 and 1.0-ml. Any code you have with element() tests might not match some elements that previously matched. For example, substitution elements previously would match the base element name, but will now only match with schema-element() test in 1.0 and 1.0-ml. For more information, see in the Release Notes.
• Some changes to the XQuery standard functions. For example, there are subtle changes to fn:avg and fn:sum, fn:error has a different signature, and fn:node-kind does not exist in 1.0 and 1.0-ml (it is replaced by xdmp:node-kind).

Inheriting the Default XQuery Version From the App Server

Each App Server has a setting for the default XQuery version. Any requests against that App Server that do not have explicitly specify an XQuery version declaration are treated as the default XQuery version value. Because of the way a request inherits it default XQuery version from the App Server environment, requests without an explicit declaration can be treated differently by different App Servers (if the App Servers have different default XQuery values). Therefore, it is best practice to specify the XQuery version in each module.

The task server does not allow you to specify a default XQuery version, and if there is no explicit version declaration in the XQuery code evaluated on the task server, the default XQuery version is determined as follows:

• If you run an xdmp:spawn call, the default XQuery version is 1.0-ml.
• If a trigger action module is executed on the task server (for example, as the result of an update on a document that has a post-commit update trigger), then the default XQuery version is the default XQuery version for the App Server that triggered the update (as specified in the configuration for the App Server).

This makes it especially important to use XQuery version declarations in modules used by CPF or modules called from triggers. For details on CPF, see the Content Processing Framework Guide.

To ensure your code is always evaluated in the dialect in which you have written it, regardless of the context in which it is run, the best practice is to begin each XQuery module with a XQuery version declaration. For the syntax of the version declaration, see XQuery Version Declaration.

Porting 0.9-ml XQuery Code to Enhanced 1.0-ml

In most cases, porting any XQuery code used in 0.9-ml to the 1.0-ml dialect will be easy and straightforward. The bulk of the differences are syntax changes in the prolog. As stated earlier, you do not need to port all of your code at one time. A sensible approach is to migrate your code one XQuery module at a time. This section outlines the basic steps to follow when migrating your XQuery code.

The following are some basic steps to take when migrating 0.9-ml XQuery code to 1.0-ml:

1. Add XQuery version declarations to all of your existing modules. For code written in 0.9-ml, the declarations will be as follows:

   xquery version "0.9-ml"

2. Review the Release Notes for any incompatibilities.
3. For each module you migrate, change the version number string in the XQuery version declaration to 1.0-ml and add a semi-colon to the line so it appears as follows:

   xquery version "1.0-ml";

4. Change all of the prolog declarations to the 1.0 syntax (change define to declare, add semi-colons, and so on, as described in XQuery Changes From Previous MarkLogic Server Releases). For the prolog syntax, see XQuery Prolog, the W3C specification (http://www.w3.org/TR/xquery/#id-grammar), or a third-party XQuery book.
5. If you are modifying a main module and it has function declarations that are used in the same module, they must be declared in a namespace. The preferred way to put functions local to a main module is to prefix those functions definitions and function calls with the local: prefix, which is predefined.
6. If you have any durations that use the xdt namespace prefix, change the prefix to xs (for example, change xdt:dayTimeDuration to xs:dayTimeDuration).
7. If you are modifying a library module, all XQuery standard functions need to be prefixed with the fn namespace prefix. Alternately, you can declare the XQuery functions namespace as the default function namespace in the prolog as follows:

   declare default function namespace
               "http://www.w3.org/2005/xpath-functions"; 

   If you do declare the default function namespace, then you will also need to prefix your own function definitions with the prefix defined in your module definition. Note that you can no longer use the XPath functions namespace as the library module namespace.

8. If you are modifying a library module that is defined with the fn namespace URI, you must change the namespace URI of that module; you cannot use the URI bound to the fn namespace prefix as the URI for a library module in 1.0 or 1.0-ml. If you do change the namespace URI of a library module, you must also change the URI in any import module statements in other modules that call the library.
9. Test the module and correct any syntax errors that occur.
10. After getting the module to run, test your code to make sure it behaves as it did before. Pay particular attention to parts of your code that might rely on boolean values that take boolean values of sequences, as those behave differently in 0.9-ml and 1.0-ml (see XQuery Changes From Previous MarkLogic Server Releases). Check for any changes due to function mapping, which is described in Function Mapping.
11. Repeat this process for other modules you want to migrate.