duckdb-variantlisted
Install: claude install-skill srimon12/duckdb-2-skills
# VARIANT
`VARIANT` is a binary columnar format where each value preserves its individual type, allowing rows within the same column to store distinct data types. `JSON` remains unparsed UTF-8 text. When filtering, projecting, or sorting semi-structured data, use `VARIANT`. When requiring byte-exact raw text preservation or JSON-specific mutation functions, retain `JSON`.
Run SQL queries with `duckdb`.
## Create and cast
To create and populate a `VARIANT` column, cast SQL literals, lists, structs, or parsed JSON text:
```sql
CREATE TABLE events (id INTEGER, data VARIANT);
INSERT INTO events VALUES
(1, 42::VARIANT),
(2, 'hello'::VARIANT),
(3, [1, 2, 3]::VARIANT),
(4, {'name': 'Alice', 'age': 30}::VARIANT),
(5, '{"user": {"id": 42}}'::JSON::VARIANT);
```
When displaying VARIANT objects, DuckDB formats keys in sorted alphabetical order: `{'name': 'Alice', 'age': 30}::VARIANT` prints as `{'age': 30, 'name': Alice}`.
VARIANT storage is supported in DuckDB native tables, Parquet files, and Delta tables. In Delta tables, write VARIANT at the top level only; nested VARIANT columns can be defined in schemas but cannot be written.
## Load JSON
Because `read_json` cannot read directly into a `VARIANT` target, ingest documents as `JSON` text first, then cast with `::VARIANT`. On 2.0.0 the failure is:
```text
Not implemented Error: Cannot read a value of type VARIANT from a json file
```
For a reliable ingest workflow:
1. Ingest as `JSON` and cast to `VARIA