Join field type

Introduced 1.0

A join field type establishes a parent/child relationship between documents in the same index.

Example

Create a mapping to establish a parent/child relationship between products and their brands:

  1. PUT testindex1
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "product_to_brand": { 
  6.         "type": "join",
  7.         "relations": {
  8.           "brand": "product" 
  9.         }
  10.       }
  11.     }
  12.   }
  13. }

copy

Then, index a parent document with a join field type:

  1. PUT testindex1/_doc/1
  2. {
  3.   "name": "Brand 1",
  4.   "product_to_brand": {
  5.     "name": "brand" 
  6.   }
  7. }

copy

You can also use a shortcut without object notation to index a parent document:

  1. PUT testindex1/_doc/1
  2. {
  3.   "name": "Brand 1",
  4.   "product_to_brand" : "brand" 
  5. }

copy

When indexing child documents, you need to specify the routing query parameter because parent and child documents in the same parent/child hierarchy must be indexed on the same shard. For more information, see Routing. Each child document refers to its parent’s ID in the parent field.

Index two child documents, one for each parent:

  1. PUT testindex1/_doc/3?routing=1
  2. {
  3.   "name": "Product 1",
  4.   "product_to_brand": {
  5.     "name": "product", 
  6.     "parent": "1" 
  7.   }
  8. }

copy

  1. PUT testindex1/_doc/4?routing=1
  2. {
  3.   "name": "Product 2",
  4.   "product_to_brand": {
  5.     "name": "product", 
  6.     "parent": "1" 
  7.   }
  8. }

copy

Querying a join field

When you query a join field, the response contains subfields that specify whether the returned document is a parent or a child. For child objects, the parent ID is also returned.

Search for all documents

  1. GET testindex1/_search
  2. {
  3.   "query": {
  4.     "match_all": {}
  5.   }
  6. }

copy

The response indicates whether a document is a parent or a child:

  1. {
  2.   "took" : 4,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 3,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 1.0,
  16.     "hits" : [
  17.       {
  18.         "_index" : "testindex1",
  19.         "_type" : "_doc",
  20.         "_id" : "1",
  21.         "_score" : 1.0,
  22.         "_source" : {
  23.           "name" : "Brand 1",
  24.           "product_to_brand" : {
  25.             "name" : "brand"
  26.           }
  27.         }
  28.       },
  29.       {
  30.         "_index" : "testindex1",
  31.         "_type" : "_doc",
  32.         "_id" : "3",
  33.         "_score" : 1.0,
  34.         "_routing" : "1",
  35.         "_source" : {
  36.           "name" : "Product 1",
  37.           "product_to_brand" : {
  38.             "name" : "product",
  39.             "parent" : "1"
  40.           }
  41.         }
  42.       },
  43.       {
  44.         "_index" : "testindex1",
  45.         "_type" : "_doc",
  46.         "_id" : "4",
  47.         "_score" : 1.0,
  48.         "_routing" : "1",
  49.         "_source" : {
  50.           "name" : "Product 2",
  51.           "product_to_brand" : {
  52.             "name" : "product",
  53.             "parent" : "1"
  54.           }
  55.         }
  56.       }
  57.     ]
  58.   }
  59. }

Search for all children of a parent

Find all products associated with Brand 1:

  1. GET testindex1/_search
  2. {
  3.   "query" : {
  4.     "has_parent": {
  5.       "parent_type":"brand",
  6.       "query": {
  7.         "match" : {
  8.           "name": "Brand 1"
  9.         }
  10.       }
  11.     }
  12.   }
  13. }

copy

The response contains Product 1 and Product 2, which are associated with Brand 1:

  1. {
  2.   "took" : 7,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 2,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 1.0,
  16.     "hits" : [
  17.       {
  18.         "_index" : "testindex1",
  19.         "_type" : "_doc",
  20.         "_id" : "3",
  21.         "_score" : 1.0,
  22.         "_routing" : "1",
  23.         "_source" : {
  24.           "name" : "Product 1",
  25.           "product_to_brand" : {
  26.             "name" : "product",
  27.             "parent" : "1"
  28.           }
  29.         }
  30.       },
  31.       {
  32.         "_index" : "testindex1",
  33.         "_type" : "_doc",
  34.         "_id" : "4",
  35.         "_score" : 1.0,
  36.         "_routing" : "1",
  37.         "_source" : {
  38.           "name" : "Product 2",
  39.           "product_to_brand" : {
  40.             "name" : "product",
  41.             "parent" : "1"
  42.           }
  43.         }
  44.       }
  45.     ]
  46.   }
  47. }

Search for the parent of a child

Find the parent of Product 1:

  1. GET testindex1/_search
  2. {
  3.   "query" : {
  4.     "has_child": {
  5.       "type":"product",
  6.       "query": {
  7.         "match" : {
  8.             "name": "Product 1"
  9.         }
  10.       }
  11.     }
  12.   }
  13. }

copy

The response returns Brand 1 as Product 1’s parent:

  1. {
  2.   "took" : 4,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 1,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 1.0,
  16.     "hits" : [
  17.       {
  18.         "_index" : "testindex1",
  19.         "_type" : "_doc",
  20.         "_id" : "1",
  21.         "_score" : 1.0,
  22.         "_source" : {
  23.           "name" : "Brand 1",
  24.           "product_to_brand" : {
  25.             "name" : "brand"
  26.           }
  27.         }
  28.       }
  29.     ]
  30.   }
  31. }

Parent with many children

One parent can have many children. Create a mapping with multiple children:

  1. PUT testindex1
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "parent_to_child": {
  6.         "type": "join",
  7.         "relations": {
  8.           "parent": ["child 1", "child 2"]  
  9.         }
  10.       }
  11.     }
  12.   }
  13. }

copy

Join field type notes

  • There can only be one join field mapping in an index.
  • You need to provide the routing parameter when retrieving, updating, or deleting a child document. This is because parent and child documents in the same relation have to be indexed on the same shard.
  • Multiple parents are not supported.
  • You can add a child document to an existing document only if the existing document is already marked as a parent.
  • You can add a new relation to an existing join field.

Next steps