Query Parquet Files with SQL in Your Browser

Query Parquet Files with SQL in Your Browser

Apache Parquet is the dominant columnar format for analytical data. Warehouse exports, Spark jobs, dbt output, and cloud storage buckets all produce it. Drop a .parquet file into the SQL Workbench and DuckDB registers it as a queryable view, with no install, upload, or conversion step required.¹

Why data engineers reach for Parquet

Parquet emerged from the Hadoop ecosystem to solve a concrete read-performance problem. Row-oriented formats like CSV store every field in a record together, which is efficient for writing one record at a time but wasteful for analytical reads that touch only a handful of columns across millions of rows. Columnar storage inverts that layout. Each column occupies its own contiguous byte range in the file, so a SELECT that reads three columns out of thirty touches roughly 10% of the bytes. Consequently, file sizes shrink, query latency drops, and bandwidth costs fall.²

That combination explains why Parquet became the standard output of tools like Apache Spark, dbt, BigQuery export, Snowflake unload, and Redshift UNLOAD. Your .parquet file most likely came from one of those systems, from a Python pandas or Polars job, or from another DuckDB instance. GeoParquet (a Parquet-based format for geospatial vector data) follows the same physical layout and loads through the same reader.³

How the workbench loads your Parquet file

DuckDB reads Parquet natively, meaning no JavaScript translation layer sits between your file and the query engine. Drop orders.parquet and the workbench registers a view named orders. You can immediately run SELECT * FROM orders. DuckDB reads the Parquet footer first (that metadata block records column names, types, and row group statistics), so DESCRIBE orders returns the full schema in milliseconds even on a 2 GB file.

Inspecting schema and nested fields

Type inference is unnecessary because Parquet encodes schema information directly: INT64, FLOAT, UTF8, TIMESTAMP, and BOOLEAN columns arrive with their types already declared. Nested structures stored as repeated groups become accessible via dot notation without any preprocessing.⁴ Your file name sets the view name: pipeline_output_2026_04.parquet becomes the view pipeline_output_2026_04. For files with deeply nested schemas, DESCRIBE reveals the full struct hierarchy so you can plan your dot-notation paths before writing the first query, which saves time when the nesting goes three or four levels deep.

For a struct column, you reach a nested field with dot notation directly in the SELECT list or a WHERE clause, and you can chain further levels without first flattening the column. Because the types are declared in the file, DuckDB returns these nested reads as properly typed values rather than opaque blobs, so joins and aggregations on nested fields behave exactly like their top-level equivalents.

Column pruning, filter pushdown, and practical query patterns

Because Parquet stores columns separately, DuckDB reads only the columns your query references. SELECT order_id, total FROM orders WHERE status = 'shipped' reads three columns from the file regardless of how many columns orders contains. Across a 200-column warehouse export, that selectivity makes exploration fast. Filter pushdown extends the savings further: DuckDB inspects row group statistics embedded in the Parquet footer and skips entire row groups when your WHERE clause eliminates them based on recorded minimum and maximum values.⁵ Start every unfamiliar Parquet file with DESCRIBE to inspect the schema, then SELECT * FROM table LIMIT 10 to see sample rows. Both complete instantly. For aggregations, GROUP BY on low-cardinality columns like region or status first, then drill into individual values with additional WHERE clauses. The workbench runs each query in a Web Worker, so a slow aggregation across millions of rows does not freeze the editor.

Exporting query results back to Parquet

After exploring or filtering a Parquet file you can export results back to Parquet. The Export button runs a COPY ... TO statement through DuckDB, producing a correctly typed output file rather than a serialized snapshot of on-screen rows. Column types carry through the export: an INT64 source column becomes INT64 in the output, not a string. This typed fidelity is what distinguishes Parquet export from CSV export, which serializes every value as plain text and forces downstream readers to re-infer types.⁴

Choosing Parquet export over CSV

You can filter, aggregate, or join before exporting, and the exported file reflects exactly what your SQL produced. Parquet export depends on DuckDB directly and is available only for DuckDB-loaded file types.⁶ Opening a SQLite database disables Parquet export because those sessions run through sql.js, which does not have access to DuckDB's native Parquet writer. The Export button still offers CSV, JSON, and Excel for SQLite results. When you know the output will feed another analytical tool, Parquet is the better export choice because it preserves column types and compresses the data, whereas CSV serializes every value as plain text and forces downstream readers to guess types all over again. That downstream guessing step is where the most time gets lost in a CSV-based workflow, because every reader has to scan values and decide whether a string of digits is a number or text.

Understanding sort order and row group skipping

When a Parquet file comes from a pipeline that sorts data by a date or ID column before writing, DuckDB can skip entire row groups on future queries that filter on that column. A file written with ORDER BY event_date before export produces row groups where the minimum and maximum date within each group are sequential and non-overlapping. A query WHERE event_date = '2026-05-01' lets DuckDB read the Parquet footer, identify which row groups contain that date based on min/max statistics, and read only those groups.⁵

Writing sorted Parquet from the workbench

To produce a sorted Parquet file from the workbench, add ORDER BY to your export query before clicking Export: SELECT * FROM orders ORDER BY order_date. The exported Parquet file stores rows in date order, which enables faster filter pushdown on future WHERE order_date queries. For very large files where you repeatedly query a specific date range, this pre-sort step is the single highest-impact optimization available without schema changes.

Common Parquet type issues and how to resolve them

For the most common type mismatch in Parquet files from Python pipelines, the culprit is a numeric column that pandas wrote as FLOAT64 when the original values were integers. DESCRIBE reveals the column type; if a column you expect to hold order IDs or counts shows as DOUBLE, cast it in your query: order_id::BIGINT. The cast works for any column where the double values have no fractional part.

Timestamp columns from pandas pipelines often arrive as TIMESTAMP WITH TIME ZONE when the source DataFrame had timezone-aware datetime values. DuckDB handles these correctly, but filtering requires including the timezone in comparisons: WHERE event_ts AT TIME ZONE 'UTC' >= TIMESTAMP '2026-01-01 00:00:00'. For pipelines that mix timezone-aware and timezone-naive values across partitions, converting all timestamps to UTC before exporting from the upstream tool is the cleanest long-term fix, and you can fix a mismatched Parquet column type with a single cast rather than re-exporting the file.

When to use this

Use this when you receive a .parquet export from a data warehouse, pipeline, or Python job and want to inspect its schema, run ad hoc SQL, or filter it before passing results to another tool. Drop your file into the workbench and run DESCRIBE first; DuckDB reads the schema straight from the footer, so you see every column and type before writing a single query.

Examples

DESCRIBE orders;

SELECT customer_id, total
FROM orders
WHERE status = 'shipped'
  AND total > 500
ORDER BY total DESC;

SELECT region, COUNT(*) AS n
FROM sales
GROUP BY region
ORDER BY n DESC;

SELECT payload.user_id, payload.event_type
FROM events
LIMIT 20;