Inputs
Declare the upstream tables your models read from, as external models.
Inputs are the upstream tables your product reads but doesn't own. You declare them as external models. This tells Vulcan the shape of each table, so it can resolve dependencies and build lineage, without copying or managing the data itself.
The raw source tables stay owned by whoever produced them. Everything you build on top of them belongs to your product.
In
orders-analytics, 9 raw tables follow thepublic.*_extnaming pattern: orders, order items, customers, products, regions, shipments, warehouses, suppliers, and dates. They stayEXTERNAL. The bronze, silver, and gold models built on top of them belong to the product.
Declare external models
External inputs live in one file, inputs.yaml, at the project root (inputs.yml works too; if both exist, inputs.yaml is used). You can write this file by hand, or generate it from a connected engine:
vulcan create_external_modelsIf some tables need manual definitions that create_external_models can't discover (or that regeneration would overwrite), put those in the inputs/ directory instead. Vulcan loads the main inputs file first, then merges in every .yaml file under inputs/.
Each entry names the source table and lists its columns, so Vulcan can validate references and build lineage. Add grains to declare each table's primary key. Vulcan needs the grains to infer joins between external tables in your semantic layer. Without it, joins across these inputs can't be resolved.
- name: public.orders_ext
grains:
- order_id
columns:
order_id: INTEGER
customer_id: INTEGER
order_date: TIMESTAMP
warehouse_id: INTEGER
order_status: VARCHAR
- name: public.customers_ext
grains:
- customer_id
columns:
customer_id: INTEGER
region_id: INTEGER
name: VARCHAR
email: VARCHAR
signup_date: DATEYou can also set dialect on an entry when the source table's SQL dialect differs from your project's default, so Vulcan parses and renders references to it correctly.
When your engine is Trino or Spark and a table is reached through a catalog that points at another system, set remote_engine to record the system the data actually lives in. It's free-text metadata that shows up with the input; Vulcan doesn't validate it:
Read an input in a model
To read an input inside a model, reference the external table by name in your FROM clause. Vulcan detects the dependency and orders the run accordingly:
Inputs versus seeds
Use an input (external model) when the table already lives in your engine and someone else owns it. Use a seed when you maintain a small reference table yourself and want to version it in Git.
If the data you need isn't reachable yet, it isn't an input. Go back to Move and bring it in first.
For the full external-model reference, see References → Vulcan → Data Models → Types → External Models.
Last updated
Was this helpful?