*! version 1.9.2 22Feb2026

help yaml examplesversion 1.9.2

Title

yaml -- Examples

Basic usage

Read a YAML file into the current dataset:

. yaml read using "config.yaml", replace

. yaml describe

Read with return locals (for immediate use):

. yaml read using "config.yaml", locals replace

. display r(yaml_name)

. display r(yaml_version)

Read with scalars (numeric values only):

. yaml read using "config.yaml", scalars replace

. scalar list

Use abbreviations for common subcommands:

. yaml desc // same as yaml describe

. yaml check // same as yaml validate

. yaml frame // same as yaml frames

Working with frames (Stata 16+)

Load into a named frame (preserves current dataset):

. sysuse auto, clear

. yaml read using "config.yaml", frame(cfg)

. display _N

74

// auto dataset is untouched

Load multiple YAML files simultaneously:

. yaml read using "dev_config.yaml", frame(dev)

. yaml read using "prod_config.yaml", frame(prod)

. yaml frames, detail

Query from a specific frame:

. yaml get database:host, frame(dev)

. local dev_host = r(host)

. yaml get database:host, frame(prod)

. local prod_host = r(host)

Clean up frames:

. yaml clear dev // clear one frame

. yaml clear, all // clear all yaml_* frames

Querying YAML data

Get indicator metadata using colon syntax:

. yaml read using "config.yaml", replace

. yaml get indicators:CME_MRY0T4

label: Under-five mortality rate

unit: Deaths per 1000 live births

dataflow: CME

Get specific attributes only:

. yaml get indicators:CME_MRY0T4, attributes(label unit)

List child keys under a parent:

. yaml list indicators, keys children

Keys under indicators: CME_MRY0T4 CME_MRY0 CME_MRY0T27D

Loop over indicator codes:

. yaml list indicators, keys children

. foreach ind in `r(keys)' {

. yaml get indicators:`ind', quiet

. display "`ind': `r(label)' (`r(unit)')"

. }

Use Stata compound quotes (for keys with special characters):

. yaml list indicators, keys children stata

. foreach ind in `r(keys)' {

. display "Processing: `ind'"

. }

Validation

Check that required keys exist:

. yaml read using "pipeline_config.yaml", replace

. yaml validate, required(name version database api)

Validate types:

. yaml validate, types(database_port:numeric api_timeout:numeric debug:boolean)

Use in a pipeline guard:

. yaml check, required(name version)

. if (r(valid) == 0) {

. display as error "Configuration validation failed!"

. exit 198

. }

Fast-read mode

Fast-read is a speed-first parser for large YAML files with regular structure
(e.g., indicator catalogs). It produces a flat table with columns:
key, field, value, list, line.

Basic fast-read:

. yaml read using "indicators.yaml", fastread replace

. list in 1/5

Fast-read with field filtering:

. yaml read using "indicators.yaml", fastread replace ///

. fields(name description source_id)

Fast-read with list extraction:

. yaml read using "indicators.yaml", fastread replace ///

. fields(name topic_ids) listkeys(topic_ids)

Fast-read with caching (Stata 16+):

. yaml read using "indicators.yaml", fastread replace ///

. fields(name description) cache(ind_cache)

// second call hits cache:

. yaml read using "indicators.yaml", fastread replace ///

. fields(name description) cache(ind_cache)

. display r(cache_hit)

1

Bulk parsing and collapse (Stata 16+)

Mata bulk-load (bulk) provides high-performance parsing via Mata.
Combined with collapse it produces wide-format output with one row per
top-level key.

Bulk parse (long format):

. yaml read using "indicators.yaml", bulk replace

Bulk parse with collapse (wide format):

. yaml read using "indicators.yaml", bulk collapse replace

Collapse with field filtering:

. yaml read using "indicators.yaml", bulk collapse replace ///

. colfields(code;name;source_id;description)

Collapse with depth limit:

. yaml read using "indicators.yaml", bulk collapse replace maxlevel(2)

Use strL for long values (>2045 chars):

. yaml read using "indicators.yaml", bulk strl replace

Indicators preset

The indicators preset is a one-step shortcut for parsing wbopendata and
unicefdata indicator metadata YAML files. It automatically enables bulk
and collapse with standard field selection.

Parse indicator metadata:

. yaml read using "unicef_indicators.yaml", indicators replace

// equivalent to: bulk collapse colfields(code;name;source_id;...)

. list key code name in 1/5

Round-trip: read, modify, write

Read a YAML file, modify a value, and write it back:

. yaml read using "config.yaml", replace

. replace value = "new_value" if key == "settings_timeout"

. yaml write using "config_modified.yaml", replace

Write scalars to a new YAML file:

. scalar project = 1

. scalar year = 2026

. yaml write using "output.yaml", scalars(project year) replace

Real-world: efficient metadata ingestion with frames

This pattern is used by unicefdata and wbopendata for processing
large indicator catalogs. Direct dataset queries are ~50x faster than iterating
yaml get calls.

. yaml read using "indicators_catalog.yaml", frame(metadata)

. frame yaml_metadata {

. gen is_match = regexm(key, "^indicators_[A-Za-z0-9_]+_dataflow$") ///

. & value == "NUTRITION"

. gen indicator_code = regexs(1) if ///

. regexm(key, "^indicators_([A-Za-z0-9_]+)_dataflow$") & is_match

. levelsof indicator_code if is_match, local(nutrition_indicators) clean

. foreach ind of local nutrition_indicators {

. levelsof value if key == "indicators_`ind'_name", local(ind_name) clean

. display "`ind': `ind_name'"

. }

. }

. frame drop yaml_metadata

Also see

Help: yaml, what's new