The MarkLogic Optic API makes it possible to perform relational operations on indexed values and documents. The Optic API is not a single API, but rather a set of APIs exposed within the XQuery, JavaScript, and Java languages.

The Optic API can read any indexed value, whether the value is in a range index, the triple index, or rows extracted by a template. The extraction templates, such as those used to create template views described in Creating Template Views in the SQL Data Modeling Guide, are a simple, powerful way to specify a relational lens over documents, making parts of your document data accessible via SQL. Optic gives you access to the same relational operations, such as joins and aggregates, over rows. The Optic API also enables document search to match rows projected from documents, joined documents as columns within rows, and dynamic document structures – all performed efficiently within the database and accessed programmatically from your application.

The Optic API allows you to use your data as-is and makes it possible to make use of MarkLogic document and search features using JavaScript or XQuery syntax, incorporating common SQL concepts, regardless of the structure of your data. Unlike SQL, Optic is well suited for building applications and accessing the full range of MarkLogic NoSQL capabilities. Because Optic is integrated into common application languages, it can perform queries within the context of broader applications that perform updates to data and process results for presentation to end users.

The Optic API supports:

  • Joins – integrating documents that are frequently updated or that have many relations with a declarative query instead of with a denormalized write
  • Grouping – summarizing aggregate properties over many documents
  • Exact matches over repeated structures in documents
  • Joining Triples – incorporating semantic triples to enrich row data or to link documents and rows
  • Document Joins – returning the entire source document to provide context to row data
  • Document Query – performing rich full text search to constrain rows in addition to relational filtering

As in the SQL and SPARQL interfaces, you can use the Optic API to build a query from standard operations such as wheregroupByorderByunion, and join but by expressing the operations through calls to JavaScript and XQuery functions. The Optic API enables you to work in the environment of the programming language, taking advantage of variables and functions for benefits such as modularizing plan construction and avoiding the parse errors and injection attacks associated with assembling a query by concatenating strings.

Learn More

Getting Started with Optic

New to the Optic API? The guide walks you through what the Optic API is and how it works, along with some sample queries that explain introductory concepts.

Optic Processing Model

Learn about the Optic API processing model and how it works, so you can better structure your queries and use the Optic API.


Read through an in-depth description of the set of APIs exposed within the JavaScript, XQuery, and Java languages.

Optic API Tutorial

This written tutorial takes you step-by-step in getting started using the Optic API using XQuery and JavaScript examples.

Search Multi-Model Data

Pull data of different shapes into a MarkLogic Data Hub and use the Optic API to view and query the data.

Deep Dive Video Series

Watch these videos for a 5-part deep dive into MarkLogic’s Optic Engine.

Page over Optic API results

Walk through how to get a stable set of results a page at a time when your Optic API query returns a large result set.

Extract Content from Retrieved Documents

This short tutorial shows you how to get more information with a particular query when extracting data using TDE.

Group by Sum

MarkLogic provides group-by with the Optic API. This short tutorial walks you through how to get the sum of counts grouped by name.

Template Driven Extraction Technical Resources

Learn how to use TDE to define a relational lens over your document data so you can query parts it using SQL or the Optic API.

This website uses cookies.

By continuing to use this website you are giving consent to cookies being used in accordance with the MarkLogic Privacy Statement.