For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 the public.*_ext naming pattern: orders, order items, customers, products, regions, shipments, warehouses, suppliers, and dates. They stay EXTERNAL. 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_models

If 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: DATE

You 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.

Last updated

Was this helpful?