Module utils 

Shared utility functions for the executor module.

This module provides common utilities used across the executor:

• Token creation for internal AST construction
• Value-to-Expression conversion
• Row combination for JOIN operations
• Value hashing and comparison
• Column index map building

Structs

JoinProjectionIndices

Result of computing join projection indices. Contains the column sources in SELECT order to satisfy the SELECT expressions.

Functions

add_table_qualifier

Add table qualifier to an expression, converting simple identifiers to qualified ones. Used when applying filters post-join that were originally stripped for pushdown.

build_column_index_map

Build a column name to index map for fast column lookups. Column names are lowercased for case-insensitive matching. Also adds unqualified base names as fallbacks for qualified columns (e.g., “t.val” also registers “val”) when the base name is unambiguous.

collect_table_qualifiers

Extract all table qualifiers (aliases) referenced in an expression. Returns a set of lowercase table names/aliases.

combine_predicates_with_and

Combine predicates with AND operator. Returns None if the input is empty.

combine_rows

Combine two rows into one for join output.

combine_rows_with_nulls

Combine a row with NULLs for the other side (used in OUTER JOINs).

compare_values

Compare two Values for ordering.

compute_join_projection

Compute projection indices for a join operator.

dummy_token

Helper to create a dummy token for internal AST construction. Use dummy_token_clone() when literal doesn’t matter to avoid allocation.

dummy_token_clone

Clone the static dummy token (single String allocation for empty string).

dummy_token_ref

Get a reference to a pre-allocated dummy token (zero allocation).

expression_contains_aggregate

Check if an expression contains an aggregate function. Used for detecting nested aggregates and determining query structure.

expression_has_parameters

Check if an expression contains any Parameter nodes ($1, $2, etc.) Parameterized queries cannot be semantically cached because the cache stores results tied to specific parameter values, but the AST only contains parameter indices, not values.

expression_to_string

Convert expression to string representation. Used for expression alias matching and display purposes.

expressions_equivalent

Check if two expressions are structurally equivalent. Used for semantic matching and predicate comparison.

extract_and_conditions

Extract all AND-ed conditions from an expression as references. Similar to flatten_and_predicates but returns references.

extract_base_column_name

Extract the base (unqualified) column name from a potentially qualified column name. For “table.column” returns “column”, for “column” returns “column”. The result is always lowercase for case-insensitive comparisons.

extract_column_name

Extract the column name from an Identifier or QualifiedIdentifier expression. Returns the column name without table qualifier.

extract_column_name_with_qualifier

Extract column name from identifier expression with optional qualifier. Returns (qualifier, column_name) where qualifier is Some for qualified identifiers. Column names are returned in lowercase for case-insensitive matching.

extract_join_keys_and_residual

Extract equality join keys and residual conditions from a join condition.

extract_literal_value

Extract a literal value from an expression. Converts AST literal expressions to runtime Values. Note: double-quoted identifiers are NOT treated as literals here. They may refer to actual column names, so pushdown should not assume they are string constants. The VM/compiler handles them correctly via column-resolution-first-then-string-fallback.

filter_references_column

Check if a filter expression references a specific column (the join key). Returns true if the filter’s main column matches the target column name. Handles IN, comparison, BETWEEN, LIKE, function calls, and nested expressions.

find_column_index

Find column index in column list, handling qualified names. Supports exact match and qualified match (table.column).

flatten_and_predicates

Flatten AND predicates into a list of individual predicates. E.g., a AND b AND c becomes [a, b, c].

flip_operator

Flip a comparison operator for when column and value are swapped. E.g., 5 > col becomes col < 5.

get_table_alias_from_expr

Get table alias from a table expression. Returns the alias if specified, otherwise the table name.

hash_composite_key

Hash multiple key columns into a single hash value. Used heavily in hash joins - called on every row during build and probe phases. Uses FxHasher which is optimized for trusted keys in embedded database context.

hash_row

Hash all values in a row into a single hash value. Used for DISTINCT operations and set operations (UNION, INTERSECT, EXCEPT). Uses FxHasher which is optimized for trusted keys in embedded database context.

hash_value_into

Hash a single value into an existing hasher.

infix_to_operator

Convert AST InfixOperator to core Operator. Returns None for operators that don’t map to comparison operators.

is_aggregate_function

Check if a function name is an aggregate function. Uses the function registry to determine this.

is_sorted_on_keys

Check if rows are sorted in ascending order on the specified key indices.

parse_vector_dimension

Parse vector dimension from a type string like “VECTOR(768)”. Returns 0 if no dimension is specified.

rows_equal

Compare two rows for equality. Returns true if both rows have the same length and all values are equal.

string_to_datatype

Convert type string to DataType. Handles common SQL type names like INTEGER, VARCHAR, BOOLEAN, etc.

strip_table_qualifier

Strip table qualifier from an expression, replacing qualified identifiers with unqualified ones. Used when pushing filters to individual table scans.

substitute_filter_column

Substitute a column reference in a filter expression with a new column name. This is used for join key equivalence: when filter o.user_id IN (1,2,3) can be transformed to u.id IN (1,2,3) based on join condition u.id = o.user_id.

substitute_outer_references

Substitute outer references in an expression with their actual values.

value_to_expression

Convert a Value to an Expression for use in subquery result replacement and other internal AST manipulation.

values_equal

Compare two Values for equality.

verify_composite_key_equality

Verify that all composite key columns match (handles hash collisions).