> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trieve.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Over Groups
> This route allows you to get groups as results instead of chunks. Each group returned will have the matching chunks sorted by similarity within the group. This is useful for when you want to get groups of chunks which are similar to the search query. If choosing hybrid search, the top chunk of each group will be re-ranked using scores from a cross encoder model. Compatible with semantic, fulltext, or hybrid search modes.
## OpenAPI
````yaml post /api/chunk_group/group_oriented_search
openapi: 3.0.3
info:
title: Trieve API
description: >-
Trieve OpenAPI Specification. This document describes all of the operations
available through the Trieve API.
contact:
name: Trieve Team
url: https://trieve.ai
email: developers@trieve.ai
license:
name: BSL
url: https://github.com/devflowinc/trieve/blob/main/LICENSE.txt
version: 0.13.0
servers:
- url: https://api.trieve.ai
description: Production server
- url: http://localhost:8090
description: Local development server
security: []
tags:
- name: Invitation
description: Invitation endpoint. Exists to invite users to an organization.
- name: Auth
description: Authentication endpoint. Serves to register and authenticate users.
- name: User
description: User endpoint. Enables you to modify user roles and information.
- name: Organization
description: >-
Organization endpoint. Enables you to modify organization roles and
information.
- name: Dataset
description: >-
Dataset endpoint. Datasets belong to organizations and hold configuration
information for both client and server. Datasets contain chunks and chunk
groups.
- name: Chunk
description: >-
Chunk endpoint. Think of chunks as individual searchable units of
information. The majority of your integration will likely be with the
Chunk endpoint.
- name: Chunk Group
description: >-
Chunk groups endpoint. Think of a chunk_group as a bookmark folder within
the dataset.
- name: Crawl
description: Crawl endpoint. Used to create and manage crawls for datasets.
- name: File
description: >-
File endpoint. When files are uploaded, they are stored in S3 and broken
up into chunks with text extraction from Apache Tika. You can upload files
of pretty much any type up to 1GB in size. See chunking algorithm details
at `docs.trieve.ai` for more information on how chunking works. Improved
default chunking is on our roadmap.
- name: Events
description: >-
Notifications endpoint. Files are uploaded asynchronously and events are
sent to the user when the upload is complete.
- name: Topic
description: >-
Topic chat endpoint. Think of topics as the storage system for gen-ai chat
memory. Gen AI messages belong to topics.
- name: Message
description: >-
Message chat endpoint. Messages are units belonging to a topic in the
context of a chat with a LLM. There are system, user, and assistant
messages.
- name: Stripe
description: >-
Stripe endpoint. Used for the managed SaaS version of this app. Eventually
this will become a micro-service. Reach out to the team using contact info
found at `docs.trieve.ai` for more information.
- name: Health
description: Health check endpoint. Used to check if the server is up and running.
- name: Metrics
description: Metrics endpoint. Used to get information for monitoring
- name: Analytics
description: Analytics endpoint. Used to get information for search and RAG analytics
- name: Experiment
description: Experiment endpoint. Used to create and manage experiments
paths:
/api/chunk_group/group_oriented_search:
post:
tags:
- Chunk Group
summary: Search Over Groups
description: >-
This route allows you to get groups as results instead of chunks. Each
group returned will have the matching chunks sorted by similarity within
the group. This is useful for when you want to get groups of chunks
which are similar to the search query. If choosing hybrid search, the
top chunk of each group will be re-ranked using scores from a cross
encoder model. Compatible with semantic, fulltext, or hybrid search
modes.
operationId: search_over_groups
parameters:
- name: TR-Dataset
in: header
description: >-
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.
required: true
schema:
type: string
format: uuid
- name: X-API-Version
in: header
description: >-
The API version to use for this request. Defaults to V2 for orgs
created after July 12, 2024 and V1 otherwise.
required: false
schema:
allOf:
- $ref: '#/components/schemas/APIVersion'
nullable: true
requestBody:
description: JSON request payload to semantically search over groups
content:
application/json:
schema:
$ref: '#/components/schemas/SearchOverGroupsReqPayload'
required: true
responses:
'200':
description: >-
Group chunks which are similar to the embedding vector of the search
query
content:
application/json:
schema:
$ref: '#/components/schemas/SearchOverGroupsResponseTypes'
'400':
description: Service error relating to searching over groups
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
security:
- ApiKey:
- readonly
components:
schemas:
APIVersion:
type: string
enum:
- V1
- V2
SearchOverGroupsReqPayload:
type: object
required:
- search_type
- query
properties:
filters:
allOf:
- $ref: '#/components/schemas/ChunkFilter'
nullable: true
get_total_pages:
type: boolean
description: >-
Get total page count for the query accounting for the applied
filters. Defaults to false, but can be set to true when the latency
penalty is acceptable (typically 50-200ms).
nullable: true
group_size:
type: integer
format: int64
description: >-
Group_size is the number of chunks to fetch for each group. The
default is 3. If a group has less than group_size chunks, all chunks
will be returned. 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 lower the amount of time required
for content download and serialization.
nullable: true
minimum: 0
highlight_options:
allOf:
- $ref: '#/components/schemas/HighlightOptions'
nullable: true
metadata:
description: >-
Metadata is any metadata you want to associate w/ the event that is
created from this request
nullable: true
page:
type: integer
format: int64
description: Page of group results to fetch. Page is 1-indexed.
nullable: true
minimum: 0
page_size:
type: integer
format: int64
description: >-
Page size is the number of group results to fetch. The default is
10.
nullable: true
minimum: 0
query:
$ref: '#/components/schemas/QueryTypes'
remove_stop_words:
type: boolean
description: >-
If true, stop words (specified in server/src/stop-words.txt in the
git repo) will be removed. Queries that are entirely stop words will
be
preserved.
nullable: true
score_threshold:
type: number
format: float
description: >-
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.
nullable: true
scoring_options:
allOf:
- $ref: '#/components/schemas/ScoringOptions'
nullable: true
search_type:
$ref: '#/components/schemas/SearchMethod'
slim_chunks:
type: boolean
description: >-
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.
nullable: true
sort_options:
allOf:
- $ref: '#/components/schemas/SortOptions'
nullable: true
typo_options:
allOf:
- $ref: '#/components/schemas/TypoOptions'
nullable: true
use_quote_negated_terms:
type: boolean
description: >-
If true, quoted and - prefixed words will be parsed from the queries
and used as required and negated words respectively. Default is
false.
nullable: true
user_id:
type: string
description: >-
The user_id is the id of the user who is making the request. This is
used to track user interactions with the search results.
nullable: true
SearchOverGroupsResponseTypes:
oneOf:
- $ref: '#/components/schemas/SearchOverGroupsResponseBody'
- $ref: '#/components/schemas/DeprecatedSearchOverGroupsResponseBody'
ErrorResponseBody:
type: object
required:
- message
properties:
message:
type: string
example:
message: Bad Request
ChunkFilter:
type: object
description: >-
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.
properties:
must:
type: array
items:
$ref: '#/components/schemas/ConditionType'
description: >-
All of these field conditions have to match for the chunk to be
included in the result set.
nullable: true
must_not:
type: array
items:
$ref: '#/components/schemas/ConditionType'
description: >-
None of these field conditions can match for the chunk to be
included in the result set.
nullable: true
should:
type: array
items:
$ref: '#/components/schemas/ConditionType'
description: >-
Only one of these field conditions has to match for the chunk to be
included in the result set.
nullable: true
example:
must:
- field: tag_set
match_all:
- A
- B
- field: num_value
range:
gte: 10
lte: 25
HighlightOptions:
type: object
description: >-
Highlight Options lets you specify different methods to highlight the
chunks in the result set. If not specified, this defaults to the score
of the chunks.
properties:
highlight_delimiters:
type: array
items:
type: string
description: >-
Set highlight_delimiters to a list of strings to use as delimiters
for highlighting. If not specified, this defaults to ["?", ",", ".",
"!"]. These are the characters that will be used to split the
chunk_html into splits for highlighting. These are the characters
that will be used to split the chunk_html into splits for
highlighting.
nullable: true
highlight_max_length:
type: integer
format: int32
description: >-
Set highlight_max_length to control the maximum number of tokens
(typically whitespace separated strings, but sometimes also word
stems) which can be present within a single highlight. If not
specified, this defaults to 8. This is useful to shorten large
splits which may have low scores due to length compared to the
query. Set to something very large like 100 to highlight entire
splits.
nullable: true
minimum: 0
highlight_max_num:
type: integer
format: int32
description: >-
Set highlight_max_num to control the maximum number of highlights
per chunk. If not specified, this defaults to 3. It may be less than
3 if no snippets score above the highlight_threshold.
nullable: true
minimum: 0
highlight_results:
type: boolean
description: >-
Set highlight_results to false for a slight latency improvement
(1-10ms). If not specified, this defaults to true. This will add
`` tags to the chunk_html of the chunks to highlight
matching splits and return the highlights on each scored chunk in
the response.
nullable: true
highlight_strategy:
allOf:
- $ref: '#/components/schemas/HighlightStrategy'
nullable: true
highlight_threshold:
type: number
format: double
description: >-
Set highlight_threshold to a lower or higher value to adjust the
sensitivity of the highlights applied to the chunk html. If not
specified, this defaults to 0.8. The range is 0.0 to 1.0.
nullable: true
highlight_window:
type: integer
format: int32
description: >-
Set highlight_window to a number to control the amount of words that
are returned around the matched phrases. If not specified, this
defaults to 0. This is useful for when you want to show more context
around the matched words. When specified, window/2 whitespace
separated words are added before and after each highlight in the
response's highlights array. If an extended highlight overlaps with
another highlight, the overlapping words are only included once.
This parameter can be overriden to respect the highlight_max_length
param.
nullable: true
minimum: 0
post_tag:
type: string
description: >-
Custom html tag which should appear after highlights. If not
specified, this defaults to ''.
nullable: true
pre_tag:
type: string
description: >-
Custom html tag which should appear before highlights. If not
specified, this defaults to ''.
nullable: true
QueryTypes:
oneOf:
- $ref: '#/components/schemas/SearchModalities'
- type: array
items:
$ref: '#/components/schemas/MultiQuery'
description: >-
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.
ScoringOptions:
type: object
description: >-
Scoring options provides ways to modify the sparse or dense vector
created for the query in order to change how potential matches are
scored. If not specified, this defaults to no modifications.
properties:
fulltext_boost:
allOf:
- $ref: '#/components/schemas/FullTextBoost'
nullable: true
semantic_boost:
allOf:
- $ref: '#/components/schemas/SemanticBoost'
nullable: true
SearchMethod:
type: string
enum:
- fulltext
- semantic
- hybrid
- bm25
SortOptions:
type: object
description: >-
Sort Options lets you specify different methods to rerank the chunks in
the result set. If not specified, this defaults to the score of the
chunks.
properties:
location_bias:
allOf:
- $ref: '#/components/schemas/GeoInfoWithBias'
nullable: true
mmr:
allOf:
- $ref: '#/components/schemas/MmrOptions'
nullable: true
recency_bias:
type: number
format: float
description: >-
Recency Bias lets you determine how much of an effect the recency of
chunks will have on the search results. If not specified, this
defaults to 0.0. We recommend setting this to 1.0 for a gentle
reranking of the results, >3.0 for a strong reranking of the
results.
nullable: true
sort_by:
allOf:
- $ref: '#/components/schemas/QdrantSortBy'
nullable: true
tag_weights:
type: object
description: >-
Tag weights is a JSON object which can be used to boost the ranking
of chunks with certain tags. This is useful for when you want to be
able to bias towards chunks with a certain tag on the fly. The keys
are the tag names and the values are the weights.
additionalProperties:
type: number
format: float
nullable: true
use_weights:
type: boolean
description: >-
Set use_weights to true to use the weights of the chunks in the
result set in order to sort them. If not specified, this defaults to
true.
nullable: true
TypoOptions:
type: object
description: >-
Typo Options lets you specify different methods to correct typos in the
query. If not specified, typos will not be corrected.
properties:
correct_typos:
type: boolean
description: >-
Set correct_typos to true to correct typos in the query. If not
specified, this defaults to false.
nullable: true
disable_on_word:
type: array
items:
type: string
description: >-
Words that should not be corrected. If not specified, this defaults
to an empty list.
nullable: true
one_typo_word_range:
allOf:
- $ref: '#/components/schemas/TypoRange'
nullable: true
prioritize_domain_specifc_words:
type: boolean
description: >-
Auto-require non-english words present in the dataset to exist in
each results chunk_html text. If not specified, this defaults to
true.
nullable: true
two_typo_word_range:
allOf:
- $ref: '#/components/schemas/TypoRange'
nullable: true
SearchOverGroupsResponseBody:
type: object
title: V2
required:
- id
- results
- total_pages
properties:
corrected_query:
type: string
nullable: true
id:
type: string
format: uuid
results:
type: array
items:
$ref: '#/components/schemas/SearchOverGroupsResults'
total_pages:
type: integer
format: int64
DeprecatedSearchOverGroupsResponseBody:
type: object
title: V1
required:
- group_chunks
- total_chunk_pages
properties:
corrected_query:
type: string
nullable: true
group_chunks:
type: array
items:
$ref: '#/components/schemas/GroupScoreChunk'
total_chunk_pages:
type: integer
format: int64
ConditionType:
oneOf:
- $ref: '#/components/schemas/FieldCondition'
- $ref: '#/components/schemas/HasChunkIDCondition'
description: >-
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.
HighlightStrategy:
type: string
enum:
- exactmatch
- v1
SearchModalities:
oneOf:
- type: object
title: Image
required:
- image_url
properties:
image_url:
type: string
llm_prompt:
type: string
nullable: true
- type: string
title: Text
- type: object
title: Audio
required:
- audio_base64
properties:
audio_base64:
type: string
MultiQuery:
type: object
description: >-
MultiQuery allows you to construct a dense vector from multiple queries
with a weighted sum. This is useful for when you want to emphasize
certain features of the query. This only works with Semantic Search and
is not compatible with cross encoder re-ranking or highlights.
required:
- query
- weight
properties:
query:
$ref: '#/components/schemas/SearchModalities'
weight:
type: number
format: float
description: >-
Float value which is applies as a multiplier to the query vector
when summing.
FullTextBoost:
type: object
description: >-
Boost the presence of certain tokens for fulltext (SPLADE) and keyword
(BM25) search. I.e. boosting title phrases to priortize title matches or
making sure that the listing for AirBNB itself ranks higher than
companies who make software for AirBNB hosts by boosting the
in-document-frequency of the AirBNB token (AKA word) for its official
listing. Conceptually it multiples the in-document-importance second
value in the tuples of the SPLADE or BM25 sparse vector of the
chunk_html innerText for all tokens present in the boost phrase by the
boost factor like so: (token, in-document-importance) -> (token,
in-document-importance*boost_factor).
required:
- phrase
- boost_factor
properties:
boost_factor:
type: number
format: double
description: >-
Amount to multiplicatevly increase the frequency of the tokens in
the phrase by
phrase:
type: string
description: The phrase to boost in the fulltext document frequency index
SemanticBoost:
type: object
description: >-
Semantic boosting moves the dense vector of the chunk in the direction
of the distance phrase for semantic search. I.e. you can force a cluster
by moving every chunk for a PDF closer to its title or push a chunk with
a chunk_html of "iphone" 25% closer to the term "flagship" by using the
distance phrase "flagship" and a distance factor of 0.25. Conceptually
it's drawing a line (euclidean/L2 distance) between the vector for the
innerText of the chunk_html and distance_phrase then moving the vector
of the chunk_html distance_factor*L2Distance closer to or away from the
distance_phrase point along the line between the two points.
required:
- phrase
- distance_factor
properties:
distance_factor:
type: number
format: float
description: >-
Arbitrary float (positive or negative) specifying the multiplicate
factor to apply before summing the phrase vector with the chunk_html
embedding vector
phrase:
type: string
description: >-
Terms to embed in order to create the vector which is weighted
summed with the chunk_html embedding vector
GeoInfoWithBias:
type: object
description: >-
Location bias lets you rank your results by distance from a location. If
not specified, this has no effect. Bias allows you to determine how much
of an effect the location of chunks will have on the search results. If
not specified, this defaults to 0.0. We recommend setting this to 1.0
for a gentle reranking of the results, >3.0 for a strong reranking of
the results.
required:
- location
- bias
properties:
bias:
type: number
format: double
description: >-
Bias lets you specify how much of an effect the location of chunks
will have on the search results. If not specified, this defaults to
0.0. We recommend setting this to 1.0 for a gentle reranking of the
results, >3.0 for a strong reranking of the results.
location:
$ref: '#/components/schemas/GeoInfo'
MmrOptions:
type: object
description: >-
MMR Options lets you specify different methods to rerank the chunks in
the result set using Maximal Marginal Relevance. If not specified, this
defaults to the score of the chunks.
required:
- use_mmr
properties:
mmr_lambda:
type: number
format: float
description: >-
Set mmr_lambda to a value between 0.0 and 1.0 to control the
tradeoff between relevance and diversity. Closer to 1.0 will give
more diverse results, closer to 0.0 will give more relevant results.
If not specified, this defaults to 0.5.
nullable: true
use_mmr:
type: boolean
description: >-
Set use_mmr to true to use the Maximal Marginal Relevance algorithm
to rerank the results.
QdrantSortBy:
oneOf:
- $ref: '#/components/schemas/SortByField'
- $ref: '#/components/schemas/SortBySearchType'
description: >-
Sort by lets you specify a method to sort the results by. If not
specified, this defaults to the score of the chunks. If specified, this
can be any key in the chunk metadata. This key must be a numeric value
within the payload.
TypoRange:
type: object
description: >-
The TypoRange struct is used to specify the range of which the query
will be corrected if it has a typo.
required:
- min
properties:
max:
type: integer
format: int32
description: >-
The maximum number of characters that the query will be corrected if
it has a typo. If not specified, this defaults to 8.
nullable: true
minimum: 0
min:
type: integer
format: int32
description: >-
The minimum number of characters that the query will be corrected if
it has a typo. If not specified, this defaults to 5.
minimum: 0
SearchOverGroupsResults:
type: object
title: V2
required:
- group
- chunks
properties:
chunks:
type: array
items:
$ref: '#/components/schemas/ScoreChunk'
file_id:
type: string
format: uuid
nullable: true
group:
$ref: '#/components/schemas/ChunkGroup'
GroupScoreChunk:
type: object
title: V1
required:
- group_id
- group_created_at
- group_updated_at
- group_dataset_id
- metadata
properties:
file_id:
type: string
format: uuid
nullable: true
group_created_at:
type: string
format: date-time
group_dataset_id:
type: string
format: uuid
group_description:
type: string
nullable: true
group_id:
type: string
format: uuid
group_metadata:
nullable: true
group_name:
type: string
nullable: true
group_tag_set:
type: array
items:
type: string
nullable: true
nullable: true
group_tracking_id:
type: string
nullable: true
group_updated_at:
type: string
format: date-time
metadata:
type: array
items:
$ref: '#/components/schemas/ScoreChunkDTO'
FieldCondition:
type: object
description: >-
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.`.
required:
- field
properties:
boolean:
type: boolean
description: >-
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.
nullable: true
date_range:
allOf:
- $ref: '#/components/schemas/DateRange'
nullable: true
field:
type: string
description: >-
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:
allOf:
- $ref: '#/components/schemas/LocationBoundingBox'
nullable: true
geo_polygon:
allOf:
- $ref: '#/components/schemas/LocationPolygon'
nullable: true
geo_radius:
allOf:
- $ref: '#/components/schemas/LocationRadius'
nullable: true
match_all:
type: array
items:
$ref: '#/components/schemas/MatchCondition'
description: >-
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.
nullable: true
match_any:
type: array
items:
$ref: '#/components/schemas/MatchCondition'
description: >-
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.
nullable: true
range:
allOf:
- $ref: '#/components/schemas/Range'
nullable: true
example:
field: metadata.key1
match:
- value1
- value2
range:
gt: 0
gte: 0
lt: 1
lte: 1
HasChunkIDCondition:
type: object
description: >-
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.
properties:
ids:
type: array
items:
type: string
format: uuid
description: >-
Ids of the chunks to apply a match_any condition with. Only chunks
with one of these ids will be returned.
nullable: true
tracking_ids:
type: array
items:
type: string
description: >-
Tracking ids of the chunks to apply a match_any condition with. Only
chunks with one of these tracking ids will be returned.
nullable: true
GeoInfo:
type: object
description: Location that you want to use as the center of the search.
required:
- lat
- lon
properties:
lat:
$ref: '#/components/schemas/GeoTypes'
lon:
$ref: '#/components/schemas/GeoTypes'
SortByField:
type: object
required:
- field
properties:
direction:
allOf:
- $ref: '#/components/schemas/SortOrder'
nullable: true
field:
type: string
description: >-
Field to sort by. This has to be a numeric field with a Qdrant
`Range` index on it. i.e. num_value and timestamp
prefetch_amount:
type: integer
format: int64
description: How many results to pull in before the sort
nullable: true
minimum: 0
SortBySearchType:
type: object
required:
- rerank_type
properties:
prefetch_amount:
type: integer
format: int64
description: How many results to pull in before the rerabj
nullable: true
minimum: 0
rerank_query:
type: string
description: Query to use for prefetching defaults to the search query
nullable: true
rerank_type:
$ref: '#/components/schemas/ReRankOptions'
ScoreChunk:
type: object
title: V2
required:
- chunk
- score
properties:
chunk:
$ref: '#/components/schemas/NewChunkMetadataTypes'
highlights:
type: array
items:
type: string
nullable: true
score:
type: number
format: float
example:
chunk:
chunk_html: Some HTML content
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
ChunkGroup:
type: object
required:
- id
- name
- description
- created_at
- updated_at
- dataset_id
properties:
created_at:
type: string
format: date-time
dataset_id:
type: string
format: uuid
description:
type: string
id:
type: string
format: uuid
metadata:
nullable: true
name:
type: string
tag_set:
type: array
items:
type: string
nullable: true
nullable: true
tracking_id:
type: string
nullable: true
updated_at:
type: string
format: date-time
example:
created_at: '2021-01-01 00:00:00.000'
dataset_id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
description: All versions and colorways of the oversized t-shirt
metadata:
foo: bar
name: Versions of Oversized T-Shirt
tag_set:
- tshirt
- oversized
- clothing
tracking_id: SNOVERSIZEDTSHIRT
updated_at: '2021-01-01 00:00:00.000'
ScoreChunkDTO:
type: object
required:
- metadata
- score
properties:
highlights:
type: array
items:
type: string
nullable: true
metadata:
type: array
items:
$ref: '#/components/schemas/ChunkMetadataTypes'
score:
type: number
format: double
example:
highlights:
- 'highlight is two tokens: high, light'
- 'whereas hello is only one token: hello'
metadata:
- chunk_html: Some HTML content
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
score: 0.5
DateRange:
type: object
description: >-
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.
properties:
gt:
type: string
nullable: true
gte:
type: string
nullable: true
lt:
type: string
nullable: true
lte:
type: string
nullable: true
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'
LocationBoundingBox:
type: object
required:
- top_left
- bottom_right
properties:
bottom_right:
$ref: '#/components/schemas/GeoInfo'
top_left:
$ref: '#/components/schemas/GeoInfo'
LocationPolygon:
type: object
required:
- exterior
properties:
exterior:
type: array
items:
$ref: '#/components/schemas/GeoInfo'
interior:
type: array
items:
type: array
items:
$ref: '#/components/schemas/GeoInfo'
nullable: true
LocationRadius:
type: object
required:
- center
- radius
properties:
center:
$ref: '#/components/schemas/GeoInfo'
radius:
type: number
format: double
MatchCondition:
oneOf:
- type: string
- type: integer
format: int64
- type: number
format: double
Range:
type: object
properties:
gt:
allOf:
- $ref: '#/components/schemas/RangeCondition'
nullable: true
gte:
allOf:
- $ref: '#/components/schemas/RangeCondition'
nullable: true
lt:
allOf:
- $ref: '#/components/schemas/RangeCondition'
nullable: true
lte:
allOf:
- $ref: '#/components/schemas/RangeCondition'
nullable: true
example:
gt: 0
gte: 0
lt: 1
lte: 1
GeoTypes:
oneOf:
- type: integer
format: int64
- type: number
format: double
SortOrder:
type: string
enum:
- desc
- asc
ReRankOptions:
type: string
enum:
- semantic
- fulltext
- bm25
- cross_encoder
NewChunkMetadataTypes:
oneOf:
- $ref: '#/components/schemas/SlimChunkMetadataWithArrayTagSet'
- $ref: '#/components/schemas/ChunkMetadata'
- $ref: '#/components/schemas/ContentChunkMetadata'
ChunkMetadataTypes:
oneOf:
- $ref: '#/components/schemas/SlimChunkMetadata'
- $ref: '#/components/schemas/ChunkMetadataStringTagSet'
- $ref: '#/components/schemas/ContentChunkMetadata'
RangeCondition:
oneOf:
- type: number
format: double
- type: integer
format: int64
SlimChunkMetadataWithArrayTagSet:
type: object
title: SlimChunkMetadataWithArrayTagSet
required:
- id
- created_at
- updated_at
- dataset_id
- weight
properties:
created_at:
type: string
format: date-time
dataset_id:
type: string
format: uuid
id:
type: string
format: uuid
image_urls:
type: array
items:
type: string
nullable: true
nullable: true
link:
type: string
nullable: true
location:
allOf:
- $ref: '#/components/schemas/GeoInfo'
nullable: true
metadata:
nullable: true
num_value:
type: number
format: double
nullable: true
tag_set:
type: array
items:
type: string
nullable: true
time_stamp:
type: string
format: date-time
nullable: true
tracking_id:
type: string
nullable: true
updated_at:
type: string
format: date-time
weight:
type: number
format: double
ChunkMetadata:
type: object
title: V2
required:
- id
- created_at
- updated_at
- dataset_id
- weight
properties:
chunk_html:
type: string
description: >-
HTML content of the chunk, can also be an arbitrary string which is
not HTML
nullable: true
created_at:
type: string
format: date-time
description: Timestamp of the creation of the chunk
dataset_id:
type: string
format: uuid
description: ID of the dataset which the chunk belongs to
id:
type: string
format: uuid
description: >-
Unique identifier of the chunk, auto-generated uuid created by
Trieve
image_urls:
type: array
items:
type: string
nullable: true
description: >-
Image URLs of the chunk, can be any list of strings. Used for image
search and RAG.
nullable: true
link:
type: string
description: Link to the chunk, should be a URL
nullable: true
location:
allOf:
- $ref: '#/components/schemas/GeoInfo'
nullable: true
metadata:
description: Metadata of the chunk, can be any JSON object
nullable: true
num_value:
type: number
format: double
description: >-
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.
nullable: true
tag_set:
type: array
items:
type: string
nullable: true
description: >-
Tag set of the chunk, can be any list of strings. Used for
tag-filtered searches.
nullable: true
time_stamp:
type: string
format: date-time
description: Timestamp of the chunk, can be any timestamp. Specified by the user.
nullable: true
tracking_id:
type: string
description: >-
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.
nullable: true
updated_at:
type: string
format: date-time
description: Timestamp of the last update of the chunk
weight:
type: number
format: double
description: >-
Weight of the chunk, can be any float. Used as a multiplier on a
chunk's relevance score for ranking purposes.
example:
chunk_html: Hello, world!
created_at: '2021-01-01 00:00:00.000'
dataset_id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
link: https://trieve.ai
metadata:
key: value
tag_set: '[tag1,tag2]'
time_stamp: '2021-01-01 00:00:00.000'
tracking_id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
updated_at: '2021-01-01 00:00:00.000'
weight: 0.5
ContentChunkMetadata:
type: object
title: ContentChunkMetadata
required:
- id
- weight
properties:
chunk_html:
type: string
nullable: true
id:
type: string
format: uuid
image_urls:
type: array
items:
type: string
nullable: true
nullable: true
num_value:
type: number
format: double
nullable: true
time_stamp:
type: string
format: date-time
nullable: true
tracking_id:
type: string
nullable: true
weight:
type: number
format: double
example:
created_at: '2021-01-01 00:00:00.000'
dataset_id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
link: https://trieve.ai
metadata:
key: value
tag_set: tag1,tag2
time_stamp: '2021-01-01 00:00:00.000'
tracking_id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
updated_at: '2021-01-01 00:00:00.000'
weight: 0.5
SlimChunkMetadata:
type: object
required:
- id
- created_at
- updated_at
- dataset_id
- weight
properties:
created_at:
type: string
format: date-time
dataset_id:
type: string
format: uuid
id:
type: string
format: uuid
image_urls:
type: array
items:
type: string
nullable: true
nullable: true
link:
type: string
nullable: true
location:
allOf:
- $ref: '#/components/schemas/GeoInfo'
nullable: true
metadata:
nullable: true
num_value:
type: number
format: double
nullable: true
tag_set:
type: string
nullable: true
time_stamp:
type: string
format: date-time
nullable: true
tracking_id:
type: string
nullable: true
updated_at:
type: string
format: date-time
weight:
type: number
format: double
example:
created_at: '2021-01-01 00:00:00.000'
dataset_id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
link: https://trieve.ai
metadata:
key: value
tag_set: tag1,tag2
time_stamp: '2021-01-01 00:00:00.000'
tracking_id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
updated_at: '2021-01-01 00:00:00.000'
weight: 0.5
ChunkMetadataStringTagSet:
type: object
title: V1
required:
- id
- created_at
- updated_at
- dataset_id
- weight
properties:
chunk_html:
type: string
nullable: true
created_at:
type: string
format: date-time
dataset_id:
type: string
format: uuid
id:
type: string
format: uuid
image_urls:
type: array
items:
type: string
nullable: true
nullable: true
link:
type: string
nullable: true
location:
allOf:
- $ref: '#/components/schemas/GeoInfo'
nullable: true
metadata:
nullable: true
num_value:
type: number
format: double
nullable: true
tag_set:
type: string
nullable: true
time_stamp:
type: string
format: date-time
nullable: true
tracking_id:
type: string
nullable: true
updated_at:
type: string
format: date-time
weight:
type: number
format: double
example:
created_at: '2021-01-01 00:00:00.000'
dataset_id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
link: https://trieve.ai
metadata:
key: value
tag_set: tag1,tag2
time_stamp: '2021-01-01 00:00:00.000'
tracking_id: e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3
updated_at: '2021-01-01 00:00:00.000'
weight: 0.5
securitySchemes:
ApiKey:
type: apiKey
in: header
name: Authorization
````