# Query a Parquet futures archive with DuckDB

Inspect schemas, query selected columns and combine annual futures files without loading a separate database server.

DuckDB can query Parquet files directly. Start with one known annual file, verify its schema and timestamps, and only then expand to a multi-year glob.

## Install and inspect one file

Install DuckDB in your research environment and point it at a downloaded file, not a directory whose contents you have not inventoried. Historical Futures Data bars contain ts, open, high, low, close, volume and trade_count. The example below uses its published MNQ annual filename; change the local path to your download location.

```
pip install duckdb

duckdb -c "DESCRIBE SELECT * FROM 'data/MNQ/bars/1m/cme.mnq.bars.1m.2025.parquet'"
```

## Select only the columns and dates you need

Column selection reduces the data a compatible Parquet reader must decode. A timestamp predicate can also help a well-organized reader skip work, although no format guarantees faster execution for every query. Measure the query on your own files and machine.

```
SELECT ts, open, high, low, close, volume
FROM 'data/MNQ/bars/1m/cme.mnq.bars.1m.2025.parquet'
WHERE ts >= TIMESTAMPTZ '2025-01-02 00:00+00'
  AND ts <  TIMESTAMPTZ '2025-01-03 00:00+00'
ORDER BY ts;
```

## Combine annual files deliberately

A glob can query several annual files with the same schema. Confirm that every matching file belongs to the same root, timeframe and schema version. An overly broad glob may accidentally include another frequency or a temporary conversion file.

```
SELECT date_trunc('day', ts) AS utc_day,
       sum(volume) AS contracts,
       count(*) AS bars
FROM read_parquet('data/MNQ/bars/1m/cme.mnq.bars.1m.*.parquet')
GROUP BY 1
ORDER BY 1;
```

## SQL does not resolve market-data semantics

HFD intraday buckets are epoch-aligned UTC, while daily bars represent Chicago trading sessions. Grouping intraday timestamps by UTC day is not the same operation as reading the daily product. Choose the session definition required by the experiment instead of allowing a convenient SQL function to define it silently.

Bars are derived from a back-adjusted continuous series. For execution analysis, join the roll ledger and actual contract records rather than pretending the continuous symbol is directly tradable. Keep these assumptions in the query documentation.

## Sources

- [DuckDB Parquet documentation](https://duckdb.org/docs/stable/data/parquet/overview)
- [HFD schema and timestamp rules](https://historicalfuturesdata.com/docs)
- [MNQ files and samples](https://historicalfuturesdata.com/browse/MNQ)