storage.md

Storage

One OmniGraph graph lives at one storage root. The root contains the graph's schema, data, branches, and commit history. Treat it as a single unit: do not edit files beneath it with storage-provider tools or write to its underlying datasets directly.

Supported graph URIs

URI Use
/absolute/path/graph.omni or file:///absolute/path/graph.omni Local filesystem
s3://bucket/prefix/graph.omni Amazon S3 or an S3-compatible service
az://container/prefix/graph.omni Azure Blob Storage qualification preview

An http:// or https:// URL addresses an OmniGraph server; it is not a graph storage URI. These are engine/server storage capabilities, not CLI target variants. Operator version 1 permits only local direct targets. Register a server or managed target to access remotely served graphs, including servers using cloud storage; see operator configuration.

Azure support is a qualification preview: local Azurite validation and a live managed-identity smoke deployment are complete, but the adversarial live-Azure matrix is still pending. Every mutation-capable Azure process must use the admission wrapper described in deployment.

Consistency and history

Although a graph contains separate data for each node and edge type, OmniGraph presents one graph-wide snapshot. A successful write makes all affected types visible together. Readers never see half of a graph commit.

Renaming a type with @rename_from preserves its identity and history. Dropping and later recreating a declaration starts a new lifetime, even when the public name is reused.

omnigraph optimize rewrites physical layout without deleting history. omnigraph cleanup is different: it permanently removes old storage versions, which can make earlier commits unreadable. Review the retention policy and backups before confirming it, and quiesce long-lived historical or Blob readers first. An unconfirmed cleanup echoes the policy but does not inspect candidates.

Cleanup reclaims table versions, not the graph's own catalog. Every graph commit adds a version of the branch's catalog, and no command removes the versions of a live branch, so its storage grows with the number of commits; plan storage for it on write-heavy graphs. A deleted branch's catalog can be collected by cleanup once nothing else depends on it.

Local filesystem requirement

Local read-write graphs require filesystem hard-link support. Read-only access can work without it, but initialization and writes fail loudly when the filesystem cannot provide the required create-if-absent behavior. Use a native local filesystem rather than a mount that emulates files incompletely.

S3 configuration

OmniGraph uses the standard AWS credential chain. Common settings include:

A graph's commit protocol relies on the store honouring conditional writes (If-None-Match and If-Match on PUT), which the server requests on every S3 binding. The project's S3 test suites run against RustFS; qualify any other S3-compatible service before production. Google Cloud Storage's S3 interoperability endpoint is untested, and a store that ignores the conditions can let two writers publish the same graph version. Native gs:// URIs are not supported.

Azure configuration

Azure roots use the strict form az://<container>/<prefix>. Credentials never belong in the URI.

Azure Container Apps supplies its managed-identity endpoint variables at runtime. Restart the process after changing storage-account, endpoint, or identity selection.

For deployment, server boot, and cloud-specific safety requirements, see Deployment.

Encryption at rest

The graph's data, history and Blob payloads are ordinary objects in the storage root, and nothing encrypts them on the way. Encryption at rest is the storage's: enable default bucket encryption (SSE-S3 or SSE-KMS) on S3, the service's equivalent on other S3-compatible stores, Azure Storage service encryption, or an encrypted volume for a local root. There is no field-level encryption; keep secrets out of graph properties, or encrypt them before they are written.