Native Experiment run metadata
A native run has a human description and tags. Projects whose
GET .../status lists the run-metadata capability accept them on create and
on update. Both writes require a signed-in user with write access to the
project, or a write session that user minted. A job session cannot set them and
gets 403 NATIVE_FORBIDDEN.
PUT /native-experiments/ns/:namespace/projects/:project/runs/:runKey creates
or returns the run, and PATCH .../runs/:runId updates it:
| Field | Absent | null / "" / [] | Value |
|---|---|---|---|
description | unchanged | null or "" clears it | a string of at most 2,000 code points |
tags | unchanged | [] clears them | replaces the whole set |
Tags are trimmed and de-duplicated in order; there can be at most 20 tags of
at most 50 code points each. Writing the stored values again changes nothing,
so a repeated PUT is safe. PATCH also accepts archived (a boolean). A
change to description or tags restores an archived run unless the same body
sets archived: true. A write-protected run rejects a change with
409 NATIVE_RUN_WRITE_PROTECTED, but can still be archived.
The same rules apply wherever the run is stored: in the main DreamLake database, or in the separate Dash database used for new runs when the server runs the native Dash store. A run keeps its storage, so a metadata write never moves it.
An invalid value returns 400 NATIVE_INVALID_RUN_METADATA. Any other field
returns 400 NATIVE_INVALID_RUN on PUT and 400 NATIVE_INVALID_ARCHIVE on
PATCH. Every run response and the run list return description (null when
unset) and tags ([] when unset).
Additional metadata
The API also accepts a metadata object or null on run creation and
updates. GraphQL Experiment.metadata and its experiment Node.metadata return
that value from the run's original storage. me, namespace and project metadata
use DreamLake's canonical records; workload and job credentials do not gain
project or account metadata access.
Run, file and folder PATCH routes also accept priority, a signed 32-bit integer.
GraphQL tree children put higher priorities first. Files initially use ml-dash's
defaults: .dashrc 200, README.md 100 (case-insensitive), and other names 0.
Renaming or moving a file retains its priority. File metadata can be any JSON
value; run metadata remains an object or null.
Project folders
POST /native-experiments/ns/:namespace/projects/:project/folders and
PATCH …/folders/:folderId also accept description, tags, metadata (any JSON)
and priority (a signed 32-bit integer). Missing fields stay unchanged; null
clears the description or metadata, and [] clears tags. These values stay with
the folder's ID through renames and moves. GraphQL updateNode edits its
description and tags. Writes require a person's WRITE access and refuse a
protected, trashed or pending folder. Empty project folders are retained.
Inside a run, GET/POST …/runs/:runId/folders and
GET/PATCH/DELETE …/runs/:runId/folders/:folderId manage file folders, including
empty ones. Create with { "path": "/checkpoints/empty" }; PATCH accepts the same
metadata fields and an optional new path. A move keeps folder and file IDs.
Delete removes the subtree permanently. These operations stay in the run's
original storage, honor its write protection, and restrict a run-bound writer
or job to that run. The server advertises them as file-folders.
Run file prefixes accept Unicode, spaces, commas and percent signs. For example,
/实验 记录/a,b/%2C keeps those names literally through uploads, folder moves,
file listings and downloads. File names are single path segments; control
characters and . or .. segments are rejected. Extended paths use the same
lifecycle rollout gate as file folders.