Write definitions Databasin can use

A Data Exchange can carry the definitions behind its data: how each metric is calculated, what your business terms mean, and the rules every query must follow. Once you approve them, the agent uses your exact calculations instead of working out its own.

Three kinds of definitions

• Guide. The few rules that apply to everything in the exchange, such as "Leave test accounts out of every customer count" or "Leave out today, it is still loading". The agent reads the guide with every question, so keep it short (at most 6,000 characters).
• Table and column notes. What a table or column really holds, such as "One row per day" or "This is the person, not the subscription". The agent sees a note whenever it looks at that table.
• Metrics and terms. One entry per metric or business term. The agent looks up only the ones a question needs, so an exchange can hold hundreds without slowing it down.

Everyone who can open the exchange gets the approved definitions in Databasin One. Only the exchange owner can add, change, check and approve them.

Add definitions from a file

Open the exchange, go to Knowledge, and import a file:

Nothing is used until you review it. Your original file is kept in your project's document storage, so you can open it again from the Sources tab.

Spreadsheets

Use one sheet for each kind of definition. Column names can be written in any case, and common alternatives work too.

• Metrics: Key, Name, Also known as, Category, Status, Summary, What it means, Query to run, How it's calculated, Watch out for, One row per, Can it be added up?, Related, Why it's blocked
• Terms: Key, Term, Also known as, What it means, Status, Ruling, Who decides, Related
• Tables: Table, Note
• Columns: Table, Column, Note
• Guide: a single Guide column, with one rule per row

Alternatives such as "In plain English", "Read it from the mart", "Where the number comes from" and "See also" are recognised. If a sheet's columns aren't recognised, the AI suggests what each column holds, and you confirm before anything is imported.

A few values have fixed choices:

• Status for a metric is Live or Blocked. Blank means Live. A blocked metric needs Why it's blocked.
• Status for a term is Open or Settled. Blank means Open. A settled term needs a Ruling.
• Can it be added up? is Yes, Not across days, No, recalculate it, or Not sure.
• Also known as and Related hold several values separated by semicolons.

Tables are written as catalog.schema.table.

Text and PDF: the card format

Write one card per metric, and one per decision or term. Headings can be in any case.

M1  active_subscribers  GROWTH
Paying subscribers on a given day.

What it means
Count the people with a running paid subscription on the day.

Query to run
SELECT day, subscribers FROM analytics.mart.daily_subscribers

How it's calculated
SELECT d.day, COUNT(DISTINCT d.customer_id) ...

Watch out for
A snapshot: never add days together.

Status: Live
Can it be added up: Not across days
Related: T1

T2  revenue  FINANCE
When we say revenue, do we mean the cash received or the plan value?
Ruling: Cash received.

Some tips for good cards:

• Keep your own keys (M1, T2). They're how a new version of the file is matched to the old one.
• Put the query people should run under Query to run, and the full calculation under How it's calculated. The agent runs the first and explains with the second.
• Write Watch out for plainly. The agent follows it, so "exclude today" there means today is left out.
• Write decisions as terms. While a term has no ruling, the agent says which meaning it used.
• Don't invent queries. A card with no query is still useful: the agent follows the meaning.

What gets skipped

Work queues, to-do lists, tasks assigned to people, dated change logs and meeting notes are not definitions, so they're skipped. After the import you'll see a list of every section that was skipped.

Importing a new version

When your document changes, import it again. Entries are matched by key and marked New, Changed, Unchanged or Removed. Changed entries go back to review, and the approved version stays in use until you approve the new one.

Tick This file is the complete list to mark entries that are missing from the file for removal. Only the kinds of definition the file contains are affected, so a metrics-only file never removes your terms.

Check against data

Check against data tests definitions against your warehouse before you approve them. It:

• confirms the tables and columns exist, and fixes renamed catalogs or schemas;
• makes sure each query compiles;
• spot-checks things like a table's grain, and that metric names exist in the table they're read from;
• previews a few metrics to confirm they return rows.

It runs at most 50 queries that read data, plus compile checks that read no rows. Nothing it reads from your data is stored: only whether each check passed, plus counts. A change to a metric's logic is only ever suggested, never saved for you.

Approve

Nothing reaches Databasin One until you approve it. Approve all that passed approves every checked entry in one click. Review anything marked Needs attention or Needs a person yourself. Terms and the guide are approved on their own.

How Databasin One uses them

• It reads the guide with every question, and sees table and column notes when it looks at those tables.
• It looks up definitions by name or "also known as", uses your query, and follows your Watch out for.
• It names the definition it used in its answer.
• For a term that is still open, it tells you which meaning it used.
• For a blocked metric, it explains why the question can't be answered yet.