Convert REST to QQL

QQL includes a converter that translates Qdrant REST API JSON payloads to native QQL statements. Use it to migrate from the REST API or the Python qdrant-client SDK.

qql-go convert

From a file:

Convert a JSON payload file

qql-go convert payload.json

From stdin:

Convert via stdin

echo '{"points":[{"id":1,"payload":{"text":"hi"}}]}' | qql-go convert
cat payload.json | qql-go convert

Validate Output

Validate converted QQL

qql-go convert --validate payload.json
Runs the generated QQL through EXPLAIN to verify it parses correctlySection titled “Runs the generated QQL through EXPLAIN to verify it parses correctly”

JSON Output

Convert with JSON output

qql-go convert --json payload.json

Quiet Output (QQL Only)

Convert with quiet output

qql-go convert --quiet payload.json
Outputs only the QQL statements, no headers or decorationSection titled “Outputs only the QQL statements, no headers or decoration”

Supported Operations

The converter auto-detects the operation type from the JSON structure:

REST Operation	QQL Output
Create collection	CREATE COLLECTION
Create field index	CREATE INDEX ON
Upsert points	INSERT INTO ... VALUES (including vector data)
Search points	QUERY ... FROM
Query points (with prefetch/formula/fusion)	WITH ... QUERY ... PREFETCH ... FUSION
Recommend points	QUERY RECOMMEND WITH (...)
Discover points	QUERY DISCOVER TARGET ...
Scroll points	SCROLL FROM
Get points	SELECT * FROM ... WHERE id = ...
Delete points	DELETE FROM ... WHERE
Set payload	UPDATE ... SET PAYLOAD = {...}

Gateway Convert RPC

The gateway exposes a Convert RPC for remote conversion:

Gateway Convert endpoint

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

Response:

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

Python SDK Interceptor

Migrate from the qdrant-client Python SDK by intercepting HTTP calls and converting them to QQL.

Setup

Set up Python environment

uv venv .venv && source .venv/bin/activate && uv pip install qdrant-client

Run Interceptor

Run the interceptor

Print converted QQL to stdoutSection titled “Print converted QQL to stdout”
python3 sdks/python/qql_intercept.py your_script.py
Save to fileSection titled “Save to file”
python3 sdks/python/qql_intercept.py your_script.py -o output.qql

The interceptor wraps QdrantClient at the HTTP layer, captures all REST JSON requests, and pipes them through qql-go convert. The result is a .qql file of your script's Qdrant operations.

Example

Given my_script.py:

from qdrant_client import QdrantClient
client = QdrantClient("localhost", port=6333)
client.upsert("docs", points=[PointStruct(id=1, payload={"text": "hello"}, vector=[0.1, 0.2, 0.3])])
client.search("docs", query_vector=[0.1, 0.2, 0.3], limit=5)

Running the interceptor:

Run interceptor on example script

python3 sdks/python/qql_intercept.py my_script.py -o out.qql

Produces out.qql:

INSERT INTO docs VALUES {'id': 1, 'text': 'hello', 'vector': {'': [0.1, 0.2, 0.3]}}
QUERY [0.1, 0.2, 0.3] FROM docs LIMIT 5

Workflow: Full Migration

Full migration workflow

Step 1: Run interceptor against your existing scriptSection titled “Step 1: Run interceptor against your existing script”
python3 sdks/python/qql_intercept.py ingest.py -o ingest.qql
Step 2: Validate the outputSection titled “Step 2: Validate the output”
qql-go convert --validate ingest.qql
Step 3: Review and edit the .qql file as neededSection titled “Step 3: Review and edit the .qql file as needed”
Step 4: Execute with qql-goSection titled “Step 4: Execute with qql-go”
qql-go execute ingest.qql