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.

Tip

Tree-Backed Regular Tables are also Regular Tables and can serve as partitions.

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"

Requiring Identical Structure

Append |schema-identical to a virtual table name to require that every partition has the same structure. The flag is case-insensitive.

quest|schema-identical:
  - quest-*

When this flag is specified, Archmage reports an error when a field exists in only some partitions. The order of fields does not matter.

Note

Here, “structure” refers to the output structure, not the input structure. Given a field foo, it is pruned by xflags during processing, so it is present in the input structure but absent from the output structure.

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 many 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 code 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 either a regular table or a tree-backed regular table.
• Partition membership — A partition belongs to exactly one virtual table.
• Consistent config ID type — Every partition within a virtual table must use the same config ID type.
• Unique config IDs — Within a virtual table, config IDs must be unique across all partitions.
• Compatible fields — Partitions within a virtual table may define different fields, but identically named fields must share the same type.
• Identical structure — A virtual table flagged as schema-identical requires all partitions to have the same structure.
• Single origin field — Once the partitions are merged, the virtual table may contain at most one origin field. All partitions with an origin field must use the same field name.
• Shared origin value — Partitions sharing an origin value must have the same structure, even without |schema-identical.
• Naming rules — Virtual table names must follow the Typical Naming Rules.