Dynamic parameters let you parameterize SQL queries with ? placeholders, similar to PrepareStatement in databases. The engine substitutes each placeholder with the corresponding value at query time.
The main benefit is cache efficiency: queries built from the same SQL template improve cache hit rate regardless of the parameter values passed. This means repeated searches with different inputs hit the cache instead of triggering a full query evaluation each time.
Note: Dynamic parameters can only replace values. They cannot replace keywords or field names.
How it works
All ? placeholders in a SQL statement are positional. Pass their values as a nested array using dynamic_params:
dynamic_params:[[value1, value2, ...]]The inner array maps to the ? placeholders in left-to-right order. Because ? carries no type information, use CAST(? AS <type>) to specify the type explicitly.
Examples
Basic type casting and string matching
SELECT i1, cast(? as bigint) FROM t1 WHERE (i2 > 5 AND d3 < 10.1) OR s5 = ?dynamic_params:[[10, "str5"]]The first ? receives 10 (cast to BIGINT), and the second receives "str5" (a string).
Geospatial search with full-text matching
SELECT
price,
title,
compute(
longitude,
latitude,
city_id,
CAST(? AS double),
CAST(? AS double),
CAST(1 AS bigint)
) AS distance
FROM
store,
unnest(store.sub_table)
WHERE
MATCHINDEX('shop', ?)
AND QUERY(name, ?)dynamic_params:[[119.98844256998,
36.776817017143,
"excellect",
"fruit OR watermelon"]]The four ? placeholders receive values in order: longitude (DOUBLE), latitude (DOUBLE), the MATCHINDEX search term, and the QUERY expression. CAST(1 AS bigint) is a literal — not a placeholder — and is not included in dynamic_params.
Limitations
?placeholders can only replace values, not SQL keywords or field names.Each
?is matched by position.