Data models

Create, review and publish data models. Learn about grains, field types, auto-suggested models, versioning and Git sync.

Updated Oct 2, 20267 min readEdit on GitHub

A data model turns raw tables into something a human can reason about. It answers three questions: what does one row represent (the grain), how does this table relate to others (the joins), and which numbers and attributes are safe to use (the measures and dimensions).

Start from a suggestion

When a source finishes its first sync, Kimo profiles every table: cardinality, null rates, value distributions and candidate keys. It then proposes models with a confidence score. Suggestions for well-known connectors (Stripe, HubSpot, Search Console, AIS) come from curated templates and are usually ready to publish as-is.

Field types

Each column in a model has a type. Types decide which aggregations are allowed, how values are formatted, and which filters appear in the UI.

Type	Examples	Allowed aggregations	Notes
`string`	plan, country, utm_source	count, count_distinct	Becomes a dimension by default.
`number`	amount, quantity, speed_kn	sum, avg, min, max, median, p90	Set a format: number, currency, percent.
`date` / `time`	created_at, observed_at	min, max	Enables time grains: hour → year.
`boolean`	is_trial, is_dark_vessel	count_true, ratio	Rendered as Yes / No.
`id`	customer_id, mmsi	count_distinct	Never summed; used for joins.
`geo`	lat/lon, country_code	—	Unlocks map tiles.

Choosing the grain

Getting the grain right prevents most analytics bugs. A subscriptions model has one row per subscription; an invoice_lines model has one row per line item. If you sum amount on a model whose grain is wrong (say, after joining lines to invoices), revenue will be inflated. Kimo warns you when a join changes the grain of a model.

Versioning and review

1
Draft
Edits create a draft. Drafts are private to editors and can be previewed against live data.
2
Review
Kimo shows a diff: added measures, changed SQL, and every dashboard tile affected by the change.
3
Publish
Publishing creates an immutable revision (rev_42). Roll back to any previous revision in one click.

Git sync

Connect a GitHub or GitLab repository under Settings → Git. Kimo commits each publish to a branch, and can also read models from main, so changes go through pull requests and CI checks. The CLI validates models locally:

1kimo models validate ./models2# ✓ subscriptions   12 measures, 9 dimensions3# ✓ web_sessions     6 measures, 14 dimensions4# ! invoice_lines    join to invoices changes grain (1:n)

Ownership and descriptions

Every model has an owner (a person or a group) who is notified when a sync breaks, a freshness SLA is breached or someone proposes a change. Owners are also shown next to certified measures, so people know who to ask. Write a two-line description for each model: what one row is, and what it should not be used for. Ask Kimo reads these descriptions to pick the right model, so a clear description directly improves answers.