Resource Addresses
Name a Table or other resource by its path, and pin it to a branch, a Project commit, or an exact version.
An address names a Table, or another resource, in a Project and optionally
says which state to read. frames@main is the frames Table at the head of
main; frames@v019a… is one exact version of it that never changes. Store
the exact-version form when you need to repeat a read, such as the data behind
a training run.
frames # the session's default state
frames@main # the head of branch main
frames@c019a7c3e2f8d7b1e9f0a1b2c3d4e5f60 # the Table in one Project commit
frames@v019a7c3e2f8d7b1e9f0a1b2c3d4e5f60 # one exact version of the TableThe Rust SDK and the DataFusion integration accept addresses. For what commits, branches, and versions are, see Commits and branches.
Grammar
address = path [ "@" ref ]
path = segment *( "/" segment )
ref = commit / version / branch
commit = "c" 32( lowercase-hex-digit )
version = "v" 32( lowercase-hex-digit )
branch = branch-segment *( "/" branch-segment )Path
The path is the resource's name in the Project, made of 1 to 64 segments
separated by /.
| Rule | Detail |
|---|---|
| Length | Each segment is 1 to 255 bytes. |
| Reserved characters | A segment cannot contain / or @. |
| Reserved segments | A segment cannot be . or ... |
| Control characters | A segment cannot contain control characters. |
Because no path can contain @, an address always splits unambiguously at
its first @.
Reference
The reference after @ selects the Project state in which the path resolves.
| Form | Example | Selects |
|---|---|---|
| None | frames | The default state of the session. |
| Branch | frames@main | The head of the branch. |
| Commit | frames@c019a… | The Project commit with this ID. |
| Version | frames@v019a… | This exact version of the resource. |
A commit or version ID is c or v followed by exactly 32 lowercase
hexadecimal digits: a UUIDv7 with its hyphens removed. To use a commit ID that
the HTTP API returns, remove the hyphens and add the c.
Every reference that is 33 characters long and starts with c or v is
reserved for IDs. If such a reference is not a valid ID, for example because
it has uppercase or non-hexadecimal digits or is not a UUIDv7, the address is
rejected as invalid; it is never read as a branch name. So a branch name can
never have that shape.
Any other reference is a branch name. A branch name is 1 to 255 bytes and can
contain /. Each part between slashes must not be empty, must not be . or
.., and must not end with . or .lock.
A reference cannot contain @ or ~. Ancestry expressions such as main~1,
and timestamps, are not supported.
Resolution
A Table session resolves addresses in one Project. You open it with a default reference, which is a branch or a Project commit.
- No reference. The path resolves in the session's default state.
- Branch. The session reads the branch head the first time the address names that branch, and every later address with the same branch uses the same commit, even when lookups run concurrently. Refresh the session to see newer commits; refreshing creates a new session and leaves Tables and Scans you already opened unchanged.
- Commit. The path resolves in that Project commit.
- Version. The path resolves in the default state to find the resource, and the session then reads the requested version of it. The path must still name that resource in the default state.
After resolution, a Table and its Scans report an address with an exact
version, such as frames@v019a…. Store it to read the same data again.
Addresses in SQL
In the DataFusion integration, a Table's
SQL name is its address. Double quotes always work. With DataFusion's default
SQL dialect, you can leave them off when the address contains only letters,
digits, _, and @, as in frames@main. Quote anything with /, -, .,
or other characters, such as "robot-a/frames" or "frames@feature-x".
Availability
Python, the CLI, and Studio links do not accept addresses yet. Support in these clients is planned.