Skip to content

RAG Data Models

Centralized documentation for core RAG Pydantic models used across the API.

These models define query parameters, responses, and hit structures for retrieval-augmented generation.

Query Request

RAGQueryRequest

Bases: BaseModel

Query parameters for RAG retrieval.

Attributes:

Name Type Description
text str

Query text to search for
top_k int

Number of top results to retrieve (default: 5)
filters str | None

Optional SQL WHERE clause for filtering (e.g., "category = 'programming'")

Examples:

Python Console Session
1
2
3
4
>>> # Basic query
>>> request = RAGQueryRequest(text="Python async programming")
>>> request.top_k
5
Python Console Session
1
2
3
4
>>> # Query with custom top_k
>>> request = RAGQueryRequest(text="machine learning", top_k=10)
>>> request.top_k
10
Python Console Session
1
2
3
4
5
6
7
>>> # Query with filters
>>> request = RAGQueryRequest(
...     text="database optimization",
...     filters="metadata_json LIKE '%postgres%'"
... )
>>> request.filters
"metadata_json LIKE '%postgres%'"

Query Response

RAGQueryResponse

Bases: BaseModel

RAG response with ranked hits.

Attributes:

Name Type Description
hits list[RAGHit]

List of retrieved chunks, ranked by similarity

Retrieval Hit

RAGHit

Bases: BaseModel

Single retrieval result (one chunk).

Represents a chunk of text retrieved from the RAG knowledge base, along with metadata and similarity score.

Attributes:

Name Type Description
document_id str

Original Document.document_id that this chunk belongs to
chunk_id str

ID of the specific chunk (e.g. "{document_id}:{i}")
text str

Chunk text content
metadata dict[str, Any]

Merged document and chunk metadata
score float

Similarity score (higher = better, cosine similarity: 0.0-1.0)