Skip to content

Release v0.6.3

Latest

Choose a tag to compare

@StevenBtw StevenBtw released this 15 Nov 19:20
aa42b90

[0.6.3] - 2026-11-15

SPARQL transactions release: SPARQL in a transaction reads one snapshot, conflicting updates fail at commit and graph operations run inside transactions; the plan cache, the per-query memory limit and path searches are bounded. Results that change on upgrade: a statement over the per-query memory limit fails with GRAFEO-S001 in builds with disk spilling, a path search over its budget fails with GRAFEO-S001 instead of GRAFEO-Q006, the second of two transactions that write one SPARQL triple, one of them deleting it, fails with GRAFEO-T001, SPARQL at a viewing epoch fails with GRAFEO-Q004, a standalone type that a graph type lists keeps applying in the default graph, CLEAR GRAPH of a missing graph fails unless SILENT, a SPARQL MINUS after another one or after a sub-SELECT removes its solutions, a time-travel read before a snapshot import or restore fails with GRAFEO-V001, a MERGE of a pattern another open transaction is creating now fails with the retryable GRAFEO-T001 instead of creating a duplicate (the application retries the statement or the transaction), and reported RDF memory rises to what the store holds, so an RDF database near its memory limit reaches it sooner. Building from source needs Rust 1.100 or later.

Added

  • Config::with_path_search_budget (#492): sets the bytes the paths of one variable-length or shortest-path search, or one RDF property path search, may hold, never above the memory limit; the nodes an ANY SHORTEST or shortestPath search visits are not counted yet. In the bindings it is path_search_budget (Python), pathSearchBudget (Node, WASM, Dart), SetPathSearchBudget (C#), PathSearchBudget (Go) and grafeo_options_set_path_search_budget (C).
  • Config::with_plan_cache_limit (#674): bounds the plan cache in bytes, by a deep estimate of each plan. The default is a sixty-fourth of the memory limit, at least 4 MiB and at most 64 MiB; 0 turns the cache off.
  • validate() names the nodes a listed type would refuse (#764): the warning LISTED_TYPE_ROWS gives, per node type and graph not bound to a graph type that lists it, the count and the first ids of the nodes that break the type, with the steps to make it a type of its own again. Run it after upgrading a file in which 0.6.2 took a standalone type over.
  • Hybrid search takes a beam width (grafeo-server#85): GrafeoDB::hybrid_search_with with HybridSearchOptions sets the vector half's ef, as vector_search does, and grafeo::FusionMethod names the fusion both take; hybrid_search is unchanged.
  • A Silicon Valley demo dataset ships on npm and PyPI: @grafeo-db/datasets and grafeo-datasets hold one 64-node graph after the HBO series Silicon Valley, as nodes and edges, a timeline, GQL, Cypher, Turtle and MiniLM vectors (384 dimensions). Both follow the engine's version.

Changed

  • Rust 1.100 or later is required: the minimum supported Rust version is 1.100.0 (was 1.99.0).
  • The documentation moves to docs.grafeo.dev with a new structure: its pages are grouped in seven sections, and every old link redirects to its new page.
  • A path search over its budget fails with GRAFEO-S001 (#492): it names the path search budget and its setting, in GQL, Cypher and SPARQL; it was GRAFEO-Q006. An RDF property path reads the same budget as the others, no longer narrowed to the memory free when it was planned.
  • The plan cache is bounded in bytes and reported in full (#674): it held 1,000 plans whatever their size, and memory_usage() counted only its map. Now one byte bound holds parsed and optimized plans, a plan larger than the bound runs uncached, a repeated statement shares the cached plan instead of copying it, and memory_usage().caches reports what the plans hold plus plan_cache_limit_bytes.
  • A standalone type a graph type lists stays in force (#764): a type made with CREATE NODE TYPE or CREATE EDGE TYPE keeps applying by its label in every graph once a graph type lists it, and also in that graph type's graphs, which reverses 0.6.2 for this case; DROP GRAPH TYPE leaves it, DROP NODE TYPE of it is refused while a graph type lists it, and a pattern may name it only as it is. Types a graph type declares itself, and files in which 0.6.2 already took a type over, keep the 0.6.2 rule.
  • Conflicting SPARQL triple updates fail at commit (#718): when two transactions write the same triple in one graph and one of them deletes it, the second to commit fails with GRAFEO-T001 and is rolled back; both committed before, so a delete could silently undo the other's insert. Two inserts of one triple both commit, and a transaction also conflicts with a bulk load (load_rdf_text, load_rdf_into, batch_insert_rdf) that commits while it is open; the load itself is never refused.
  • SPARQL graph operations run inside a transaction (#718): CREATE, DROP, CLEAR, COPY, MOVE and ADD apply at the commit in order with the transaction's triple updates, and its later statements see them; 0.6.2 refused any SPARQL statement after one with GRAFEO-T004. Graph operations on different graphs, or a graph operation and a triple update in one graph, no longer conflict; two transactions changing one graph still fail with GRAFEO-T001.
  • The per-query memory limit covers every operator that holds rows (#674): Config::with_query_memory_limit now caps what one statement's sorts, groupings, hash and nested-loop joins, distincts, set operations, top-k heaps, correlated subqueries, eager reads and stored procedure results hold together, strings and lists included, where it covered sorts and groupings only; at the cap a GQL sort spills first and the others fail with GRAFEO-S001 naming the limit, changing nothing. It holds in builds with disk spilling (the Python, Node, C, C#, Go and Dart packages, grafeo-server and the CLI); the default grafeo crate and the edge and WebAssembly builds do not enforce it yet.
  • A SPARQL ORDER BY past the per-query memory limit fails (#674): a full sort over Config::with_query_memory_limit fails with GRAFEO-S001 naming the limit in the builds that enforce it, since SPARQL sorts do not spill yet; ORDER BY ... LIMIT keeps only the rows it returns and answers.
  • SPARQL reads at a viewing epoch are refused (#718): with set_viewing_epoch set, a SPARQL query or SHACL validation fails with GRAFEO-Q004 (RDF data keeps no history) instead of reading the present.

Deprecated

  • GrafeoDB::rdf_store() is deprecated: writes through the RDF store bypass transactions and snapshot reads; use SPARQL updates in a session or transaction, or batch_insert_rdf. Removed in 0.7.0.

Fixed

  • Index names across graphs (#723): DROP INDEX in one graph keeps the name of the same index in other graphs, SHOW INDEXES lists only the current graph's indexes, and the direct index drops and DROP GRAPH remove a name no graph uses any more.
  • CLEAR GRAPH of a missing graph fails unless SILENT (#718): as DROP GRAPH does (SPARQL 1.1 Update 3.1.5), in a transaction or not. Inside a transaction a CLEAR no longer makes a missing or dropped graph exist until the commit, so a later CREATE GRAPH of it succeeds and a later DROP GRAPH fails, as when run one by one.
  • The memory limit counts label and edge-type names in full (#751): memory_usage() and the limit's account missed about 41 bytes per label and 27 per edge type (1.35 MB at 20,000 of each), so a database with many labels held more than the limit saw.
  • The memory limit counts RDF term text, and holds each term once (#718): memory_usage() and the limit's account missed the text of every IRI, literal and blank node and each stored triple's allocation, so a stored triple held 761.6 B against 549.1 B counted. A term repeated across triples is now held once, 113 B less per triple in the test data (648.3 B held, 647.2 B counted), and reported RDF memory rises to what is held.
  • What a transaction at an older snapshot keeps is counted and freed when it ends (#718): the triples later commits deleted, the graphs they cleared or dropped, and the writes kept for conflict checks are in memory_usage().rdf.snapshot_bytes and the memory limit, and are freed when the last reader that needs them ends.
  • A plan chosen on an empty graph replans after a bulk load (#674): a cached plan is made again once a count the planner reads (nodes, edges, a label's nodes, an edge type's edges) doubles or halves by at least 1,000 rows.
  • A plan built before a schema change is no longer cached after it (#674): a statement planned while an index, constraint, type or graph changed runs once and is planned again next time; a schema change queued in an open transaction no longer drops other sessions' plans, and a rollback keeps them.
  • The default path search budget is at most 256 MiB (#492): a quarter of the memory limit, so a 64 GiB limit let one search hold 16 GiB before it failed.
  • A SPARQL MINUS after another MINUS, a VALUES block or a sub-SELECT removes its solutions: such a MINUS (after a sub-SELECT with DISTINCT, ORDER BY, LIMIT, OFFSET, GROUP BY or a renamed variable) was skipped and kept every solution, also in 0.6.2. Such queries now return fewer rows.
  • A read before a snapshot import is refused: after import_snapshot or restore_snapshot, a time-travel read before the snapshot's epoch, or before the restore by time, fails with GRAFEO-V001 ("history before epoch ... is not retained") under every history retention, where with retention on it answered with the imported data.
  • Concurrent MERGEs of one pattern create it once: two transactions that MERGE the same pattern no longer both create it; the second fails with the retryable GRAFEO-T001, its retry of the statement or transaction matches, INSERT or CREATE still add an element each time, and a UNIQUE or NODE KEY constraint covers every writer. A bulk MERGE that creates new keys costs about 3% more per statement.
  • A MERGE that only matches no longer conflicts: two transactions that MERGE the same existing node without ON MATCH SET both commit; before, the second failed with GRAFEO-T001.
  • Concurrent inserts under a key constraint make progress: when open transactions claim each other's key values in a cycle, the one that began first commits and the others fail with the retryable GRAFEO-T001; before, all of them could fail on every retry. Updates of existing nodes in overlapping orders (MERGE ... ON MATCH SET, SET n += ..., upsert_nodes) can still fail on every retry until 0.6.4.
  • SPARQL reads in a transaction are snapshot isolated (#718): every SPARQL query in a transaction reads the triples and named graphs as they were when the transaction began, with its own updates, at the same point as its GQL and Cypher reads; an auto-commit query reads one committed state for its whole run. It saw triples, graphs and clears that other sessions committed meanwhile.
  • Checkpoints, copies and exports write the RDF data of one epoch (#718): a checkpoint, save, a copy or export_snapshot that runs while SPARQL updates commit writes the RDF triples and named graphs as of its epoch, with commits going on while it writes. rdf_schema() lists the named graphs (it returned an empty list) and reads at one epoch.
  • The CLI opens every database the default grafeo build writes (#763): cargo install grafeo-cli and the pre-built binaries now have the same features, vector, text and hybrid search, change data capture and graph algorithms included, so a file with a vector or text index opens. A database holding data the build cannot read, such as RDF triples, is refused with the cargo install grafeo-cli --features ... line that adds the feature.
  • SQL/PGQ ranges on one-kind columns use the range scan again: a <, <=, >, >= or BETWEEN on a property whose values are all of the bound's kind reads its index by range and skips chunks by their stored bounds, as in 0.6.1. A column holding values of several kinds still scans and raises 22G04.
  • Concurrent sorts and groupings keep their memory consumers (#674): each spillable sort and aggregate registers under a name of its own and unregisters only that one when it finishes or fails.

What's Changed

  • Update README.md by @StevenBtw in #755
  • deps(python): bump pyarrow from 26.0.0 to 26.0.1 in /crates/bindings/python by @dependabot[bot] in #760
  • deps(python): bump ruff from 0.17.3 to 0.17.4 in /crates/bindings/python by @dependabot[bot] in #759
  • deps(python): bump grafeo-cli from 0.6.0 to 0.6.1 in /crates/bindings/python by @dependabot[bot] in #758
  • deps(npm): bump @napi-rs/cli from 3.10.9 to 3.10.12 in /crates/bindings/node in the npm-dependencies group across 1 directory by @dependabot[bot] in #756
  • deps(python): bump ty from 0.0.95 to 0.0.98 in /crates/bindings/python by @dependabot[bot] in #757
  • work on the docs by @StevenBtw in #766
  • updated CHANGELOG.md by @StevenBtw in #767
  • Fix/docs move paths by @StevenBtw in #768
  • fixed the docs not publishing before a release by @StevenBtw in #769
  • Release 0.6.3 by @StevenBtw in #761

Full Changelog: v0.6.2...v0.6.3