Virtual Table

A virtual table allows several regular tables to act as a unified logical table. Each contributing table is known as a partition.

Virtual tables fit three typical scenarios:

• Data polymorphism: when multiple, differently-structured tables share a single concept. Users only fill in the fields relevant to each partition, while the generated type covers the combined fields of all partitions.
• Collaborative workflow: when a regular table is co-managed by multiple team members. Sharding the data into separate partitions by config IDs reduces editing conflicts and improves team collaboration.
• Size management: when a table is too large for a single sheet and needs to be split across multiple sheets.

Configuration

To use virtual tables, you first need to create a configuration file that groups partitions under each virtual table name:

YAML

# Each key names a virtual table;
# each entry specifies a partition or a wildcard pattern.
item:
  - item-weapon
  - item-armor
  - item-potion

skill:
  - skill-*

JSON

{
  "item": ["item-weapon", "item-armor", "item-potion"],
  "skill": ["skill-*"]
}

Note

Archmage supports configuration files in YAML, JSON, JSON5, JS, TOML, and XML.

In the above example, item gathers three named partitions, and skill gathers every partition whose name matches skill-*. Each entry targets a partition via Referent Syntax (a file or worksheet name). You can use * and ? wildcards to match multiple partitions at once.

Once defined, pass the file to Archmage using the --vtables-config CLI flag.

archmage export -o ./cooked --vtables-config ./vtables.yaml "configs/*.xlsx"

How It Works

• Data Export: Each partition writes its own output file, exactly as it would on its own; no merged file is produced. In atlas.json, these output files are grouped into the multiple section as an array per virtual table. See Data Export for details.
• Code Generation: Archmage generates a single unified type for the virtual table, accommodating the combined fields of all partitions. Fields unique to a specific partition default to their zero values for entries from other partitions.
• Runtime: At config load time, the partition output files are read together and merged into a single runtime dictionary keyed by config ID.

Tip

When partitions have different structures, keep shared fields identically named so they resolve into a single field. Additionally, place partition-specific fields under their own Sections to keep the generated type organized.

Tip

Use the origin type to identify which partition a config entry belongs to.

References

A virtual table acts as a single referent for all cross-table references. When using ref@, backref@, or backref-n@, you must target the virtual table itself by its name. Its partitions cannot be referenced on their own.

Constraints

• Eligible partitions — A partition must be a regular table or a tree-backed regular table.
• One virtual table per partition — A partition must not belong to two virtual tables.
• Consistent config ID type — Every partition within a virtual table must use the same config ID type.
• Unique config IDs — Config IDs must be unique across all partitions; the same ID cannot appear in more than one partition.
• Compatible fields — Partitions may define different fields, but identically named fields across partitions must share the same type.
• Naming rules — A virtual table name must follow the Typical Naming Rules.