Repository navigation
[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 anANY SHORTESTorshortestPathsearch visits are not counted yet. In the bindings it ispath_search_budget(Python),pathSearchBudget(Node, WASM, Dart),SetPathSearchBudget(C#),PathSearchBudget(Go) andgrafeo_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 warningLISTED_TYPE_ROWSgives, 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_withwithHybridSearchOptionssets the vector half'sef, asvector_searchdoes, andgrafeo::FusionMethodnames the fusion both take;hybrid_searchis unchanged. - A Silicon Valley demo dataset ships on npm and PyPI:
@grafeo-db/datasetsandgrafeo-datasetshold 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 wasGRAFEO-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, andmemory_usage().cachesreports what the plans hold plusplan_cache_limit_bytes. - A standalone type a graph type lists stays in force (#764): a type made with
CREATE NODE TYPEorCREATE EDGE TYPEkeeps 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 TYPEleaves it,DROP NODE TYPEof 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-T001and 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,MOVEandADDapply 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 withGRAFEO-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 withGRAFEO-T001. - The per-query memory limit covers every operator that holds rows (#674):
Config::with_query_memory_limitnow 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 withGRAFEO-S001naming 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 defaultgrafeocrate and theedgeand WebAssembly builds do not enforce it yet. - A SPARQL
ORDER BYpast the per-query memory limit fails (#674): a full sort overConfig::with_query_memory_limitfails withGRAFEO-S001naming the limit in the builds that enforce it, since SPARQL sorts do not spill yet;ORDER BY ... LIMITkeeps only the rows it returns and answers. - SPARQL reads at a viewing epoch are refused (#718): with
set_viewing_epochset, a SPARQL query or SHACL validation fails withGRAFEO-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, orbatch_insert_rdf. Removed in 0.7.0.
Fixed
- Index names across graphs (#723):
DROP INDEXin one graph keeps the name of the same index in other graphs,SHOW INDEXESlists only the current graph's indexes, and the direct index drops andDROP GRAPHremove a name no graph uses any more. CLEAR GRAPHof a missing graph fails unlessSILENT(#718): asDROP GRAPHdoes (SPARQL 1.1 Update 3.1.5), in a transaction or not. Inside a transaction aCLEARno longer makes a missing or dropped graph exist until the commit, so a laterCREATE GRAPHof it succeeds and a laterDROP GRAPHfails, 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_bytesand 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
MINUSafter anotherMINUS, aVALUESblock or a sub-SELECT removes its solutions: such aMINUS(after a sub-SELECT withDISTINCT,ORDER BY,LIMIT,OFFSET,GROUP BYor 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_snapshotorrestore_snapshot, a time-travel read before the snapshot's epoch, or before the restore by time, fails withGRAFEO-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,INSERTorCREATEstill add an element each time, and aUNIQUEorNODE KEYconstraint 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 SETboth commit; before, the second failed withGRAFEO-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 orexport_snapshotthat 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
grafeobuild writes (#763):cargo install grafeo-cliand 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 thecargo install grafeo-cli --features ...line that adds the feature. - SQL/PGQ ranges on one-kind columns use the range scan again: a
<,<=,>,>=orBETWEENon 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