Skip to content
QQL Documentation

Filters

WHERE describes which points qualify. It lowers to a Qdrant filter for REST, gRPC, and edge execution. It is independent from SHARD, which is request routing rather than access control.

Compose scalar predicates

Section titled “Compose scalar predicates”

Predicates combine with NOT, AND, and OR; precedence is predicate → NOT → AND → OR. Add parentheses when a mixed condition should be obvious to the reader.

QQLComparisons, membership, and boolean logicTry in playground
QUERY TEXT 'search'
FROM docs
WHERE status = 'published'
  AND year BETWEEN 2024 AND 2026
  AND tags NOT IN ('archived', 'private')
  AND (score >= 0.7 OR featured = true)
LIMIT 10;
PredicateUse it for
=, !=, >, >=, <, <=Scalar equality and range comparison
BETWEEN, IN, NOT INInclusive ranges and membership sets
IS NULL, IS EMPTYMissing or empty payload values
MATCH, MATCH ANY, MATCH PHRASEText payload matching
HAS_VECTOR, VALUES_COUNTVector presence and array cardinality

The unicode operators ≠, ≥, and ≤ normalize to !=, >=, and <=. !=, NOT IN, IS NOT NULL, and IS NOT EMPTY all normalize to a NOT around the corresponding positive predicate. Comparison against the point id field permits =, IN, and — via the same NOT normalization — != and NOT IN; every value must be a valid point ID (an unsigned integer or a string).

Text, cardinality, and presence predicates

Section titled “Text, cardinality, and presence predicates”

MATCH covers three text forms: a plain string match, MATCH ANY over a non-empty list, and MATCH PHRASE for ordered multi-token phrases. Field and text-index compatibility is enforced by the backend at execution time. VALUES_COUNT <op> <non_negative_integer> tests array cardinality.

QQLText matching, cardinality, and presenceTry in playground
QUERY TEXT 'search'
FROM docs
WHERE content MATCH 'hello world'
  AND tags MATCH ANY ('hello', 'world')
  AND description MATCH PHRASE 'vector database'
  AND reviews VALUES_COUNT >= 2
  AND HAS_VECTOR 'dense'
  AND notes IS NOT NULL
LIMIT 10;

Match nested document data

Section titled “Match nested document data”

Use NESTED when predicates must apply within the same object of a nested payload array. This avoids accidentally matching rating from one review and verified from another.

QQLPhrase and nested-payload matchingTry in playground
QUERY TEXT 'quality'
FROM products
WHERE description MATCH PHRASE 'machine washable'
  AND NESTED('reviews', rating >= 4 AND verified = true)
LIMIT 20;

Filter geographic data

Section titled “Filter geographic data”

Geo predicates accept structured point and shape objects. Latitude, longitude, radius, and polygon structure are validated before planning.

QQLPoints within a radiusTry in playground
QUERY TEXT 'coffee'
FROM places
WHERE location GEO_RADIUS {
  center: {lat: 52.52, lon: 13.405},
  radius: 1500.0
}
LIMIT 10;
QQLA geographic bounding boxTry in playground
QUERY TEXT 'museum'
FROM places
WHERE location GEO_BBOX {
  top_left: {lat: 52.54, lon: 13.36},
  bottom_right: {lat: 52.49, lon: 13.45}
}
LIMIT 10;

GEO_POLYGON matches points inside an exterior ring and optionally excludes holes in interiors. Every ring needs at least three points. Latitudes are validated to [-90, 90], longitudes to [-180, 180], and radii must be positive — all before planning.

QQLA polygon with an interior holeTry in playground
QUERY TEXT 'territory'
FROM places
WHERE location GEO_POLYGON {
  exterior: [
    {lat: -70.0, lon: -70.0},
    {lat: 60.0, lon: -70.0},
    {lat: 60.0, lon: 60.0},
    {lat: -70.0, lon: 60.0}
  ],
  interiors: [
    [
      {lat: -50.0, lon: -50.0},
      {lat: 50.0, lon: -50.0},
      {lat: 50.0, lon: 50.0},
      {lat: -50.0, lon: 50.0}
    ]
  ]
}
LIMIT 10;

See Multitenancy for the host-side policy pattern.