File Formats

Blue Butterfly produces and accepts several file formats. Pick the right one for the job.

CSV (.csv)

Comma-separated text, one row per line, headers in row 1.

Tradeoffs:

• Universal — every analysis tool reads CSV
• No types — everything is text. Numbers, dates, booleans all need to be re-parsed by the consumer.
• No multi-sheet — one file per “sheet”; use ZIP to bundle several.

Excel (.xlsx)

Modern Excel format. Multiple sheets in a single file. Preserves typed values (dates as dates, numbers as numbers).

Tradeoffs:

• Multi-sheet — collar plus all data tables in one file
• Typed values — numbers stay numbers when round-tripped
• More work to parse programmatically than CSV — most analytics pipelines prefer CSV
• Older .xls is not supported — convert to .xlsx first

ZIP (.zip) — file mode, not format

ZIP is a packaging mode, not a data format. The contents are CSV files (one per data table).

Tradeoffs:

• One download for many CSVs — convenient when you have several data tables
• Recipient extracts to get the individual files — adds a step
• Each CSV is independent — easier to import into tools that expect one file per table

ZIP is selected via the File Mode option in Export Data, in combination with the Format (CSV).

Project Backup JSON (.json)

A custom Blue Butterfly format containing the complete state of a project — schema, drillholes, tables, columns, records, validation rules, formulas, dropdown options, and dropdown colour maps.

Tradeoffs:

• Full restoration — a Project Backup is the only file that lets you fully restore a project inside Blue Butterfly
• Specific to Blue Butterfly — not directly readable by external tools (it’s structured JSON, but the schema is bespoke)
• Includes everything — including any sensitive notes; treat backup files as you’d treat the underlying data

Template JSON (.json)

A schema-only JSON file: drillhole template fields, data tables, columns, validation rules, formulas, dropdown options, colour maps. No records.

Tradeoffs:

• Schema only — perfect for “give me the same setup but a fresh project”
• Same file extension as Project Backup — pay attention which one you’re picking up; they’re produced by different buttons (Export Template vs Download Backup)
• Importing into a project with existing data is supported but cautious work — see the warning in Drillhole Template

SQL Export (.sql)

A Postgres-flavoured SQL dump containing schema definitions and insert statements for the project’s data.

Tradeoffs:

• Portable — load with psql or any Postgres client
• Text — grep, awk, or read directly with a text editor
• Not restorable in Blue Butterfly — SQL files don’t round-trip back into the app
• Requires Postgres — not directly importable into MS SQL, MySQL, etc., without translation

Quick reference