Inner hits

In OpenSearch, when you perform a search using nested objects or parent-join, the underlying hits (nested inner objects or child documents) are hidden by default. You can retrieve inner hits by using the inner_hits parameter in the search query.

You can also use inner_hits with the following features:

Inner hits with nested objects

Nested objects allow you to index an array of objects and maintain their relationship within the same document. The following example request uses the inner_hits parameter to retrieve the underlying inner hits.

  1. Create an index mapping with a nested object:

    1.  PUT /my_index
    2.  {
    3.    "mappings": {
    4.      "properties": {
    5.        "user": {
    6.          "type": "nested",
    7.          "properties": {
    8.            "name": { "type": "text" },
    9.            "age": { "type": "integer" }
    10.          }
    11.        }
    12.      }
    13.    }
    14.  }

    copy

  2. Index data:

    1.  POST /my_index/_doc/1
    2.  {
    3.    "group": "fans",
    4.    "user": [
    5.      {
    6.        "name": "John Doe",
    7.        "age": 28
    8.      },
    9.      {
    10.        "name": "Jane Smith",
    11.        "age": 34
    12.      }
    13.    ]
    14.  }

    copy

  3. Query with inner_hits:

    1.  GET /my_index/_search
    2.  {
    3.    "query": {
    4.      "nested": {
    5.        "path": "user",
    6.        "query": {
    7.          "bool": {
    8.            "must": [
    9.              { "match": { "user.name": "John" } }
    10.            ]
    11.          }
    12.        },
    13.        "inner_hits": {}
    14.      }
    15.    }
    16.  }

    copy

The preceding query searches for nested user objects containing the name John and returns the matching nested documents in the inner_hits section of the response:

  1. {
  2.   "hits" : {
  3.     "total" : {
  4.       "value" : 1,
  5.       "relation" : "eq"
  6.     },
  7.     "max_score" : 0.6931471,
  8.     "hits" : [
  9.       {
  10.         "_index" : "my_index",
  11.         "_id" : "1",
  12.         "_score" : 0.6931471,
  13.         "_source" : {
  14.           "group" : "fans",
  15.           "user" : [
  16.             {
  17.               "name" : "John Doe",
  18.               "age" : 28
  19.             },
  20.             {
  21.               "name" : "Jane Smith",
  22.               "age" : 34
  23.             }
  24.           ]
  25.         },
  26.         "inner_hits" : {
  27.           "user" : {
  28.             "hits" : {
  29.               "total" : {
  30.                 "value" : 1,
  31.                 "relation" : "eq"
  32.               },
  33.               "max_score" : 0.6931471,
  34.               "hits" : [
  35.                 {
  36.                   "_index" : "my_index",
  37.                   "_id" : "1",
  38.                   "_nested" : {
  39.                     "field" : "user",
  40.                     "offset" : 0
  41.                   },
  42.                   "_score" : 0.6931471,
  43.                   "_source" : {
  44.                     "name" : "John Doe",
  45.                     "age" : 28
  46.                   }
  47.                 }
  48.               ]
  49.             }
  50.           }
  51.         }
  52.       }
  53.     ]
  54.   }
  55. }

Inner hits with parent/child objects

Parent-join relationships allow you to create relationships between documents of different types within the same index. The following example request searches with inner_hits using parent/child objects.

  1. Create an index with a parent-join field:

    1.  PUT /my_index
    2.  {
    3.    "mappings": {
    4.      "properties": {
    5.        "my_join_field": {
    6.          "type": "join",
    7.          "relations": {
    8.            "parent": "child"
    9.          }
    10.        },
    11.        "text": {
    12.          "type": "text"
    13.        }
    14.      }
    15.    }
    16.  }

    copy

  2. Index data:

    1.  # Index a parent document
    2.  PUT /my_index/_doc/1
    3.  {
    4.    "text": "This is a parent document",
    5.    "my_join_field": "parent"
    6.  }
    8.  # Index a child document
    9.  PUT /my_index/_doc/2?routing=1
    10.  {
    11.    "text": "This is a child document",
    12.    "my_join_field": {
    13.      "name": "child",
    14.      "parent": "1"
    15.    }
    16.  }

    copy

  3. Search with inner_hits:

    1.  GET /my_index/_search
    2.  {
    3.    "query": {
    4.      "has_child": {
    5.        "type": "child",
    6.        "query": {
    7.          "match": {
    8.            "text": "child"
    9.          }
    10.        },
    11.        "inner_hits": {}
    12.      }
    13.    }
    14.  }

    copy

The preceding query searches for parent documents that have child documents matching the query criteria (in this case, containing the term "child"). It returns the matching child documents in the inner_hits section of the response:

  1. {
  2.   "hits" : {
  3.     "total" : {
  4.       "value" : 1,
  5.       "relation" : "eq"
  6.     },
  7.     "max_score" : 1.0,
  8.     "hits" : [
  9.       {
  10.         "_index" : "my_index",
  11.         "_id" : "1",
  12.         "_score" : 1.0,
  13.         "_source" : {
  14.           "text" : "This is a parent document",
  15.           "my_join_field" : "parent"
  16.         },
  17.         "inner_hits" : {
  18.           "child" : {
  19.             "hits" : {
  20.               "total" : {
  21.                 "value" : 1,
  22.                 "relation" : "eq"
  23.               },
  24.               "max_score" : 0.6931471,
  25.               "hits" : [
  26.                 {
  27.                   "_index" : "my_index",
  28.                   "_id" : "2",
  29.                   "_score" : 0.6931471,
  30.                   "_routing" : "1",
  31.                   "_source" : {
  32.                     "text" : "This is a child document",
  33.                     "my_join_field" : {
  34.                       "name" : "child",
  35.                       "parent" : "1"
  36.                     }
  37.                   }
  38.                 }
  39.               ]
  40.             }
  41.           }
  42.         }
  43.       }
  44.     ]
  45.   }
  46. }

Using both parent-join and nested objects with inner_hits

The following example demonstrates using both parent-join and nested objects with inner_hits.

  1. Create an index with the following mapping:

    1.  PUT /my_index
    2.  {
    3.    "mappings": {
    4.      "properties": {
    5.        "my_join_field": {
    6.          "type": "join",
    7.          "relations": {
    8.            "parent": "child"
    9.          }
    10.        },
    11.        "text": {
    12.          "type": "text"
    13.        },
    14.        "comments": {
    15.          "type": "nested",
    16.          "properties": {
    17.            "user": { "type": "text" },
    18.            "message": { "type": "text" }
    19.          }
    20.        }
    21.      }
    22.    }
    23.  }

    copy

  2. Index data:

    1.  # Index a parent document
    2.  PUT /my_index/_doc/1
    3.  {
    4.    "text": "This is a parent document",
    5.    "my_join_field": "parent"
    6.  }
    8.  # Index a child document with nested comments
    9.  PUT /my_index/_doc/2?routing=1
    10.  {
    11.    "text": "This is a child document",
    12.    "my_join_field": {
    13.      "name": "child",
    14.      "parent": "1"
    15.    },
    16.    "comments": [
    17.      {
    18.        "user": "John",
    19.        "message": "This is a comment"
    20.      },
    21.      {
    22.        "user": "Jane",
    23.        "message": "Another comment"
    24.      }
    25.    ]
    26.  }

    copy

  3. Query with inner_hits:

    1.  GET /my_index/_search
    2.  {
    3.    "query": {
    4.      "has_child": {
    5.        "type": "child",
    6.        "query": {
    7.          "nested": {
    8.            "path": "comments",
    9.            "query": {
    10.              "bool": {
    11.                "must": [
    12.                  { "match": { "comments.user": "John" } }
    13.                ]
    14.              }
    15.            },
    16.            "inner_hits": {}
    17.          }
    18.        },
    19.        "inner_hits": {}
    20.      }
    21.    }
    22.  }

    copy

The preceding query searches for parent documents that have child documents containing comments made by John. Specifying inner_hits ensures that the matching child documents and their nested comments are returned:

  1. {
  2.   "hits" : {
  3.     "total" : {
  4.       "value" : 1,
  5.       "relation" : "eq"
  6.     },
  7.     "max_score" : 1.0,
  8.     "hits" : [
  9.       {
  10.         "_index" : "my_index",
  11.         "_id" : "1",
  12.         "_score" : 1.0,
  13.         "_source" : {
  14.           "text" : "This is a parent document",
  15.           "my_join_field" : "parent"
  16.         },
  17.         "inner_hits" : {
  18.           "child" : {
  19.             "hits" : {
  20.               "total" : {
  21.                 "value" : 1,
  22.                 "relation" : "eq"
  23.               },
  24.               "max_score" : 0.6931471,
  25.               "hits" : [
  26.                 {
  27.                   "_index" : "my_index",
  28.                   "_id" : "2",
  29.                   "_score" : 0.6931471,
  30.                   "_routing" : "1",
  31.                   "_source" : {
  32.                     "text" : "This is a child document",
  33.                     "my_join_field" : {
  34.                       "name" : "child",
  35.                       "parent" : "1"
  36.                     },
  37.                     "comments" : [
  38.                       {
  39.                         "user" : "John",
  40.                         "message" : "This is a comment"
  41.                       },
  42.                       {
  43.                         "user" : "Jane",
  44.                         "message" : "Another comment"
  45.                       }
  46.                     ]
  47.                   },
  48.                   "inner_hits" : {
  49.                     "comments" : {
  50.                       "hits" : {
  51.                         "total" : {
  52.                           "value" : 1,
  53.                           "relation" : "eq"
  54.                         },
  55.                         "max_score" : 0.6931471,
  56.                         "hits" : [
  57.                           {
  58.                             "_index" : "my_index",
  59.                             "_id" : "2",
  60.                             "_nested" : {
  61.                               "field" : "comments",
  62.                               "offset" : 0
  63.                             },
  64.                             "_score" : 0.6931471,
  65.                             "_source" : {
  66.                               "message" : "This is a comment",
  67.                               "user" : "John"
  68.                             }
  69.                           }
  70.                         ]
  71.                       }
  72.                     }
  73.                   }
  74.                 }
  75.               ]
  76.             }
  77.           }
  78.         }
  79.       }
  80.     ]
  81.   }
  82. }

inner_hits parameters

You can pass the following additional parameters to a search with inner_hits using both nested objects and parent-join relationships:

  • from: The offset from where to start fetching hits in the inner_hits results.
  • size: The maximum number of inner hits to return.
  • sort: The sorting order for the inner hits.
  • name: A custom name for the inner hits in the response. This is useful in differentiating between multiple inner hits in a single query.

Example: inner_hits parameters with nested objects

  1. Create an index with the following mappings:

    1.  PUT /products
    2.  {
    3.    "mappings": {
    4.      "properties": {
    5.        "product_name": { "type": "text" },
    6.        "reviews": {
    7.          "type": "nested",
    8.          "properties": {
    9.            "user": { "type": "text" },
    10.            "comment": { "type": "text" },
    11.            "rating": { "type": "integer" }
    12.          }
    13.        }
    14.      }
    15.    }
    16.  }

    copy

  2. Index data:

    1.  POST /products/_doc/1
    2.  {
    3.    "product_name": "Smartphone",
    4.    "reviews": [
    5.      { "user": "Alice", "comment": "Great phone", "rating": 5 },
    6.      { "user": "Bob", "comment": "Not bad", "rating": 3 },
    7.      { "user": "Charlie", "comment": "Excellent", "rating": 4 }
    8.    ]
    9.  }

    copy

    1.  POST /products/_doc/2
    2.  {
    3.    "product_name": "Laptop",
    4.    "reviews": [
    5.      { "user": "Dave", "comment": "Very good", "rating": 5 },
    6.      { "user": "Eve", "comment": "Good value", "rating": 4 }
    7.    ]
    8.  }

    copy

  3. Query with inner_hits and provide additional parameters:

    1.  GET /products/_search
    2.  {
    3.    "query": {
    4.      "nested": {
    5.        "path": "reviews",
    6.        "query": {
    7.          "match": { "reviews.comment": "Good" }
    8.        },
    9.        "inner_hits": {
    10.          "from": 0,
    11.          "size": 2,
    12.          "sort": [
    13.            { "reviews.rating": { "order": "desc" } }
    14.          ],
    15.          "name": "top_reviews"
    16.        }
    17.      }
    18.    }
    19.  }

    copy

The following is the expected result:

  1. {
  2.   "hits" : {
  3.     "total" : {
  4.       "value" : 1,
  5.       "relation" : "eq"
  6.     },
  7.     "max_score" : 0.83740485,
  8.     "hits" : [
  9.       {
  10.         "_index" : "products",
  11.         "_id" : "2",
  12.         "_score" : 0.83740485,
  13.         "_source" : {
  14.           "product_name" : "Laptop",
  15.           "reviews" : [
  16.             {
  17.               "user" : "Dave",
  18.               "comment" : "Very good",
  19.               "rating" : 5
  20.             },
  21.             {
  22.               "user" : "Eve",
  23.               "comment" : "Good value",
  24.               "rating" : 4
  25.             }
  26.           ]
  27.         },
  28.         "inner_hits" : {
  29.           "top_reviews" : {
  30.             "hits" : {
  31.               "total" : {
  32.                 "value" : 2,
  33.                 "relation" : "eq"
  34.               },
  35.               "max_score" : null,
  36.               "hits" : [
  37.                 {
  38.                   "_index" : "products",
  39.                   "_id" : "2",
  40.                   "_nested" : {
  41.                     "field" : "reviews",
  42.                     "offset" : 0
  43.                   },
  44.                   "_score" : null,
  45.                   "_source" : {
  46.                     "rating" : 5,
  47.                     "comment" : "Very good",
  48.                     "user" : "Dave"
  49.                   },
  50.                   "sort" : [
  51.                     5
  52.                   ]
  53.                 },
  54.                 {
  55.                   "_index" : "products",
  56.                   "_id" : "2",
  57.                   "_nested" : {
  58.                     "field" : "reviews",
  59.                     "offset" : 1
  60.                   },
  61.                   "_score" : null,
  62.                   "_source" : {
  63.                     "rating" : 4,
  64.                     "comment" : "Good value",
  65.                     "user" : "Eve"
  66.                   },
  67.                   "sort" : [
  68.                     4
  69.                   ]
  70.                 }
  71.               ]
  72.             }
  73.           }
  74.         }
  75.       }
  76.     ]
  77.   }
  78. }

Example: inner_hits parameters with a parent-join relationship

  1. Create an index with the following mappings:

    1.  PUT /company
    2.  {
    3.    "mappings": {
    4.      "properties": {
    5.        "my_join_field": {
    6.          "type": "join",
    7.          "relations": {
    8.            "employee": "task"
    9.          }
    10.        },
    11.        "name": { "type": "text" },
    12.        "description": {
    13.          "type": "text",
    14.          "fields": {
    15.            "keyword": { "type": "keyword" }
    16.          }
    17.        }
    18.      }
    19.    }
    20.  }

    copy

  2. Index data:

    1.  # Index a parent document
    2.  PUT /company/_doc/1
    3.  {
    4.    "name": "Alice",
    5.    "my_join_field": "employee"
    6.  }

    copy

    1.  # Index child documents
    2.  PUT /company/_doc/2?routing=1
    3.  {
    4.    "description": "Complete the project",
    5.    "my_join_field": {
    6.      "name": "task",
    7.      "parent": "1"
    8.    }
    9.  }

    copy

    1.  PUT /company/_doc/3?routing=1
    2.  {
    3.    "description": "Prepare the report",
    4.    "my_join_field": {
    5.      "name": "task",
    6.      "parent": "1"
    7.    }
    8.  }

    copy

    1.  PUT /company/_doc/4?routing=1
    2.  {
    3.    "description": "Update project",
    4.    "my_join_field": {
    5.      "name": "task",
    6.      "parent": "1"
    7.    }
    8.  }

    copy

  3. Query with inner_hits parameters:

    1.  GET /company/_search
    2.  {
    3.    "query": {
    4.      "has_child": {
    5.        "type": "task",
    6.        "query": {
    7.          "match": { "description": "project" }
    8.        },
    9.        "inner_hits": {
    10.          "from": 0,
    11.          "size": 10,
    12.          "sort": [
    13.            { "description.keyword": { "order": "asc" } }
    14.          ],
    15.          "name": "related_tasks"
    16.        }
    17.      }
    18.    }
    19.  }

    copy

The following is the expected result:

  1. {
  2.   "hits" : {
  3.     "total" : {
  4.       "value" : 1,
  5.       "relation" : "eq"
  6.     },
  7.     "max_score" : 1.0,
  8.     "hits": [
  9.       {
  10.         "_index": "company",
  11.         "_id": "1",
  12.         "_score": 1,
  13.         "_source": {
  14.           "name": "Alice",
  15.           "my_join_field": "employee"
  16.         },
  17.         "inner_hits": {
  18.           "related_tasks": {
  19.             "hits": {
  20.               "total": {
  21.                 "value": 2,
  22.                 "relation": "eq"
  23.               },
  24.               "max_score": null,
  25.               "hits": [
  26.                 {
  27.                   "_index": "company",
  28.                   "_id": "2",
  29.                   "_score": null,
  30.                   "_routing": "1",
  31.                   "_source": {
  32.                     "description": "Complete the project",
  33.                     "my_join_field": {
  34.                       "name": "task",
  35.                       "parent": "1"
  36.                     }
  37.                   },
  38.                   "sort": [
  39.                     "Complete the project"
  40.                   ]
  41.                 },
  42.                 {
  43.                   "_index": "company",
  44.                   "_id": "4",
  45.                   "_score": null,
  46.                   "_routing": "1",
  47.                   "_source": {
  48.                     "description": "Update project",
  49.                     "my_join_field": {
  50.                       "name": "task",
  51.                       "parent": "1"
  52.                     }
  53.                   },
  54.                   "sort": [
  55.                     "Update project"
  56.                   ]
  57.                 }
  58.               ]
  59.             }
  60.           }
  61.         }
  62.       }
  63.     ]
  64.   }
  65. }

Benefits of using inner_hits

  • Detailed query results

    You can use inner_hits to retrieve detailed information about matching nested or child documents directly from the parent document’s search results. This is particularly useful for understanding the context and specifics of the match without having to perform additional queries.

    Example use case: In a blog post index, you have comments as nested objects. When searching for blog posts containing specific comments, you can retrieve relevant comments that match the search criteria along with information about the post.

  • Optimized performance

    Without inner_hits, you may need to run multiple queries to fetch related documents. Using inner_hits consolidates these into a single query, reducing the number of round trips to the OpenSearch server and improving overall performance.

    Example use case: In an e-commerce application, you have products as parent documents and reviews as child documents. A single query using inner_hits can fetch products and their relevant reviews, avoiding multiple separate queries.

  • Simplified query logic

    You can combine parent/child or nested document logic in a single query to simplify the application code and reduce complexity. This helps to ensure that the code is more maintainable and consistent by centralizing the query logic in OpenSearch

    Example use case: In a job portal, you have jobs as parent documents and applications as nested or child documents. You can simplify the application logic by fetching jobs along with specific applications in one query.

  • Contextual relevance

    Using inner_hits provides contextual relevance by showing exactly which nested or child documents match the query criteria. This is crucial for applications in which the relevance of results depends on a specific part of the document that matches the query.

    Example use case: In a customer support system, you have tickets as parent documents and comments or updates as nested or child documents. You can determine which specific comment matches the search in order to better understand the context of the ticket search.

Next steps