'%3e%3cpath%20fill-rule='evenodd'%20clip-rule='evenodd'%20d='M0%2062.3176C0%2027.9001%2027.8995%200.00181961%2062.3134%200.00181961L62.3999%2062.2311C62.3999%2096.6462%2034.5004%20124.544%200.0852901%20124.544'%20fill='%233A3D3C'/%3e%3c/g%3e%3cpath%20d='M62.3994%2062.2461V0C96.8133%200%20124.713%2027.8982%20124.713%2062.3158'%20fill='url(%23paint0_linear_6331_3458)'/%3e%3cpath%20fill-rule='evenodd'%20clip-rule='evenodd'%20d='M45.617%2026.2827C47.7276%2026.2827%2049.4382%2027.9933%2049.4382%2030.1052C49.4382%2032.2146%2047.7276%2033.9252%2045.617%2033.9252C43.5064%2033.9252%2041.7958%2032.2146%2041.7958%2030.1052C41.7958%2027.9933%2043.5064%2026.2827%2045.617%2026.2827Z'%20fill='%23F9F6EF'/%3e%3cpath%20fill-rule='evenodd'%20clip-rule='evenodd'%20d='M45.6168%2045.2338C37.2596%2045.2338%2030.4857%2038.461%2030.4857%2030.1038C30.4857%2021.7454%2037.2596%2014.9702%2045.6168%2014.9702C53.9753%2014.9702%2060.7492%2021.7454%2060.7492%2030.1038C60.7492%2038.461%2053.9753%2045.2338%2045.6168%2045.2338ZM45.6168%2012.6686C35.9875%2012.6686%2028.1816%2020.4744%2028.1816%2030.1038C28.1816%2039.7308%2035.9875%2047.5378%2045.6168%2047.5378C55.245%2047.5378%2063.0508%2039.7308%2063.0508%2030.1038C63.0508%2020.4744%2055.245%2012.6686%2045.6168%2012.6686Z'%20fill='%23FECE01'/%3e%3cdefs%3e%3clinearGradient%20id='paint0_linear_6331_3458'%20x1='62.2719'%20y1='4.01754'%20x2='108.703'%20y2='70.5262'%20gradientUnits='userSpaceOnUse'%3e%3cstop%20stop-color='%239ED5CB'/%3e%3cstop%20offset='1'%20stop-color='%23FCE18E'/%3e%3c/linearGradient%3e%3c/defs%3e%3c/svg%3e)
AI analysis overview
Target Audience: Non technical users
TL;DR
Toucan.ai uses AI analysis to propose semantic metadata on connected databases. You review and confirm those proposals before they are applied. Confirmed metadata is required for accurate chart generation, natural language queries, and security configuration.
When to use this
Use this page to understand how metadata affects the platform's AI reasoning, how analysis runs work, and when to initiate the process.
Purpose of AI Analysis
The Analyze feature adds a semantic layer to raw data. This process is a required step for the following workflows:
- Natural Language Queries: Enriches tables and columns so the AI can interpret user prompts.
- Dashboard Generation: Improves the selection of relevant charts based on data types.
- Security Preparation: Prepares column structures for Row-Level Security (RLS) mapping by inferring data types, which determines the available comparison operators.
- User Clarity: Replaces raw database names with human-readable display names.
How it works
Analysis does not write metadata directly to your tables. It produces proposals that you can review and confirm by review section. Until you confirm, your existing metadata stays unchanged.
- You select schemas and tables.
- Toucan.ai starts an analysis run and walks a fixed pipeline.
- The agent writes column proposals (and may suggest relationships).
- You open AI analyses, review each section, accept or reject rows, and confirm.
- Confirmed proposals are applied; rejected ones are discarded.
Pipeline stages
When an analysis is triggered, Toucan.ai runs these stages on the selected scope:
| Stage | What Toucan AI does |
|---|---|
| Reading the database structure | Loads schema/table/column structure for the selection. |
| Reconciling declared foreign keys | Aligns declared foreign keys with the connection. |
| Analyzing tables | AI proposes descriptions, display names, and type casts per table. |
| Looking for relationships | Suggests and describes relationships (joins) between tables that aren't described by foreign keys. |
Selection phase
Before the pipeline starts, a selection modal lets you target specific schemas and tables rather than the entire connection, which optimizes processing time and relevance.
What gets proposed
| Component | Proposal |
|---|---|
| Columns — type casts | Semantic field typing (e.g. Category, Text, Date, Metric) via casts. |
| Columns — naming | Display names for use in the UI and chat. |
| Columns — context | Short descriptions of what each column represents. |
| Tables | Table-level descriptions summarizing content. |
| Relationships | Suggested joins (reviewed separately from column proposals). |
Each column proposal can show confidence and justification (rationale) to help you decide during review. These are not saved with your metadata and are not available to the AI assistant.
Note: Nothing is applied until you confirm a review section. After confirmation, metadata remains editable in the table Structure view for further refinement.
Refresh schema: If your database structure changes (e.g., added tables or modified columns), use Refresh Schema. Then run a new analysis on the affected tables so proposals match the current architecture.
Analysis runs
- Each launch creates a run with its own scope, start time, and starter.
- Runs coexist: starting a new analysis never deletes or supersedes an older run's proposals. You can analyze one set of tables today and another tomorrow, then still review the first.
- Multiple pending runs: each run is reviewed on its own. If the same column has proposals in more than one run, confirming one run does not change the others — the values you confirm last are the ones that apply.
- Open AI analyses from the database More options menu (⋮) to see history and continue review.
- Tables included in an analysis are set to Available for chat and charts by default.
Usage Requirements
- Timing: Initiate analysis immediately after connecting a new database or whenever the underlying schema changes.
- Prerequisite: Confirm relevant proposals before configuring RLS or relying on AI-powered dashboards and chat.
- Persona: Designed for Product Managers and Data Analysts preparing data for end-users.
- Credits: Metadata enrichment consumes AI credits (indicative cost in Credits & Usage).
Limitations
- Sample-Based: Inference is based on schema structure and sampled values; it is not an exhaustive data audit.
- Scope: Multiple schemas and tables can be selected within a single run via the selection modal.
- Manual Review: Until you confirm proposals, the enriched metadata is not available to the AI assistant. Validate proposals before relying on chat, charts, or security configuration.
- Non-destructive history: Re-running analysis does not remove previous runs; review each run that still has pending proposals (see Multiple pending runs above).