XQuery and Node.js Support for Optic Update (Technical Preview)
Important
Technical Preview means a feature that is in whole or in part under active development and in stages of testing. Its purpose is to establish a feedback loop, allowing customers to influence its development and direction. Backward-incompatible changes may be introduced to the service or its APIs.
MarkLogic 11.1.0 adds XQuery support for the Optic Update feature that was introduced in 11.0.0.
This capability is released as a Technical Preview (defined above) with the intention of removing the known limitations and incorporating user feedback in coming minor releases of MarkLogic.
New Operators
Optic Update includes three new Optic operators for performing updates:
Function |
Description |
|---|---|
Operator that gets an early lock on documents that will be updated later in the pipeline with an operation like |
|
Operator that deletes documents. |
|
Operator that inserts or overwrites documents as supplied by document descriptors. |
New operators have also been added to support common scenarios when updating documents. These operators will often be used with update operators, but they can be used with existing Optic query operators as well:
Function |
Description |
|---|---|
Data accessor that returns document rows from one or more "document descriptors," which are a combination of URI, the document, collections, metadata, permissions, quality, and temporal collection. |
|
Data accessor that returns a list of URIs that match a given CTS query. |
|
Data accessor that returns document rows from a given set of parameters. |
|
Operator that can be used to join in document descriptor columns using the supporting |
|
Operator that applies a transformation to the documents in the document column for each row. |
|
Operator that validates documents based on a supplied JSON, XML, or Schematron schema. |
|
Executor that executes the Optic pipeline/plan but does not return results out of the pipeline. This is useful if you want to update a list of documents but not actually return anything from the pipeline. |
Examples
This example does a simple insert of a single document, specifying the collections as well:
xquery version "1.0-ml";
import module namespace op="http://marklogic.com/optic"
at "/MarkLogic/optic.xqy";
declare option xdmp:update "true";
let $doc-descriptors := (
map:entry("uri", '/helloworld.xml')
=>map:with("doc", <doc>hello world</doc>)
=>map:with("collections", ("mydocs"))
)
return op:from-doc-descriptors($doc-descriptors)
=>op:write()
=>op:execute()
op:validate-doc() can be used to validate documents against a schema as they are inserted. This example validates the given document against the schemas installed. In this example, op:select() is used to just return the URI and op:result() is used instead of op:execute() so that we can see which URIs were inserted vs. had validation errors. Validation errors are currently reported in the app server error log:
xquery version "1.0-ml";
import module namespace op="http://marklogic.com/optic"
at "/MarkLogic/optic.xqy";
declare option xdmp:update "true";
let $doc-descriptors := (
map:entry("uri", '/helloworld.xml')
=>map:with("doc", <doc xmlns="http://marklogic.com/xdmp/helloWorld">hello world</doc>)
=>map:with("collections", ("mydocs"))
)
return op:from-doc-descriptors($doc-descriptors)
=>op:validate-doc(op:col("doc"), map:entry("kind", "xmlSchema")
=>map:with("mode", "strict"))
=>op:write()
=>op:select("uri")
=>op:result()
op:remove() can be used to delete a list of documents. Once again, op:result() can be used to return the list of URIs that were removed. op:execute() can be used if the result list is not needed:
xquery version "1.0-ml";
import module namespace op="http://marklogic.com/optic"
at "/MarkLogic/optic.xqy";
declare option xdmp:update "true";
op:from-doc-uris(cts:word-query("world", ("case-sensitive")))
=>op:remove()
=>op:result();
Node.js Client
As of version 3.1.0, the MarkLogic Node.js client also supports the use of the Optic Update operators.
Limitations
The "patch" operator that supports declarative modifications of documents is not yet available.
The error handling operator that allows detailed control of error disposition is not yet available.