Retrievals

Your documents in Ragie are queried via the Retrievals API. The parameters are described in detail in the API reference. It's important to note that Ragie searches for semantic similarity and the options to use will vary depending on your data and the queries you're making. We provide good general defaults for options, but it's important to test your specific use case and tune as needed. Some important options you may want to experiment with are:

• top_k: Determines how many chunks to return. When rerank is on, this is a ceiling and reranking may filter out some of the results. Setting a higher top_k increases the likelihood that your query will return a given result, but will also increase latency and LLM token usage.
• rerank: Filters the results to determine if they are actually relevant for the query rather than just being semantically similar. Turning this on can improve results, but it also increases latency and in some cases can filter out results that may be useful. If you're seeing few or no results for a given query try again with rerank off and analyze the results to see if they're relevant for the query.
• filter: A metadata filter that allows scoping the query to a subset of your documents. Read Metadata & Filters for more info.
• max_chunks_per_document: Ensures no more than N chunks are returned from a single document. If your use case benefits from a diversity of documents in the results, but results tend to cluster from one document, experiment with this option.

Retrieval Response

Generating a retrieval will yield scored_chunks, an array of the most relevant chunks from your data for the given query.

They include the following fields:

• text: The text from a section of one of your documents that was relevant for the query
• score: A score representing how relevant the chunk is to the query. Importantly this score is not global across multiple retrievals, it is a relative score for this retrieval and should not be compared across retrievals or compared against static score thresholds. In advanced cases it may be used to determine where in the result set relevancy has a statistically significant drop (e.g. Elbow method). Ragie uses multiple search indexes and merges scores from each type of index using Reciprocal Rank Fusion to derive the score. More details are available in this blog post.
• id: The canonical id of the chunk. Can be used to fetch more information about the chunk.
• index: The index of the chunk within its document's set of chunks.
• metadata: Any chunk specific metadata. This field can be populated with information about the chunk that depends on its parent document type. For instance if the document was an audio file, metadata will include fields for start_time and end_time representing where in the original audio stream the chunk was derived from.
• document_metadata: The metadata of the document that the chunk is from.
• links: A set of URLs within the Ragie API that are related to the chunk. This includes URLs for fetching the chunk's content in various formats.

Depending on your use case you may just collect the text fields from the chunks and inject them into your LLM prompts. In some cases you may want to fetch more information about the chunk, or even use the index to fetch adjacent chunks for more context. You may also want to fetch media from the links section to display in your app.

Scored Chunk Links

The links property of each chunk can be used to download and/or stream data from the documents to which the chunk belong.

For example, chunks generated from an image will have the self_imageproperty under links. This can be used to download the image or stream the raw bytes. For more information on streaming, see the audio and video example.

Here is an example of a retrieval response that returned only 1 chunk. This chunk came from an image.

{
  "scored_chunks": [
    {
      "text": "TIGER\nThe image shows a close-up side profile of a tiger's head. The focus is on its face, highlighting the tiger's distinct black stripes on the orange and white fur. The tiger's whiskers are prominent, and its ears are slightly back. The blurred background suggests an outdoor setting, possibly near water, as there is a hint of reflection or water surface visible. The overall lighting is natural.",
      "score": 0.18181818181818182,
      "id": "chunkId",
      "index": 0,
      "metadata": {},
      "document_id": "docId",
      "document_name": "TIGER",
      "document_metadata": {},
      "links": {
        "self": {
          "href": "https://api.ragie.ai/documents/docId/chunks/chunkId",
          "type": "application/json"
        },
        "self_text": {
          "href": "https://api.ragie.ai/documents/docId/chunks/chunkId/content?media_type=text/plain-text",
          "type": "text/plain-text"
        },
        "document": {
          "href": "https://api.ragie.ai/documents/docId",
          "type": "application/json"
        },
        "document_text": {
          "href": "https://api.ragie.ai/documents/docId/content?media_type=text/plain-text",
          "type": "text/plain-text"
        },
        "self_image": {
          "href": "https://api.ragie.ai/documents/docId/chunks/chunkId/content?media_type=image/jpeg",
          "type": "image/jpeg"
        }
      }
    }
  ]
}