lora-python 0.7.0__tar.gz → 0.8.0__tar.gz

{lora_python-0.7.0 → lora_python-0.8.0}/Cargo.lock

@@ -797,7 +797,7 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lora-analyzer"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "lora-ast",
  "lora-parser",
@@ -807,14 +807,22 @@ dependencies = [
 
 [[package]]
 name = "lora-ast"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "smallvec 2.0.0-alpha.12",
 ]
 
+[[package]]
+name = "lora-binding-buffer"
+version = "0.8.0"
+dependencies = [
+ "lora-database",
+ "lora-store",
+]
+
 [[package]]
 name = "lora-compiler"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "lora-analyzer",
  "lora-ast",
@@ -822,7 +830,7 @@ dependencies = [
 
 [[package]]
 name = "lora-database"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "arc-swap",
@@ -844,7 +852,7 @@ dependencies = [
 
 [[package]]
 name = "lora-executor"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "lora-analyzer",
  "lora-ast",
@@ -859,9 +867,10 @@ dependencies = [
 
 [[package]]
 name = "lora-ffi"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
+ "lora-binding-buffer",
  "lora-database",
  "lora-store",
  "serde",
@@ -870,9 +879,10 @@ dependencies = [
 
 [[package]]
 name = "lora-node"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
+ "lora-binding-buffer",
  "lora-database",
  "lora-store",
  "napi",
@@ -884,7 +894,7 @@ dependencies = [
 
 [[package]]
 name = "lora-parser"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "lora-ast",
  "pest",
@@ -895,7 +905,7 @@ dependencies = [
 
 [[package]]
 name = "lora-python"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "lora-database",
@@ -907,7 +917,7 @@ dependencies = [
 
 [[package]]
 name = "lora-server"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "axum",
@@ -921,7 +931,7 @@ dependencies = [
 
 [[package]]
 name = "lora-snapshot"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "argon2",
  "bincode",
@@ -936,7 +946,7 @@ dependencies = [
 
 [[package]]
 name = "lora-store"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "bincode",
  "crc32fast",
@@ -948,7 +958,7 @@ dependencies = [
 
 [[package]]
 name = "lora-wal"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "crc32fast",
  "lora-store",
@@ -958,11 +968,12 @@ dependencies = [
 
 [[package]]
 name = "lora-wasm"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "console_error_panic_hook",
  "js-sys",
+ "lora-binding-buffer",
  "lora-database",
  "lora-store",
  "serde",
@@ -973,7 +984,7 @@ dependencies = [
 
 [[package]]
 name = "lora_ruby"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "lora-database",

{lora_python-0.7.0 → lora_python-0.8.0}/Cargo.toml

@@ -4,7 +4,7 @@ resolver = "2"
 
 [workspace.package]
 edition = "2021"
-version = "0.7.0"
+version = "0.8.0"
 license = "BUSL-1.1"
 authors = ["LoraDB, Inc."]
 repository = "https://github.com/lora-db/lora"
@@ -15,15 +15,16 @@ rust-version = "1.87"
 # Internal crates — versions are kept in lockstep with [workspace.package].version
 # by `scripts/sync-versions.mjs`. Both `path` and `version` are set so that
 # `cargo publish` works (crates.io cannot resolve path-only deps).
-lora-ast = { path = "crates/lora-ast", version = "=0.7.0" }
-lora-parser = { path = "crates/lora-parser", version = "=0.7.0" }
-lora-analyzer = { path = "crates/lora-analyzer", version = "=0.7.0" }
-lora-compiler = { path = "crates/lora-compiler", version = "=0.7.0" }
-lora-store = { path = "crates/lora-store", version = "=0.7.0" }
-lora-snapshot = { path = "crates/lora-snapshot", version = "=0.7.0", default-features = false }
-lora-wal = { path = "crates/lora-wal", version = "=0.7.0" }
-lora-executor = { path = "crates/lora-executor", version = "=0.7.0" }
-lora-database = { path = "crates/lora-database", version = "=0.7.0" }
+lora-ast = { path = "crates/lora-ast", version = "=0.8.0" }
+lora-parser = { path = "crates/lora-parser", version = "=0.8.0" }
+lora-analyzer = { path = "crates/lora-analyzer", version = "=0.8.0" }
+lora-compiler = { path = "crates/lora-compiler", version = "=0.8.0" }
+lora-store = { path = "crates/lora-store", version = "=0.8.0" }
+lora-snapshot = { path = "crates/lora-snapshot", version = "=0.8.0", default-features = false }
+lora-wal = { path = "crates/lora-wal", version = "=0.8.0" }
+lora-executor = { path = "crates/lora-executor", version = "=0.8.0" }
+lora-database = { path = "crates/lora-database", version = "=0.8.0" }
+lora-binding-buffer = { path = "crates/bindings/lora-binding-buffer", version = "=0.8.0" }
 
 # External crates.
 anyhow = "1"

{lora_python-0.7.0 → lora_python-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lora-python
-Version: 0.7.0
+Version: 0.8.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
@@ -76,6 +76,37 @@ persistent = Database.create("app", {"database_dir": "./data"})  # persistent: .
 If you want persistence, pass a database name and `database_dir` to
 `Database.create(...)` or `Database(...)`.
 
+## Explain & Profile
+
+`db.explain()` and `db.profile()` are first-class methods alongside
+`db.execute()`. They are intentionally separate calls — neither
+routes through `execute()` — so plan inspection and runtime metrics
+must be requested explicitly.
+
+```python
+plan = db.explain(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(plan["shape"])             # "readOnly"
+print(plan["tree"]["operator"])  # top-most operator label
+
+profile = db.profile(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(profile["metrics"]["total_elapsed_ns"])
+print(profile["metrics"]["per_operator"])  # per-step inclusive timing
+```
+
+`explain()` never invokes the executor — calling it on a mutating
+query (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
+untouched.
+
+> **`profile()` executes the query for real.** Mutating queries
+> produce the same side effects as `execute()`. Use `explain()` to
+> inspect a mutating plan without running it.
+
 ## Async usage (non-blocking)
 
 ```python

{lora_python-0.7.0 → lora_python-0.8.0}/README.md

@@ -46,6 +46,37 @@ persistent = Database.create("app", {"database_dir": "./data"})  # persistent: .
 If you want persistence, pass a database name and `database_dir` to
 `Database.create(...)` or `Database(...)`.
 
+## Explain & Profile
+
+`db.explain()` and `db.profile()` are first-class methods alongside
+`db.execute()`. They are intentionally separate calls — neither
+routes through `execute()` — so plan inspection and runtime metrics
+must be requested explicitly.
+
+```python
+plan = db.explain(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(plan["shape"])             # "readOnly"
+print(plan["tree"]["operator"])  # top-most operator label
+
+profile = db.profile(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(profile["metrics"]["total_elapsed_ns"])
+print(profile["metrics"]["per_operator"])  # per-step inclusive timing
+```
+
+`explain()` never invokes the executor — calling it on a mutating
+query (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
+untouched.
+
+> **`profile()` executes the query for real.** Mutating queries
+> produce the same side effects as `execute()`. Use `explain()` to
+> inspect a mutating plan without running it.
+
 ## Async usage (non-blocking)
 
 ```python

{lora_python-0.7.0 → lora_python-0.8.0}/crates/bindings/lora-python/README.md

@@ -46,6 +46,37 @@ persistent = Database.create("app", {"database_dir": "./data"})  # persistent: .
 If you want persistence, pass a database name and `database_dir` to
 `Database.create(...)` or `Database(...)`.
 
+## Explain & Profile
+
+`db.explain()` and `db.profile()` are first-class methods alongside
+`db.execute()`. They are intentionally separate calls — neither
+routes through `execute()` — so plan inspection and runtime metrics
+must be requested explicitly.
+
+```python
+plan = db.explain(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(plan["shape"])             # "readOnly"
+print(plan["tree"]["operator"])  # top-most operator label
+
+profile = db.profile(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(profile["metrics"]["total_elapsed_ns"])
+print(profile["metrics"]["per_operator"])  # per-step inclusive timing
+```
+
+`explain()` never invokes the executor — calling it on a mutating
+query (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
+untouched.
+
+> **`profile()` executes the query for real.** Mutating queries
+> produce the same side effects as `execute()`. Use `explain()` to
+> inspect a mutating plan without running it.
+
 ## Async usage (non-blocking)
 
 ```python

{lora_python-0.7.0 → lora_python-0.8.0}/crates/bindings/lora-python/src/lib.rs

@@ -42,7 +42,8 @@ use from_python::{
     py_statements_to_transaction, PyDatabaseOpenOptions,
 };
 use to_python::{
-    lora_value_to_py, row_arrays_to_py, row_to_py_dict, snapshot_info_to_meta, snapshot_meta_to_py,
+    lora_value_to_py, query_plan_to_py, query_profile_to_py, row_arrays_to_py, row_to_py_dict,
+    snapshot_info_to_meta, snapshot_meta_to_py,
 };
 
 // ============================================================================
@@ -185,6 +186,54 @@ impl Database {
         Ok(out)
     }
 
+    /// Compile a query and return its plan as a `dict` without
+    /// executing it.
+    ///
+    /// Mutating queries (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`)
+    /// leave the graph untouched. Errors surface with the same
+    /// `LoraQueryError` shape as `execute()`.
+    #[pyo3(signature = (query, params=None))]
+    fn explain<'py>(
+        &self,
+        py: Python<'py>,
+        query: String,
+        params: Option<&Bound<'py, PyAny>>,
+    ) -> PyResult<Bound<'py, PyDict>> {
+        let params_map = match params {
+            Some(p) if !p.is_none() => Some(py_object_to_params(p)?),
+            _ => None,
+        };
+        let db = self.inner()?;
+        let plan = py
+            .allow_threads(move || db.explain(&query, params_map))
+            .map_err(lora_query_err_from_anyhow)?;
+        query_plan_to_py(py, &plan)
+    }
+
+    /// Execute a query and return the plan plus runtime metrics as a
+    /// `dict`.
+    ///
+    /// **PROFILE executes the query for real.** Mutating queries are
+    /// persisted exactly as in `execute()`. Use `explain()` to inspect
+    /// a mutating plan without running it.
+    #[pyo3(signature = (query, params=None))]
+    fn profile<'py>(
+        &self,
+        py: Python<'py>,
+        query: String,
+        params: Option<&Bound<'py, PyAny>>,
+    ) -> PyResult<Bound<'py, PyDict>> {
+        let params_map = match params {
+            Some(p) if !p.is_none() => Some(py_object_to_params(p)?),
+            _ => None,
+        };
+        let db = self.inner()?;
+        let prof = py
+            .allow_threads(move || db.profile(&query, params_map))
+            .map_err(lora_query_err_from_anyhow)?;
+        query_profile_to_py(py, &prof)
+    }
+
     /// Return an iterator over result rows. The query is materialized by
     /// `execute()` first, then Python consumes the row list lazily.
     #[pyo3(signature = (query, params=None))]

{lora_python-0.7.0 → lora_python-0.8.0}/crates/bindings/lora-python/src/to_python.rs

@@ -8,7 +8,9 @@
 use pyo3::prelude::*;
 use pyo3::types::{PyBytes, PyDict, PyList};
 
-use lora_database::{LoraValue, Row, SnapshotInfo, SnapshotMeta};
+use lora_database::{
+    LoraValue, PlanTreeNode, QueryPlan, QueryProfile, Row, SnapshotInfo, SnapshotMeta,
+};
 use lora_store::{LoraBinary, LoraPoint, LoraVector, VectorValues};
 
 pub(crate) fn snapshot_info_to_meta(info: SnapshotInfo) -> SnapshotMeta {
@@ -64,6 +66,67 @@ pub(crate) fn row_to_py_dict<'py>(py: Python<'py>, row: &Row) -> PyResult<Bound<
     Ok(out)
 }
 
+pub(crate) fn query_plan_to_py<'py>(
+    py: Python<'py>,
+    plan: &QueryPlan,
+) -> PyResult<Bound<'py, PyDict>> {
+    let out = PyDict::new_bound(py);
+    out.set_item("query", &plan.query)?;
+    out.set_item("shape", plan.shape.as_str())?;
+    let cols = PyList::new_bound(py, plan.result_columns.iter().map(|c| c.as_str()));
+    out.set_item("result_columns", cols)?;
+    out.set_item("tree", plan_tree_node_to_py(py, &plan.tree.root)?)?;
+    Ok(out)
+}
+
+pub(crate) fn query_profile_to_py<'py>(
+    py: Python<'py>,
+    profile: &QueryProfile,
+) -> PyResult<Bound<'py, PyDict>> {
+    let out = PyDict::new_bound(py);
+    out.set_item("plan", query_plan_to_py(py, &profile.plan)?)?;
+
+    let metrics = PyDict::new_bound(py);
+    metrics.set_item("total_elapsed_ns", profile.metrics.total_elapsed_ns)?;
+    metrics.set_item("total_rows", profile.metrics.total_rows)?;
+    metrics.set_item("mutated", profile.metrics.mutated)?;
+
+    let per_op = PyDict::new_bound(py);
+    for (id, op) in &profile.metrics.per_operator {
+        let entry = PyDict::new_bound(py);
+        entry.set_item("rows", op.rows)?;
+        entry.set_item("db_hits", op.db_hits)?;
+        entry.set_item("elapsed_ns", op.elapsed_ns)?;
+        entry.set_item("next_calls", op.next_calls)?;
+        per_op.set_item(*id as u64, entry)?;
+    }
+    metrics.set_item("per_operator", per_op)?;
+
+    out.set_item("metrics", metrics)?;
+    Ok(out)
+}
+
+fn plan_tree_node_to_py<'py>(py: Python<'py>, node: &PlanTreeNode) -> PyResult<Bound<'py, PyDict>> {
+    let out = PyDict::new_bound(py);
+    out.set_item("id", node.id as u64)?;
+    out.set_item("operator", &node.operator)?;
+    let details = PyDict::new_bound(py);
+    for (k, v) in &node.details {
+        details.set_item(k, v)?;
+    }
+    out.set_item("details", details)?;
+    match node.estimated_rows {
+        Some(r) => out.set_item("estimated_rows", r)?,
+        None => out.set_item("estimated_rows", py.None())?,
+    }
+    let children = PyList::empty_bound(py);
+    for child in &node.children {
+        children.append(plan_tree_node_to_py(py, child)?)?;
+    }
+    out.set_item("children", children)?;
+    Ok(out)
+}
+
 pub(crate) fn lora_value_to_py<'py>(
     py: Python<'py>,
     value: &LoraValue,

lora_python-0.8.0/crates/bindings/lora-python/tests/test_explain_profile.py

@@ -0,0 +1,78 @@
+"""Tests for Database.explain and Database.profile."""
+
+from __future__ import annotations
+
+import pytest
+
+from lora_python import Database, LoraQueryError
+
+
+def test_explain_does_not_execute_mutating_query() -> None:
+    db = Database.create()
+    plan = db.explain("CREATE (:Foo {n: 1})")
+    assert plan["shape"] == "mutating"
+    assert db.node_count == 0
+
+
+def test_explain_returns_plan_tree() -> None:
+    db = Database.create()
+    db.execute("CREATE (:Person {name: 'Alice'})")
+    plan = db.explain("MATCH (p:Person) RETURN p")
+    assert plan["shape"] == "readOnly"
+    assert plan["result_columns"] == ["p"]
+    assert plan["query"] == "MATCH (p:Person) RETURN p"
+    assert "operator" in plan["tree"]
+
+
+def test_explain_with_params_forwarded() -> None:
+    db = Database.create()
+    db.execute("CREATE (:Person {name: 'Alice'})")
+    plan = db.explain(
+        "MATCH (p:Person) WHERE p.name = $name RETURN p",
+        {"name": "Alice"},
+    )
+    assert plan["shape"] == "readOnly"
+
+
+def test_explain_surfaces_parse_error_like_execute() -> None:
+    db = Database.create()
+    with pytest.raises(LoraQueryError) as exec_exc:
+        db.execute("INVALID")
+    with pytest.raises(LoraQueryError) as explain_exc:
+        db.explain("INVALID")
+    # Both errors share the LORA_PARSE prefix.
+    assert str(exec_exc.value).split(":")[0] == str(explain_exc.value).split(":")[0]
+
+
+def test_profile_executes_mutating_query() -> None:
+    db = Database.create()
+    profile = db.profile("CREATE (:Foo {n: 1}) RETURN 1 AS one")
+    assert profile["metrics"]["mutated"] is True
+    assert profile["metrics"]["total_rows"] == 1
+    assert db.node_count == 1
+
+
+def test_profile_reports_per_operator_timing() -> None:
+    db = Database.create()
+    for name in ["Alice", "Bob", "Carol", "Dave"]:
+        db.execute(f"CREATE (:Person {{name: '{name}'}})")
+    profile = db.profile(
+        "MATCH (p:Person) WHERE p.name <> 'Bob' RETURN p.name AS name"
+    )
+    assert profile["metrics"]["total_rows"] == 3
+    assert profile["metrics"]["mutated"] is False
+    per_op = profile["metrics"]["per_operator"]
+    assert len(per_op) > 0
+    for op_id, op in per_op.items():
+        assert op["next_calls"] > 0
+
+
+def test_profile_with_params_forwarded() -> None:
+    db = Database.create()
+    db.execute("CREATE (:Person {name: 'Alice'})")
+    db.execute("CREATE (:Person {name: 'Bob'})")
+    profile = db.profile(
+        "MATCH (p:Person) WHERE p.name = $name RETURN p",
+        {"name": "Alice"},
+    )
+    assert profile["metrics"]["total_rows"] == 1

{lora_python-0.7.0 → lora_python-0.8.0}/crates/lora-compiler/src/lib.rs

@@ -1,10 +1,13 @@
 pub mod logical;
 pub mod optimizer;
 pub mod physical;
+pub mod plan_tree;
 
 mod pattern;
 mod planner;
 
+pub use plan_tree::{plan_tree_from_compiled, PlanTree, PlanTreeNode};
+
 pub use logical::{
     Aggregation, Argument, Create, Delete, Expand, Filter, Limit, LogicalOp, LogicalPlan, Merge,
     NodeByPropertyScan, NodeScan, OptionalMatch, PathBuild, PlanNodeId, Projection, Remove, Set,