Matlab Use DuckdbSAFE

The MATLAB Agentic Toolkit brings proven MATLAB capabilities to AI agents, making engineering and scientific workflows agent-ready.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: matlab-use-duckdb
description: "Use DuckDB from MATLAB via Database Toolbox (R2026a+) as a non-math operations engine on large tabular files (CSV/Parquet/JSON) and as a zero-config embedded database. Use when connecting to DuckDB, querying CSV, Parquet, and JSON files directly with SQL, reducing or profiling large data before MATLAB analysis, creating portable development databases, or installing DuckDB extensions. Triggers on: DuckDB, duckdb(), large CSV/Parquet/JSON, file too large for readtable, filter/aggregate at source, deduplicate, reduce before analysis, profile large file, persistent file import, analytical engine, SQL on CSV, SQL on Parquet, SQL on JSON, query CSV with SQL, query Parquet with SQL, run SQL on files, SQL queries on files, query files directly, SQL without database, in-process SQL."
license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
metadata:
  author: MathWorks
  version: "1.2"
---

# MATLAB Database Toolbox Interface to DuckDB

Use when working with DuckDB databases from MATLAB using Database Toolbox. DuckDB is an embedded analytical database engine that ships with Database Toolbox starting in R2026a. It enables SQL-based analytics on files, out-of-memory data preprocessing, and portable development databases — all without external database server configuration.

## When to Use This Skill

- Connecting to a DuckDB database (in-memory or file-based)
- Creating a new DuckDB database file for development workflows
- Querying CSV, Parquet, or JSON files directly with SQL
- Reducing or profiling large data before analysis
- Using DuckDB as a non-math operations engine (filter, aggregate, deduplicate, string cleanup, type cast, sort, sample)
- Installing and using DuckDB extensions
- Persisting file data into a `.duckdb` file for repeated queries
- User mentions keywords: DuckDB, duckdb(), analytical engine, embedded database, large CSV, large Parquet/JSON, file too large for readtable, filter/aggregate at source, deduplicate, reduce before analysis, profile large file, persistent file import, SQL on CSV, SQL on Parquet, SQL on JSON, query CSV with SQL, query Parquet with SQL, run SQL on files, SQL queries on files, query files directly, SQL without database, in-process SQL

## When NOT to Use

- **Single file that fits in memory** — use native MATLAB I/O (`readtable`/`readmatrix`)
- **Multi-file workflows** — use `datastore`/`tall` first; DuckDB glob is the fallback, not the default
- **Data exceeds memory and no SQL reduction will make it fit** — use `datastore`/`tall` for streaming
- **Math-heavy or numerically sensitive operations** (normalize, windowed stats, outlier detection) — hand off to MATLAB after reduction
- Connecting to MySQL, PostgreSQL, SQLite, or other external databases — use their native interfaces or JDBC/ODBC
- Object-relational mapping — use ORM (`ormread`/`ormwrite` with `Mappable` classes)
- MongoDB, Cassandra, or Neo4j — use their dedicated Database Toolbox interfaces

## On-Load Protocol

When this skill is loaded into a session where code already exists:

1. **Audit the data pipeline** — Identify how data enters the workflow:
   - Is data read via MATLAB I/O (`readtable`, `readmatrix`, `readcell`, `readtimetable`, `parquetread`, `xlsread`, `csvread`)?
   - Is data then written to DuckDB with `sqlwrite` before querying?
   - If yes: this is the **load-then-query anti-pattern**. DuckDB can likely read the source file directly via `read_csv`, `read_parquet`, or `read_xlsx` (excel extension).

2. **Evaluate each data source** against the decision framework:
   - Can DuckDB read this file type directly? (CSV, Parquet, JSON, Excel via extension)
   - Can filtering/aggregation be pushed into the SQL read?
   - Is the MATLAB I/O step a performance bottleneck?

3. **Recommend architectural changes** — Do not limit review to API correctness. Propose replacing `readtable`/`xlsread` + `sqlwrite` + query chains with `fetch(conn, "SELECT ... FROM read_csv/read_parquet/read_xlsx(...)")`.

The highest-value patterns in this skill are architectural: file-analytics pushdown eliminates entire pipeline stages and can yield 10x+ speedups.

## Pre-Flight Check

Before committing to the DuckDB path, estimate the file-size-to-available-RAM ratio (accounting for in-memory expansion of the file format) and route accordingly:

| Condition | Route | Rationale |
|-----------|-------|-----------|
| Single file, ratio < 0.5 | Native MATLAB I/O | Fits in memory; DuckDB adds unnecessary complexity |
| Multi-file OR per-file processing | `datastore`/`tall` (fallback: DuckDB glob) | Streaming is the primary multi-file pattern |
| Single file, ratio ≥ 0.5, SQL-expressible reduction | DuckDB: profile → operate → close | DuckDB is warranted |
| Single file, ratio ≥ 0.5, no SQL reduction applies | `datastore`/`tall` | No reduction = no DuckDB advantage |


## Operations Menu

### DO in DuckDB SQL

| Operation | Example SQL |
|-----------|-------------|
| Filter rows | `WHERE status = 'active'` |
| Aggregate | `GROUP BY region`, `SUM(revenue)`, `COUNT(*)`, `AVG(price)` |
| Deduplicate | `SELECT DISTINCT ...` or `ROW_NUMBER() OVER (PARTITION BY ...)` |
| String cleanup | `TRIM()`, `LOWER()`, `REPLACE()`, `REGEXP_REPLACE()` |
| Type casting | `TRY_CAST(col AS DATE)`, `CAST(col AS DOUBLE)` |
| Sort | `ORDER BY timestamp` |
| Sample | `USING SAMPLE 10000` or `TABLESAMPLE RESERVOIR(10%)` |
| Profile | `COUNT(*)`, `MIN/MAX`, `APPROX_COUNT_DISTINCT` |
| Limit | `LIMIT 50000` |

### DO NOT in DuckDB SQL

| Operation | Why Not |
|-----------|---------|
| Normalize / z-score | Requires population context |
| Windowed statistics (moving avg, cumsum) | Fragile semantics, NULL handling differs |
| Outlier detection | Statistical judgment call |
| Interpolation / resampling | Domain-specific logic |
| Signal processing | Not SQL's domain |
| Machine learning features | Model-dependent |

SQL operations do not always match MATLAB semantics (NULL handling,

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.