Get Recommended Chunks

Get recommendations of chunks similar to the positive samples in the request and dissimilar to the negative.

POST /api/chunk/recommend

Get Recommended Chunks

cURL

curl --request POST \
  --url https://api.trieve.ai/api/chunk/recommend \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'TR-Dataset: <tr-dataset>' \
  --data '
{
  "filters": {
    "must": [
      {
        "field": "tag_set",
        "match_all": [
          "A",
          "B"
        ]
      },
      {
        "field": "num_value",
        "range": {
          "gte": 10,
          "lte": 25
        }
      }
    ]
  },
  "limit": 1,
  "metadata": "<unknown>",
  "negative_chunk_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "negative_tracking_ids": [
    "<string>"
  ],
  "positive_chunk_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "positive_tracking_ids": [
    "<string>"
  ],
  "slim_chunks": true,
  "user_id": "<string>"
}
'

200

{
  "chunks": [
    {
      "chunk": {
        "chunk_html": "<p>Some HTML content</p>",
        "content": "Some content",
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "link": "https://example.com",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "time_stamp": "2021-01-01 00:00:00.000",
        "weight": 0.5
      },
      "highlights": [
        "highlight is two tokens: high, light",
        "whereas hello is only one token: hello"
      ],
      "score": 0.5
    }
  ],
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

Authorization · string · header · required

Headers

TR-Dataset · string<uuid> · required

The dataset id or tracking_id to use for the request. We assume you intend to use an id if the value is a valid uuid.

X-API-Version · enum<string> | null

The API version to use for this request. Defaults to V2 for orgs created after July 12, 2024 and V1 otherwise.

Available options: V1, V2

Body

application/json

JSON request payload to get recommendations of chunks similar to the chunks in the request

filters · object | null

ChunkFilter is a JSON object which can be used to filter chunks. This is useful for when you want to filter chunks by arbitrary metadata. Unlike with tag filtering, there is a performance hit for filtering on metadata.

Show child attributes

Example:

{
  "must": [
    {
      "field": "tag_set",
      "match_all": ["A", "B"]
    },
    {
      "field": "num_value",
      "range": { "gte": 10, "lte": 25 }
    }
  ]
}

limit · integer<int64> | null

The number of chunks to return. This is the number of chunks which will be returned in the response. The default is 10.

Required range: x >= 0

metadata · any | null

Metadata is any metadata you want to associate w/ the event that is created from this request

negative_chunk_ids · string<uuid>[] | null

The ids of the chunks to be used as negative examples for the recommendation. The chunks in this array will be used to filter out similar chunks.

negative_tracking_ids · string[] | null

The tracking_ids of the chunks to be used as negative examples for the recommendation. The chunks in this array will be used to filter out similar chunks.

positive_chunk_ids · string<uuid>[] | null

The ids of the chunks to be used as positive examples for the recommendation. The chunks in this array will be used to find similar chunks.

positive_tracking_ids · string[] | null

The tracking_ids of the chunks to be used as positive examples for the recommendation. The chunks in this array will be used to find similar chunks.

recommend_type · enum<string> | null

The type of recommendation to make. This lets you choose whether to recommend based off of semantic or fulltext similarity. The default is semantic.

Available options: semantic, fulltext, bm25

slim_chunks · boolean | null

Set slim_chunks to true to avoid returning the content and chunk_html of the chunks. This is useful for when you want to reduce amount of data over the wire for latency improvement (typicall 10-50ms). Default is false.

strategy · enum<string> | null

Strategy to use for recommendations, either "average_vector" or "best_score". The default is "average_vector". The "average_vector" strategy will construct a single average vector from the positive and negative samples then use it to perform a pseudo-search. The "best_score" strategy is more advanced and navigates the HNSW with a heuristic of picking edges where the point is closer to the positive samples than it is the negatives.

Available options: average_vector, best_score

user_id · string | null

User ID is the id of the user who is making the request. This is used to track user interactions with the recommendation results.

Response

200

application/json

Chunks with embedding vectors which are similar to positives and dissimilar to negatives

V2 · object

V1 · object[]

chunks · V2 · object[] · required

Show child attributes

id · string<uuid> · required