> For the complete documentation index, see [llms.txt](https://docs.omics.ai/products/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omics.ai/products/command-line-interface/reference/workbench/samples-metadata-upload.md). # samples metadata upload Upload pedigree, phenopacket or attributes files ## Synopsis ```shell 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`. {% hint style="warning" %} 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. {% endhint %} | 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. ```json { "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](/products/command-line-interface/reference/workbench/samples-attributes-set.md) and [samples attributes clear](/products/command-line-interface/reference/workbench/samples-attributes-clear.md). ### 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 | {% hint style="info" %} Exit code `2` is also the code the CLI returns for a usage error, such as an unrecognized flag. {% endhint %} ### 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: ```shell omics workbench samples metadata upload family.ped ``` Upload several files of different kinds at once: ```shell omics workbench samples metadata upload family.ped subject.json lab.attributes.json ``` Upload an archive containing a mix of files: ```shell omics workbench samples metadata upload cohort.zip ``` Add metadata without overwriting values the samples already have: ```shell omics workbench samples metadata upload family.ped --preserve-existing ``` Treat a partial upload as a failure in a script: ```shell 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. {% hint style="info" %} This flag has no effect on custom attributes. An attributes upload always replaces the named sample's attributes. {% endhint %} ### `--namespace`=`STRING` An optional flag to define the namespace to connect to. By default, the namespace is extracted from the user's credentials. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.omics.ai/products/command-line-interface/reference/workbench/samples-metadata-upload.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.