Getting started

Begin with a constructed value in a Cargo project. This example calls Zirql directly, without a domain parser or renderer. The word examples then introduce a small host for queries over native data.

Add a pinned dependency

Development uses pinned Git revisions. This revision contains the native program and constructed-value APIs used below:

[dependencies]
zirql = { git = "https://github.com/zayenz/zirql", rev = "9c3ce81dca3d35cde55b2fba77567d73e431ae54" }

Use Rust 1.88 or newer (the crate uses edition 2024). Keep the revision pin when integrating a host, and review API changes before moving it. Usable alpha packages also exist on crates.io, but they may describe a different revision. The yanked 0.0.0-prerelease name reservation is not an installation target.

Evaluate a small expression

Put this in src/main.rs in a Cargo project with the dependency above:

use zirql::{
    Bindings, Budget, ConstructedValue, Located, ProgramLimits,
    ValueBinaryOperator, ValueExpressionKind, evaluate_value,
};

fn main() -> Result<(), zirql::QueryError> {
    // A frontend would retain the byte ranges from the text "6 * 7".
    let expression = Located::new(
        ValueExpressionKind::Binary {
            operator: ValueBinaryOperator::Multiply,
            left: Box::new(Located::new(
                ValueExpressionKind::Literal(ConstructedValue::Integer(6)), 0..1,
            )),
            right: Box::new(Located::new(
                ValueExpressionKind::Literal(ConstructedValue::Integer(7)), 4..5,
            )),
        },
        0..5,
    );
    let mut budget = Budget::for_program(ProgramLimits {
        work: 1_000, results: 100, nesting: 16, stream_items: 100,
    });
    let value = evaluate_value(&expression, &Bindings::default(), &mut budget)?;
    assert_eq!(value, ConstructedValue::Integer(42));
    println!("{value:?}");
    Ok(())
}

Run cargo run. The result is Integer(42). The limits here are small-example choices, not library defaults. Debug prints the returned Rust value.

The example constructs the expression tree directly in Rust. A text frontend would parse 6 * 7 into the same representation and retain its source ranges. The common pipeline reader accepts the smaller pipeline syntax described in the next guide.

Read API documentation for your revision

cargo doc --open

The published API documentation is useful for looking up names, but check its version against your dependency. Continue with values and comprehensions for collection construction, or host integration to query native domain items.

For a native pipeline, the complete borrowed-word host example shows the predicate callback and input admission. Read embedding in Rust before adapting it to a document model.