Module params 

Parameter binding for :name / ? placeholders with type-checked substitution. Parameter binding and prepared query substitution.

Provides type-safe substitution of named (:name) and positional (?) parameter placeholders in QQL query text.

Placeholders & Syntax Rules

• Named placeholders: :name (e.g. :category, :limit).
• Positional placeholders: ? (sequential 1-to-1 mapping with parameters list).

In QQL, $ is a first-class identifier character (e.g. $category, $1), so parameter placeholders exclusively use :name and ?. This guarantees that $-prefixed identifiers in queries are never accidentally or silently rewritten.

Furthermore, a colon : is only recognized as a parameter placeholder when it occurs at a valid token boundary (preceded by whitespace, punctuation, or start of query). Colons in compact dictionary syntax (e.g. {a:b}, {'a':b}) are not placeholders and are preserved without modification. Note that unconventional spacing with whitespace before the colon ({a :b}) makes :b lexically indistinguishable from a placeholder.

Literals and dictionary keys are safely formatted and escaped to prevent query injection breakouts. String literals ('...', r'...', """...""", and `...`) and comments (-- ...) in the source query are preserved verbatim and never substituted.

params (typed Value) and params_json (JSON serde_json::Value) are dual contracts that must stay in lockstep: a binding-rule fix in one must be ported to the other. JSON is the host-SDK round-trip; typed Value is the zero-copy FFI fast path (F32Array, packed multivector).

Functions

bind_filter

Recursively bind parameters into a FilterExpr in-place.

bind_formula

Recursively bind parameters into a FormulaExpr in-place.

bind_named

Substitute named parameters (:name) into source.

bind_named_readable

Substitute named parameters (:name) into source, truncating long vector literals for readable preview.

bind_page_spec

Bind parameters into a PageSpec in-place.

bind_point_id

Bind parameters into a PointId in-place.

bind_point_selector

Bind parameters into a PointSelector in-place.

bind_positional

Substitute positional parameters (?) sequentially into source.

bind_positional_readable

Substitute positional parameters (?) sequentially into source, truncating long vector literals for readable preview.

bind_query_expr

Recursively bind parameters into a QueryExpr in-place.

bind_query_input

Recursively bind parameters into a QueryInput in-place.

bind_query_stmt

Recursively bind parameters into a QueryStmt in-place.

bind_shard_key

Bind parameters into a routing ShardKey in-place.

bind_stmt

Bind parameters into a parsed AST Stmt in-place.

bind_value

Recursively bind parameters into an AST Value in-place.

collect_statement_params

Collect all named parameter names and the maximum positional parameter index present anywhere in a statement AST.

escape_str_literal

Escape a string literal for QQL single-quoted representation.

ident_at

ASCII identifier slice at [start, end). Infallible because the scanner only advances over is_ident_start / is_ident_continue bytes.

is_ident_continue

Check if a byte is a valid parameter identifier continue character.

is_ident_start

Check if a byte is a valid parameter identifier start character.

is_placeholder_start

Returns true if the : at byte offset i is at a valid token boundary to begin a parameter placeholder.

resolve_param_u64

Resolve a parameter string (:name or ?N) to a u64.

skip_protected

If bytes[i] begins a comment, string literal, or backtick identifier, returns Some(next_offset) skipping the protected region. Otherwise None.

stmt_has_point_params

Whether an upsert template carries whole-point placeholders (VALUES :p / VALUES ?) needing dict splice at execution time.

truncate_vector_literals

Truncate long numeric vector literals inside a QQL query string for compact preview.

validate_no_unbound_params

Verify that a statement contains no unbound parameters, without cloning the AST.

validate_no_unbound_scalar_params

Verify that a statement contains no unbound scalar parameters, allowing vector parameter placeholders (VectorValue::Param, PointVectors::Param, QueryInput::Param). Returns Ok(true) if vector parameters exist.

value_to_literal

Convert an AST Value into its canonical, safely escaped QQL literal string.