Querying Data

ColdPlane lets you query archived data directly using SQL without rehydrating to a live database.

Local Queries

If you created a backup with --local, you can query it directly on your machine. No account or network connection required.

coldplane query run --local \
  --backup-id my_backup_name \
  --sql "SELECT user_id, COUNT(*) as total FROM restore_input GROUP BY user_id ORDER BY total DESC" \
  --output table

Local queries use restore_input as the default table name. Use --table to query a specific table from a multi-table backup. All output formats (table, json, csv) are supported.

Basic Query

coldplane query run \
  --backup-id bck_abc123 \
  --table users \
  --sql "SELECT count(*) as total_users FROM users"

By default, queries return a 100-row preview. To download the full result set, use the --export flag.

Exporting Full Results

Export full query results as CSV or Parquet for download:

# Export as CSV (default)
coldplane query run \
  --backup-id bck_abc123 \
  --table users \
  --sql "SELECT id, email, created_at FROM users WHERE created_at > '2024-01-01'" \
  --export --format csv

# Export as Parquet (compact, typed columns)
coldplane query run \
  --backup-id bck_abc123 \
  --table orders \
  --sql "SELECT id, amount, status FROM orders" \
  --export --format parquet

Exported results are stored temporarily and available for download based on your plan's retention period.

Result Retention

Exported results are automatically cleaned up after your plan's retention period:

If a result expires, simply re-run the query — your archived data is always available.

Performance Tips

• Specify explicit columns when possible -- selecting only the columns you need reduces data scanned
• Use WHERE clauses -- partition pruning reduces data scanned
• Prefer aggregations -- COUNT, SUM, AVG process data server-side
• Limit results -- use LIMIT to cap large result sets