# DuckDB Tool

The DuckDB Tool allows DinoAI to explore your DuckDB instance — listing schemas, tables, and columns — so you can query and understand your analytical data directly from the Code IDE without switching contexts.

This tool connects DinoAI to your DuckDB database, enabling it to navigate your data structure, identify available tables, and surface column-level details to inform the SQL and dbt models you're building.

{% hint style="info" %}
Requires a DuckDB connection. Before using this tool, make sure your DuckDB instance is accessible from your Paradime workspace.
{% endhint %}

### Capabilities

The DuckDB Tool exposes three underlying operations:

**`list_all_duckdb_schemas`** lists all schemas in your DuckDB database, excluding system schemas (`information_schema` and `pg_catalog`). Use this to get an overview of the available namespaces in your instance before drilling down into specific tables.

**`list_all_tables_in_duckdb_schema`** lists all tables and views within a given schema. Results include the table name and type, giving you a complete inventory of what's available in each namespace.

**`list_all_columns_in_duckdb_table`** fetches full column-level details for a specific table — including column names, data types, and ordinal positions. Use this when you need to understand a table's structure before writing SQL or defining dbt sources.

### Using the DuckDB Tool

1. Open DinoAI in the right panel of the Code IDE
2. Describe what you want to explore — a schema, a table, or a specific column
3. Grant permission when DinoAI asks to access your DuckDB instance
4. Review the results DinoAI surfaces and incorporate them into your workflow

### Example Use Cases

#### Exploring Available Schemas

**Prompt**

```
What schemas are available in my DuckDB instance?
```

**Result:** DinoAI lists all non-system schemas in your DuckDB database, giving you an at-a-glance overview of your data namespaces so you can decide where to look next.

***

#### Discovering Tables in a Schema

**Prompt**

```
What tables are available in the analytics schema?
```

**Result:** DinoAI queries the `analytics` schema and returns a list of all tables and views with their types, so you can identify the right table for your query or model.

***

#### Understanding a Table's Structure

**Prompt**

```
What columns does the orders table in the analytics schema have?
```

**Result:** DinoAI fetches the full column list for `analytics.orders`, including data types and positions, giving you the schema context to write accurate SQL or define a dbt source without leaving the IDE.

### Working with Other Tools

The DuckDB Tool works well alongside DinoAI's other capabilities to support your full development workflow:

* Combine with the **Terminal Tool** to run dbt commands or SQL queries against the tables DinoAI discovers
* Use alongside the **Data Warehouse Tools** for cross-warehouse exploration when your stack includes both DuckDB and a cloud warehouse
* Pair with **Git Lite** to commit generated models and source definitions after exploring your DuckDB structure

### Best Practices

**Start broad, then drill down** — Use `list_all_duckdb_schemas` first to orient yourself, then move to tables and columns. This keeps DinoAI's context focused and responses accurate.

**Provide exact schema and table names** — If you already know the schema, include it in your prompt. This avoids unnecessary round-trips and keeps the conversation efficient.

**Verify column types before writing SQL** — Always check data types when writing transformations, especially for date, timestamp, or JSON columns, which behave differently across DuckDB versions.

**Use results to define dbt sources** — Column-level output from DinoAI can be directly incorporated into `schema.yml` source definitions, saving manual lookup time.