Join query #

Status: not yet functional. The join query parses and its wire format is stable, but execution currently returns no matches — the rewrite_joins machinery exists in the engine yet no production caller resolves the inner index. Do not rely on it; use traverse (graph edges) or application-side lookups until a release note declares joins operational. There is no live playground demo for this reason.

Matches documents in the current index whose target_field values intersect the join_on values of documents matching a query on another (inner) index — a semi-join. Use "_key" as the field name to join on document primary keys.

Examples #

Find orders (current index) whose customer matches a query on the customers index:

POST /orders/_search
{
  "query": {
    "join": {
      "index": "customers",
      "query": {
        "term": { "field": "tier", "value": "gold" }
      },
      "join_on": "_key",
      "target_field": "customer_id"
    }
  }
}

Parameters for join #

• index
  (Required, string) Name of the inner (foreign) index to query.
• query
  (Required, query) Query to execute on the inner index.
• join_on
  (Required, string) Field in the inner index whose values are used as join keys. Use "_key" to join on the document primary key.
• target_field
  (Required, string) Field in the outer (current) index matched against the inner join keys. Use "_key" to match the outer document primary key.
• score_mode
  (Optional, string) How inner-query scores affect the outer document score: none (default — pure filter, inner scores are discarded), max, sum or avg.
• inner_hits_cap
  (Optional, integer, default: 10000) Maximum number of inner hits to collect — protects against runaway inner queries.