Pagination & Browse

QQL supports multiple patterns for browsing and paginating through points.

ORDER BY — Sort by Field

QUERY ORDER BY sorts by a payload field without vector similarity. It uses Qdrant's OrderBy query variant.

-- Newest first
QUERY ORDER BY created_at DESC FROM articles LIMIT 20

-- Oldest first
QUERY ORDER BY created_at ASC FROM articles LIMIT 20

-- Page 2 (offset-based)
QUERY ORDER BY created_at DESC FROM articles LIMIT 20 OFFSET 20

-- With filter
QUERY ORDER BY created_at DESC FROM articles
  WHERE status = 'published' AND category = 'engineering'
  LIMIT 20 OFFSET 40

Index for Performance

Create an index on the sort field for performance:

CREATE INDEX ON articles FOR created_at TYPE datetime

SCROLL — Cursor Pagination

SCROLL paginates through points using a cursor (point ID offset). It's more efficient than OFFSET for large collections.

-- Page 1
SCROLL FROM docs LIMIT 20

-- Page 2 (using last point ID from page 1)
SCROLL FROM docs AFTER '<point-id>' LIMIT 20

-- With filter
SCROLL FROM docs WHERE topic = 'search' LIMIT 20

-- Filter + cursor
SCROLL FROM docs WHERE category = 'tech' AFTER '<point-id>' LIMIT 20

The response includes a next_offset field (the next cursor). Pass it as AFTER '<next_offset>' to get the next page.

SELECT — Point Lookup by ID

Retrieve a single point by ID without a vector search:

-- UUID
SELECT * FROM docs WHERE id = 'a3f8c2d1-...'

-- Integer ID
SELECT * FROM docs WHERE id = 42

SELECT returns the point's payload but not its vectors. Use WITH VECTORS true in a QUERY statement if you need stored vectors back.

OFFSET — Skip-Based Pagination

OFFSET skips results in a QUERY or SCROLL statement:

QUERY 'vector database' FROM docs LIMIT 10 OFFSET 20
SCROLL FROM docs LIMIT 20 OFFSET 40

GROUP BY Limitation

OFFSET cannot be combined with GROUP BY. For grouped search, use cursor-based pagination.

Pattern Comparison

Pattern	Best For
QUERY ORDER BY ... OFFSET	UI list views, admin panels
SCROLL ... AFTER '<id>'	Exporting data, large collections, ETL
SELECT * WHERE id = ...	Single point lookup by known ID
QUERY ... OFFSET	Paginated similarity search

Payload and Vector Selectors

Control what gets returned to reduce network overhead:

QUERY 'search' FROM docs LIMIT 10
  WITH PAYLOAD (include = ['title', 'summary', 'url'], exclude = ['raw_text'])
  WITH VECTORS ('dense')

Clause	Description
WITH PAYLOAD (include = ['a', 'b'])	Return only these payload fields
WITH PAYLOAD (exclude = ['a', 'b'])	Return all payload except these
WITH PAYLOAD false	Return no payload
WITH PAYLOAD true	Return all payload (default)
WITH VECTORS ('name1', 'name2')	Return specific named vectors
WITH VECTORS true	Return all stored vectors
WITH VECTORS false	Return no vectors (default)