Skip to main content

Module expr

Module expr 

Source
Expand description

Scalar expression evaluator: turns an Expr into a Value under a row context (column -> value) and a parameter binding.

Modules§

bit_string
SQL bit-string input, length constraints and output over Core’s packed values.
composites
Composite type values through the statement’s catalog: attribute metadata, record_in input and the coercion of rows and records to a composite type.
datums
Read retained physical scalar bytes only when a SQL operation observes the value. Type inspection, copying and NULL tests do not invoke this decoder.
enums
Enum label input and output, ordered label functions and I/O casts through the statement’s catalog.
variadic_any
Built-ins declared VARIADIC "any": an explicit VARIADIC array argument supplies the variadic values element by element, flattening every dimension, as PostgreSQL’s extract_variadic_args does.

Structs§

CanonicalMultirange
CanonicalRange
CatalogCastScope
An immutable catalog’s identity for already bound or schema-qualified type names. A hook must replace this identity when those names can resolve differently; unqualified search-path-dependent names are excluded by the SQL owner.
CompiledLikePattern
A LIKE/ILIKE pattern compiled once for repeated evaluation. ASCII values use a byte matcher; Unicode retains character-oriented _ semantics. ILIKE matches the input collation’s lowercase forms of the input and of the whole pattern, as PostgreSQL’s Generic_Text_IC_like does.
DateOrderScope
Restore the calling thread’s date order when the input scope ends.
EngineValueCatalog
Adapt a scalar context without requiring embedders that only provide domain or composite metadata to implement enum support.
EvalContext
IntervalFields
The months, days and microseconds of an interval.
IntervalStyleScope
Restore the invoking thread’s interval input/output style on every exit.
RangeBoundValues
RangeValueDescriptor
RegexCache
A logical session’s bounded regular-expression cache. The supplied allowance owns pattern keys, cache slots and compiled contexts. Active calls temporarily remove their entry so independent workers never serialize matching on this lock. In-flight entries remain charged; at most 32 completed patterns are retained.
RegexCacheScope
Enter a session’s cache on this thread, restoring its caller on every exit.
RegexMatches
The rows of one regexp_matches call. Like PostgreSQL’s first call, preparing the cursor finds every match; the cursor owns the input’s code points and the match spans, so a caller can draw each row under its own control.
RegexSplit
The pieces of one split. Preparing the cursor finds every match; the cursor owns the input’s code points and the match spans, so a caller can draw each piece under its own control.
ResolvedCast
A conversion’s immutable selection, without retaining a row value or a catalog decision.
ResolvedNumericOperator
A selected builtin numeric operation. Every evaluation still converts all operands in order and uses the invoking memory and cancellation controls.
RetainedCatalogCast
Successfully resolved metadata for one expression’s fixed source/target spellings. Owned descriptors retain their original production allowances; values, input routines, domain checks and session settings remain per evaluation.
SQLRecordFields
Record values and declared field identities from one pinned catalog generation. Constructing the view does not read or copy any field value.
SQLRecordView
A record selected by its declared SQL type. Physical values use the tuple’s actual type, while anonymous rows keep their producer’s field identities. This short-lived view borrows the invoking catalog scope and invokes no input callbacks.
ScopedCastResult
The original conversion result and optional immutable metadata, never a cached row value.
StatementCancellationScope
Runs the current thread under one statement’s cancellation until it drops, restoring the enclosing statement’s so nested statements and workers return to their caller’s.
TemporalInputContext
A copyable context passed from a statement to its workers. Entering it reproduces every captured input exactly, including the absence of a transaction clock, so a thread never keeps an earlier statement’s clock.
TemporalInputScope
TransactionClockScope
Enters a transaction start for the current thread until it drops, restoring the clock entered before it. The engine enters its transaction timestamp at every statement boundary, and the parallel executor enters the dispatching thread’s clock on each worker.

Enums§

BTreeInput
A borrowed input in the selected class’s equality domain. Arrays retain their shape even when the original carrier is an atomic catalog vector. Image records keep a distinct observation contract.
FloatWidth
IntegerWidth
NumericCast
An immutable builtin numeric conversion selected from resolved source and destination identities.
RangeBoundsInput
A host constructor supplies already converted endpoints. An absent bound is unbounded; an empty range invokes neither endpoint input nor canonical support.
RangeComparisonValue
Admitted range bounds shared by comparison and exact SQL equality-key consumers. Parsing and normalization retain the caller’s reservations until this value is released.
RowKeySpace
Read-only row interface used by the expression evaluator. Most callers use a materialised ResultRow, while hot execution paths can expose a projected value slice without rebuilding a string-keyed map for every row. The address space of a row lookup’s column keys.

Traits§

CatalogInputFunctions
Catalog input needed after analysis selects a type for an unknown literal. Domain array input includes each element’s constraints, so the caller must retain this value rather than read the text again at execution.
EngineHook
Engine-side hook that scalar function evaluation calls for stateful sequence and user-defined functions. Query-valued expressions are not accepted here: lowering assigns them physical query-plan slots executed by uqa-execution::ScalarSubqueryRunner.
RangeConstruction
Operations selected by the range definition, independently of its endpoint layout. Invocation state and effects belong to the caller; observation never uses this interface.
RowLookup
SQLValueCatalog
Type metadata and enum support used to observe already admitted SQL values. Implementations borrow one statement catalog generation and never invoke type input.

Functions§

array_dimensions
Return every dimension of a rectangular array value.
array_transform_argument_positions
Map call-order arguments onto the declared array_sort and array_reverse slots. None means the arity or a named argument does not select a catalogued overload.
array_transform_argument_positions_with_control
array_value_to_string
bound_scalar_function_strictness
Return the PostgreSQL 18 strictness contract selected by a structural function binding. Parser-owned syntax and overload-specific built-ins must be classified by FunctionDispatch, never by their diagnostic display label.
builtin_named_args
Reorder a built-in call’s named arguments into declared positions, or None when the function has no such signature.
builtin_scalar_function_strictness
call_argument_name
Borrow the name attached to a supplied call argument without evaluating its value.
call_argument_value
Return a call argument’s value expression after stripping named and explicit VARIADIC syntax markers.
cast_value
Cast a value to the named SQL type, mirroring CAST(expr AS ty). Types outside the engine’s coercion surface return SQLError::Unsupported.
cast_value_from
Cast a value while preserving an explicitly declared source type when the runtime carrier erases it. PostgreSQL 18 integer-to-bytea/oid casts and xid cast rejection require the source’s declared identity.
cast_value_from_with_control
cast_value_with_numeric_resolution_with_control
Return an immutable numeric conversion when the ordinary catalog-aware cast selected one. Callers may retain it only within the same prepared expression and type-schema scope; the first evaluation keeps the original resolution, callback and failure order.
cast_value_with_resolution_with_control
Return the builtin scalar selection reached by an ordinary successful conversion. The caller may reuse it only for the same immutable expression and type-schema identity with explicit builtin type names.
cast_value_with_scoped_resolution
Resolve both names at their original boundary and retain the successful descriptors only while an explicit immutable catalog capability remains valid. Hooks without that capability keep live name resolution.
cast_value_with_type_resolution
Cast a value after resolving catalog-owned types and enforcing domain constraints before exposing a base-type carrier.
cast_value_with_type_resolution_with_control
Resolve catalog inputs at their external handoff, then admit SQL-owned names, element conversions and output before constructing them.
catalog_output_required
A value whose text is owned by the SQL catalog reached a context-free conversion. Catalog-aware callers render these carriers before delegating here.
check_constant_similar_translation
Translate the SQL form’s constant pattern and escape while planning. PostgreSQL inlines substring(text, text, text) and folds a constant similar_to_escape call, so its errors surface even when no row is read; the call itself is unchanged.
check_statement_cancellation
Report the running statement’s cancellation with the reason its token was canceled for, or Ok while it may continue. Work outside any statement has no cancellation to observe and continues.
clock_timestamp_micros
Read the platform wall clock as Unix microseconds.
coercion_type_name
compare_btree_inputs_with_catalog_and_control
Invoke the selected native B-tree comparison over admitted inputs. This shares scalar, array and record owners; it does not execute input, domain checks or range canonicalization. Pattern support explicitly ignores the invoking collation, while ordinary record fields retain their own descriptors.
compare_btree_inputs_with_invocation_state
The selected support function’s private state is distinct from the shared type support used by nested array and record fields. Its caller retains this state for the support function’s lifetime.
compare_grouping_values_with_enum_catalog
Order internal equality groups by physical enum identity, including nested keys. This ordering is not exposed as SQL ORDER BY and never observes an enum label merely to eliminate duplicates.
compare_nullable_with_control
compare_record_images_with_catalog
Compare admitted records using PostgreSQL’s image support function. Reached field identities and arity share ordinary record comparison’s lazy checks; field images use the existing controlled SQL Datum codec.
compare_selected_grouping_values_with_catalog
Preserve selected scalar types in internal equality grouping, retaining enum identity order rather than observing labels.
compare_selected_values_with_catalog
Compare an admitted ordering key under its selected SQL type. The caller controls top-level NULL placement; this never infers a range type from a string.
compare_typed_values_with_catalog_and_collation
Compare already-bound values with the selected collation. Arrays carry it to their elements; record fields select their retained descriptors independently. NULL placement and unreached fields preserve the ordinary comparison’s lazy behavior.
compare_typed_values_with_control
Compare already-bound values, preserving type operator failures and total container NULL semantics. Callers supply top-level NULL placement and must apply operator-selected casts first.
compare_typed_values_with_enum_catalog
Compare one physical ordering key with its private scalar enum call state. Nested array/record fields use the catalog’s shared type comparison state.
compare_unicode_with_control
Compare the deterministic PostgreSQL unicode built-in (root ICU, tertiary strength, normalization checking off). Byte-distinct strings retain distinct equality classes even when their Unicode weights match.
compare_with_control
Compare with the existing two-valued selector convention that SQL UNKNOWN sorts as equal.
construct_array_with_control
Form ARRAY expression output from already selected scalar element metadata. Domain input has already run in each evaluated expression; retaining an array-valued scalar must not run it again.
core_value_to_json
Enum carriers need catalog label output and are rejected rather than rendered from their storage key.
current_regex_cache
Capture the current session cache for a worker. Outside a session, no cache survives the call and the ordinary resource contract is unchanged.
declared_multirange_datum_with_control
The caller supplies an already normalized multirange; serialization neither sorts members nor invokes canonicalization.
declared_range_datum_with_control
Preserve a completed range’s identity and admitted bounds in the physical carrier, without repeating any selected construction operation.
equal_selected_values_with_catalog
Compare equality keys with their selected scalar type, including SQL grouping’s equal NULLs.
equal_selected_values_with_engine
Evaluate a selected SQL equality predicate with its invoking session. Unlike grouping keys, cross-type datetime operands can require the session timezone.
equal_typed_values_with_catalog_and_collation
Equality uses the same reached collation diagnostics; every fixed built-in is deterministic, so successful equality retains byte equivalence without computing unused Unicode weights.
equal_typed_values_with_enum_catalog
Compare already-bound group/hash keys without enum output. Physical enum identities use the same equality as enum_eq, including inside containers.
eval
Evaluate a value-producing AST expression against one row and parameter context.
eval_array_access_with_catalog_and_control
The value catalog interprets an admitted physical array after every reached bound has evaluated. It never repeats array or element input.
eval_array_access_with_control
The caller owns expression scheduling and input guards; SQL owns NULL reachability, bound conversion and selected array output.
eval_binary_values
Apply a binary SQL operator to values that have already been evaluated. Execution engines use this when a hot path compiles expression traversal ahead of time but must retain the evaluator’s exact comparison, numeric promotion, NULL, overflow, and division-by-zero semantics.
eval_binary_values_with_control
Evaluate the existing binary operator while owning every value producer and comparison workspace under one allowance.
eval_binary_values_with_engine
Evaluate already produced operands with their selected integer width and live session inputs.
eval_binary_values_with_integer_width
Evaluate an operator while retaining the integer type selected by SQL operator resolution. The dynamic Value carrier stores all integers as i64, so expression plans pass this width alongside the operands.
eval_binary_values_with_integer_width_with_control
Preserve the selected integer width without separating an allocated result from its owner on errors.
eval_bound_builtin_function_call
Evaluate a call’s argument list, unwrapping name => value
eval_builtin_function_call
Execute a call whose stored binding selects a built-in routine. Dynamic runtime callbacks and SQL routines must not override this stable binding.
eval_builtin_function_call_with_control
Execute SQL-owned native built-ins with admitted arguments and the caller’s catalog/comparison context. Session and user-function callbacks keep their separate execution boundaries.
eval_comparison_truth
Compare two values without allocating an intermediate Value::Bool. None represents SQL UNKNOWN, including an undecided anonymous row comparison.
eval_comparison_truth_with_control
Evaluate the same three-valued comparison while admitting the native numeric, JSONB and array comparison workspace to the caller’s allowance.
eval_comparison_truth_with_deferred_state
Primitive scalar comparisons need no catalog or private enum call state. Resolve that state only when the evaluated carriers require the general comparison path; operand evaluation and its SQL ordering remain the caller’s responsibility.
eval_comparison_truth_with_engine
Borrow physical type metadata from scalar hooks even when the embedder provides no enum capability.
eval_comparison_truth_with_enum_catalog
Observe scalar and nested enums through the caller’s catalog, preserving private scalar/row call state, shared type support state and ordinary three-valued rules.
eval_distinct_boolean
Evaluate Boolean nodes synthesized by DISTINCT syntax. Unlike written Boolean contexts, their already-Boolean field comparisons may contain set-returning inputs. Row comparisons retain PostgreSQL’s left-to-right short circuit.
eval_float_arithmetic
Apply arithmetic at its resolved float width before widening the storage carrier.
eval_float_arithmetic_with_control
Evaluate the same width-specific arithmetic with controlled numeric coercion workspace. The resulting float carrier is inline.
eval_function_call
Execute a scalar function after its argument expressions have already been evaluated.
eval_generated_function_call_with_control
Execute a built-in selected by generated-column validation. This boundary has no session, host-function or query callbacks; general runtime dispatch remains with eval_function_call. Argument values arrive already admitted by their producers.
eval_numeric_operator
eval_numeric_operator_with_control
Evaluate the existing selected numeric overload while casts, type names and intermediate values remain owned by the original allowance.
eval_numeric_operator_with_resolution
Evaluate before retaining an immutable builtin numeric selection. Unknown, domain and other catalog-defined operands preserve their original conversion path.
eval_record_comparison_truth_with_engine
Compare record operands selected by SQL syntax. A record-valued column, cast or parameter retains record field operators even when its carrier is an anonymous Row; only two uncast ROW constructors select three-valued row comparison.
eval_value_comparison_truth_with_engine
Compare complete SQL values selected by a consumer such as CASE, NULLIF or ANY. Anonymous record carriers retain record operators; three-valued ROW constructor comparison is selected separately by expression syntax.
evaluate_call_args
Return the PostgreSQL 18 strictness contract for a built-in scalar call when its implemented overload is known.
format_real
Format a real value using PostgreSQL’s shortest decimal and exponent thresholds.
format_regtype_value
Format a scalar or array OID carrier using the catalog-aware output function of a reg* type. None means the declared type is not one of the supported alias types or the value is SQL NULL.
format_regtype_value_with_control
Retain a resolver’s returned spelling and construct SQL-owned array and fallback text under the invoking allowance.
format_uuid_with_control
Format network-order UUID octets as canonical text under the original production allowance.
in_range
in_range(val, base, offset, sub, less) for a non-null val and base of one ordering type and an offset of the type transformFrameOffset selected for it.
in_range_with_engine
Apply the ordering family’s frame predicate with live session calendar arithmetic.
integer_width_for_literal
integer_width_for_type
internal_char_byte
Observe an admitted internal-character carrier without applying text input conversion.
internal_char_value_with_control
Construct an internal-character carrier from its complete unsigned byte domain.
invalid_boolean_input
The error boolin reports for text that is not a boolean.
invalid_numeric_input
The error numeric_in reports for text it cannot read.
json_strip_nulls_argument_positions
Map call-order arguments onto the declared (target, strip_in_arrays DEFAULT false) slots. None means the arity or a named argument does not select either catalogued overload.
multirange_from_ranges
multirange_from_ranges_with_operations
Normalize already constructed members without repeating their input or canonical calls. Every union invokes the selected canonical operation once, as range construction does.
multirange_value_from_members_with_control
negate_value
Apply PostgreSQL prefix - while retaining the operand’s declared type.
negate_value_with_control
parse_boolean_input
boolin: PostgreSQL’s parse_bool over trimmed text, accepting case-insensitive prefixes of true, false, yes and no, on, at least two letters of off, and 1 and 0.
parse_multirange
parse_multirange_with_operations
Parse each member through the same range constructor before sorting and joining overlapping or adjacent members.
parse_pg_array_literal
Parse a PostgreSQL array literal ({1,2,3}, {"a b",NULL}, {{1,2},{3,4}}) into nested lists of string/NULL values; the caller casts elements.
parse_pg_array_literal_with_control
parse_range
parse_range_with_operations
Parse complete range syntax, then input the lower and upper endpoints in order. Already empty input does not invoke endpoint or canonical functions.
parse_uuid_bytes
Parse every UUID input spelling accepted by PostgreSQL into network-order bytes.
parse_uuid_bytes_with_control
Parse PostgreSQL UUID input under the invoking cancellation scope without allocating a payload.
quote_ident
Double-quote unless the identifier starts with a lowercase letter or an underscore, holds only lowercase letters, digits and underscores, and is not a keyword other than an unreserved one (quote_identifier).
quote_ident_with_control
quote_json_string_with_control
Quote borrowed UTF-8 with the native JSON string escaper, charging output and bounded scratch to the invoking allowance.
quote_literal_with_control
Single-quote with doubled quotes; backslashes select the escaped-literal form.
range_bound_flags
Validate a range constructor’s explicit flags argument. The two-argument constructor supplies Some("[)"); SQL NULL remains an error.
range_from_bounds_with_operations
Construct from already coerced, admitted, non-NULL endpoints; None represents an unbounded endpoint. This does not repeat endpoint input or domain checks. Bounds are validated before the optional canonical call; the canonical result is returned without a second call or validation pass.
range_value_from_bounds_with_control
read_catalog_array_input
Read an array whose elements are domains with the same input and constraint path as a catalog-aware cast. The resolved target preserves domain identity; a scalar outer domain remains the surrounding expression’s runtime coercion.
read_catalog_input
Read a catalog-dependent constant once, retaining its typed datum in stored syntax.
read_catalog_input_with_control
sql_null_test_with_control
SQL row NULL tests inspect the current live fields while preserving deferred scalar reads.
statement_cancellation
The running statement’s cancellation token, which a thread dispatching part of the statement to a worker captures for the worker to enter; None outside any statement.
temporal_date_order
temporal_interval_style
transaction_clock_micros
The transaction start entered for the current thread, or None outside any statement.
truthy
Whether a condition holds. NULL does not; text, which reaches a condition only as an unknown literal or parameter, holds when boolin reads it as true (parse analysis rejects any other text); the engine’s numeric retrieval predicates hold when non-zero.
type_comparison_can_fail
Declared SQL keys whose runtime values may require a fallible comparison operator.
unknown_function_error
function name(arg types) does not exist - the error PostgreSQL raises when call resolution fails (SQLSTATE 42883).
validate_json_object_key_type
JSON object keys must be scalar SQL datums, including when an array-shaped catalog vector has a distinct runtime carrier. Each constructor retains its own NULL-key diagnostic.
validate_json_object_key_type_with_catalog
validate_legacy_vector_comparison
Validate the layout required by the oidvector scalar equality, ordering and hashing operators. Array operators on int2vector permit dimensionless arrays.
validate_named_argument_order
Enforce PostgreSQL function-call ordering before overload resolution. Positional arguments must precede named arguments, and each explicit name may occur only once.
validate_named_argument_order_with_control
value_comparison_can_fail
Whether an opaque value key can suppress a SQL operator failure. A single such input remains legal until an operator compares it.
value_to_json_text
Render an engine value as PostgreSQL JSON input text without losing the lexical representation of values already typed as json or jsonb.
value_to_json_text_with_catalog
Render admitted composite, array and enum values through the observing statement’s catalog.
value_to_string
Produce SQL text, including errors from type output functions.
value_to_string_with_control
value_to_tensor
Coerce a Value into a tensor: an array of homogeneous numeric vectors. Used by TENSOR(N) columns to store chunk embeddings for one row while still indexing each vector element.
value_to_tensor_with_control
value_to_text
value_to_text_with_control
value_to_vector
Coerce a Value into a Vec<f32> if it is a homogeneous numeric list (used to read vector literals from ARRAY[...] or $N Vector params).
value_to_vector_with_control
value_type_name
values_equal_nullable_with_control
values_equal_with_control
variadic_argument_value
Return the value expression carried by an explicit VARIADIC marker, including one nested inside a named argument.
vector_value_to_string
PostgreSQL’s legacy vector text format separates values with spaces.
visit_record_image_fields_with_catalog
Visit each live field’s selected identity and admitted image, with None for NULL. The callback borrows each image only while its controlled owner remains live. Execution owns framing and exact-key production; observation invokes no field operators or type input.
with_btree_input
Observe one already admitted bound under its selected class. The callback cannot outlive physical decoding or a required carrier projection; unchanged values and vector arrays are borrowed. Collation and support invocation remain the consuming operation’s responsibility.
wrap_variadic_argument
Wrap the last actual argument of an explicit VARIADIC invocation while preserving a named-argument marker at the top level.