About Interceptors

MarkLogic Data Hub provides two mechanisms to add custom processing to a step:

  • An interceptor is executed within the same database transaction as the core step processes, after the core step processes are run and before the results are saved.
  • A custom hook is executed in a separate database transaction either before or after the core step process transaction.
    Note: Custom hooks are deprecated. Use interceptors instead.

A step interceptor runs in the same transaction as the step module that produces the array of content objects that are passed to the step interceptor. A step interceptor can modify each content object in any way that it sees fit, and it may also choose to add and remove content objects from the array that it receives. Step interceptors differ from custom hooks in that custom hooks run in a separate transaction and are not always able to manipulate the array of content objects that will be persisted.

MarkLogic recommends to use step interceptors unless your custom logic must run in a separate transaction (where it may also perform updates separate from those represented by the array of content objects).

Results are saved within each transaction.

For example, if your step has interceptors and custom hooks that make changes to the data, the processing might be as follows:


Flow of step with interceptor and pre-step and post-step custom hooks
  1. In the pre-step custom hook transaction,
    1. The pre-step custom hook is executed.
    2. The custom hook module can save its own changes to the database.
  2. In the main step transaction,
    1. The core processes of the step are executed.
    2. The post-step interceptor is executed.
  3. In the post-step custom hook transaction,
    1. The post-step custom hook is executed.
    2. The custom hook module can save its own changes to the database.
  4. All changes by the core processes and by the interceptor, as well as unsaved changes by all custom hooks, are saved to the database.

You can use interceptors to perform various processes that modify documents, URIs, collections, or permissions. For example:

  • Fine-tune the instance with additional metadata after the core step processes.
  • Apply collections and permissions based on logic.
  • Replace the default URIs of documents to be written.
  • Insert triples.

Go to GitHub for an example project that uses step interceptors.