(tinkerpop) 15/20: Document TinkerStorageGraph compact encoding and vertex-property id option

[sp...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

spmallette pushed a commit to branch tinkergraph-storage
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git

commit 571488d52ef5a1966eda57d3e001b0faff27038b
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Wed Aug 19 14:41:17 2026 +0000

    Document TinkerStorageGraph compact encoding and vertex-property id option
    
    Add gremlin.tinkergraph.storage.preserveVertexPropertyIds to the TinkerGraph
    configuration table and note in the persistence section that element and edge
    ids are always preserved on reopen while auto-generated vertex-property ids are
    regenerated by default. Fold the compact dictionary encoding and the new
    option into the storage CHANGELOG entry.
    
    Assisted-by: Claude Code:claude-opus-4-8
---
 CHANGELOG.asciidoc                                      | 2 +-
 docs/src/reference/implementations-tinkergraph.asciidoc | 8 ++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc
index 6a6b2bd684..fa611f6ddf 100644
--- a/CHANGELOG.asciidoc
+++ b/CHANGELOG.asciidoc
@@ -28,7 +28,7 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 * Fixed `gremlin-go` to report a malformed or truncated GraphBinary response as a deserialization error rather than a bare decoder message.
 * Made `TinkerGraph` an interface and renamed the in-memory implementation to `TinkerMemoryGraph`; `TinkerGraph.open()` and `gremlin.graph=...TinkerGraph` behave as before. *(breaking)*
 * Renamed `TinkerTransactionGraph` to `TinkerStorageGraph`. *(breaking)*
-* Added a pluggable storage layer to `TinkerStorageGraph` that durably persists each committed transaction to disk, selected with the `gremlin.tinkergraph.storage` config key and shipping a GraphBinary engine, with a `gremlin.tinkergraph.storage.sync` key to choose `commit` (fsync per commit) or `os` durability; a storage location is locked to a single writer, so opening one already in use fails fast; the append log auto-compacts once it exceeds `gremlin.tinkergraph.storage.compactThresh [...]
+* Added a pluggable storage layer to `TinkerStorageGraph` that durably persists each committed transaction to disk, selected with the `gremlin.tinkergraph.storage` config key and shipping a GraphBinary engine, with a `gremlin.tinkergraph.storage.sync` key to choose `commit` (fsync per commit) or `os` durability; a storage location is locked to a single writer, so opening one already in use fails fast; the append log auto-compacts once it exceeds `gremlin.tinkergraph.storage.compactThresh [...]
 * Removed automatic persistence from `TinkerMemoryGraph`, which is now purely in-memory and ignores `gremlin.tinkergraph.graphLocation`/`graphFormat`. Use `TinkerStorageGraph` for durability or `g.io()` for interchange. *(breaking)*
 
 [[release-4-0-0-beta-3]]
diff --git a/docs/src/reference/implementations-tinkergraph.asciidoc b/docs/src/reference/implementations-tinkergraph.asciidoc
index b657d0c9f4..7f7db73fbe 100644
--- a/docs/src/reference/implementations-tinkergraph.asciidoc
+++ b/docs/src/reference/implementations-tinkergraph.asciidoc
@@ -186,6 +186,10 @@ may be lost on an operating system crash or power loss. Only meaningful when `gr
 automatically compacts its append log, bounding the log growth and restart time of a long-running graph that is never
 explicitly closed. Defaults to `67108864` (64 MB). A value of `0` disables automatic compaction, leaving it to
 `close()` or an explicit `compact()`. Only meaningful when `gremlin.tinkergraph.storage` is set.
+|gremlin.tinkergraph.storage.preserveVertexPropertyIds |Whether a `TinkerStorageGraph` storage engine persists
+auto-generated vertex-property ids so they are stable across a close and reopen. Defaults to `false`, which
+regenerates those ids on load and keeps the store smaller. Element and edge ids are always preserved regardless. Only
+meaningful when `gremlin.tinkergraph.storage` is set.
 |=========================================================
 
 NOTE: To use <<tinkergraph-gremlin-tx, transactions>> and <<tinkergraph-gremlin-persistence, persistence>>, configure
@@ -456,6 +460,10 @@ committed state. Compaction runs when the graph is closed and can be requested e
 unbounded log, compaction also runs automatically once the log grows past `gremlin.tinkergraph.storage.compactThreshold`
 bytes. Setting that threshold to `0` disables automatic compaction.
 
+Element and edge ids are always preserved across a reopen. Auto-generated vertex-property ids are not, by default,
+so a vertex property may receive a different id after a reopen. Setting `gremlin.tinkergraph.storage.preserveVertexPropertyIds`
+to `true` persists those ids as well, at the cost of a larger store.
+
 A storage location may be opened by only one graph at a time. `TinkerStorageGraph` takes an exclusive lock on the
 storage directory when it opens, so a second attempt to open the same location, whether from the same JVM or another
 process, fails rather than corrupting the data. The lock is released when the graph is closed. A store also records