# Data Readiness requirements (/core/build/data-connections/data-readiness-requirements)



### TL;DR [#tldr]

Toucan AI relies on semantic metadata to power accurate chart generation and Natural Language Queries. Before connecting, your data must be structured to eliminate ambiguity, as the platform performs read-only operations and cannot "clean" your source data.

### When to read this [#when-to-read-this]

Review these requirements before or during the Build phase to confirm your database is prepared for AI analysis.

### Data Preparation Standards [#data-preparation-standards]

#### **1. Structural Logic: The "Single Grain" Rule** [#1-structural-logic-the-single-grain-rule]

The AI engine requires a clearly defined granularity for every table.

* Requirement: Each table should represent a single level of detail (e.g., one row per transaction).
* Constraint: Do not include "Total" or "Sub-total" rows within the same table as individual records.
* Why: AI agents use simple aggregations; mixed grains result in double-counting and massive errors in dashboards.

#### **2. Naming Conventions: Natural Language Mapping** [#2-naming-conventions-natural-language-mapping]

Toucan AI uses column names and display names to interpret user prompts and map chart axes.

* Requirement: Use declarative, nouns for table names and human-readable column names, reveiw the display names for columns
* Constraint: Avoid cryptic abbreviations or "computer-speak."
  * ❌ `rev_ext_tax` ->✅ `revenue_excluding_tax`
  * ❌ `ts_crtd` ->✅ `created_at_timestamp`

#### **3. Type Integrity** [#3-type-integrity]

Field type inference is based on sampled values.

* Metrics: Must be strictly numeric (float/int). Remove currency symbols or "N/A" strings from cells.
* Dates: Use [ISO 8601 / RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html) format (`YYYY-MM-DD`) to avoid regional formatting errors.
* Categories: Use standardized strings or enums to prevent the AI from seeing "USA" and "United States" as two different entities.

### Summary [#summary]

| **Feature**      | **Requirement**              | **Purpose**                                |
| ---------------- | ---------------------------- | ------------------------------------------ |
| **Table Names**  | Use nouns (e.g., `orders`)   | Identifies entities for AI                 |
| **Column Names** | Human-readable, no codes     | <p>Enables Natural Language Query</p><p /> |
| **Data Types**   | Cast and Clean (Strict Type) | Correct field-type inference               |
| **Logic**        | Atomic grain (no sub-totals) | Prevents calculation errors                |

#### Constraints [#constraints]

* **Read-Only**: Toucan AI never writes to your database; all cleaning must be done at the source.
* **Sampling**: Inference is based on schema structure and sampled values, not a full data audit.
* **Manual review**: AI proposals must be reviewed and confirmed before production; confirmed metadata remains editable.