union

simetrik union list

List source unions

Lists the source unions in your workspace. A union is a type of Simetrik resource that stacks multiple segments into a single combined table; this command returns each union's ID and name so you can pick one to act on next.

Filter by name with --search and cap the result set with --limit. Use it to find an existing union's ID before inspecting it with simetrik union describe or editing it. For the full detail of a single union — its segments, columns, and draft status — follow up with union describe.

See also: union describe, union create. Requires CLI access to the workspace. See permissions.

Flags

• -s, --search <query> — Search by name
• -l, --limit <n> — Max results
• -f, --format <fmt> — Output format: table|json

Examples

simetrik union list
simetrik union list --search ventas --limit 20
simetrik union list --format json

Exit codes

simetrik union describe

Describe a source union: segments, columns, union_segments, and draft status

Shows a single source union in detail: its segments, columns, union_segments, and whether it is still in draft (is_draft). Reach for this when you need to know the exact column layout or confirm a union has been confirmed before wiring it into downstream resources.

This is the deep view for one union; for a flat list across your workspace use simetrik union list instead. Note the default output format here is json (most other listings default to table), since the nested segment and column structure reads better as JSON.

See also: union list, union confirm. Requires CLI access to the workspace. See permissions.

Arguments

• resource_id — Union resource ID

Flags

• -f, --format <fmt> — Output format: table|json

Examples

simetrik union describe res_abc123
simetrik union describe res_abc123 --format table

Exit codes

simetrik union create

Create a source union from multiple segments. Pass --column-mappings (or its alias --columns) with empty "cells" lists to create schema-only columns, then populate them later with add-source-cells-bulk.

Creates a source union — a type of Simetrik resource that stacks several segments into one combined table. Pass --segments (required) with a JSON array of segment objects to define what gets unioned. Reach for this when you need a single dataset that spans multiple segments before reconciling.

Define columns up front with --column-mappings (alias --columns); pass empty "cells" lists to create schema-only columns and populate them later with simetrik union add-source-cells-bulk. A new union starts in draft and must be confirmed before its backing table exists — add --auto-confirm to run that step inline, or call simetrik union confirm afterward. If you pass both --column-mappings and --columns, --column-mappings wins.

See also: union confirm, union add-source-cells-bulk, union update. Requires the resources · create_edit permission. See permissions.

Arguments

• name — Union name

Flags

• --segments <json> — JSON array of segment objects
• --column-mappings <json> — JSON array of column mappings
• --columns <json> — Alias of --column-mappings
• -d, --description <text> — Description
• --folder <id> — Folder ID
• --auto-confirm — Auto-confirm after create
• -f, --format <fmt> — Output format: table|json

Examples

simetrik union create "Ventas consolidadas" --segments '[{"segment_id":"seg_1"},{"segment_id":"seg_2"}]'
simetrik union create "Pagos" --segments '[{"segment_id":"seg_1"}]' --column-mappings '[{"name":"amount","cells":[]}]' --folder fld_123
simetrik union create "Cuentas" --segments '[{"segment_id":"seg_1"}]' --auto-confirm

Exit codes

simetrik union update

Update a source union

Updates a source union's metadata: its --name and --description. This edits only the union's labels, not its segments or column structure — to change which columns map to which source cells use simetrik union add-source-cells-bulk, and to build a brand-new union use simetrik union create.

Pass the union_id (not the resource ID) as the argument, then any subset of --name and --description; only the flags you supply are sent.

See also: union create, union add-source-cells-bulk, union describe. Requires the resources · create_edit permission. See permissions.

Arguments

• union_id — Union ID

Flags

• --name <n> — New name
• -d, --description <text> — New description
• -f, --format <fmt> — Output format: table|json

Examples

simetrik union update uni_123 --name "Ventas 2026"
simetrik union update uni_123 --description "Unión de segmentos Q1 y Q2"

Exit codes

simetrik union confirm

Confirm a source union (creates Snowflake table)

Confirms a draft source union, which provisions its backing Snowflake table. A freshly created union stays in draft until you confirm it; run this once the union's segments and columns are set so the table materializes and downstream resources can read from it.

Confirmation kicks off an asynchronous task. By default the command returns as soon as the task is submitted; add -w/--wait to block until it finishes, tuning the deadline with -t/--timeout (seconds, default 120). When waiting, the command exits non-zero if the task fails or the timeout is hit. You normally won't call this if you created the union with --auto-confirm.

See also: union create, union describe. Requires the resources · create_edit permission. See permissions.

Arguments

• union_id — Union ID

Flags

• -w, --wait — Wait for completion
• -t, --timeout <n> — Timeout in seconds
• -f, --format <fmt> — Output format: table|json

Examples

simetrik union confirm uni_123
simetrik union confirm uni_123 --wait
simetrik union confirm uni_123 --wait --timeout 300

Exit codes

simetrik union add-source-cells-bulk

Add/update multiple columns with source-cell mappings in one bulk call. Each column object may include an optional "union_column_id": when present, cells of that existing UnionColumn are upserted (update mode); when omitted, a brand-new UnionColumn is created (legacy create mode). Create and update columns can be mixed in the same request.

Adds or updates multiple union columns and their source-cell mappings in a single bulk call. A source cell maps a union column to a specific column of one of the union's segments; this is how you populate the schema-only columns left empty at union create time.

Each object in --columns may include an optional "union_column_id": include it to upsert cells on that existing column (update mode), or omit it to create a brand-new union column (create mode). You can mix create and update objects in the same request. The target union_id must still be in draft state — confirm it only after the columns are wired, since confirming materializes the table.

See also: union create, union confirm, union describe. Requires the resources · create_edit permission. See permissions.

Arguments

• union_id — Union ID (must be in draft state)

Flags

• --columns <json> — JSON array of column definitions
• -f, --format <fmt> — Output format: table|json

Examples

simetrik union add-source-cells-bulk uni_123 --columns '[{"name":"amount","cells":[{"segment_id":"seg_1","column_id":"col_a"}]}]'
simetrik union add-source-cells-bulk uni_123 --columns '[{"union_column_id":"ucol_9","cells":[{"segment_id":"seg_2","column_id":"col_b"}]}]'

Exit codes