Blobs | Omnigraph
Blobs
Use Blob properties for bytes that should not be projected through .gq. Blob values can contain graph-managed bytes, an external URI reference, or null. A valid empty managed Blob is distinct from null.
Writing Blob values
load and mutation input use one String representation:
base64:<payload>supplies managed bytes owned by the graph;- any other String requests an external URI reference;
nullstores a null value when the property is nullable.
Query behavior
Blob properties are not ordinary .gq read values. They cannot be projected, filtered, ordered, or aggregated. Write them through load or mutation assignment, then read an individual Blob value through the dedicated CLI or HTTP surface.
CLI reads
The selector is ENTITY TYPE ID PROPERTY, where ENTITY is node or edge. Blob commands address the graph with --target NAME|ADDRESS; they do not take a positional graph URI.
# Stream managed bytes to a file.
omnigraph blob get node Document manual content \
--out manual.bin --target ./graph.omni
# Inspect the value without reading payload bytes.
omnigraph blob stat node Document manual content \
--json --target ./graph.omni
HTTP reads
Servers expose the same logical selector with GET and HEAD:
GET /graphs/knowledge/blob?entity=node&type=Document&id=manual&property=content&branch=main
Omnigraph-Http-Api: 0.14
Both methods follow the HTTP contract, including checking the response header before consuming bytes. Use snapshot=<commit-id> instead of branch for an immutable historical read.
For managed values:
- GET returns bytes; HEAD returns the same metadata without a body;
- a single standard
Rangerequest returns206, or416when unsatisfiable; ETag,If-Match, andIf-None-Matchsupport conditional delivery;- the response identifies the exact resolved graph snapshot.
Limits
Blob limits bound the memory one operation needs. An operation over a limit fails before it changes the graph. Over HTTP, it returns 413 with a resource_limit detail naming the resource, its limit and the actual value observed. For a write, the CLI reports the same three fields; the omnigraph blob commands report an over-limit range read as Blob read range exceeds the limit.