> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/build/v1/productize/assets/inputs.md).

# Inputs

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, `input.yaml`, at the project root. You can write this file by hand, or generate it from a connected engine:

```bash
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 `external_models/` directory instead. Vulcan loads `input.yaml` first, then merges in every `.yaml` file under `external_models/`.

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.

```yaml
- 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.

## 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:

```sql
MODEL (
  name bronze.orders,
  kind FULL,
  grains (order_id)
);

SELECT order_id, customer_id, order_date, order_status
FROM public.orders_ext;
```

## Inputs versus seeds

Use an input (external model) when the table already lives in your engine and someone else owns it. Use a [seed](/build/v1/productize/assets/seeds.md) 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](/build/v1/move/overview.md) and bring it in first.

{% hint style="warning" %}
`input.yaml` is a pure contract: name, dialect, grains, and columns. It carries no validation rules, and Vulcan never detects drift on it: if someone alters or empties the source table, Vulcan doesn't know. An external table is only queried when a Vulcan model actually references it. To validate upstream data, add standalone [assertions](/build/v1/productize/assertions.md) or a [data quality](/build/v1/productize/data-quality.md) rule pack on the model that reads the input, not the input declaration itself.
{% endhint %}

For the full external-model reference, see [References → Vulcan → Data Models → Types → External Models](https://v2.dataos.info/references/resources/vulcan/models/data-models/types/external-models).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/build/v1/productize/assets/inputs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.