Coordinate Search API

This plugin introduces two new search actions, _coordinate_search that replaces the _search action, and_coordinate_msearch that replaces the _msearch action. Both actions are wrappers around the original elasticsearch actions and therefore supports the same API. One must use these actions with the filterjoin filter, as the filterjoin filter is not supported by the original elaticsearch actions.


  • filterjoin: the filter name
  • indices: the index names to lookup the terms from (optional, default to all indices).
  • types: the index types to lookup the terms from (optional, default to all types).
  • path: the path within the document to lookup the terms from.
  • query: the query used to lookup terms with.
  • orderBy: the ordering to use to lookup the maximum number of terms: default, doc_score (optional, default to default ordering).
  • maxTermsPerShard: the maximum number of terms per shard to lookup (optional, default to all terms).
  • termsEncoding: the encoding to use when transferring terms across the network: long, integer, bloom, bytes (optional, default to long).


In this example, we will join all the documents from index1 with the documents of index2. The query first filters documents from index2 and of type type with the query { "terms" : { "tag" : [ "aaa" ] } }. It then retrieves the ids of the documents from the field id specified by the parameter path. The list of ids is then used as filter and applied on the fieldforeign_key of the documents from index1.

      "bool" : {
        "filter" : {
          "filterjoin" : {
            "foreign_key" : {
              "indices" : ["index2"],
              "types" : ["type"],
              "path" : "id",
              "query" : {
                "terms" : {
                  "tag" : [ "aaa" ]

Response Format

The response returned by the coordinate search API is identical to the response returned by Elasticsearch's search API, but augmented with additional information about the execution of the relational query planning. This additional information is stored within the field named coordinate_search at the root of the response, see example below. The object contains the following parameters:

  • actions: a list of actions that has been executed - an action represents the execution of one single join.
  • relations: the definition of the relations of the join - it contains two nested objects, from and to, one for each relation.
  • size: the size of the filter used to compute the join, i.e., the number of terms across all shards used by the filterjoin.
  • size_in_bytes: the size in bytes of the filter used to compute the join.
  • is_pruned: a flag to indicate if the join computation has been pruned based on the maxTermsPerShard limit.
  • cache_hit: a flag to indicate if the join was already computed and cached.
  • terms_encoding: the terms encoding used to transfer terms across the network.
  • took: the time it took to construct the filter.

      "coordinate_search": {
        "actions": [
            "relations": {
              "from": {
                "indices": ["index2"],
                "types": ["type"],
                "field": "id"
              "to": {
                "indices": null,
                "types": null,
                "field": "foreign_key"
            "size": 2,
            "size_in_bytes": 20,
            "is_pruned": false,
            "cache_hit": false,
            "terms_encoding" : "long",
            "took": 313