Retrievers examples
- Retrievers examples

Retrievers examples

Add example data

To begin with, lets create the retrievers_example index, and add some documents to it.

resp = client.indices.create(
    index="retrievers_example",
    mappings={
        "properties": {
            "vector": {
                "type": "dense_vector",
                "dims": 3,
                "similarity": "l2_norm",
                "index": True
            },
            "text": {
                "type": "text"
            },
            "year": {
                "type": "integer"
            },
            "topic": {
                "type": "keyword"
            }
        }
    },
)
print(resp)
resp1 = client.index(
    index="retrievers_example",
    id="1",
    document={
        "vector": [
            0.23,
            0.67,
            0.89
        ],
        "text": "Large language models are revolutionizing information retrieval by boosting search precision, deepening contextual understanding, and reshaping user experiences in data-rich environments.",
        "year": 2024,
        "topic": [
            "llm",
            "ai",
            "information_retrieval"
        ]
    },
)
print(resp1)
resp2 = client.index(
    index="retrievers_example",
    id="2",
    document={
        "vector": [
            0.12,
            0.56,
            0.78
        ],
        "text": "Artificial intelligence is transforming medicine, from advancing diagnostics and tailoring treatment plans to empowering predictive patient care for improved health outcomes.",
        "year": 2023,
        "topic": [
            "ai",
            "medicine"
        ]
    },
)
print(resp2)
resp3 = client.index(
    index="retrievers_example",
    id="3",
    document={
        "vector": [
            0.45,
            0.32,
            0.91
        ],
        "text": "AI is redefining security by enabling advanced threat detection, proactive risk analysis, and dynamic defenses against increasingly sophisticated cyber threats.",
        "year": 2024,
        "topic": [
            "ai",
            "security"
        ]
    },
)
print(resp3)
resp4 = client.index(
    index="retrievers_example",
    id="4",
    document={
        "vector": [
            0.34,
            0.21,
            0.98
        ],
        "text": "Elastic introduces Elastic AI Assistant, the open, generative AI sidekick powered by ESRE to democratize cybersecurity and enable users of every skill level.",
        "year": 2023,
        "topic": [
            "ai",
            "elastic",
            "assistant"
        ]
    },
)
print(resp4)
resp5 = client.index(
    index="retrievers_example",
    id="5",
    document={
        "vector": [
            0.11,
            0.65,
            0.47
        ],
        "text": "Learn how to spin up a deployment of our hosted Elasticsearch Service and use Elastic Observability to gain deeper insight into the behavior of your applications and systems.",
        "year": 2024,
        "topic": [
            "documentation",
            "observability",
            "elastic"
        ]
    },
)
print(resp5)
resp6 = client.indices.refresh(
    index="retrievers_example",
)
print(resp6)

const response = await client.indices.create({
  index: "retrievers_example",
  mappings: {
    properties: {
      vector: {
        type: "dense_vector",
        dims: 3,
        similarity: "l2_norm",
        index: true,
      },
      text: {
        type: "text",
      },
      year: {
        type: "integer",
      },
      topic: {
        type: "keyword",
      },
    },
  },
});
console.log(response);
const response1 = await client.index({
  index: "retrievers_example",
  id: 1,
  document: {
    vector: [0.23, 0.67, 0.89],
    text: "Large language models are revolutionizing information retrieval by boosting search precision, deepening contextual understanding, and reshaping user experiences in data-rich environments.",
    year: 2024,
    topic: ["llm", "ai", "information_retrieval"],
  },
});
console.log(response1);
const response2 = await client.index({
  index: "retrievers_example",
  id: 2,
  document: {
    vector: [0.12, 0.56, 0.78],
    text: "Artificial intelligence is transforming medicine, from advancing diagnostics and tailoring treatment plans to empowering predictive patient care for improved health outcomes.",
    year: 2023,
    topic: ["ai", "medicine"],
  },
});
console.log(response2);
const response3 = await client.index({
  index: "retrievers_example",
  id: 3,
  document: {
    vector: [0.45, 0.32, 0.91],
    text: "AI is redefining security by enabling advanced threat detection, proactive risk analysis, and dynamic defenses against increasingly sophisticated cyber threats.",
    year: 2024,
    topic: ["ai", "security"],
  },
});
console.log(response3);
const response4 = await client.index({
  index: "retrievers_example",
  id: 4,
  document: {
    vector: [0.34, 0.21, 0.98],
    text: "Elastic introduces Elastic AI Assistant, the open, generative AI sidekick powered by ESRE to democratize cybersecurity and enable users of every skill level.",
    year: 2023,
    topic: ["ai", "elastic", "assistant"],
  },
});
console.log(response4);
const response5 = await client.index({
  index: "retrievers_example",
  id: 5,
  document: {
    vector: [0.11, 0.65, 0.47],
    text: "Learn how to spin up a deployment of our hosted Elasticsearch Service and use Elastic Observability to gain deeper insight into the behavior of your applications and systems.",
    year: 2024,
    topic: ["documentation", "observability", "elastic"],
  },
});
console.log(response5);
const response6 = await client.indices.refresh({
  index: "retrievers_example",
});
console.log(response6);

PUT retrievers_example
{
   "mappings": {
       "properties": {
           "vector": {
               "type": "dense_vector",
               "dims": 3,
               "similarity": "l2_norm",
               "index": true
           },
           "text": {
               "type": "text"
           },
           "year": {
               "type": "integer"
           },
           "topic": {
               "type": "keyword"
           }
       }
   }
}
POST /retrievers_example/_doc/1
{
 "vector": [0.23, 0.67, 0.89],
 "text": "Large language models are revolutionizing information retrieval by boosting search precision, deepening contextual understanding, and reshaping user experiences in data-rich environments.",
 "year": 2024,
 "topic": ["llm", "ai", "information_retrieval"]
}
POST /retrievers_example/_doc/2
{
 "vector": [0.12, 0.56, 0.78],
 "text": "Artificial intelligence is transforming medicine, from advancing diagnostics and tailoring treatment plans to empowering predictive patient care for improved health outcomes.",
 "year": 2023,
 "topic": ["ai", "medicine"]
}
POST /retrievers_example/_doc/3
{
 "vector": [0.45, 0.32, 0.91],
  "text": "AI is redefining security by enabling advanced threat detection, proactive risk analysis, and dynamic defenses against increasingly sophisticated cyber threats.",
 "year": 2024,
 "topic": ["ai", "security"]
}
POST /retrievers_example/_doc/4
{
 "vector": [0.34, 0.21, 0.98],
 "text": "Elastic introduces Elastic AI Assistant, the open, generative AI sidekick powered by ESRE to democratize cybersecurity and enable users of every skill level.",
 "year": 2023,
 "topic": ["ai", "elastic", "assistant"]
}
POST /retrievers_example/_doc/5
{
 "vector": [0.11, 0.65, 0.47],
 "text": "Learn how to spin up a deployment of our hosted Elasticsearch Service and use Elastic Observability to gain deeper insight into the behavior of your applications and systems.",
 "year": 2024,
 "topic": ["documentation", "observability", "elastic"]
}
POST /retrievers_example/_refresh

Now that we have our documents in place, let’s try to run some queries using retrievers.

Example: Combining query and kNN with RRF

First, let’s examine how to combine two different types of queries: a kNN query and a query_string query. While these queries may produce scores in different ranges, we can use Reciprocal Rank Fusion (rrf) to combine the results and generate a merged final result list.

To implement this in the retriever framework, we start with the top-level element: our rrf retriever. This retriever operates on top of two other retrievers: a knn retriever and a standard retriever. Our query structure would look like this:

resp = client.search(
    index="retrievers_example",
    retriever={
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "query_string": {
                                "query": "(information retrieval) OR (artificial intelligence)",
                                "default_field": "text"
                            }
                        }
                    }
                },
                {
                    "knn": {
                        "field": "vector",
                        "query_vector": [
                            0.23,
                            0.67,
                            0.89
                        ],
                        "k": 3,
                        "num_candidates": 5
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    source=False,
)
print(resp)

const response = await client.search({
  index: "retrievers_example",
  retriever: {
    rrf: {
      retrievers: [
        {
          standard: {
            query: {
              query_string: {
                query: "(information retrieval) OR (artificial intelligence)",
                default_field: "text",
              },
            },
          },
        },
        {
          knn: {
            field: "vector",
            query_vector: [0.23, 0.67, 0.89],
            k: 3,
            num_candidates: 5,
          },
        },
      ],
      rank_window_size: 10,
      rank_constant: 1,
    },
  },
  _source: false,
});
console.log(response);

GET /retrievers_example/_search
{
    "retriever": {
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "query_string": {
                                "query": "(information retrieval) OR (artificial intelligence)",
                                "default_field": "text"
                            }
                        }
                    }
                },
                {
                    "knn": {
                        "field": "vector",
                        "query_vector": [
                            0.23,
                            0.67,
                            0.89
                        ],
                        "k": 3,
                        "num_candidates": 5
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    "_source": false
}

This returns the following response based on the final rrf score for each result.

Example response

{
    "took": 42,
    "timed_out": false,
    "_shards": {
        "total": 1,
        "successful": 1,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 3,
            "relation": "eq"
        },
        "max_score": 0.8333334,
        "hits": [
            {
                "_index": "retrievers_example",
                "_id": "1",
                "_score": 0.8333334
            },
            {
                "_index": "retrievers_example",
                "_id": "2",
                "_score": 0.8333334
            },
            {
                "_index": "retrievers_example",
                "_id": "3",
                "_score": 0.25
            }
        ]
    }
}

Example: Grouping results by year with `collapse`

In our result set, we have many documents with the same year value. We can clean this up using the collapse parameter with our retriever. This, as with the standard collapse feature, enables grouping results by any field and returns only the highest-scoring document from each group. In this example we’ll collapse our results based on the year field.

resp = client.search(
    index="retrievers_example",
    retriever={
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "query_string": {
                                "query": "(information retrieval) OR (artificial intelligence)",
                                "default_field": "text"
                            }
                        }
                    }
                },
                {
                    "knn": {
                        "field": "vector",
                        "query_vector": [
                            0.23,
                            0.67,
                            0.89
                        ],
                        "k": 3,
                        "num_candidates": 5
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    collapse={
        "field": "year",
        "inner_hits": {
            "name": "topic related documents",
            "_source": [
                "year"
            ]
        }
    },
    source=False,
)
print(resp)

const response = await client.search({
  index: "retrievers_example",
  retriever: {
    rrf: {
      retrievers: [
        {
          standard: {
            query: {
              query_string: {
                query: "(information retrieval) OR (artificial intelligence)",
                default_field: "text",
              },
            },
          },
        },
        {
          knn: {
            field: "vector",
            query_vector: [0.23, 0.67, 0.89],
            k: 3,
            num_candidates: 5,
          },
        },
      ],
      rank_window_size: 10,
      rank_constant: 1,
    },
  },
  collapse: {
    field: "year",
    inner_hits: {
      name: "topic related documents",
      _source: ["year"],
    },
  },
  _source: false,
});
console.log(response);

GET /retrievers_example/_search
{
    "retriever": {
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "query_string": {
                                "query": "(information retrieval) OR (artificial intelligence)",
                                "default_field": "text"
                            }
                        }
                    }
                },
                {
                    "knn": {
                        "field": "vector",
                        "query_vector": [
                            0.23,
                            0.67,
                            0.89
                        ],
                        "k": 3,
                        "num_candidates": 5
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    "collapse": {
        "field": "year",
        "inner_hits": {
            "name": "topic related documents",
            "_source": [
                "year"
            ]
        }
    },
    "_source": false
}

This returns the following response with collapsed results.

Example response

{
    "took": 42,
    "timed_out": false,
    "_shards": {
        "total": 1,
        "successful": 1,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 3,
            "relation": "eq"
        },
        "max_score": 0.8333334,
        "hits": [
            {
                "_index": "retrievers_example",
                "_id": "1",
                "_score": 0.8333334,
                "fields": {
                    "year": [
                        2024
                    ]
                },
                "inner_hits": {
                    "topic related documents": {
                        "hits": {
                            "total": {
                                "value": 2,
                                "relation": "eq"
                            },
                            "max_score": 0.8333334,
                            "hits": [
                                {
                                    "_index": "retrievers_example",
                                    "_id": "1",
                                    "_score": 0.8333334,
                                    "_source": {
                                        "year": 2024
                                    }
                                },
                                {
                                    "_index": "retrievers_example",
                                    "_id": "3",
                                    "_score": 0.25,
                                    "_source": {
                                        "year": 2024
                                    }
                                }
                            ]
                        }
                    }
                }
            },
            {
                "_index": "retrievers_example",
                "_id": "2",
                "_score": 0.8333334,
                "fields": {
                    "year": [
                        2023
                    ]
                },
                "inner_hits": {
                    "topic related documents": {
                        "hits": {
                            "total": {
                                "value": 1,
                                "relation": "eq"
                            },
                            "max_score": 0.8333334,
                            "hits": [
                                {
                                    "_index": "retrievers_example",
                                    "_id": "2",
                                    "_score": 0.8333334,
                                    "_source": {
                                        "year": 2023
                                    }
                                }
                            ]
                        }
                    }
                }
            }
        ]
    }
}

Example: Highlighting results based on nested sub-retrievers

Highlighting is now also available for nested sub-retrievers matches. For example, consider the same rrf retriever as above, with a knn and standard retriever as its sub-retrievers. We can specify a highlight section, as defined in highlighting documentation, and compute highlights for the top results.

resp = client.search(
    index="retrievers_example",
    retriever={
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "query_string": {
                                "query": "(information retrieval) OR (artificial intelligence)",
                                "default_field": "text"
                            }
                        }
                    }
                },
                {
                    "knn": {
                        "field": "vector",
                        "query_vector": [
                            0.23,
                            0.67,
                            0.89
                        ],
                        "k": 3,
                        "num_candidates": 5
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    highlight={
        "fields": {
            "text": {
                "fragment_size": 150,
                "number_of_fragments": 3
            }
        }
    },
    source=False,
)
print(resp)

const response = await client.search({
  index: "retrievers_example",
  retriever: {
    rrf: {
      retrievers: [
        {
          standard: {
            query: {
              query_string: {
                query: "(information retrieval) OR (artificial intelligence)",
                default_field: "text",
              },
            },
          },
        },
        {
          knn: {
            field: "vector",
            query_vector: [0.23, 0.67, 0.89],
            k: 3,
            num_candidates: 5,
          },
        },
      ],
      rank_window_size: 10,
      rank_constant: 1,
    },
  },
  highlight: {
    fields: {
      text: {
        fragment_size: 150,
        number_of_fragments: 3,
      },
    },
  },
  _source: false,
});
console.log(response);

GET /retrievers_example/_search
{
    "retriever": {
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "query_string": {
                                "query": "(information retrieval) OR (artificial intelligence)",
                                "default_field": "text"
                            }
                        }
                    }
                },
                {
                    "knn": {
                        "field": "vector",
                        "query_vector": [
                            0.23,
                            0.67,
                            0.89
                        ],
                        "k": 3,
                        "num_candidates": 5
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    "highlight": {
        "fields": {
            "text": {
                "fragment_size": 150,
                "number_of_fragments": 3
            }
        }
    },
    "_source": false
}

This would highlight the text field, based on the matches produced by the standard retriever. The highlighted snippets would then be included in the response as usual, i.e. under each search hit.

Example response

{
    "took": 42,
    "timed_out": false,
    "_shards": {
        "total": 1,
        "successful": 1,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 3,
            "relation": "eq"
        },
        "max_score": 0.8333334,
        "hits": [
            {
                "_index": "retrievers_example",
                "_id": "1",
                "_score": 0.8333334,
                "highlight": {
                    "text": [
                        "Large language models are revolutionizing <em>information</em> <em>retrieval</em> by boosting search precision, deepening contextual understanding, and reshaping user experiences"
                    ]
                }
            },
            {
                "_index": "retrievers_example",
                "_id": "2",
                "_score": 0.8333334,
                "highlight": {
                    "text": [
                        "<em>Artificial</em> <em>intelligence</em> is transforming medicine, from advancing diagnostics and tailoring treatment plans to empowering predictive patient care for improved"
                    ]
                }
            },
            {
                "_index": "retrievers_example",
                "_id": "3",
                "_score": 0.25
            }
        ]
    }
}

Example: Computing inner hits from nested sub-retrievers

We can also define inner_hits to be computed on any of the sub-retrievers, and propagate those computations to the top level compound retriever. For example, let’s create a new index with a knn field, nested under the nested_field field, and index a couple of documents.

resp = client.indices.create(
    index="retrievers_example_nested",
    mappings={
        "properties": {
            "nested_field": {
                "type": "nested",
                "properties": {
                    "paragraph_id": {
                        "type": "keyword"
                    },
                    "nested_vector": {
                        "type": "dense_vector",
                        "dims": 3,
                        "similarity": "l2_norm",
                        "index": True
                    }
                }
            },
            "topic": {
                "type": "keyword"
            }
        }
    },
)
print(resp)
resp1 = client.index(
    index="retrievers_example_nested",
    id="1",
    document={
        "nested_field": [
            {
                "paragraph_id": "1a",
                "nested_vector": [
                    -1.12,
                    -0.59,
                    0.78
                ]
            },
            {
                "paragraph_id": "1b",
                "nested_vector": [
                    -0.12,
                    1.56,
                    0.42
                ]
            },
            {
                "paragraph_id": "1c",
                "nested_vector": [
                    1,
                    -1,
                    0
                ]
            }
        ],
        "topic": [
            "ai"
        ]
    },
)
print(resp1)
resp2 = client.index(
    index="retrievers_example_nested",
    id="2",
    document={
        "nested_field": [
            {
                "paragraph_id": "2a",
                "nested_vector": [
                    0.23,
                    1.24,
                    0.65
                ]
            }
        ],
        "topic": [
            "information_retrieval"
        ]
    },
)
print(resp2)
resp3 = client.index(
    index="retrievers_example_nested",
    id="3",
    document={
        "topic": [
            "ai"
        ]
    },
)
print(resp3)
resp4 = client.indices.refresh(
    index="retrievers_example_nested",
)
print(resp4)

const response = await client.indices.create({
  index: "retrievers_example_nested",
  mappings: {
    properties: {
      nested_field: {
        type: "nested",
        properties: {
          paragraph_id: {
            type: "keyword",
          },
          nested_vector: {
            type: "dense_vector",
            dims: 3,
            similarity: "l2_norm",
            index: true,
          },
        },
      },
      topic: {
        type: "keyword",
      },
    },
  },
});
console.log(response);
const response1 = await client.index({
  index: "retrievers_example_nested",
  id: 1,
  document: {
    nested_field: [
      {
        paragraph_id: "1a",
        nested_vector: [-1.12, -0.59, 0.78],
      },
      {
        paragraph_id: "1b",
        nested_vector: [-0.12, 1.56, 0.42],
      },
      {
        paragraph_id: "1c",
        nested_vector: [1, -1, 0],
      },
    ],
    topic: ["ai"],
  },
});
console.log(response1);
const response2 = await client.index({
  index: "retrievers_example_nested",
  id: 2,
  document: {
    nested_field: [
      {
        paragraph_id: "2a",
        nested_vector: [0.23, 1.24, 0.65],
      },
    ],
    topic: ["information_retrieval"],
  },
});
console.log(response2);
const response3 = await client.index({
  index: "retrievers_example_nested",
  id: 3,
  document: {
    topic: ["ai"],
  },
});
console.log(response3);
const response4 = await client.indices.refresh({
  index: "retrievers_example_nested",
});
console.log(response4);

PUT retrievers_example_nested
{
    "mappings": {
        "properties": {
            "nested_field": {
                "type": "nested",
                "properties": {
                    "paragraph_id": {
                        "type": "keyword"
                    },
                    "nested_vector": {
                        "type": "dense_vector",
                        "dims": 3,
                        "similarity": "l2_norm",
                        "index": true
                    }
                }
            },
            "topic": {
                "type": "keyword"
            }
        }
    }
}
POST /retrievers_example_nested/_doc/1
{
    "nested_field": [
        {
            "paragraph_id": "1a",
            "nested_vector": [
                -1.12,
                -0.59,
                0.78
            ]
        },
        {
            "paragraph_id": "1b",
            "nested_vector": [
                -0.12,
                1.56,
                0.42
            ]
        },
        {
            "paragraph_id": "1c",
            "nested_vector": [
                1,
                -1,
                0
            ]
        }
    ],
    "topic": [
        "ai"
    ]
}
POST /retrievers_example_nested/_doc/2
{
    "nested_field": [
        {
            "paragraph_id": "2a",
            "nested_vector": [
                0.23,
                1.24,
                0.65
            ]
        }
    ],
    "topic": [
        "information_retrieval"
    ]
}
POST /retrievers_example_nested/_doc/3
{
    "topic": [
        "ai"
    ]
}
POST /retrievers_example_nested/_refresh

Now we can run an rrf retriever query and also compute inner hits for the nested_field.nested_vector field, based on the knn query specified.

resp = client.search(
    index="retrievers_example_nested",
    retriever={
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "nested": {
                                "path": "nested_field",
                                "inner_hits": {
                                    "name": "nested_vector",
                                    "_source": False,
                                    "fields": [
                                        "nested_field.paragraph_id"
                                    ]
                                },
                                "query": {
                                    "knn": {
                                        "field": "nested_field.nested_vector",
                                        "query_vector": [
                                            1,
                                            0,
                                            0.5
                                        ],
                                        "k": 10
                                    }
                                }
                            }
                        }
                    }
                },
                {
                    "standard": {
                        "query": {
                            "term": {
                                "topic": "ai"
                            }
                        }
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    source=[
        "topic"
    ],
)
print(resp)

const response = await client.search({
  index: "retrievers_example_nested",
  retriever: {
    rrf: {
      retrievers: [
        {
          standard: {
            query: {
              nested: {
                path: "nested_field",
                inner_hits: {
                  name: "nested_vector",
                  _source: false,
                  fields: ["nested_field.paragraph_id"],
                },
                query: {
                  knn: {
                    field: "nested_field.nested_vector",
                    query_vector: [1, 0, 0.5],
                    k: 10,
                  },
                },
              },
            },
          },
        },
        {
          standard: {
            query: {
              term: {
                topic: "ai",
              },
            },
          },
        },
      ],
      rank_window_size: 10,
      rank_constant: 1,
    },
  },
  _source: ["topic"],
});
console.log(response);

GET /retrievers_example_nested/_search
{
    "retriever": {
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "nested": {
                                "path": "nested_field",
                                "inner_hits": {
                                    "name": "nested_vector",
                                    "_source": false,
                                    "fields": [
                                        "nested_field.paragraph_id"
                                    ]
                                },
                                "query": {
                                    "knn": {
                                        "field": "nested_field.nested_vector",
                                        "query_vector": [
                                            1,
                                            0,
                                            0.5
                                        ],
                                        "k": 10
                                    }
                                }
                            }
                        }
                    }
                },
                {
                    "standard": {
                        "query": {
                            "term": {
                                "topic": "ai"
                            }
                        }
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    "_source": [
        "topic"
    ]
}

This would propagate the inner_hits defined for the knn query to the rrf retriever, and compute inner hits for rrf‘s top results.

Example response

{
    "took": 42,
    "timed_out": false,
    "_shards": {
        "total": 1,
        "successful": 1,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 3,
            "relation": "eq"
        },
        "max_score": 1.0,
        "hits": [
            {
                "_index": "retrievers_example_nested",
                "_id": "1",
                "_score": 1.0,
                "_source": {
                    "topic": [
                        "ai"
                    ]
                },
                "inner_hits": {
                    "nested_vector": {
                        "hits": {
                            "total": {
                                "value": 3,
                                "relation": "eq"
                            },
                            "max_score": 0.44353113,
                            "hits": [
                                {
                                    "_index": "retrievers_example_nested",
                                    "_id": "1",
                                    "_nested": {
                                        "field": "nested_field",
                                        "offset": 2
                                    },
                                    "_score": 0.44353113,
                                    "fields": {
                                        "nested_field": [
                                            {
                                                "paragraph_id": [
                                                    "1c"
                                                ]
                                            }
                                        ]
                                    }
                                },
                                {
                                    "_index": "retrievers_example_nested",
                                    "_id": "1",
                                    "_nested": {
                                        "field": "nested_field",
                                        "offset": 1
                                    },
                                    "_score": 0.26567122,
                                    "fields": {
                                        "nested_field": [
                                            {
                                                "paragraph_id": [
                                                    "1b"
                                                ]
                                            }
                                        ]
                                    }
                                },
                                {
                                    "_index": "retrievers_example_nested",
                                    "_id": "1",
                                    "_nested": {
                                        "field": "nested_field",
                                        "offset": 0
                                    },
                                    "_score": 0.18478848,
                                    "fields": {
                                        "nested_field": [
                                            {
                                                "paragraph_id": [
                                                    "1a"
                                                ]
                                            }
                                        ]
                                    }
                                }
                            ]
                        }
                    }
                }
            },
            {
                "_index": "retrievers_example_nested",
                "_id": "2",
                "_score": 0.33333334,
                "_source": {
                    "topic": [
                        "information_retrieval"
                    ]
                },
                "inner_hits": {
                    "nested_vector": {
                        "hits": {
                            "total": {
                                "value": 1,
                                "relation": "eq"
                            },
                            "max_score": 0.32002488,
                            "hits": [
                                {
                                    "_index": "retrievers_example_nested",
                                    "_id": "2",
                                    "_nested": {
                                        "field": "nested_field",
                                        "offset": 0
                                    },
                                    "_score": 0.32002488,
                                    "fields": {
                                        "nested_field": [
                                            {
                                                "paragraph_id": [
                                                    "2a"
                                                ]
                                            }
                                        ]
                                    }
                                }
                            ]
                        }
                    }
                }
            },
            {
                "_index": "retrievers_example_nested",
                "_id": "3",
                "_score": 0.33333334,
                "_source": {
                    "topic": [
                        "ai"
                    ]
                },
                "inner_hits": {
                    "nested_vector": {
                        "hits": {
                            "total": {
                                "value": 0,
                                "relation": "eq"
                            },
                            "max_score": null,
                            "hits": []
                        }
                    }
                }
            }
        ]
    }
}

Note: if using more than one inner_hits we need to provide custom names for each inner_hits so that they are unique across all retrievers within the request.

Example: Combine RRF with aggregations

Retrievers support both composability and most of the standard _search functionality. For instance, we can compute aggregations with the rrf retriever. When using a compound retriever, the aggregations are computed based on its nested retrievers. In the following example, the terms aggregation for the topic field will include all results, not just the top rank_window_size, from the 2 nested retrievers, i.e. all documents whose year field is greater than 2023, and whose topic field matches the term elastic.

resp = client.search(
    index="retrievers_example",
    retriever={
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "range": {
                                "year": {
                                    "gt": 2023
                                }
                            }
                        }
                    }
                },
                {
                    "standard": {
                        "query": {
                            "term": {
                                "topic": "elastic"
                            }
                        }
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    source=False,
    aggs={
        "topics": {
            "terms": {
                "field": "topic"
            }
        }
    },
)
print(resp)

const response = await client.search({
  index: "retrievers_example",
  retriever: {
    rrf: {
      retrievers: [
        {
          standard: {
            query: {
              range: {
                year: {
                  gt: 2023,
                },
              },
            },
          },
        },
        {
          standard: {
            query: {
              term: {
                topic: "elastic",
              },
            },
          },
        },
      ],
      rank_window_size: 10,
      rank_constant: 1,
    },
  },
  _source: false,
  aggs: {
    topics: {
      terms: {
        field: "topic",
      },
    },
  },
});
console.log(response);

GET retrievers_example/_search
{
    "retriever": {
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "range": {
                                "year": {
                                    "gt": 2023
                                }
                            }
                        }
                    }
                },
                {
                    "standard": {
                        "query": {
                            "term": {
                                "topic": "elastic"
                            }
                        }
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    "_source": false,
    "aggs": {
        "topics": {
            "terms": {
                "field": "topic"
            }
        }
    }
}

Example response

{
    "took": 42,
    "timed_out": false,
    "_shards": {
        "total": 1,
        "successful": 1,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 4,
            "relation": "eq"
        },
        "max_score": 0.5833334,
        "hits": [
            {
                "_index": "retrievers_example",
                "_id": "5",
                "_score": 0.5833334
            },
            {
                "_index": "retrievers_example",
                "_id": "1",
                "_score": 0.5
            },
            {
                "_index": "retrievers_example",
                "_id": "4",
                "_score": 0.5
            },
            {
                "_index": "retrievers_example",
                "_id": "3",
                "_score": 0.33333334
            }
        ]
    },
    "aggregations": {
        "topics": {
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0,
            "buckets": [
                {
                    "key": "ai",
                    "doc_count": 3
                },
                {
                    "key": "elastic",
                    "doc_count": 2
                },
                {
                    "key": "assistant",
                    "doc_count": 1
                },
                {
                    "key": "documentation",
                    "doc_count": 1
                },
                {
                    "key": "information_retrieval",
                    "doc_count": 1
                },
                {
                    "key": "llm",
                    "doc_count": 1
                },
                {
                    "key": "observability",
                    "doc_count": 1
                },
                {
                    "key": "security",
                    "doc_count": 1
                }
            ]
        }
    }
}

Example: Explainability with multiple retrievers

By adding explain: true to the request, each retriever will now provide a detailed explanation of all the steps and calculations required to compute the final score. Composability is fully supported in the context of explain, and each retriever will provide its own explanation, as shown in the example below.

resp = client.search(
    index="retrievers_example",
    retriever={
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "term": {
                                "topic": "elastic"
                            }
                        }
                    }
                },
                {
                    "rrf": {
                        "retrievers": [
                            {
                                "standard": {
                                    "query": {
                                        "query_string": {
                                            "query": "(information retrieval) OR (artificial intelligence)",
                                            "default_field": "text"
                                        }
                                    }
                                }
                            },
                            {
                                "knn": {
                                    "field": "vector",
                                    "query_vector": [
                                        0.23,
                                        0.67,
                                        0.89
                                    ],
                                    "k": 3,
                                    "num_candidates": 5
                                }
                            }
                        ],
                        "rank_window_size": 10,
                        "rank_constant": 1
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    source=False,
    size=1,
    explain=True,
)
print(resp)

const response = await client.search({
  index: "retrievers_example",
  retriever: {
    rrf: {
      retrievers: [
        {
          standard: {
            query: {
              term: {
                topic: "elastic",
              },
            },
          },
        },
        {
          rrf: {
            retrievers: [
              {
                standard: {
                  query: {
                    query_string: {
                      query:
                        "(information retrieval) OR (artificial intelligence)",
                      default_field: "text",
                    },
                  },
                },
              },
              {
                knn: {
                  field: "vector",
                  query_vector: [0.23, 0.67, 0.89],
                  k: 3,
                  num_candidates: 5,
                },
              },
            ],
            rank_window_size: 10,
            rank_constant: 1,
          },
        },
      ],
      rank_window_size: 10,
      rank_constant: 1,
    },
  },
  _source: false,
  size: 1,
  explain: true,
});
console.log(response);

GET /retrievers_example/_search
{
    "retriever": {
        "rrf": {
            "retrievers": [
                {
                    "standard": {
                        "query": {
                            "term": {
                                "topic": "elastic"
                            }
                        }
                    }
                },
                {
                    "rrf": {
                        "retrievers": [
                            {
                                "standard": {
                                    "query": {
                                        "query_string": {
                                            "query": "(information retrieval) OR (artificial intelligence)",
                                            "default_field": "text"
                                        }
                                    }
                                }
                            },
                            {
                                "knn": {
                                    "field": "vector",
                                    "query_vector": [
                                        0.23,
                                        0.67,
                                        0.89
                                    ],
                                    "k": 3,
                                    "num_candidates": 5
                                }
                            }
                        ],
                        "rank_window_size": 10,
                        "rank_constant": 1
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    "_source": false,
    "size": 1,
    "explain": true
}

The output of which, albeit a bit verbose, will provide all the necessary info to assist in debugging and reason with ranking.

Example response

{
    "took": 42,
    "timed_out": false,
    "_shards": {
        "total": 1,
        "successful": 1,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 5,
            "relation": "eq"
        },
        "max_score": 0.5,
        "hits": [
            {
                "_shard": "[retrievers_example][0]",
                "_node": "jnrdZFKS3abUgWVsVdj2Vg",
                "_index": "retrievers_example",
                "_id": "1",
                "_score": 0.5,
                "_explanation": {
                    "value": 0.5,
                    "description": "rrf score: [0.5] computed for initial ranks [0, 1] with rankConstant: [1] as sum of [1 / (rank + rankConstant)] for each query",
                    "details": [
                        {
                            "value": 0.0,
                            "description": "rrf score: [0], result not found in query at index [0]",
                            "details": []
                        },
                        {
                            "value": 1,
                            "description": "rrf score: [0.5], for rank [1] in query at index [1] computed as [1 / (1 + 1)], for matching query with score",
                            "details": [
                                {
                                    "value": 0.8333334,
                                    "description": "rrf score: [0.8333334] computed for initial ranks [2, 1] with rankConstant: [1] as sum of [1 / (rank + rankConstant)] for each query",
                                    "details": [
                                        {
                                            "value": 2,
                                            "description": "rrf score: [0.33333334], for rank [2] in query at index [0] computed as [1 / (2 + 1)], for matching query with score",
                                            "details": [
                                                {
                                                    "value": 2.8129659,
                                                    "description": "sum of:",
                                                    "details": [
                                                        {
                                                            "value": 1.4064829,
                                                            "description": "weight(text:information in 0) [PerFieldSimilarity], result of:",
                                                            "details": [
                                                                ***
                                                            ]
                                                        },
                                                        {
                                                            "value": 1.4064829,
                                                            "description": "weight(text:retrieval in 0) [PerFieldSimilarity], result of:",
                                                            "details": [
                                                                ***
                                                            ]
                                                        }
                                                    ]
                                                }
                                            ]
                                        },
                                        {
                                            "value": 1,
                                            "description": "rrf score: [0.5], for rank [1] in query at index [1] computed as [1 / (1 + 1)], for matching query with score",
                                            "details": [
                                                {
                                                    "value": 1,
                                                    "description": "doc [0] with an original score of [1.0] is at rank [1] from the following source queries.",
                                                    "details": [
                                                        {
                                                            "value": 1.0,
                                                            "description": "found vector with calculated similarity: 1.0",
                                                            "details": []
                                                        }
                                                    ]
                                                }
                                            ]
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Example: Rerank results of an RRF retriever

To demonstrate the full functionality of retrievers, the following examples also require access to a semantic reranking model set up using the Elastic inference APIs.

In this example we’ll set up a reranking service and use it with the text_similarity_reranker retriever to rerank our top results.

resp = client.inference.put(
    task_type="rerank",
    inference_id="my-rerank-model",
    inference_config={
        "service": "cohere",
        "service_settings": {
            "model_id": "rerank-english-v3.0",
            "api_key": "{{COHERE_API_KEY}}"
        }
    },
)
print(resp)

const response = await client.inference.put({
  task_type: "rerank",
  inference_id: "my-rerank-model",
  inference_config: {
    service: "cohere",
    service_settings: {
      model_id: "rerank-english-v3.0",
      api_key: "{{COHERE_API_KEY}}",
    },
  },
});
console.log(response);

PUT _inference/rerank/my-rerank-model
{
 "service": "cohere",
 "service_settings": {
   "model_id": "rerank-english-v3.0",
   "api_key": "{{COHERE_API_KEY}}"
 }
}

Let’s start by reranking the results of the rrf retriever in our previous example.

resp = client.search(
    index="retrievers_example",
    retriever={
        "text_similarity_reranker": {
            "retriever": {
                "rrf": {
                    "retrievers": [
                        {
                            "standard": {
                                "query": {
                                    "query_string": {
                                        "query": "(information retrieval) OR (artificial intelligence)",
                                        "default_field": "text"
                                    }
                                }
                            }
                        },
                        {
                            "knn": {
                                "field": "vector",
                                "query_vector": [
                                    0.23,
                                    0.67,
                                    0.89
                                ],
                                "k": 3,
                                "num_candidates": 5
                            }
                        }
                    ],
                    "rank_window_size": 10,
                    "rank_constant": 1
                }
            },
            "field": "text",
            "inference_id": "my-rerank-model",
            "inference_text": "What are the state of the art applications of AI in information retrieval?"
        }
    },
    source=False,
)
print(resp)

const response = await client.search({
  index: "retrievers_example",
  retriever: {
    text_similarity_reranker: {
      retriever: {
        rrf: {
          retrievers: [
            {
              standard: {
                query: {
                  query_string: {
                    query:
                      "(information retrieval) OR (artificial intelligence)",
                    default_field: "text",
                  },
                },
              },
            },
            {
              knn: {
                field: "vector",
                query_vector: [0.23, 0.67, 0.89],
                k: 3,
                num_candidates: 5,
              },
            },
          ],
          rank_window_size: 10,
          rank_constant: 1,
        },
      },
      field: "text",
      inference_id: "my-rerank-model",
      inference_text:
        "What are the state of the art applications of AI in information retrieval?",
    },
  },
  _source: false,
});
console.log(response);

GET retrievers_example/_search
{
    "retriever": {
        "text_similarity_reranker": {
            "retriever": {
                "rrf": {
                    "retrievers": [
                        {
                            "standard": {
                                "query": {
                                    "query_string": {
                                        "query": "(information retrieval) OR (artificial intelligence)",
                                        "default_field": "text"
                                    }
                                }
                            }
                        },
                        {
                            "knn": {
                                "field": "vector",
                                "query_vector": [
                                    0.23,
                                    0.67,
                                    0.89
                                ],
                                "k": 3,
                                "num_candidates": 5
                            }
                        }
                    ],
                    "rank_window_size": 10,
                    "rank_constant": 1
                }
            },
            "field": "text",
            "inference_id": "my-rerank-model",
            "inference_text": "What are the state of the art applications of AI in information retrieval?"
        }
    },
    "_source": false
}

Example: RRF with semantic reranker

For this example, we’ll replace the rrf’s standard retriever with the text_similarity_reranker retriever, using the my-rerank-model reranker we previously configured. Since this is a reranker, it needs an initial pool of documents to work with. In this case, we’ll rerank the top rank_window_size documents matching the ai topic.

resp = client.search(
    index="retrievers_example",
    retriever={
        "rrf": {
            "retrievers": [
                {
                    "knn": {
                        "field": "vector",
                        "query_vector": [
                            0.23,
                            0.67,
                            0.89
                        ],
                        "k": 3,
                        "num_candidates": 5
                    }
                },
                {
                    "text_similarity_reranker": {
                        "retriever": {
                            "standard": {
                                "query": {
                                    "term": {
                                        "topic": "ai"
                                    }
                                }
                            }
                        },
                        "field": "text",
                        "inference_id": "my-rerank-model",
                        "inference_text": "Can I use generative AI to identify user intent and improve search relevance?"
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    source=False,
)
print(resp)

const response = await client.search({
  index: "retrievers_example",
  retriever: {
    rrf: {
      retrievers: [
        {
          knn: {
            field: "vector",
            query_vector: [0.23, 0.67, 0.89],
            k: 3,
            num_candidates: 5,
          },
        },
        {
          text_similarity_reranker: {
            retriever: {
              standard: {
                query: {
                  term: {
                    topic: "ai",
                  },
                },
              },
            },
            field: "text",
            inference_id: "my-rerank-model",
            inference_text:
              "Can I use generative AI to identify user intent and improve search relevance?",
          },
        },
      ],
      rank_window_size: 10,
      rank_constant: 1,
    },
  },
  _source: false,
});
console.log(response);

GET /retrievers_example/_search
{
    "retriever": {
        "rrf": {
            "retrievers": [
                {
                    "knn": {
                        "field": "vector",
                        "query_vector": [
                            0.23,
                            0.67,
                            0.89
                        ],
                        "k": 3,
                        "num_candidates": 5
                    }
                },
                {
                    "text_similarity_reranker": {
                        "retriever": {
                            "standard": {
                                "query": {
                                    "term": {
                                        "topic": "ai"
                                    }
                                }
                            }
                        },
                        "field": "text",
                        "inference_id": "my-rerank-model",
                        "inference_text": "Can I use generative AI to identify user intent and improve search relevance?"
                    }
                }
            ],
            "rank_window_size": 10,
            "rank_constant": 1
        }
    },
    "_source": false
}

Example: Chaining multiple semantic rerankers

Full composability means we can chain together multiple retrievers of the same type. For instance, imagine we have a computationally expensive reranker that’s specialized for AI content. We can rerank the results of a text_similarity_reranker using another text_similarity_reranker retriever. Each reranker can operate on different fields and/or use different inference services.

resp = client.search(
    index="retrievers_example",
    retriever={
        "text_similarity_reranker": {
            "retriever": {
                "text_similarity_reranker": {
                    "retriever": {
                        "knn": {
                            "field": "vector",
                            "query_vector": [
                                0.23,
                                0.67,
                                0.89
                            ],
                            "k": 3,
                            "num_candidates": 5
                        }
                    },
                    "rank_window_size": 100,
                    "field": "text",
                    "inference_id": "my-rerank-model",
                    "inference_text": "What are the state of the art applications of AI in information retrieval?"
                }
            },
            "rank_window_size": 10,
            "field": "text",
            "inference_id": "my-other-more-expensive-rerank-model",
            "inference_text": "Applications of Large Language Models in technology and their impact on user satisfaction"
        }
    },
    source=False,
)
print(resp)

const response = await client.search({
  index: "retrievers_example",
  retriever: {
    text_similarity_reranker: {
      retriever: {
        text_similarity_reranker: {
          retriever: {
            knn: {
              field: "vector",
              query_vector: [0.23, 0.67, 0.89],
              k: 3,
              num_candidates: 5,
            },
          },
          rank_window_size: 100,
          field: "text",
          inference_id: "my-rerank-model",
          inference_text:
            "What are the state of the art applications of AI in information retrieval?",
        },
      },
      rank_window_size: 10,
      field: "text",
      inference_id: "my-other-more-expensive-rerank-model",
      inference_text:
        "Applications of Large Language Models in technology and their impact on user satisfaction",
    },
  },
  _source: false,
});
console.log(response);

GET retrievers_example/_search
{
    "retriever": {
        "text_similarity_reranker": {
            "retriever": {
                "text_similarity_reranker": {
                    "retriever": {
                        "knn": {
                            "field": "vector",
                            "query_vector": [
                                0.23,
                                0.67,
                                0.89
                            ],
                            "k": 3,
                            "num_candidates": 5
                        }
                    },
                    "rank_window_size": 100,
                    "field": "text",
                    "inference_id": "my-rerank-model",
                    "inference_text": "What are the state of the art applications of AI in information retrieval?"
                }
            },
            "rank_window_size": 10,
            "field": "text",
            "inference_id": "my-other-more-expensive-rerank-model",
            "inference_text": "Applications of Large Language Models in technology and their impact on user satisfaction"
        }
    },
    "_source": false
}

Note that our example applies two reranking steps. First, we rerank the top 100 documents from the knn search using the my-rerank-model reranker. Then we pick the top 10 results and rerank them using the more fine-grained my-other-more-expensive-rerank-model.

Retrievers examples

Retrievers examples