List the data files you can query (CSV, TSV, Parquet, JSON, NDJSON, optionally .gz).

Shows each file's path relative to its allowed folder, its type and size. Use this first: those paths can be used directly in SQL, e.g. SELECT * FROM 'sales.csv'. Optional pattern is a case-insensitive glob on the path, e.g. '2024' or 'logs/*.json'. At most 500 files are shown.

Show a file's schema (column names and types), its row count and a few sample rows.

path is relative to an allowed folder (as list_files shows it) or absolute inside one. Column types are DuckDB's auto-detected types, which is what SQL will see. The row count of a CSV/JSON file needs a full scan; Parquet answers from metadata. Use this before writing a query, to get exact column names.

Profile each column of a file in one pass: type, null %, approximate distinct count, min, max, average, median and the three most common values.

Use it to spot data-quality problems (many nulls, constant columns, odd ranges) before analysing. columns limits it to named columns; otherwise the first 50 columns are profiled. On a very large file this scans everything and can hit the time limit - then profile fewer columns.

Show a few rows of a file: the first rows (mode='head') or a random sample (mode='random', scans the whole file). Cheaper than describe_file when you only want to see the data. rows is 1 to 100.

Run one read-only SQL statement (DuckDB dialect) over the data files.

Reference files by name: SELECT * FROM 'sales.csv', or read_csv('sales.csv'), read_parquet('dir/*.parquet'), read_json_auto('events.ndjson'). Paths are relative to the allowed folders (see list_files) or absolute inside them. Allowed: SELECT, WITH, VALUES, FROM-first queries, DESCRIBE, SUMMARIZE, SHOW and EXPLAIN. Anything that writes or reaches outside the allowed folders (INSERT, CREATE, COPY, ATTACH, INSTALL, SET, PRAGMA, files elsewhere on disk, URLs) is rejected.

Output is a markdown table by default; format='csv' or 'json' is more compact for big results. Results stop at the server's row cap (default 1000) with a TRUNCATED notice; pass a smaller max_rows to see less. Queries have a time limit. Prefer aggregation (GROUP BY, COUNT, SUM) over fetching raw rows. Use describe_file first for column names.

Show DuckDB's execution plan for a SELECT query without returning its rows.

Useful to check whether a filter is pushed down into a Parquet scan, or why a query is slow. With analyze=true the query is actually executed and per-operator timings and row counts are included (still read-only, still time-limited). Same SQL rules and file naming as query.