--- title: "Get Recommended Groups" method: POST path: "/api/chunk_group/recommend" tags: ["Chunk Group"] --- # Get Recommended Groups `POST /api/chunk_group/recommend` Route to get recommended groups. This route will return groups which are similar to the groups in the request body. You must provide at least one positive group id or group tracking id. ## Headers - `TR-Dataset` string, uuid, required - `X-API-Version` 'V1' | 'V2' ## Request body - RecommendGroupsReqPayload - `filters` ChunkFilter — 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. - `must` ConditionType[], nullable — All of these field conditions have to match for the chunk to be included in the result set. - union — 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. - FieldCondition — FieldCondition is a JSON object which can be used to filter chunks by a field. 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.`. - `boolean` boolean, nullable — 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. - `date_range` DateRange — 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. - `gt` string, nullable - `gte` string, nullable - `lt` string, nullable - `lte` string, nullable - `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.`. - `geo_bounding_box` LocationBoundingBox - `bottom_right` GeoInfo, required — Location that you want to use as the center of the search. - … - `top_left` GeoInfo, required — Location that you want to use as the center of the search. - … - `geo_polygon` LocationPolygon - `exterior` GeoInfo[], required - … - `interior` array[], nullable - … - `geo_radius` LocationRadius - `center` GeoInfo, required — Location that you want to use as the center of the search. - … - `radius` number, double, required - `match_all` MatchCondition[], nullable — 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. - union - … - `match_any` MatchCondition[], nullable — 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. - union - … - `range` Range - `gt` union - … - `gte` union - … - `lt` union - … - `lte` union - … - HasChunkIDCondition — HasChunkIDCondition is a JSON object which can be used to filter chunks by their ids or tracking ids. This is useful for when you want to filter chunks by their ids or tracking ids. - `ids` string[], nullable — Ids of the chunks to apply a match_any condition with. Only chunks with one of these ids will be returned. - `tracking_ids` string[], nullable — Tracking ids of the chunks to apply a match_any condition with. Only chunks with one of these tracking ids will be returned. - `must_not` ConditionType[], nullable — None of these field conditions can match for the chunk to be included in the result set. - union — 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. - FieldCondition — FieldCondition is a JSON object which can be used to filter chunks by a field. 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.`. - `boolean` boolean, nullable — 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. - `date_range` DateRange — 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. - `gt` string, nullable - `gte` string, nullable - `lt` string, nullable - `lte` string, nullable - `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.`. - `geo_bounding_box` LocationBoundingBox - `bottom_right` GeoInfo, required — Location that you want to use as the center of the search. - … - `top_left` GeoInfo, required — Location that you want to use as the center of the search. - … - `geo_polygon` LocationPolygon - `exterior` GeoInfo[], required - … - `interior` array[], nullable - … - `geo_radius` LocationRadius - `center` GeoInfo, required — Location that you want to use as the center of the search. - … - `radius` number, double, required - `match_all` MatchCondition[], nullable — 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. - union - … - `match_any` MatchCondition[], nullable — 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. - union - … - `range` Range - `gt` union - … - `gte` union - … - `lt` union - … - `lte` union - … - HasChunkIDCondition — HasChunkIDCondition is a JSON object which can be used to filter chunks by their ids or tracking ids. This is useful for when you want to filter chunks by their ids or tracking ids. - `ids` string[], nullable — Ids of the chunks to apply a match_any condition with. Only chunks with one of these ids will be returned. - `tracking_ids` string[], nullable — Tracking ids of the chunks to apply a match_any condition with. Only chunks with one of these tracking ids will be returned. - `should` ConditionType[], nullable — Only one of these field conditions has to match for the chunk to be included in the result set. - union — 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. - FieldCondition — FieldCondition is a JSON object which can be used to filter chunks by a field. 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.`. - `boolean` boolean, nullable — 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. - `date_range` DateRange — 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. - `gt` string, nullable - `gte` string, nullable - `lt` string, nullable - `lte` string, nullable - `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.`. - `geo_bounding_box` LocationBoundingBox - `bottom_right` GeoInfo, required — Location that you want to use as the center of the search. - … - `top_left` GeoInfo, required — Location that you want to use as the center of the search. - … - `geo_polygon` LocationPolygon - `exterior` GeoInfo[], required - … - `interior` array[], nullable - … - `geo_radius` LocationRadius - `center` GeoInfo, required — Location that you want to use as the center of the search. - … - `radius` number, double, required - `match_all` MatchCondition[], nullable — 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. - union - … - `match_any` MatchCondition[], nullable — 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. - union - … - `range` Range - `gt` union - … - `gte` union - … - `lt` union - … - `lte` union - … - HasChunkIDCondition — HasChunkIDCondition is a JSON object which can be used to filter chunks by their ids or tracking ids. This is useful for when you want to filter chunks by their ids or tracking ids. - `ids` string[], nullable — Ids of the chunks to apply a match_any condition with. Only chunks with one of these ids will be returned. - `tracking_ids` string[], nullable — Tracking ids of the chunks to apply a match_any condition with. Only chunks with one of these tracking ids will be returned. - `group_size` integer, nullable — The number of chunks to fetch for each group. This is the number of chunks which will be returned in the response for each group. The default is 3. If this is set to a large number, we recommend setting slim_chunks to true to avoid returning the content and chunk_html of the chunks so as to reduce latency due to content download and serialization. - `limit` integer, nullable — The number of groups to return. This is the number of groups which will be returned in the response. The default is 10. - `metadata` unknown - `negative_group_ids` string[], nullable — The ids of the groups to be used as negative examples for the recommendation. The groups in this array will be used to filter out similar groups. - `negative_group_tracking_ids` string[], nullable — The ids of the groups to be used as negative examples for the recommendation. The groups in this array will be used to filter out similar groups. - `positive_group_ids` string[], nullable — The ids of the groups to be used as positive examples for the recommendation. The groups in this array will be used to find similar groups. - `positive_group_tracking_ids` string[], nullable — The ids of the groups to be used as positive examples for the recommendation. The groups in this array will be used to find similar groups. - `recommend_type` 'semantic' | 'fulltext' | 'bm25' — The type of recommendation to make. This lets you choose whether to recommend based off of `semantic` or `fulltext` similarity. The default is `semantic`. - `slim_chunks` boolean, nullable — 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` 'average_vector' | 'best_score' — 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. - `user_id` string, nullable — The user_id is the id of the user who is making the request. This is used to track user interactions with the rrecommendation results. ## Response `200` JSON body representing the groups which are similar to the positive groups and dissimilar to the negative ones - union - RecommendGroupsResponseBody - `id` string, uuid, required - `results` SearchOverGroupsResults[], required - `chunks` ScoreChunk[], required - `chunk` union, required - SlimChunkMetadataWithArrayTagSet - `created_at` string, date-time, required - `dataset_id` string, uuid, required - `id` string, uuid, required - `image_urls` string[], nullable - `link` string, nullable - `location` GeoInfo — Location that you want to use as the center of the search. - … - `metadata` unknown - `num_value` number, double, nullable - `tag_set` string[], nullable - `time_stamp` string, date-time, nullable - `tracking_id` string, nullable - `updated_at` string, date-time, required - `weight` number, double, required - ChunkMetadata - `chunk_html` string, nullable — HTML content of the chunk, can also be an arbitrary string which is not HTML - `created_at` string, date-time, required — Timestamp of the creation of the chunk - `dataset_id` string, uuid, required — ID of the dataset which the chunk belongs to - `id` string, uuid, required — Unique identifier of the chunk, auto-generated uuid created by Trieve - `image_urls` string[], nullable — Image URLs of the chunk, can be any list of strings. Used for image search and RAG. - `link` string, nullable — Link to the chunk, should be a URL - `location` GeoInfo — Location that you want to use as the center of the search. - … - `metadata` unknown - `num_value` number, double, nullable — Numeric value of the chunk, can be any float. Can represent the most relevant numeric value of the chunk, such as a price, quantity in stock, rating, etc. - `tag_set` string[], nullable — Tag set of the chunk, can be any list of strings. Used for tag-filtered searches. - `time_stamp` string, date-time, nullable — Timestamp of the chunk, can be any timestamp. Specified by the user. - `tracking_id` string, nullable — Tracking ID of the chunk, can be any string, determined by the user. Tracking ID's are unique identifiers for chunks within a dataset. They are designed to match the unique identifier of the chunk in the user's system. - `updated_at` string, date-time, required — Timestamp of the last update of the chunk - `weight` number, double, required — Weight of the chunk, can be any float. Used as a multiplier on a chunk's relevance score for ranking purposes. - ContentChunkMetadata - `chunk_html` string, nullable - `id` string, uuid, required - `image_urls` string[], nullable - `num_value` number, double, nullable - `time_stamp` string, date-time, nullable - `tracking_id` string, nullable - `weight` number, double, required - `highlights` string[], nullable - `score` number, float, required - `file_id` string, uuid, nullable - `group` ChunkGroup, required - `created_at` string, date-time, required - `dataset_id` string, uuid, required - `description` string, required - `id` string, uuid, required - `metadata` unknown - `name` string, required - `tag_set` string[], nullable - `tracking_id` string, nullable - `updated_at` string, date-time, required - GroupScoreChunk - `file_id` string, uuid, nullable - `group_created_at` string, date-time, required - `group_dataset_id` string, uuid, required - `group_description` string, nullable - `group_id` string, uuid, required - `group_metadata` unknown - `group_name` string, nullable - `group_tag_set` string[], nullable - `group_tracking_id` string, nullable - `group_updated_at` string, date-time, required - `metadata` ScoreChunkDTO[], required - `highlights` string[], nullable - `metadata` ChunkMetadataTypes[], required - union - SlimChunkMetadata - `created_at` string, date-time, required - `dataset_id` string, uuid, required - `id` string, uuid, required - `image_urls` string[], nullable - `link` string, nullable - `location` GeoInfo — Location that you want to use as the center of the search. - … - `metadata` unknown - `num_value` number, double, nullable - `tag_set` string, nullable - `time_stamp` string, date-time, nullable - `tracking_id` string, nullable - `updated_at` string, date-time, required - `weight` number, double, required - ChunkMetadataStringTagSet - `chunk_html` string, nullable - `created_at` string, date-time, required - `dataset_id` string, uuid, required - `id` string, uuid, required - `image_urls` string[], nullable - `link` string, nullable - `location` GeoInfo — Location that you want to use as the center of the search. - … - `metadata` unknown - `num_value` number, double, nullable - `tag_set` string, nullable - `time_stamp` string, date-time, nullable - `tracking_id` string, nullable - `updated_at` string, date-time, required - `weight` number, double, required - ContentChunkMetadata - `chunk_html` string, nullable - `id` string, uuid, required - `image_urls` string[], nullable - `num_value` number, double, nullable - `time_stamp` string, date-time, nullable - `tracking_id` string, nullable - `weight` number, double, required - `score` number, double, required ## Other responses - `400` — Service error relating to to getting similar chunks --- [API](https://skmtc.net/devflowinc/apis/trieve-api.md) · [All operations](https://skmtc.net/devflowinc/apis/trieve-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/devflowinc/trieve-api/versions/84583e7c9fc1/schema)