Crate kimberlite_query

Source

Expand description

§kmb-query: SQL query layer for `Kimberlite` projections

This crate provides a minimal SQL query engine for compliance lookups against the projection store.

§SQL Subset

Supported SQL features:

SELECT with column list or *
FROM single table or JOIN (INNER, LEFT, RIGHT, FULL OUTER, CROSS, with ON or USING(...) clauses)
WHERE with comparison predicates (=, <, >, <=, >=, IN)
IN (SELECT), NOT IN (SELECT), EXISTS, NOT EXISTS — both uncorrelated (pre-execute fast path) and correlated (semi-join decorrelation or nested-loop fallback; see docs/reference/sql/correlated-subqueries.md)
ORDER BY (ascending/descending)
LIMIT and OFFSET — literal or $N parameter
GROUP BY with aggregates (COUNT, SUM, AVG, MIN, MAX)
Aggregate FILTER (WHERE ...) clauses, independent per aggregate
HAVING with aggregate filtering
UNION / UNION ALL / INTERSECT / INTERSECT ALL / EXCEPT / EXCEPT ALL
DISTINCT
JSON operators ->, ->>, @> in WHERE clauses
CASE (searched and simple form)
WITH (Common Table Expressions / CTEs), including WITH RECURSIVE via iterative fixed-point evaluation (depth cap 1000)
Subqueries in FROM and JOIN (SELECT * FROM (SELECT ...) AS t)
Window functions (OVER, PARTITION BY, ROW_NUMBER, RANK, DENSE_RANK, LAG, LEAD, FIRST_VALUE, LAST_VALUE)
ALTER TABLE (ADD COLUMN, DROP COLUMN) — parser only; kernel execution pending
Parameterized queries ($1, $2, …) in WHERE, LIMIT, OFFSET, and DML values
Scalar functions in SELECT projection and WHERE predicates: UPPER, LOWER, LENGTH, TRIM, CONCAT, ||, ABS, ROUND, CEIL/CEILING, FLOOR, COALESCE, NULLIF, CAST
ILIKE, NOT LIKE, NOT ILIKE pattern matching
NOT IN (list), NOT BETWEEN low AND high

Not yet supported:

Scalar subquery WHERE col = (SELECT ...), ANY, ALL, SOME
Clock-dependent functions (NOW(), CURRENT_DATE, EXTRACT, DATE_TRUNC) — deferred pending a clock-threading decision
MOD, POWER, SQRT, SUBSTRING — deferred

§Usage

use kimberlite_query::{QueryEngine, Schema, SchemaBuilder, ColumnDef, DataType, Value};
use kimberlite_store::{BTreeStore, TableId};

// Define schema
let schema = SchemaBuilder::new()
    .table(
        "users",
        TableId::new(1),
        vec![
            ColumnDef::new("id", DataType::BigInt).not_null(),
            ColumnDef::new("name", DataType::Text).not_null(),
        ],
        vec!["id".into()],
    )
    .build();

// Create engine
let engine = QueryEngine::new(schema);

// Execute query
let mut store = BTreeStore::open("data/projections")?;
let result = engine.query(&mut store, "SELECT * FROM users WHERE id = $1", &[Value::BigInt(42)])?;

§Point-in-Time Queries

For compliance, you can query at a specific log position:

let result = engine.query_at(
    &mut store,
    "SELECT * FROM users WHERE id = 1",
    &[],
    Offset::new(1000),  // Query state as of log position 1000
)?;

§Scalar expressions (v0.5.1)

The parser accepts scalar functions in SELECT projection and WHERE predicates. Each of these queries parses cleanly and produces a ParsedStatement::Select with either a ScalarCmp predicate or entries in scalar_projections:

use kimberlite_query::{parse_statement, ParsedStatement, Predicate};

// WHERE col NOT IN (list) — mirror of IN, v0.5.1.
let s = parse_statement("SELECT id FROM t WHERE x NOT IN (1, 2, 3)").unwrap();
let ParsedStatement::Select(sel) = s else { panic!() };
assert!(matches!(sel.predicates[0], Predicate::NotIn(_, _)));

// WHERE UPPER(name) = 'ALICE' — scalar LHS routes to ScalarCmp.
let s = parse_statement("SELECT id FROM t WHERE UPPER(name) = 'ALICE'").unwrap();
let ParsedStatement::Select(sel) = s else { panic!() };
assert!(matches!(sel.predicates[0], Predicate::ScalarCmp { .. }));

// SELECT col AS alias — alias preserved end-to-end.
let s = parse_statement("SELECT name AS display FROM t").unwrap();
let ParsedStatement::Select(sel) = s else { panic!() };
let aliases = sel.column_aliases.as_ref().unwrap();
assert_eq!(aliases[0].as_deref(), Some("display"));

// SELECT CAST(x AS INTEGER) — lands in scalar_projections with a
// synthesised output column name.
let s = parse_statement("SELECT CAST(x AS INTEGER) FROM t").unwrap();
let ParsedStatement::Select(sel) = s else { panic!() };
assert_eq!(sel.scalar_projections.len(), 1);
assert_eq!(sel.scalar_projections[0].output_name.as_str(), "cast");

Re-exports§

pub use expression::EvalContext;
pub use expression::ScalarExpr;
pub use expression::evaluate;

Modules§

correlated: Correlated subquery support (v0.6.0).
depth_check: Pre-parse input validation that rejects deeply-nested SQL to prevent DoS attacks that exploit super-linear behavior in the upstream SQL parser on expressions like (NOT(NOT(NOT(...)))).
dml_planner: AUDIT-2026-04 S3.1 — translate parsed DML AST into the wire-event payloads that kimberlite-kernel’s Command::Insert / Command::Update / Command::Delete carry as row_data.
explain: EXPLAIN renderer for query plans.
expression: Scalar expression evaluator (ROADMAP v0.5.0 item A).
information_schema: information_schema virtual tables.
key_encoder: Lexicographic key encoding for B+tree lookups.
rbac_filter: RBAC query filtering and rewriting.
window: AUDIT-2026-04 S3.2 — SQL window functions.

Structs§

ColumnDef: Definition of a table column.
ColumnName: SQL column name.
IndexDef: Definition of a secondary index on a table.
OnConflictClause: Parsed ON CONFLICT (cols) DO ... clause attached to an INSERT.
ParsedAlterTable: Parsed ALTER TABLE statement.
ParsedAttachMaskingPolicy: Parsed ALTER TABLE <t> ALTER COLUMN <c> SET MASKING POLICY <policy> statement.
ParsedColumn: Parsed column definition.
ParsedCreateIndex: Parsed CREATE INDEX statement.
ParsedCreateMask: Parsed CREATE MASK <name> ON <table>.<column> USING <strategy> statement.
ParsedCreateMaskingPolicy: Parsed CREATE MASKING POLICY <name> STRATEGY <kind> [<arg>] EXEMPT ROLES (<r>, ...) statement.
ParsedCreateTable: Parsed CREATE TABLE statement.
ParsedCreateUser: Parsed CREATE USER statement.
ParsedCte: A Common Table Expression (CTE) parsed from a WITH clause.
ParsedDelete: Parsed DELETE statement.
ParsedDetachMaskingPolicy: Parsed ALTER TABLE <t> ALTER COLUMN <c> DROP MASKING POLICY statement.
ParsedGrant: Parsed GRANT statement.
ParsedInsert: Parsed INSERT statement.
ParsedSelect: Parsed SELECT statement.
ParsedSetClassification: Parsed ALTER TABLE <t> MODIFY COLUMN <c> SET CLASSIFICATION '<class>'.
ParsedUnion: Parsed UNION / INTERSECT / EXCEPT statement (with or without ALL).
ParsedUpdate: Parsed UPDATE statement.
PreparedQuery: A prepared (planned) query ready for execution.
QueryEngine: Query engine for executing SQL against a projection store.
QueryResult: Result of executing a query.
Schema: Schema registry mapping SQL names to store types.
SchemaBuilder: Builder for constructing schemas fluently.
TableDef: Definition of a table in the schema.
TableName: SQL table name.

Enums§

AlterTableOperation: ALTER TABLE operation.
DataType: SQL data types supported by the query engine.
HavingCondition: A condition in the HAVING clause.
HavingOp: Comparison operators for HAVING conditions.
OnConflictAction: The action to take when ON CONFLICT (target) fires.
ParsedMaskingStrategy: Parser-level mirror of the kernel’s MaskingStrategyKind. Kept independent of kimberlite-kernel so the query crate does not depend on the kernel; translation happens in the planner.
ParsedStatement: Top-level parsed SQL statement.
Predicate: A comparison predicate from the WHERE clause.
PredicateValue: A value in a predicate (literal or parameter reference).
QueryError: Errors that can occur during query parsing and execution.
ScalarCmpOp: Comparison operator for a Predicate::ScalarCmp.
TimeTravel: Time-travel coordinate extracted from a SQL string.
TimestampResolution: Outcome returned by a timestamp→offset resolver.
UpsertExpr: Expression permitted on the RHS of SET col = <expr> inside ON CONFLICT ... DO UPDATE.
Value: A typed SQL value.

Functions§

execute: Executes a query plan against the current store state.
expr_to_scalar_expr: Translate a sqlparser expression into a ScalarExpr.
extract_at_offset: Extracts AT OFFSET <n> from a SQL string.
extract_time_travel: Extracts a TimeTravel coordinate from a SQL string, covering both AT OFFSET <n> and the SQL:2011 temporal forms FOR SYSTEM_TIME AS OF '<iso8601>' and AS OF '<iso8601>'.
parse_statement: Parses a SQL statement string into a ParsedStatement.
plan_query: Plans a parsed SELECT statement.
try_parse_custom_statement: Attempts to parse custom SQL extensions that sqlparser does not support.

Type Aliases§

Result: Result type for query operations.
Row: A single result row.

Crate kimberlite_query

Crate kimberlite_query Copy item path

§kmb-query: SQL query layer for Kimberlite projections

§SQL Subset

§Usage

§Point-in-Time Queries

§Scalar expressions (v0.5.1)

Re-exports§

Modules§

Structs§

Enums§

Functions§

Type Aliases§

Crate kimberlite_query

§kmb-query: SQL query layer for `Kimberlite` projections