# Open Parquet Files

VisiGrid opens Apache Parquet (`.parquet`) files in the desktop app, the `vgrid` CLI, and the web app. Parquet support starts in **VisiGrid 0.34.0**; this page describes **0.34.2** and later.

Parquet is **read-only**: VisiGrid reads Parquet files and exports them to other formats, but it does not write Parquet.

Looking for an overview rather than reference? See [Parquet Viewer](https://visigrid.app/parquet-viewer/).

## Open a Parquet file

Open the file with `Ctrl+O`, the same as any other spreadsheet. The import runs in the background, so large files do not freeze the window.

- The column names become the header row (row 1).
- Each record becomes one row below it.
- Top-level columns become sheet columns, in file order.

## How column types come through

Parquet stores a type for every column, so VisiGrid uses it instead of guessing from text the way CSV import has to.

| Parquet type | In VisiGrid |
|--------------|-------------|
| Integers | Numbers. Integers larger than ±2^53 (9,007,199,254,740,992) stay as text so they are not rounded. |
| Floats and doubles | Numbers. `NaN` and infinity become text. |
| Booleans | `TRUE` or `FALSE`. |
| Strings | Text, exactly as stored. `007` keeps its leading zeros, and `=1+1` stays text rather than becoming a formula. |
| Decimals | Numbers when the value has 15 significant digits or fewer; otherwise text, so the exact value is kept. |
| Dates | Dates. Dates before 1 March 1900 stay as text. |
| Times | Times. |
| Timestamps (milli, micro, nano) | Date-times, as stored in the file, with no time-zone conversion. Timestamps before 1 March 1900 stay as text. |
| UUIDs | Text. |
| Binary | Text when the bytes are valid UTF-8; otherwise hexadecimal (`0x…`). |
| Structs, lists, and maps | JSON text, for example `["vip","eu"]`. |
| Nulls | Empty cells. |

## Size limits

A sheet holds **1,048,576 rows** (including the header row) and **16,384 columns**, the same as Excel. Before 0.35.0 it held 65,536 rows and 256 columns, so files that were refused then may open now.

- **Desktop app:** a larger file loads what fits, and a note tells you how many rows and columns were left out.
- **CLI:** `vgrid convert`, `vgrid sheet import`, and `vgrid sheet inspect --calc` refuse a file that does not fit:

```
error: big.parquet has 2000000 rows and 1 columns; a sheet holds 1048576 rows (including the header row) and 16384 columns
hint:  split or filter the file into smaller Parquet files first
```

Other `vgrid sheet inspect` views show the rows that fit and print the truncation note on stderr, so JSON on stdout stays parseable.

A file that fits still has to fit in memory: a million rows of five columns needs roughly a gigabyte while it is open. For files past the row limit, or wide files on a small machine, filter or split them with a query engine first, then open the result in VisiGrid.

## Export

Once a Parquet file is open, export it from the desktop app to CSV, TSV, JSON, or Excel (`.xlsx`), or save it as a VisiGrid workbook.

CSV and TSV write dates, times, and timestamps as ISO 8601 (`2026-09-01 14:02:00`, with milliseconds when non-zero). Before 0.34.2 they were written as spreadsheet serial numbers.

## From the command line

`vgrid` uses the same Parquet reader as the desktop app. It needs a file path; Parquet cannot be read from stdin.

```bash
# Parquet to CSV
vgrid convert events.parquet -t csv -o events.csv

# Parquet to Excel
vgrid convert events.parquet -t xlsx -o events.xlsx

# Filter rows and choose columns on the way out
vgrid convert events.parquet -t csv --headers \
  --where 'status=paid' --select order_id,amount

# Answer a question without opening the file
vgrid sheet inspect events.parquet --headers --calc "SUM(amount)"

# Import into a VisiGrid workbook
vgrid sheet import events.parquet events.sheet --headers
```

See [`vgrid convert`](https://docs.visigrid.app/cli/convert/) and [`vgrid sheet`](https://docs.visigrid.app/cli/sheet/) for every option.

:::note
`vgrid peek` does not open Parquet files yet. Use `vgrid convert` or `vgrid sheet inspect`.
:::

## In the web app

The [web app](https://docs.visigrid.app/web/) at app.visigrid.app imports `.parquet` files up to 30 MB, with the same row and column limits.