CSV Ingest

CSV Ingest

Each upload is one stored report. There is no live API — data comes from files the user uploads on the bundle page. If nothing is stored yet, say so; never invent figures.

Exploration workflow (any CSV)

1. List recent uploads — note report_id and optional row_count when comparing files.
2. Describe — column names, DuckDB types, row count, and a few sample rows. Always do this before assuming column names or types.
3. Profile column (optional) — nulls, approximate distinct count, top values, numeric min/max when parseable.
4. Query SQL — aggregates, filters, GROUP BY on table data (one row per CSV line).
5. Query rows — paginated raw strings when you need exact cell text without SQL.
6. Latest / get report — small files only; large exports return a short pointer — use describe and SQL instead.

SQL (query_sql)

• Table name is always data.
• Column names match the CSV header (case-sensitive); get them from describe.
• Types may be VARCHAR — use CAST(your_column AS DOUBLE) or BIGINT for math.
• Results cap at 500 rows; add LIMIT in SQL for top-N.

Response shape

• source — report_id, filename, captured_at.
• Describe — columns, sample_rows, total_rows, next_steps.
• Profile column — null_count, approx_distinct, top_values, optional numeric_range.
• Query SQL — columns, rows, returned, truncated, optional cache_hit.
• Query rows — headers, rows, offset, limit, has_more, optional total_rows.

Gotchas

• Read-only except delete-report — uploads happen on the bundle page.
• Each upload is separate — no merged warehouse across files unless you run SQL per report_id.
• User agent context on the connection may explain domain-specific column meanings — read it when present.