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 adds a new capability that allows developers to perform inserts, updates, and deletes via the Optic API. This expands the capability of MarkLogic's unique multi-model query language to make it easier to insert and update documents without having to write server-side code.
With the new Optic Update functions, developers can start an Optic pipeline with one or more new or existing documents as input, transform the documents, add metadata, and write them to the database in a single expression.
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 remove() or write() |
|
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 op.docCols() and op.docColTypes() functions |
|
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 first example just does a simple insert of a single document, specifying the collections as well.
declareUpdate();
const op = require("/MarkLogic/optic");
op
.fromDocDescriptors({
uri: "/helloworld.json", doc: {"hello": "world"}, collections: [ "mydocs" ]
})
.write()
.execute()
op.validateDoc() can be used to validate documents against a schema as they are inserted. In this example, op.select() is used to just return the URI and op.result() is used instead of op.execute() so we can see which URIs were inserted vs. had validation errors. Validation errors are currently reported in the app server error log.
declareUpdate();
const op = require("/MarkLogic/optic");
op
.fromDocDescriptors({
uri: "/helloworld.json", doc: {"hello": "world"}, collections: [ "mydocs" ]
})
.validateDoc('doc', {kind:'jsonSchema', schemaUri:'/myschema.json'})
.write()
.select('uri')
.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.
declareUpdate();
const op = require("/MarkLogic/optic");
op
.fromDocUris(cts.wordQuery('world'))
.remove()
.result()
Limitations
The new Optic Update operators are only available in server-side JavaScript
"Builders" for the new Optic Update operators have only been implemented in the Java Client
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
Additional Information
See Getting Started with Optic for more detail about working with the Optic API.