Tables

A table is the raw analytical object that connected data lands in. Tables are the foundation of Gaur: models are built on tables, and contracts ultimately read from tables and models.

How tables are created

You don't create tables by hand. A table appears when you connect a data source. Gaur ingests the source, infers a schema, verifies the declared primary key, and registers the result as one or more tables.

The Jaffle Shop sample dataset, used as the running example throughout these docs, ships as six raw CSV files. After ingestion they become six tables: raw_orders, raw_items, raw_customers, raw_products, raw_stores, and raw_supplies. raw_supplies is the one with a composite primary key (id, sku), because the BOM has one row per (supply, product). The others are keyed on a single column.

Each table has:

• A name, its stable identifier within the workspace.
• A schema, the columns and their data types, inferred at ingestion.
• A primary key, the column or columns that uniquely identify a row, declared at ingestion. See Primary keys.
• Metadata: row count, data size, and the source it came from.
• An optional refresh schedule (see below).

Inspecting a table

Open a table to see its schema and metadata, and use exploration to run read-only SQL against it. That's how you learn what a table contains before building on it.

Refreshing a table

A table holds a snapshot of its source as of the last ingestion. To keep it current, you run refreshes. Gaur supports full, append, and incremental refresh modes, on demand or on a schedule. See Refreshes for the full picture.

Tables in contracts

A contract can read directly from a table by listing it as a source:

{
  "source_type": "table",
  "name": "raw_items",
  "alias": "i"
}

A table is a fine contract source when the data is already in the shape you need. When it isn't, when you need cleaning, reshaping, or pre-aggregation, build a model on top of the table first.

Limitations

Tables are deliberately simple. Knowing their limits tells you when to reach for a model or a contract instead.

• Tables are raw. A table reflects its source as ingested. Cleaning, renaming, type-fixing, and reshaping don't happen at the table level. Use a model for that.
• No business logic. Tables have no measures, no dimensions, and no governed semantics. Those belong to contracts.
• The source defines the schema. A table's schema is inferred from the data at ingestion. If the source schema changes, a refresh can surface those changes, so design models and contracts to tolerate it.
• Not directly consumable. Applications never query a table. Tables are a building block; consumers only ever query contracts through a consumer.
• Snapshot semantics. Without a refresh schedule, a table doesn't update on its own. It's only as fresh as its last ingestion or refresh.

Next