For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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:

Upload several files of different kinds at once:

Upload an archive containing a mix of files:

Add metadata without overwriting values the samples already have:

Treat a partial upload as a failure in a script:

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.

Last updated

Was this helpful?