Count chunks above threshold

This route can be used to determine the number of chunk results that match a search query including score threshold and filters. It may be high latency for large limits. There is a dataset configuration imposed restriction on the maximum limit value (default 10,000) which is used to prevent DDOS attacks. Auth’ed user or api key must have an admin or owner role for the specified dataset’s organization.

POST /api/chunk/count

Try it

Count chunks above threshold

cURL

curl --request POST \
  --url https://api.trieve.ai/api/chunk/count \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'TR-Dataset: <tr-dataset>' \
  --data '{
  "query": "Some search query",
  "score_threshold": 0.5,
  "search_type": "semantic"
}'

200

{
  "count": 1
}

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.

Body

application/json

JSON request payload to count chunks for a search query

query · required

Query is the search query. This can be any string. The query will be used to create an embedding vector and/or SPLADE vector which will be used to find the result set. You can either provide one query, or multiple with weights. Multi-query only works with Semantic Search and is not compatible with cross encoder re-ranking or highlights.

Show child attributes

query. image_url · string · required

query. llm_prompt · string | null

search_type · enum<string> · required

Available options: fulltext, semantic, bm25

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.

Show child attributes

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.

Option 1

Show child attributes

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.

Show child attributes

filters.must.date_range. gt · string | null

filters.must.date_range. gte · string | null

filters.must.date_range. lt · string | null

filters.must.date_range. lte · string | null

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

Show child attributes

filters.must.geo_bounding_box. bottom_right · object · required

Location that you want to use as the center of the search.

Show child attributes

filters.must.geo_bounding_box.bottom_right. lat · required

filters.must.geo_bounding_box.bottom_right. lon · required

filters.must.geo_bounding_box. top_left · object · required

Location that you want to use as the center of the search.

Show child attributes

filters.must.geo_bounding_box.top_left. lat · required

filters.must.geo_bounding_box.top_left. lon · required

filters.must. geo_polygon · object

Show child attributes

filters.must.geo_polygon. exterior · object[] · required

Show child attributes

filters.must.geo_polygon.exterior. lat · required

filters.must.geo_polygon.exterior. lon · required

filters.must.geo_polygon. interior · object[][] | null

Show child attributes

filters.must.geo_polygon.interior. lat · required

filters.must.geo_polygon.interior. lon · required

filters.must. geo_radius · object

Show child attributes

filters.must.geo_radius. center · object · required

Location that you want to use as the center of the search.

Show child attributes

filters.must.geo_radius.center. lat · required

filters.must.geo_radius.center. lon · required

filters.must.geo_radius. radius · number<double> · required

filters.must. match_all · (string | integer<int64> | number<double>)[] | 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<int64> | number<double>)[] | 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

Show child attributes

filters.must.range. gt

filters.must.range. gte

filters.must.range. lt

filters.must.range. lte

Example:

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

Example:

{
  "field": "metadata.key1",
  "match": ["value1", "value2"],
  "range": { "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.

Option 1

Show child attributes

filters.must_not. 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_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

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.

Show child attributes

filters.must_not.date_range. gt · string | null

filters.must_not.date_range. gte · string | null

filters.must_not.date_range. lt · string | null

filters.must_not.date_range. lte · string | null

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

Show child attributes

filters.must_not.geo_bounding_box. bottom_right · object · required

Location that you want to use as the center of the search.

Show child attributes

filters.must_not.geo_bounding_box.bottom_right. lat · required

filters.must_not.geo_bounding_box.bottom_right. lon · required

filters.must_not.geo_bounding_box. top_left · object · required

Location that you want to use as the center of the search.

Show child attributes

filters.must_not.geo_bounding_box.top_left. lat · required

filters.must_not.geo_bounding_box.top_left. lon · required

filters.must_not. geo_polygon · object

Show child attributes

filters.must_not.geo_polygon. exterior · object[] · required

Show child attributes

filters.must_not.geo_polygon.exterior. lat · required

filters.must_not.geo_polygon.exterior. lon · required

filters.must_not.geo_polygon. interior · object[][] | null

Show child attributes

filters.must_not.geo_polygon.interior. lat · required

filters.must_not.geo_polygon.interior. lon · required

filters.must_not. geo_radius · object

Show child attributes

filters.must_not.geo_radius. center · object · required

Location that you want to use as the center of the search.

Show child attributes

filters.must_not.geo_radius.center. lat · required

filters.must_not.geo_radius.center. lon · required

filters.must_not.geo_radius. radius · number<double> · required

filters.must_not. match_all · (string | integer<int64> | number<double>)[] | 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_not. match_any · (string | integer<int64> | number<double>)[] | 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_not. range · object

Show child attributes

filters.must_not.range. gt

filters.must_not.range. gte

filters.must_not.range. lt

filters.must_not.range. lte

Example:

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

Example:

{
  "field": "metadata.key1",
  "match": ["value1", "value2"],
  "range": { "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.

Option 1

Show child attributes

filters.should. 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.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

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.

Show child attributes

filters.should.date_range. gt · string | null

filters.should.date_range. gte · string | null

filters.should.date_range. lt · string | null

filters.should.date_range. lte · string | null

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

Show child attributes

filters.should.geo_bounding_box. bottom_right · object · required

Location that you want to use as the center of the search.

Show child attributes

filters.should.geo_bounding_box.bottom_right. lat · required

filters.should.geo_bounding_box.bottom_right. lon · required

filters.should.geo_bounding_box. top_left · object · required

Location that you want to use as the center of the search.

Show child attributes

filters.should.geo_bounding_box.top_left. lat · required

filters.should.geo_bounding_box.top_left. lon · required

filters.should. geo_polygon · object

Show child attributes

filters.should.geo_polygon. exterior · object[] · required

Show child attributes

filters.should.geo_polygon.exterior. lat · required

filters.should.geo_polygon.exterior. lon · required

filters.should.geo_polygon. interior · object[][] | null

Show child attributes

filters.should.geo_polygon.interior. lat · required

filters.should.geo_polygon.interior. lon · required

filters.should. geo_radius · object

Show child attributes

filters.should.geo_radius. center · object · required

Location that you want to use as the center of the search.

Show child attributes

filters.should.geo_radius.center. lat · required

filters.should.geo_radius.center. lon · required

filters.should.geo_radius. radius · number<double> · required

filters.should. match_all · (string | integer<int64> | number<double>)[] | 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.should. match_any · (string | integer<int64> | number<double>)[] | 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.should. range · object

Show child attributes

filters.should.range. gt

filters.should.range. gte

filters.should.range. lt

filters.should.range. lte

Example:

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

Example:

{
  "field": "metadata.key1",
  "match": ["value1", "value2"],
  "range": { "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<int64> | null

Set limit to restrict the maximum number of chunks to count. This is useful for when you want to reduce the latency of the count operation. By default the limit will be the number of chunks in the dataset.

Required range: x >= 0

score_threshold · number<float> | null

Set score_threshold to a float to filter out chunks with a score below the threshold. This threshold applies before weight and bias modifications. If not specified, this defaults to 0.0.

use_quote_negated_terms · boolean | null

If true, quoted and - prefixed words will be parsed from the queries and used as required and negated words respectively. Default is false.

Response

200

application/json

Number of chunks satisfying the query

count · integer<int32> · required

Required range: x >= 0