GRADUAL_ROLLOUT()

All functions > BUSINESS > GRADUAL_ROLLOUT()

Returns the exposure to a new version based on the given hashing key and rollout parameters.

Signatures

Returns: TRUE if user should see new version at given time

GRADUAL_ROLLOUT(hashing_key: VARCHAR, time_ref: TIMESTAMP, time_0pc: TIMESTAMP, time_100pc: TIMESTAMP, [power: DOUBLE], [chunks: BIGINT]) → BOOLEAN
sql
ParameterTypeRequiredDescription
hashing_keyVARCHARYesString value to hash (typically user ID or session ID)
time_refTIMESTAMPYesReference timestamp to evaluate rollout at
time_0pcTIMESTAMPYesStart time of rollout (0% exposure)
time_100pcTIMESTAMPYesEnd time of rollout (100% exposure)
powerDOUBLENoOptional power curve exponent (default 1.0 = linear)
chunksBIGINTNoOptional number of discrete rollout chunks (default 10)

Notes

  • Deterministic - same key and time always produce same result
  • Gradually increases exposure from 0% to 100% over time period
  • Before time_0pc: 0% exposure (Returns FALSE)
  • After time_100pc: 100% exposure (Returns TRUE)
  • Between times: gradual rollout based on user hash
  • Power parameter controls rollout curve (>1 = slow start, <1 = fast start)
  • Chunks parameter creates discrete rollout steps
  • Useful for controlled feature releases, phased migrations

Examples

FeatureQL
SELECT
    f1 := GRADUAL_ROLLOUT('salt', TIMESTAMP '2025-04-20 14:00:00', TIMESTAMP '2025-04-20 10:00:00', TIMESTAMP '2025-04-20 18:00:00', 1E0, 8) -- Mid-rollout hour with linear curve and eight chunks (example key not yet exposed)
;
Result
f1 BOOLEAN
false

Suggest changes to this page
Last update at: 2026/05/26 17:22:09