> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/build/analyze-your-database-with-ai/ai-analysis-overview.md).

# AI analysis overview

{% hint style="info" %}
**Target Audience**: Non technical users
{% endhint %}

### 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.

```mermaid
flowchart LR
  start[Launch Analyze] --> run[Analysis run]
  run --> propose[Proposals stored]
  propose --> review[Review by section]
  review --> confirm[Confirm section]
  confirm --> apply[Apply metadata]
```

1. You select schemas and tables.
2. Toucan.ai starts an **analysis run** and walks a fixed pipeline.
3. The agent writes **column proposals** (and may suggest relationships).
4. You open **AI analyses**, review each section, accept or reject rows, and confirm.
5. 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. |

{% hint style="info" %}
**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.
{% endhint %}

***

### 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.

{% hint style="info" %}
**Note**: Nothing is applied until you confirm a review section. After confirmation, metadata remains editable in the table Structure view for further refinement.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

***

### 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](/getting-started/credits-and-usage.md)).

***

### 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).

***

### Related how-tos

* [Analyze your database with AI](/build/analyze-your-database-with-ai/how-to/analyze-your-database-with-ai.md)
* [Review AI analysis proposals](/build/analyze-your-database-with-ai/how-to/review-ai-analysis-proposals.md)