Skip to main content

Crate kimberlite_query

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)

  • WHERE with comparison predicates (=, <, >, <=, >=, IN)

  • ORDER BY (ascending/descending)

  • LIMIT

  • GROUP BY with aggregates (COUNT, SUM, AVG, MIN, MAX)

  • HAVING with aggregate filtering

  • UNION / UNION ALL

  • DISTINCT

  • ALTER TABLE (ADD COLUMN, DROP COLUMN)

  • Parameterized queries ($1, $2, …)

  • WITH (Common Table Expressions / CTEs)

  • Subqueries in FROM and JOIN (SELECT * FROM (SELECT ...) AS t)

Not yet supported:

  • WITH RECURSIVE
  • Window functions

§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
)?;

Modules§

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.
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.
ParsedAlterTable
Parsed ALTER TABLE statement.
ParsedColumn
Parsed column definition.
ParsedCreateIndex
Parsed CREATE INDEX statement.
ParsedCreateMask
Parsed CREATE MASK <name> ON <table>.<column> USING <strategy> 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.
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 / UNION ALL statement.
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§

DataType
SQL data types supported by the query engine.
HavingCondition
A condition in the HAVING clause.
HavingOp
Comparison operators for HAVING conditions.
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.
TimeTravel
Time-travel coordinate extracted from a SQL string.
Value
A typed SQL value.

Functions§

execute
Executes a query plan against the current store state.
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.