Crate velr

Expand description

Rust bindings for the Velr runtime.

This crate exposes a high-level API over the Velr runtime ABI (loaded via the runtime module), wrapping raw FFI pointers in RAII types with predictable lifetimes.

§Threading model

Velr uses a connection-affine model:

Velr (the connection) is Send + !Sync.
- ✅ You may move a connection to another thread. Example: spawn a worker thread and move the connection into it.
- ❌ Wrapping a connection in Arc does not make it safe to share across threads; Velr is !Sync, so concurrent shared use is not supported.
In-flight / handle-based objects are !Send + !Sync (thread-affine): ExecTables, TableResult, RowIter, VelrTx, ExecTablesTx, VelrSavepoint, ExplainTrace.
- ❌ You may not move these to another thread.
- ❌ You may not share these across threads.

Practical implications:

✅ Many connections across many threads is fine (open one connection per thread).
✅ You can move a connection between threads (e.g., create in main, move into worker).
❌ You cannot run concurrent operations on the same connection across threads.

If you need parallelism, open multiple connections and/or use a pool.

§Results and lifetimes

Queries can produce zero or more result tables:

Velr::exec / VelrTx::exec stream tables via ExecTables / ExecTablesTx.
Velr::exec_one / VelrTx::exec_one return a single TableResult.

Rows are processed via callbacks. Individual cell values are represented by CellRef, which may borrow bytes from buffers owned by the underlying row cursor. For Text/Json values, the borrowed bytes remain valid until the next call to RowIter::next on the same iterator (or until the iterator is dropped). In typical usage this means the borrows are scoped to the row callback invocation.

§Bounded result previews

Hosts that need projected column names plus a small sample can use QueryOptions with Velr::exec_with_options, Velr::exec_one_with_options, or Velr::run_with_options. The row cap is enforced by Velr while emitting result rows; the driver does not rewrite the Cypher text.

let db = Velr::open(None)?;
let mut table = db.exec_one_with_options(
    "UNWIND [1,2,3,4,5,6] AS x RETURN x ORDER BY x LIMIT 10",
    QueryOptions::max_result_rows(5),
)?;

assert_eq!(table.column_names(), &["x".to_string()]);
let rows = table.collect(|row| Ok(format!("{:?}", row[0])))?;
assert_eq!(rows.len(), 5);

Existing Cypher LIMIT clauses still apply. For example, LIMIT 3 with QueryOptions::max_result_rows(5) emits at most three rows, while LIMIT 10 with the same option emits at most five rows. Use QueryOptions::max_result_rows(0) when you want result table metadata, including column names, without materializing any rows.

§Query parameter binding

Use params! or QueryParams for params-only calls, or combine params with bounded previews through QueryOptions. Query text uses $name; API parameter names omit the leading $.

let db = Velr::open(None)?;
db.run_with_params(
    "CREATE (:Person {name: $name, age: $age})",
    velr::params! {
        name: "Alice",
        age: 42_i64,
    }?,
)?;

let mut table = db.exec_one_with_options(
    "MATCH (p:Person) WHERE p.age >= $min_age RETURN p.name AS name ORDER BY name",
    QueryOptions::max_result_rows(20).with_param("min_age", 18_i64)?,
)?;
assert_eq!(table.column_names(), &["name".to_string()]);

§Errors

Most operations return Result<T>. On failure, you get an Error containing a numeric code (originating from the runtime ABI) and an optional message.

§Schema migration and introspection

This runtime’s current on-disk schema is version 7. Supported older databases can be opened without automatic migration. Reads remain available on those databases, but writes and features that require the current schema return a query error until the user explicitly migrates. SHOW CURRENT GRAPH SHAPE is available once a database has reached schema version 5.

Use Velr::schema_version, Velr::current_schema_version, and Velr::needs_migration to inspect the connection state. Use Velr::migrate or execute MIGRATE DATABASE from maintenance code when upgrading is intended.

SHOW CURRENT GRAPH SHAPE exposes Velr’s observed graph schema: labels, relationship types, properties, observed value types, and counts. Use YIELD to compose it with WHERE and RETURN, or YIELD * to inspect the full row shape.

Fulltext search is also available through normal Cypher execution. Use CREATE FULLTEXT INDEX to define an index and CALL db.index.fulltext.queryNodes(...) to search it. Fulltext indexes use a sidecar next to file-backed databases, and no dedicated driver methods are required. The query grammar supports terms, phrases, field scoping, boolean grouping, required/excluded terms, phrase slop, phrase-prefix, boosts, and * match-all. score is a non-normalized relevance score. Higher scores are better within a single query result set; scores are not guaranteed to be in 0..1 or comparable across different queries.

Macros§

params: Build a QueryParams map with compact syntax.

Structs§

DateValue
DurationValue
Error: Error returned by the Velr API.
ExecTables: Streaming result of an execution that may yield multiple tables.
ExecTablesTx: Streaming result of an execution within a transaction.
ExplainPlan: One explain plan plus all steps in it.
ExplainPlanMeta: Owned plan metadata returned from an ExplainTrace.
ExplainStatement: One explain statement plus its SQLite query-plan detail lines.
ExplainStatementMeta: Owned statement metadata returned from an ExplainTrace.
ExplainStep: One explain step plus all statements in it.
ExplainStepMeta: Owned step metadata returned from an ExplainTrace.
ExplainTrace: EXPLAIN / EXPLAIN ANALYZE trace handle.
GeographyValue
GeometryValue
LineStringValue
LinearRingValue
LocalDateTimeValue
LocalTimeValue
MigrationReport: Report returned by Velr::migrate.
PointValue
PolygonValue
QueryOptions: Out-of-band execution options for query result emission.
QueryParamError: Error returned while constructing or binding query parameters.
QueryParams: Named parameters supplied to a Cypher query.
RowIter: Iterator over rows of a table.
TableResult: A single result table produced by query execution.
VectorEmbeddingField: One named Velr value passed to a registered vector embedding callback.
VectorEmbeddingInput: One source row passed to a registered vector embedding callback.
VectorValue
Velr
VelrSavepoint: A scoped savepoint handle within a transaction (thread-affine).
VelrTx: A transaction handle (thread-affine).
ZonedDateTimeValue
ZonedTimeValue

Enums§

CellRef: Borrowed view of a single cell value in a result row.
GeometryShape
ListIter
ListValue
MigrationStatus: Status returned by Velr::migrate.
Position
PropertyValue
PropertyValueRef
QueryValue: A Cypher value supplied out-of-band through QueryParams.
VectorElem
VectorEmbeddingPurpose: Why Velr is asking an embedder to produce vectors.
VectorEntityKind: Graph entity kind for indexed vector embedding inputs.
VectorIter
VectorStorage
VectorType

Traits§

TryIntoQueryValue: Fallible conversion from a Rust value into a Cypher parameter value.

Type Aliases§

Result: Convenience result type used throughout the public API.
VectorEmbeddingBatchResult

Crate velr

Crate velr Copy item path

§Threading model

§Results and lifetimes

§Bounded result previews

§Query parameter binding

§Errors

§Schema migration and introspection

Macros§

Structs§

Enums§

Traits§

Type Aliases§

Crate velr