# 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;
- `null` stores 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.

```bash
# 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 `Range` request returns `206`, or `416` when unsatisfiable; 
- `ETag`, `If-Match`, and `If-None-Match` support 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`.
