samples metadata upload

Upload pedigree, phenopacket or attributes files

Synopsis

omics workbench samples metadata upload [FILE...]
  [--preserve-existing]
  [--namespace=STRING]

Description

Upload sample metadata from one or more files. A single upload can carry pedigree, phenopacket and custom attribute files together, including inside a .zip.

The file name decides how each file is read. There is no content detection and no fallback, so a correctly formatted file with the wrong name fails as the format its name implies.

File name	Read as
*.ped	Pedigree
*.attributes.json	Custom attributes
*.json, *.jsonl	Phenopacket
*.zip	An archive containing any of the above

A file named cohort.json is read as a phenopacket and fails as one, even when it contains attributes. Rename it to cohort.attributes.json.

The attributes document

An attributes file is a JSON object keyed by sample ID. The sample must already exist.

{
  "HG002": {"kit_lot": "A7-2291", "passed_qc": true},
  "HG003": {"kit_lot": "A7-2291"}
}

Values can be text, numbers, lists or nested objects.

Uploading attributes replaces each named sample's attributes outright — anything the document omits is deleted, so include everything you want to keep. Every sample in the document needs at least one attribute; an empty object is reported as an error for that sample rather than clearing it. To change or remove a single sample's attributes, use samples attributes set and samples attributes clear.

Results and exit codes

Every file is reported on its own row, and sampleIds lists the samples that file wrote. Partial success is normal: a file naming one sample that does not exist applies the rest and names the missing one in errors.

The operation is not atomic. Files that already succeeded stay written when a later file fails.

Exit code	Meaning
0	Every file applied cleanly
1	Nothing was written
2	Partial — some samples were written, some were not

Exit code 2 is also the code the CLI returns for a usage error, such as an unrecognized flag.

Limits

5 MB per file and 25 MB per request. A .zip is additionally bounded at 50 MB decompressed and 1000 entries. Exceeding a limit returns an error rather than a truncated upload.

Examples

Upload a pedigree file:

omics workbench samples metadata upload family.ped

Upload several files of different kinds at once:

omics workbench samples metadata upload family.ped subject.json lab.attributes.json

Upload an archive containing a mix of files:

omics workbench samples metadata upload cohort.zip

Add metadata without overwriting values the samples already have:

omics workbench samples metadata upload family.ped --preserve-existing

Treat a partial upload as a failure in a script:

omics workbench samples metadata upload lab.attributes.json || echo "not everything landed"

Positional Arguments

FILE

A metadata file to upload. Specify multiple files to upload them in a single request. The file name is sent exactly as given, and determines how the service reads the file.

Flags

--preserve-existing

Keep the values a sample already has instead of overwriting them. Without this flag, a pedigree or phenopacket replaces the sample's existing sex, affected status, family and parentage, and replaces its phenotypes rather than adding to them.

With this flag, only fields the sample does not already have are filled, and phenotypes are added to the sample's existing ones.

This flag has no effect on custom attributes. An attributes upload always replaces the named sample's attributes.

--namespace=STRING

An optional flag to define the namespace to connect to. By default, the namespace is extracted from the user's credentials.