RPC Reference

The QQL gateway exposes five RPCs defined in proto/qql.proto. All RPCs accept JSON over HTTP POST (Connect RPC protocol).

Exec

Parse and execute a single QQL statement.

Endpoint

POST /qql.QQL/Exec

Request:

{
  "query": "QUERY \"search\" FROM docs LIMIT 5 USING HYBRID"
}

Response:

{
  "ok": true,
  "operation": "QUERY",
  "message": "Found 5 results",
  "data": "<base64-encoded JSON bytes>"
}

curl:

Exec curl

curl -X POST http://localhost:50051/qql.QQL/Exec
-H "Content-Type: application/json"
-H "Authorization: Bearer <jwt>"
-d '{"query": "QUERY "search" FROM docs LIMIT 5 USING HYBRID"}'

ExecBatch

Execute multiple statements in one request. Supports mixed statement types.

Endpoint

POST /qql.QQL/ExecBatch

Request:

{
  "queries": [
    {"query": "QUERY \"a\" FROM docs LIMIT 5"},
    {"query": "QUERY \"b\" FROM docs LIMIT 5"}
  ],
  "stop_on_error": true
}

Response:

{
  "results": [
    {"ok": true, "operation": "QUERY", "message": "Found 3 results", "data": "..."},
    {"ok": true, "operation": "QUERY", "message": "Found 1 result", "data": "..."}
  ]
}

curl:

ExecBatch curl

curl -X POST http://localhost:50051/qql.QQL/ExecBatch
-H "Content-Type: application/json"
-d '{ "queries": [ {"query": "QUERY "a" FROM docs LIMIT 5"}, {"query": "QUERY "b" FROM docs LIMIT 5"} ], "stop_on_error": true }'

Explain

Return the execution plan without running the query.

Endpoint

POST /qql.QQL/Explain

Request:

{
  "query": "QUERY \"search\" FROM docs LIMIT 5 USING HYBRID RERANK",
  "json": false
}

Response:

{
  "ok": true,
  "query": "QUERY \"search\" FROM docs LIMIT 5 USING HYBRID RERANK",
  "plan": "Statement: QUERY\nCollection: docs\nUSING: HYBRID\nRERANK: true\nLIMIT: 5\n..."
}

Set "json": true for a structured JSON plan.

curl:

Explain curl

curl -X POST http://localhost:50051/qql.QQL/Explain
-H "Content-Type: application/json"
-d '{"query": "QUERY "search" FROM docs LIMIT 5 USING HYBRID RERANK"}'

Health

Check gateway and Qdrant connectivity.

Endpoint

GET /health or POST /qql.QQL/Health

Response:

{
  "version": "X.Y.Z",
  "qdrant_connected": true,
  "qdrant_status": "ok — 3 collections"
}

curl:

Health check

curl http://localhost:50051/health

Convert

Translate Qdrant REST API JSON to QQL statements.

Endpoint

POST /qql.QQL/Convert

Request:

{
  "json_payload": "{\"points\":[{\"id\":1,\"payload\":{\"text\":\"hello\"}}]}"
}

Response:

{
  "ok": true,
  "statements": [
    "INSERT INTO <collection> VALUES {'id': 1, 'text': 'hello'}"
  ],
  "error": ""
}

curl:

Convert curl

curl -X POST http://localhost:50051/qql.QQL/Convert
-H "Content-Type: application/json"
-d '{"json_payload": "{"points":[{"id":1,"payload":{"text":"hello"}}]}"}'

Proto Definition

See the full protobuf reference for the complete service and message definitions.