Recommendations, Context & Discover

QQL supports three example-driven query modes: RECOMMEND, CONTEXT, and DISCOVER. All use the same QUERY statement with different sub-modes.

RECOMMEND

Find points similar to positive examples and dissimilar to negatives:

-- Positive examples only
QUERY RECOMMEND WITH (positive = ('id-1', 'id-2')) FROM docs LIMIT 5

-- With negatives
QUERY RECOMMEND WITH (positive = ('id-1'), negative = ('id-3')) FROM docs LIMIT 5

-- With strategy
QUERY RECOMMEND WITH (positive = ('id-1')) STRATEGY 'best_score' FROM docs LIMIT 5

Strategies

Strategy	Description
average_vector (default)	Average of positive example vectors
best_score	Best score across positive examples
sum_scores	Sum of scores from all positive examples

With Filters

QUERY RECOMMEND WITH (positive = ('user-click-1', 'user-click-2'), negative = ('user-skip-1'))
  FROM product_catalog
  LIMIT 20
  WHERE availability = 'in_stock' AND price >= 10
  SCORE THRESHOLD 0.5

Cross-Collection Lookup

When your example IDs live in a different collection than your search target:

QUERY RECOMMEND WITH (positive = ('user-click-1', 'user-click-2'))
  FROM product_catalog
  LOOKUP FROM user_interactions VECTOR 'dense'
  USING 'product_dense'
  LIMIT 20

• LOOKUP FROM user_interactions — fetch example vectors from this collection
• VECTOR 'dense' — use the dense named vector from user_interactions
• USING 'product_dense' — search in this named vector space in product_catalog

Common Clauses

QUERY RECOMMEND WITH (positive = ('id-1'))
  FROM <collection>
  [NEGATIVE IDS ('id-neg')]
  [STRATEGY '<strategy>']
  [LOOKUP FROM <other_collection> [VECTOR '<name>']]
  [USING '<vector_name>']
  [WHERE <filter>]
  [SCORE THRESHOLD <float>]
  [LIMIT <n>] [OFFSET <n>]
  [WITH (hnsw_ef = <n>, exact = <bool>)]

---

CONTEXT

Find points that are similar to the positive members and dissimilar to the negative members of each pair, without a specific target:

QUERY CONTEXT PAIRS (('id-1', 'id-2'), ('id-3', 'id-4')) FROM docs LIMIT 5

When to use CONTEXT

Useful for finding items that share the "direction" of positive over negative examples — without anchoring to a specific target point.

---

DISCOVER

Navigate the vector space starting from a target point, guided by context pairs:

QUERY DISCOVER TARGET 'uuid-anchor-item'
  CONTEXT PAIRS (
    ('uuid-positive-1', 'uuid-negative-1'),
    ('uuid-positive-2', 'uuid-negative-2')
  )
  FROM product_catalog
  LIMIT 15
  WHERE category = 'electronics' AND rating >= 4.0
  WITH (hnsw_ef = 128)

Key decisions

• TARGET anchors the search direction.
• CONTEXT PAIRS teach the algorithm what "similar" and "different" mean.
• Useful for exploration: "show me items like these but not like those."

---

When to Use Each

Mode	Use When
NEAREST (default)	Semantic text search
RECOMMEND	"More like these, less like those" by ID
CONTEXT	Directional search without a specific anchor
DISCOVER	Exploration from a seed point with context
ORDER BY	Browse by field value, no similarity
SAMPLE	Random sampling