Qql Skill

QQL Skill

Use this skill to turn retrieval intent into valid QQL for the current Go implementation. Treat QQL as a query language and execution surface, not as a retrieval strategy engine.

Reference Wiki

Read these reference documents ONLY when you need details on their specific topics:

• [references/qql-install.md](references/qql-install.md) — Read if qql-go is not installed or for local/external mode setup.
• [references/qql-gaps.md](references/qql-gaps.md) — Read if a user asks for unsupported features (ReadConsistency, Timeout, ShardKeySelector).
• [references/qql-examples.md](references/qql-examples.md) — Read for advanced examples (CTEs, MMR, Context patterns).

For runnable demo scripts, see scripts/demo_retrieval_modes.py, scripts/demo_medical_records.py, scripts/demo_kitchen_sink.py, and scripts/demo_multivector.py.

Intent Mapping

Translate user intent directly into QQL syntax:

• Semantic similarity -> QUERY '' FROM
• Exact terms also matter -> add USING HYBRID
• Hybrid retrieval with DBSF fusion -> USING HYBRID FUSION DBSF
• Hybrid retrieval with tuned RRF -> USING HYBRID WITH (rrf_k = ..., rrf_weights = [...])
• Multi-stage retrieval -> WITH AS (...), ... QUERY ... PREFETCH (name1, name2) FUSION RRF
• Pure fusion (no search target) -> FUSION RRF LIMIT PREFETCH (, )
• Multi-stage with different vectors -> WITH _pf0 AS (QUERY ... USING 'dense'), _pf1 AS (QUERY ... USING 'sparse') QUERY ... USING 'colbert' PREFETCH (_pf0, _pf1)
• PDF retrieval (ColBERT/ColPali) -> create with MULTIVECTOR (comparator = 'max_sim') + HNSW (m = 0), search with prefetch + USING
• Keyword-only retrieval -> USING SPARSE
• Query by point ID -> QUERY FROM
• Recommendation by example -> QUERY RECOMMEND WITH (positive = (...), negative = (...))
• Context-aware search -> QUERY CONTEXT PAIRS (...)
• Exploration search -> QUERY DISCOVER TARGET CONTEXT PAIRS (...)
• Random sampling -> QUERY SAMPLE FROM LIMIT
• Browse by field -> QUERY ORDER BY [ASC|DESC] FROM
• Score boosting -> BOOST ($score + 0.3 * popularity) or BOOST (CASE WHEN ... THEN ... ELSE ... END)
• Recall debugging -> add EXACT
• Query-time recall tuning -> add WITH (hnsw_ef = ...)
• Filtered recall concern -> add WITH (acorn = true)
• Diverse dense/hybrid results -> add WITH (mmr_diversity = ..., mmr_candidates = ...)
• Better ordering (Cloud Only) -> add RERANK
• Grouped top results by field -> add GROUP BY [GROUP_SIZE ]
• Cross-collection group lookup -> add WITH LOOKUP FROM on grouped queries
• Exact point lookup -> SELECT * FROM WHERE id =
• Browse points -> SCROLL FROM [AFTER ] LIMIT
• Batch ingest -> INSERT INTO VALUES {...}, {...}
• Insert with pre-computed vectors -> INSERT INTO VALUES {'id': 1, 'vector': {'dense': [...], 'colbert': [[...]]}}
• Convert Python SDK to QQL -> python3 sdks/python/qql_intercept.py your_script.py
• Convert REST JSON to QQL -> qql-go convert payload.json

QQL Capabilities & Grammar

Use the following bracketed syntax. Elements in [] are optional. Elements separated by | are choices.

Collection Management

CREATE COLLECTION  [HYBRID [RERANK]]
  [WITH HNSW (m = , ef_construct = , ...)]
  [WITH OPTIMIZERS (deleted_threshold = , ...)]
  [WITH PARAMS (replication_factor = , ...)]
  [WITH QUANTIZATION (type = 'scalar'|'binary'|'product'|'turbo', ...)]
  [USING MODEL '' | USING HYBRID [DENSE MODEL '']]

-- Named vectors with per-vector config
CREATE COLLECTION  (
  dense VECTOR(384, COSINE),
  colbert VECTOR(128, COSINE) WITH MULTIVECTOR (comparator = 'max_sim') WITH HNSW (m = 0)
)

ALTER COLLECTION  ... -- Supports WITH HNSW, WITH OPTIMIZERS, WITH PARAMS, WITH QUANTIZATION (disabled = true)
SHOW COLLECTIONS
SHOW COLLECTION 
DROP COLLECTION 

Payload Indexes

Always index fields before using them in WHERE filters.

CREATE INDEX ON COLLECTION  FOR  TYPE 
  [WITH (
    is_tenant = bool, on_disk = bool, enable_hnsw = bool,
    tokenizer = 'word|whitespace|prefix|multilingual', min_token_len = , max_token_len = ,
    lowercase = bool, ascii_folding = bool, phrase_matching = bool, stopwords = ['en', ...]
  )]

Insert & Update

INSERT INTO  VALUES { 'text': '...', 'category': '...' }, {...}, {...}
  [USING [HYBRID [DENSE MODEL '' SPARSE MODEL ''] | MODEL '']]

-- Insert with pre-computed named vectors (dense + multivector)
INSERT INTO  VALUES { 'id': 1, 'text': '...', 'vector': {'dense': [0.1, 0.2], 'colbert': [[0.1, 0.2], [0.3, 0.4]]} }

UPDATE  SET VECTOR ['vector_name'] = [, ...] WHERE id = 
UPDATE  SET PAYLOAD = {...} WHERE 
DELETE FROM  WHERE 

Query

QUERY ['' |  | RECOMMEND WITH (positive = (...), negative = (...)) [STRATEGY ''] | CONTEXT PAIRS (...) | DISCOVER TARGET  CONTEXT PAIRS (...) | ORDER BY  [ASC|DESC] | SAMPLE]
FROM 
  [PREFETCH (  [WHERE ] [SCORE THRESHOLD ], ... ) FUSION ]
  [LOOKUP FROM  [VECTOR '']]
  [USING [HYBRID [FUSION DBSF] | SPARSE | DENSE | '']]
  [WITH MODEL '']
  [WHERE ]
  [GROUP BY  [GROUP_SIZE ] [WITH LOOKUP FROM ]]
  [WITH (hnsw_ef = , exact = , acorn = , mmr_diversity = , mmr_candidates = , rrf_k = , rrf_weights = [...])]
  [WITH PAYLOAD [true | false | (include = ['', ...], exclude = ['', ...])]]
  [WITH VECTORS [true | false | ('', ...)]]
  [BOOST ()]
  [DEFAULTS ( = , ...)]
  [RERANK [MODEL '']]
  [EXACT]
  [LIMIT ] [OFFSET ] [SCORE THRESHOLD ]

-- Pure fusion (no search target, just fuse CTE results)
FUSION  [FROM ] [LIMIT ] [PREFETCH (, )]

BOOST Formula Expressions

The BOOST clause applies a mathematical expression to modify search scores.

• Variables: $score (current score), bare names for payload fields (e.g., popularity, freshness)
• Operators: +, -, *, / (where / supports optional [default=value] suffix for division-by-zero safety)
• Functions: ABS(x), SQRT(x), LOG(x), LN(x), EXP(x), POW(base, exp)
• Geo: GEO_DISTANCE(lat, lon, field) or GEO_DISTANCE({'lat': x, 'lon': y}, field)
• Decay: GAUSS_DECAY(x, target, scale, midpoint), EXP_DECAY(...), LIN_DECAY(...) — supports kwargs: gauss_decay(x, scale=5000, decay=0.5) or gauss_decay(x, target=datetime('2026-01-01'), scale=30d, midpoint=0.5)
• Datetime: datetime('2026-01-01T00:00:00Z') (literal), datetime_key('field') (payload field)
• Conditional: CASE WHEN THEN ELSE END
• Defaults: DEFAULTS (var1 = 1.0, var2 = 0.0) — fallback values for missing payload fields

Examples:

BOOST ($score + 0.3 * popularity)
BOOST (CASE WHEN category = 'premium' THEN $score * 2.0 ELSE $score END)
BOOST ($score * gauss_decay(geo_distance({'lat': 48.85, 'lon': 2.35}, location), scale=5000))
BOOST (SQRT($score) * LOG(citation_count + 1)) DEFAULTS (citation_count = 0)
BOOST ($score + exp_decay(datetime_key('published_at'), target=datetime('2026-06-17T00:00:00Z'), scale=86400))

CTEs (Common Table Expressions)

WITH  AS (QUERY ... USING '' [LIMIT ]) [,  AS (QUERY ...)]
QUERY ... FROM  USING '' PREFETCH (, ...) FUSION RRF LIMIT 

-- Pure fusion (no search target)
WITH  AS (QUERY ...),  AS (QUERY ...)
FUSION RRF LIMIT  PREFETCH (, )

Notes:

• Each CTE can target a different named vector with USING ''.
• PREFETCH references CTE names, not inline queries.
• Each prefetch ref can have an inline WHERE filter and SCORE THRESHOLD.
• OFFSET cannot be used with GROUP BY.
• Filters use standard SQL operators: =, !=, >, "
• qql-go explain --quiet --json ""
• qql-go execute --quiet --json
• qql-go doctor --quiet --json
• qql-go connect --quiet --json --url ...
• qql-go dump --quiet --json [--batch-size ]
• qql-go convert --quiet — REST JSON to QQL
• python3 sdks/python/qql_intercept.py — Python SDK to QQL

Script format: .qql files use newline-delimited statements WITHOUT semicolons.

-- Comment
CREATE COLLECTION my_collection
INSERT INTO my_collection VALUES {'text': 'hello'}
QUERY 'hello' FROM my_collection LIMIT 5

Go Library API

For programmatic usage, use pkg/qql:

import "github.com/srimon12/qql-go/pkg/qql"

// Parse (no Qdrant client needed)
node, err := qql.Parse("QUERY 'search' FROM docs LIMIT 5")

// Execute single query
result, err := qql.Exec(ctx, client, "QUERY 'search' FROM docs LIMIT 5")

// Execute mixed statements sequentially
results, err := qql.ExecBatch(ctx, client, queries, true)

// Execute pure QUERY batch (single round-trip via Qdrant QueryBatch API)
results, err := qql.BatchQuery(ctx, client, []string{
    "QUERY 'stroke' FROM medical LIMIT 5",
    "QUERY 'cardiac' FROM medical LIMIT 5",
    "QUERY 'pulmonary' FROM medical LIMIT 5",
})

// Explain without executing
plan, err := qql.Explain("QUERY 'test' FROM docs LIMIT 5")

Batch Operations

• Mixed statements (INSERT, CREATE, QUERY): Use ExecBatch — sequential execution
• Pure QUERY batches: Use BatchQuery — single round-trip via Qdrant's native QueryBatch API
• Bulk insert: Use comma-separated INSERT INTO VALUES {...}, {...}

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: srimon12
• Source: srimon12/qql-go
• License: MIT
• Homepage: https://qql-go.veristamp.in/

Install and usage instructions live in the source repository linked above.