Connecting Your Data
A user-level overview of how KeyOne reads your data — what it needs, the grain it works at, how a warehouse is bound to KeyOne’s vocabulary, what is automated versus done with the KeyOne team, and what to expect once a source is bound. About 8 minutes.
KeyOne is only as good as the data behind it. This guide explains, in plain terms, what data KeyOne needs and how it reaches the screens — without the engineering detail. It is deliberately honest about which steps are hands-on today.
The two data worlds KeyOne joins
A principal (brand owner) lives in two data worlds, and KeyOne’s job is to unify them:
| World | What it contains | Typical source |
|---|---|---|
| Internal (your ERP) | Sell-in, orders and deliveries, prices and costs, targets, trade spend | SAP / ERP extracts |
| External (the retailer and the field) | Sell-out, store stock, shelf audits, prices seen in store, visits | Retailer scan / POS portals, KeyLink captures |
Neither world alone tells the whole story. Your ERP knows what you shipped; the retailer knows what sold and what’s on shelf. KeyOne reads both from one place — your warehouse.
DiagramTwo data worlds, reconciled into one trusted number
The grain: SKU × Store × Day
KeyOne works at the lowest useful grain — every SKU, in every Store, on every Day. Almost every metric you’ll see (rate of sale, OSA, distribution, share) is computed from this base and rolled up from there. Where a figure is only available at a coarser grain, KeyOne says so on the screen rather than implying a drill-down that does not exist.
Why this matters to you: because the data is held at SKU × Store × Day, you can drill from a national KPI down to a single store and a single product on a single date. Every decision carries a Show the data behind this card link to the exact rows and query it came from.
KeyOne reads your warehouse — it does not copy it
KeyOne does not ingest files into a data lake of its own. It connects to a warehouse you run and reads from it directly. Supported today: PostgreSQL, BigQuery, Snowflake, Databricks and Athena (and DuckDB, which is what the demo runs on).
Every rule, KPI and chart in KeyOne is written against a fixed canonical vocabulary — 60 named fields across the entities (product, customer, outlet, distributor, geography, channel, rep, promotion, time) and the fact tables (sales, price, stock, orders, targets, shelf, visits, trade spend). A binding maps each canonical field to a real table and column in your warehouse. Once bound, the same shipped rules run over your data without being rewritten.
Only a handful of fields are required for a source to be usable at all; the rest switch on what they feed. A hub whose facts are unbound says so — “the field-execution hub is empty” becomes “you have no visit data bound”, which is a different problem with a different fix.
Settings → Sources & binding shows all of this live: whether the source is reachable, how many of the 60 canonical fields are mapped, which fact tables are usable, and which required fields (if any) are missing.
What’s automated vs. hands-on today
This is where honesty matters. As of today:
| Step | Status |
|---|---|
| Landing your ERP and retailer extracts in your warehouse | Yours — KeyOne reads the warehouse; it does not run your ETL |
| Writing the binding (canonical field → your column) | With the KeyOne team — a configuration file per deployment, not yet a screen |
| Checking the binding | Automated — Settings → Sources & binding reports coverage and reachability |
| Adopting products and outlets into KeyOne’s master records | Automated, one click — see below |
| Computing KPIs, charts and decisions once bound | Automated — scheduled runs every fifteen minutes, visible under Settings → Run history |
No false green. Binding a warehouse from inside the app is something KeyOne is building toward, but it is not a click-it-yourself feature today. If you need a source bound, that’s arranged with the KeyOne team. We’d rather tell you that plainly than ship a wizard that silently does nothing.
Master data: adopting what your data already names
KeyOne does not invent products or outlets. It reads the codes that appear in your bound facts and lets you adopt them into its master records:
- Products and Customers each open on a line saying how many codes in your data have a record, and how many do not.
- One click adopts the rest — name, code and whatever the warehouse carries (a list price, a case size, a region). Nothing else is filled in: a field your data does not carry stays blank rather than being guessed.
- Anything you know beyond the sales figures — a store grade, cold storage, a delivery day, a contact — is recorded by a person, in the app, and kept apart from the figures the warehouse supplies.
A code your data references but nobody has adopted still counts in every KPI; adoption is what gives it a page, a name and the fields above.
What to expect once a source is bound
- Hubs populate. KPI strips and charts render from your warehouse on the next scheduled run. (See Using a Hub.)
- Decisions appear. The definitions start raising decisions, which land in Decisions and on the hub they belong to.
- KeyChat gets useful. You can ask grounded questions about the data, answered with the same read-only tools. (See KeyChat.)
A source that is unreachable, or a fact table that is unbound, shows an honest state on every screen that needs it — a KPI reads “no source”, a hub says which facts it lacks — never a zero standing in for a number nobody measured. (See FAQ & Troubleshooting.)
Common pitfalls
- Expecting instant charts. The first run after binding is scheduled, not immediate. Settings → Freshness shows when each rule last succeeded.
- Reading an unbound fact as “no data”. “Unbound” means KeyOne has not been told where to look; “no rows” means it looked and found nothing. The Sources & binding page tells them apart.
- Codes that differ between systems. KeyOne keys everything on the codes in your bound facts. If your ERP and your retailer feed name the same product differently, that is resolved in your warehouse before KeyOne reads it — not guessed at afterwards.
Next: Notifications