Get Recommended Chunks

POST

api

chunk

recommend

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": "<any>",
  "negative_chunk_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "negative_tracking_ids": [
    "<string>"
  ],
  "positive_chunk_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "positive_tracking_ids": [
    "<string>"
  ],
  "recommend_type": "semantic",
  "slim_chunks": true,
  "strategy": "average_vector",
  "user_id": "<string>"
}'

{
  "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

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>

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

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.

filters.must

object[] | null

All of these field conditions have to match for the chunk to be included in the result set.

Filters can be constructed using either fields on the chunk objects, ids or tracking ids of chunks, and finally ids or tracking ids of groups.

filters.must.field

string

required

Field is the name of the field to filter on. Commonly used fields are timestamp, link, tag_set, location, num_value, group_ids, and group_tracking_ids. The field value will be used to check for an exact substring match on the metadata values for each existing chunk. This is useful for when you want to filter chunks by arbitrary metadata. To access fields inside of the metadata that you provide with the card, prefix the field name with metadata..

filters.must.boolean

boolean | null

Boolean is a true false value for a field. This only works for boolean fields. You can specify this if you want values to be true or false.

filters.must.date_range

object

DateRange is a JSON object which can be used to filter chunks by a range of dates. This leverages the time_stamp field on chunks in your dataset. You can specify this if you want values in a certain range. You must provide ISO 8601 combined date and time without timezone.

Example:

{
  "gt": "2021-01-01 00:00:00.000",
  "gte": "2021-01-01 00:00:00.000",
  "lt": "2021-01-01 00:00:00.000",
  "lte": "2021-01-01 00:00:00.000"
}

filters.must.geo_bounding_box

object

filters.must.geo_polygon

object

filters.must.geo_radius

object

filters.must.match_all

(string | integer | number)[] | null

Match all lets you pass in an array of values that will return results if all of the items match. The match value will be used to check for an exact substring match on the metadata values for each existing chunk. If both match_all and match_any are provided, the match_any condition will be used.

filters.must.match_any

(string | integer | number)[] | null

Match any lets you pass in an array of values that will return results if any of the items match. The match value will be used to check for an exact substring match on the metadata values for each existing chunk. If both match_all and match_any are provided, the match_any condition will be used.

filters.must.range

object

Example:

{ "gt": 0, "gte": 0, "lt": 1, "lte": 1 }

filters.must_not

object[] | null

None of these field conditions can match for the chunk to be included in the result set.

Filters can be constructed using either fields on the chunk objects, ids or tracking ids of chunks, and finally ids or tracking ids of groups.

filters.must_not.field

string

required

filters.must_not.boolean

boolean | null

Boolean is a true false value for a field. This only works for boolean fields. You can specify this if you want values to be true or false.

filters.must_not.date_range

object

Example:

{
  "gt": "2021-01-01 00:00:00.000",
  "gte": "2021-01-01 00:00:00.000",
  "lt": "2021-01-01 00:00:00.000",
  "lte": "2021-01-01 00:00:00.000"
}

filters.must_not.geo_bounding_box

object

filters.must_not.geo_polygon

object

filters.must_not.geo_radius

object

filters.must_not.match_all

(string | integer | number)[] | null

filters.must_not.match_any

(string | integer | number)[] | null

filters.must_not.range

object

Example:

{ "gt": 0, "gte": 0, "lt": 1, "lte": 1 }

filters.should

object[] | null

Only one of these field conditions has to match for the chunk to be included in the result set.

Filters can be constructed using either fields on the chunk objects, ids or tracking ids of chunks, and finally ids or tracking ids of groups.

filters.should.field

string

required

filters.should.boolean

boolean | null

Boolean is a true false value for a field. This only works for boolean fields. You can specify this if you want values to be true or false.

filters.should.date_range

object

Example:

{
  "gt": "2021-01-01 00:00:00.000",
  "gte": "2021-01-01 00:00:00.000",
  "lt": "2021-01-01 00:00:00.000",
  "lte": "2021-01-01 00:00:00.000"
}

filters.should.geo_bounding_box

object

filters.should.geo_polygon

object

filters.should.geo_radius

object

filters.should.match_all

(string | integer | number)[] | null

filters.should.match_any

(string | integer | number)[] | null

filters.should.range

object

Example:

{ "gt": 0, "gte": 0, "lt": 1, "lte": 1 }

Example:

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

limit

integer | 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[] | 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[] | 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.

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>

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

chunks

object[]

required

string

required

Was this page helpful?

Raise issue

Autocomplete Scroll Chunks

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": "<any>",
  "negative_chunk_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "negative_tracking_ids": [
    "<string>"
  ],
  "positive_chunk_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "positive_tracking_ids": [
    "<string>"
  ],
  "recommend_type": "semantic",
  "slim_chunks": true,
  "strategy": "average_vector",
  "user_id": "<string>"
}'

{
  "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"
}

Chunk

Chunk Group

Topic

Message

Crawl

File

Analytics

Dataset

Organization

User

Auth

Health

Invitation

Stripe

Metrics

Get Recommended Chunks

Authorizations

Headers

Body

Response