Use Table

Data Manipulation

Synopsis

Selects which allocated virtual table the entry marshals from for the shipped output. name: "map", name: "none", or an empty name revert output to the untyped Map — the default before any use_table runs.

Schema

- use_table:
    name: <string>
    description: <text>
    if: <script>
    tag: <string>
    disabled: <boolean>
    ignore_failure: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>

Configuration

Field	Required	Default	Description
name	Y		Table to marshal the entry from. map, none, or an empty string revert output to the untyped Map. Matched case-insensitively; supports templating, e.g. name: "{{table}}".
description	N		Explanatory note.
if	N		Condition that must be true for the processor to run.
tag	N		Identifier for this processor instance.
disabled	N	false	When true, the processor is skipped.
ignore_failure	N	false	Continue pipeline processing if the processor fails.
on_failure	N		See Handling Failures.
on_success	N		See Handling Success.

Details

What use_table Selects

use_table is the single switch every output path reads when it marshals the entry: the final pipeline result, reroute's parked payload, and any debug or JSON dump of the entry. Selecting name: Syslog after Syslog has been allocated and written to (see Create Table) means every one of those paths emits the Syslog table's present fields instead of Map.

The Map Is Dropped Entirely

Once a table is selected, the output is only that table's present fields. Map is not merged, appended, or referenced in any way — every field the pipeline ever left in Map, including fields written by earlier processors, enrichment steps, or the _vmetric system namespace itself, is absent from the shipped output unless it was also written into the table through an explicit $<table>.Field path. There is no fallback and no warning: a field a downstream reader expects, that only ever landed in Map, silently does not ship.

Reverting to Map

name: "", name: "map", and name: "none" are synonyms that revert output to Map — the state before any use_table runs. Dropping the selected table with Drop Table has the same reverting effect if the dropped table was the current selection; otherwise a live table stays selected until one of these two things happens.

Failure Mode

Selecting a name that is not one of the 12 registered tables fails the processor, same as create_table. Selecting a known table name that was never allocated with create_table on this entry also fails — cannot use virtual table "<name>": unknown or not created — there is no silent fallback to Map in either case. Add ignore_failure: true to treat either failure as a soft skip.

Clones

pipeline: { clone: true }, reroute's clone: true, and every other internal entry-copy path copy every allocated table by value into the new entry and carry over whichever table the source had selected as output, if any. A clone is then free to run its own use_table — selecting a different table, or reverting to Map — without affecting the source entry or any sibling clone.

Examples

Selecting a Table as the Marshal Source

Writing into the table, then selecting it as the marshal source...	{ "message": "raw line" } - create_table: name: Syslog - set: field: $syslog.SyslogMessage value: "{{{message}}}" - use_table: name: Syslog
Output is now the Syslog table's present fields only; the message key that lived in Map is gone...	{ "SyslogMessage": "raw line" }

The Map-Drop Trap: Fields Left in Map Do Not Ship

Enriching a field after Syslog has already been selected as the output...	{ "message": "raw line" } - create_table: name: Syslog - set: field: $syslog.SyslogMessage value: "{{{message}}}" - use_table: name: Syslog - set: field: geo.country value: "US"
geo.country is a bare field name, so it lands in Map like any ordinary write — but Map no longer ships once use_table has selected Syslog, so geo.country never reaches the output. It must be written as $syslog.<column> to survive...	{ "SyslogMessage": "raw line" }

Reverting Output to Map

Selecting Syslog, then reverting with name: "map"...	{ "message": "raw line", "app": "sshd" } - create_table: name: Syslog - set: field: $syslog.SyslogMessage value: "{{{message}}}" - use_table: name: Syslog - use_table: name: "map"
Output reverts to the full, untouched Map — message and app both ship; the Syslog table's contents, still allocated, are simply not what marshals...	{ "message": "raw line", "app": "sshd" }

Failing on a Table That Was Never Created

Selecting Syslog before anything has allocated it on this entry...	{} - use_table: name: Syslog ignore_failure: true
Syslog is a known table name, but nothing ever create_table-d it on this entry, so selecting it fails; ignore_failure skips the failure and output stays on Map...	{}