User Guide¶

This guide covers the core features of the DuckDB YAML extension in depth.

Overview¶

The YAML extension provides comprehensive support for working with YAML data in DuckDB:

Feature	Description
Reading YAML Files	Load YAML files into tables with automatic schema detection
Frontmatter Extraction	Extract YAML frontmatter from Markdown and text files
YAML Type	Native YAML type with conversion functions
Writing YAML Files	Export query results to YAML format
Type Detection	Automatic detection of dates, times, and numeric types
Error Handling	Robust error recovery and validation

Core Concepts¶

YAML Documents¶

YAML supports multiple documents in a single file, separated by ---:

---
name: Document 1
---
name: Document 2

The extension handles multi-document YAML automatically, treating each document as a separate row.

YAML Sequences¶

Top-level sequences are expanded into individual rows:

- name: Alice
  age: 30
- name: Bob
  age: 25

This produces two rows when read with read_yaml.

Path Expressions¶

Many functions use path expressions to navigate YAML structures:

$ - Root of the document
$.field - Access object field
$[0] - Access array element
$.user.address.city - Nested access

Type System¶

The extension provides a native YAML type that:

Stores YAML as text internally
Supports casting to/from JSON and VARCHAR
Enables type-safe operations

Quick Reference¶

Reading Functions¶

-- Table functions
read_yaml(path, ...)           -- Read YAML files into rows
read_yaml_objects(path, ...)   -- Read files preserving structure
read_yaml_frontmatter(path, ...)  -- Extract frontmatter from files
parse_yaml(string, ...)        -- Parse YAML string into rows

Extraction Functions¶

yaml_extract(yaml, path)         -- Extract value at path
yaml_extract_string(yaml, path)  -- Extract as string
yaml_exists(yaml, path)          -- Check if path exists
yaml_type(yaml [, path])         -- Get value type
yaml_keys(yaml [, path])         -- Get object keys
yaml_array_length(yaml [, path]) -- Get array length

Conversion Functions¶

yaml_to_json(yaml)    -- Convert to JSON
value_to_yaml(value)  -- Convert DuckDB value to YAML
format_yaml(yaml, style)  -- Format with specific style

Table Functions¶

yaml_each(yaml)            -- Key-value pairs
yaml_array_elements(yaml)  -- Array elements as rows

Next Steps¶

Start with Reading YAML Files to learn how to load YAML data into DuckDB.