RAG Tools (/mcp/rag)
ProxySQL v4.0.10 advertises seven tools on /mcp/rag. Search-result counts use k, not limit, and are
clamped by genai-rag_k_max (default 50). Hybrid candidate counts are separately clamped by
genai-rag_candidates_max (default 500), and query text is checked against genai-rag_query_max_bytes.
Shared schema objects
The three search tools accept a filters object with these optional properties:
| Property | Type | Meaning |
|---|---|---|
source_ids | array of integers | Match source IDs. |
source_names | array of strings | Match source names. |
doc_ids | array of strings | Match document IDs. |
min_score | number | Minimum score threshold. |
post_type_ids | array of integers | Match post-type IDs. |
tags_any | array of strings | Match any supplied tag. |
tags_all | array of strings | Match all supplied tags. |
created_after | date-time string | Match documents created after the timestamp. |
created_before | date-time string | Match documents created before the timestamp. |
rag.search_fts and rag.search_vector also accept a return object with optional Boolean
include_title (default true), include_metadata (default true), and include_snippets (default false).
Search tools
rag.search_fts
Runs SQLite FTS5 keyword search over indexed chunks and returns ranked results plus timing/count statistics.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
query | string | yes | FTS query text. |
k | integer | no | Result count; default 10, clamped to the configured maximum. |
offset | integer | no | Pagination offset; default 0. |
filters | object | no | Shared filters listed above. |
return | object | no | Shared result-field controls listed above. |
rag.search_vector
Embeds query_text through the configured embedding service and searches indexed vectors. The advertised
embedding and query_embedding objects are present in the released schema, but the v4.0.10 execution path
does not read them; it generates an embedding from query_text.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
query_text | string | yes | Text to embed and search semantically. |
k | integer | no | Result count; default 10, clamped to the configured maximum. |
filters | object | no | Shared filters listed above. |
return | object | no | Shared result-field controls listed above. |
embedding | object | no | Advertised object with optional model (string); not consumed by the released executor. |
query_embedding | object | no | Advertised object with optional dim (integer) and values_b64 (string); not consumed by the released executor. |
rag.search_hybrid
Combines FTS and generated query embeddings. mode=fuse performs reciprocal-rank fusion; mode
fts_then_vec generates FTS candidates and vector-reranks them.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
query | string | yes | Text used for both lexical and vector retrieval. |
k | integer | no | Final result count; default 10, clamped to the configured maximum. |
mode | string | no | fuse (default) or fts_then_vec. |
filters | object | no | Shared filters listed above. |
fuse | object | no | Optional fts_k (integer, default 50), vec_k (integer, default 50), rrf_k0 (integer, default 60), w_fts (number, default 1.0), and w_vec (number, default 1.0). |
fts_then_vec | object | no | Optional candidates_k (integer, default 200), rerank_k (integer, default 50), and advertised vec_metric (string, default cosine). |
Indexed-content retrieval
rag.get_chunks
Fetches indexed chunk rows by ID.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
chunk_ids | array of strings | yes | Chunk IDs to fetch. |
return | object | no | Optional Boolean include_title, include_doc_metadata, and include_chunk_metadata; all default true. |
rag.get_docs
Fetches indexed document content and metadata by ID.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
doc_ids | array of strings | yes | Document IDs to fetch. |
return | object | no | Optional Boolean include_body and include_metadata; both default true. |
rag.fetch_from_source
Retrieves authoritative rows for the requested documents from each document’s configured source database. It
uses the source metadata and primary-key JSON stored in the RAG index, then queries the configured MySQL or
PostgreSQL source. It does not accept an arbitrary URL/file or re-download a singular doc_id.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
doc_ids | array of strings | yes | Document IDs whose configured source rows should be fetched. |
columns | array of strings | no | Source columns to return. |
limits | object | no | Optional max_rows (integer, default 10, maximum 100) and max_bytes (integer, default 200000, maximum 1000000). |
The result contains one row or error per requested document, source identity/type, truncation state, and timing.
Operational statistics
rag.admin.stats
Takes no parameters. It returns sources[] entries with source_id, source_name, document count, chunk
count, and a last_sync placeholder, plus handler timing. It does not return index size, search-count, average
query-latency, or cache-hit aggregates in v4.0.10.
See RAG Overview for architecture and RAG Ingest for source configuration.