BOOST Expression Reference

BOOST Expression

Score Shaping Qdrant Score Builder API

The BOOST clause applies a mathematical expression to each result's score. Expressions are compiled to Qdrant's Score Builder API and evaluated server-side.

Syntax

QUERY '<text>' FROM <collection> LIMIT <n>
  BOOST (<expression>)
  [DEFAULTS (var = <float>, ...)]

Variables

Variable	Type	Description
`$score`	float	The relevance score from the retrieval stage
`<field_name>`	any	A payload field value (e.g., `popularity`, `year`)

Arithmetic Operators

Operator	Description	Example
`+`	Addition	`$score + 0.5`
`-`	Subtraction	`$score - penalty`
`*`	Multiplication	`$score * 2.0`
`/`	Division	`$score / views`
`/ [default=v]`	Division with zero-safety	`$score / views [default=1.0]`

Math Functions

Function	Description
`ABS(x)`	Absolute value
`SQRT(x)`	Square root
`LOG(x)`	Base-10 logarithm
`LN(x)`	Natural logarithm
`EXP(x)`	Exponential (e^x)
`POW(base, exp)`	Power function

BOOST (SQRT($score) * LOG(citation_count + 1))
BOOST (EXP($score) * ABS(distance))
BOOST (POW($score, 2))

Geo Distance

-- Positional syntax
GEO_DISTANCE(lat, lon, field)

-- Dict syntax (recommended)
GEO_DISTANCE({'lat': 48.8566, 'lon': 2.3522}, location)

Returns the haversine distance in meters from a fixed coordinate to a payload geo field.

BOOST ($score * GAUSS_DECAY(GEO_DISTANCE({'lat': 48.8566, 'lon': 2.3522}, location), 0.0, 5000.0, 0.5))

Decay Functions

All decay functions take a numeric input and return a value in the 0..1 range.

Function	Curve
`GAUSS_DECAY(x, target, scale, midpoint)`	Gaussian bell curve
`EXP_DECAY(x, target, scale, midpoint)`	Exponential decay
`LIN_DECAY(x, target, scale, midpoint)`	Linear decay

Parameters

Parameter	Description
`x`	The input value (field name or expression)
`target`	The optimal value — decay is 1.0 at this point
`scale`	Distance/time at which the decay reaches `midpoint`
`midpoint`	Decay factor at `target ± scale` (default: `0.5`)

Keyword Argument Syntax (Recommended)

GAUSS_DECAY(field, target: 0.0, scale: 5000.0, midpoint: 0.5)
EXP_DECAY(field, scale: 86400, midpoint: 0.5)
LIN_DECAY(field, target: datetime('2026-01-01'), scale: 30d)

Positional Syntax

GAUSS_DECAY(field, 0.0, 5000.0, 0.5)

Datetime Expressions

Expression	Description
`datetime('2026-01-01T00:00:00Z')`	Parse a literal ISO 8601 datetime
`datetime_key('field')`	Read a payload field as datetime

BOOST (
  $score + exp_decay(
    datetime_key('published_at'),
    target=datetime('2026-06-17T00:00:00Z'),
    scale=86400,
    midpoint=0.5
  )
)

Conditional (CASE WHEN)

CASE WHEN <filter> THEN <expr> ELSE <expr> END

Supports the full WHERE filter syntax in the condition:

BOOST (
  CASE WHEN priority = 'high' THEN $score * 2.0
  ELSE CASE WHEN status = 'deprecated' THEN $score * 0.5
  ELSE $score END END
)

DEFAULTS

Provides fallback values for payload fields that may be missing:

BOOST ($score + 0.3 * popularity + 0.1 * freshness)
DEFAULTS (popularity = 0.0, freshness = 0.0)

Complete Examples

-- Linear score amplification
BOOST ($score * 2 + 1)

-- Citation-weighted search
BOOST (SQRT($score) * LOG(citation_count + 1))
DEFAULTS (citation_count = 0)

-- Geo proximity decay
BOOST (
  $score * gauss_decay(
    geo_distance({'lat': 48.8566, 'lon': 2.3522}, location),
    scale=5000, midpoint=0.5
  )
)

-- Time freshness decay
BOOST (
  $score + exp_decay(
    datetime_key('published_at'),
    target=datetime('2026-06-17T00:00:00Z'),
    scale=86400
  )
)

-- Conditional category boost
BOOST (
  CASE WHEN category = 'premium' THEN $score * 2.0
  ELSE CASE WHEN status = 'deprecated' THEN $score * 0.5
  ELSE $score END END
)

-- Combined signals
BOOST (
  $score
  + exp_decay(datetime_key('updated_at'), target=datetime('2026-06-17T00:00:00Z'), scale=86400)
  + CASE WHEN priority = 'critical' THEN 0.5 ELSE 0 END
)

-- Venue bonus (hybrid + BOOST)
BOOST (
  $score + 0.2 * CASE WHEN venue IN ('NeurIPS', 'ICML', 'ICLR') THEN 1.0 ELSE 0.0 END
)