elastic-transform

ElasticSearch Transform

ElasticSearch query transformations using the visitor pattern.

Installation

Install using npm:

$ npm install elastic-transform

Usage

elastic-transform exports a traverse function which expects an ElasticSearch query and a visitor object. It will then visit each node in the query, invoking methods on the visitor as it does so, corresponding with the type of the node being visited. Depending on the visitor, the query may be modified in place.

Example

Traversing an ElasticSearch query with the following visitor would add a must clause specifying an account value:

var traverse = require('elastic-traverse')
 
var visitor = {
  visitor: {
    bool: function (path) {
      // Ensure a must node exists and is an array.
      path.node.bool.must = path.node.bool.must || []
      if (!Array.isArray(path.node.bool.must)) {
        path.node.bool.must = [path.node.bool.must]
      }
 
      // Prepend an account term to the must.
      path.node.bool.must.unshift({ term: { account: accountId } })
 
      // Stop traversal. Only apply transform to the first bool traversed.
      path.stop()
    }
  }
}
 
var elasticQuery = {
  query: {
    bool: {
      should: [{ term: { user: 'kimchy' } }]
    }
  }
}
 
traverse(elasticQuery, visitor)
console.log(elasticQuery)
//=> {
//=>   query: {
//=>     bool: {
//=>       should: [{ term: { user: 'kimchy' } }],
//=>       must: [{ term: account: 42 }]
//=>     }
//=>   }
//=> }

See the examples directory for this and more examples.

Visitor Interface

Visitors can be implemented with plain JavaScript objects of the following shape:

var visitor = {
  pre: function (state) {
    // Optional pre-traversal callback. May be used to set up state.
  },
  visitor: {
    // Define visitor methods here
    term: function (path, state) {
      // Short visit method form. Invoked on node enter.
    },
    bool: {
      // Long visit form. Specify enter/exit individually.
      enter: function (path, state) {
        // Do something on bool enter
      },
      exit: function (path, state) {
        // Do something else on bool exit, after children have been processed.
      }
    }
  },
  post: function (state) {
    // Optional post-traversal callback. May be used to process state.
  }
}

As can be seen above, a state object is threaded throughout the traversal process, and is passed along to all visit callbacks. This object is only provided out of convenience. It is not necessary to use, and is not used at all by the library. Optional pre and post callbacks can be defined on the visitor object to set up and process this state as needed.

In order to specify what should happen when any node of an ElasticSearch query is processed, define a corresponding function or object identified by the type of the node (one of query, bool, must, should, mustNot, filter, term, exists, match, matchAll, nested, range, regexp, geoDistance). The function form will be executed on enter, while the object form can be used for advanced enter/exit processing.

Node Paths

Visit methods are passed 2 arguments: path and state. Paths are wrappers around the original nodes and provide a number of additional state attributes and methods, in addition to the raw node itself.

Path Properties

path.node

Raw node reference in the query. Modifying this object will in turn modify the query.

path.parent

Parent path. Recursive reference to parent node(s) up the tree. path.parent will be null for the root node of the query.

path.type

Type of the node. Types generally correspond directly with their ElasticSearch counterparts, though they will be in camelcase (e.g., geoDistance) rather than snake case.

Path Methods

path.findLogicParent()

Walk up the query tree, returning the first "logic" node found (must, should, or mustNot), or undefined.

path.findParent(callback)

Walk up the query tree, calling the callback function with the current node path. Return the first node where the callback returns true, or otherwise, return undefined.

path.get(objectPath)

Helper method around manually looking up deeply nested keys on path.node. path.get can be called with a dot-delimited string (e.g., "bool.must.0"), that in addition to being more terse, is also null-safe (i.e., if a sub-path is undefined, the method will return undefined rather than throw).

path.get may also be called with an array of keys if any keys contain a dot.

path.getField()

Return the "field" value of a leaf node. For example, if path.node pointed to a term node of { term: { user: "kimchy" } }, path.getField() would return "user".

path.getPair()

Return the "field" and "value" pair of a leaf node. For example, if path.node pointed to a term node of { term: { user: "kimchy" } }, path.getPair() would return ["user", "kimchy"].

path.getPath(objectPath)

Identical in functionality to path.get, except that the return value will be wrapped as a node path. Note that this means this method will throw if the resolved path is not a traversable node.

path.getSibling(siblingKey)

Return a sibling node with the given siblingKey, i.e., an object key or array index.

path.getValue()

Return the "value" of a leaf node. For example, if path.node pointed to a term node of { term: { user: "kimchy" } }, path.getValue() would return "kimchy".

path.insertAfter(node)

Insert the given node immediately after the current node. This method should only be called on nodes whose parents are must/should/mustNot arrays.

path.insertBefore(node)

Insert the given node immediately before the current node. This method should only be called on nodes whose parents are must/should/mustNot arrays.

path.isBool()

Is the current node a bool node?

path.isEmptySearch()

Is the current node an empty search?

path.isExists()

Is the current node an exists node?

path.isFilter()

Is the current node a filter node?

path.isGeoDistance()

Is the current node a geoDistance node?

path.isMatch()

Is the current node a match node?

path.isMatchAll()

Is the current node a matchAll node?

path.isMust()

Is the current node a must node?

path.isMustNot()

Is the current node a mustNot node?

path.isNested()

Is the current node a nested node?

path.isNumericRange()

Is the current node a numeric range node?

NOTE: This method returns a best guess, based on the value of the node. When in doubt, refer to your ElasticSearch index.

path.isQuery()

Is the current node a query node?

path.isRange()

Is the current node a range node?

path.isRegexp()

Is the current node a regexp node?

path.isRemovable()

Can the current node be removed/replaced?

path.isShould()

Is the current node a should node?

path.isTerm()

Is the current node a term node?

path.remove()

Remove the current node from the query. This method may throw if path.parent is null, or if the node cannot be removed (check path.isRemovable()) if this is a concern).

path.replaceWith(node)

Replace the current node with a new node. This method may throw if path.parent is null, or if the node cannot be replaced (check path.isRemovable() if this is a concern).

path.replaceWithMany(nodeList)

Like path.replaceWith, but accepts an array of nodes.

path.skip()

Trigger the query traversal to skip any further descendants of the current node.

path.stop()

Stop traversal entirely.

License

MIT