Retrieve from Knowledge Base

client.retrieve.documents(, , ?): RetrieveDocumentsResponse { results, total_results }

post/{knowledgeBaseId}/retrieve

Retrieve relevant documents from a knowledge base using semantic search.

This endpoint:

Authenticates the request using the provided bearer token
Generates embeddings for the query using the knowledge base's configured model
Performs vector similarity search in the knowledge base
Returns the most relevant document chunks

ParametersExpand Collapse

knowledgeBaseID: string

formatuuid

body: RetrieveDocumentsParams { num_results, query, alpha, filters }

num_results: number

Number of results to return

minimum1

maximum100

query: string

The search query text

minLength1

alpha?: number

Weight for hybrid search (0-1):

0 = pure keyword search (BM25)
1 = pure vector search (default)
0.5 = balanced hybrid search

formatdouble

minimum0

maximum1

filters?: Filters

Metadata filters to apply to the search

must?: Array<Must>

All conditions must match (AND)

field: string

Metadata field name

operator: "eq" | "ne" | "gt" | 6 more

Comparison operator

Accepts one of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

"in"

"not_in"

"contains"

value: string | number | boolean | Array<string>

Value to compare against (type depends on field)

Accepts one of the following:

string

number

boolean

Array<string>

must_not?: Array<MustNot>

No conditions should match (NOT)

field: string

Metadata field name

operator: "eq" | "ne" | "gt" | 6 more

Comparison operator

Accepts one of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

"in"

"not_in"

"contains"

value: string | number | boolean | Array<string>

Value to compare against (type depends on field)

Accepts one of the following:

string

number

boolean

Array<string>

should?: Array<Should>

At least one condition must match (OR)

field: string

Metadata field name

operator: "eq" | "ne" | "gt" | 6 more

Comparison operator

Accepts one of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

"in"

"not_in"

"contains"

value: string | number | boolean | Array<string>

Value to compare against (type depends on field)

Accepts one of the following:

string

number

boolean

Array<string>

ReturnsExpand Collapse

RetrieveDocumentsResponse { results, total_results }

results: Array<Result>

Array of retrieved document chunks

metadata: Record<string, unknown>

Metadata associated with the document

text_content: string

The text content of the document chunk

total_results: number

Number of results returned

Retrieve from Knowledge Base

import Gradient from '@digitalocean/gradient';

const client = new Gradient();

const response = await client.retrieve.documents('550e8400-e29b-41d4-a716-446655440000', {
  num_results: 5,
  query: 'What are the best practices for deploying machine learning models?',
});

console.log(response.results);

{
  "results": [
    {
      "metadata": {
        "source": "bar",
        "page": "bar",
        "category": "bar",
        "timestamp": "bar"
      },
      "text_content": "Machine learning models should be deployed with proper monitoring and versioning..."
    }
  ],
  "total_results": 5
}

Returns Examples

{
  "results": [
    {
      "metadata": {
        "source": "bar",
        "page": "bar",
        "category": "bar",
        "timestamp": "bar"
      },
      "text_content": "Machine learning models should be deployed with proper monitoring and versioning..."
    }
  ],
  "total_results": 5
}