How to rename snake_case / camelcase csv columns to readable names
- Step 1Export the API response or query result as CSV — Download the CSV from your API client, BI tool, or warehouse query. The first row should be the column-name header. The tool reads
.csv,.tsv, and.txt; PapaParse auto-detects whether it's comma- or tab-delimited. - Step 2Decide on your display-name convention — Pick a consistent style: Title Case with spaces (
User ID,Created Date), units in parentheses (Total (£),Latency (ms)), and expanded acronyms where the audience needs them. Consistency is what makes the report scannable. - Step 3Drop the CSV onto the tool above — PapaParse lists every API key from the header row with a rename box beside it. Long keys are visually truncated in the label, but the box accepts and the rename writes the full display name you type.
- Step 4Type the friendly name next to each key —
user_id→User ID,created_at→Created,total_amount_gbp→Total (£),isActive→Active. Leave a box blank for any key you'd rather keep as-is or drop later. - Step 5Run and download the relabelled CSV — The button reads
Rename N headers. The result panel shows Headers renamed, Data rows, and a 10-row preview so you can sanity-check the labels against the data. Click Download for<name>.renamed.csv. - Step 6Share the report or load it into your BI tool — Send the relabelled CSV to stakeholders, or import it into a dashboard. Keep the original machine-named export for any pipeline or script that matches on
user_id/created_at— see the edge cases on not breaking downstream readers.
Machine key to friendly label — patterns
Common API/warehouse column patterns and a readable display name. Adapt the exact wording to your audience.
| Machine key | Friendly label | Pattern |
|---|---|---|
user_id | User ID | snake_case → Title Case, expand ID |
created_at, updated_at | Created, Updated | Drop the _at, keep it short |
total_amount_gbp | Total (£) | Move the currency code into a symbol in parentheses |
lifetime_value_cents | Lifetime Value (£) | Note: value is in cents — relabel only; division is a data step, not a rename |
isActive, hasPaid | Active, Paid | camelCase boolean → adjective |
avg_response_ms | Avg Response (ms) | Unit into parentheses |
country_iso2 | Country | Hide the encoding detail from the reader |
What the rename does vs. what reporting often also needs
Header rename is a labelling step. Number formatting, unit conversion, and column trimming are separate operations.
| Need | Rename handles it? | Use instead |
|---|---|---|
| Make the header readable | Yes | This tool |
Divide _cents values by 100 | No | A spreadsheet formula — rename only relabels |
Drop internal columns (_internal_flag) | Leave blank, or | csv-column-remover |
| Title-case the data cells, not just headers | No | csv-case-converter |
| Reorder columns for the report | No | csv-column-reorder |
Cookbook
Real API/warehouse header rows before and after relabelling. Data rows shown to confirm values are untouched.
snake_case API export to a client-ready report
ExampleA raw endpoint dump with machine keys. Four renames turn it into something a non-technical client can read at a glance — the data stays identical.
Input header: user_id,created_at,total_amount_gbp,is_active 10293,2026-06-01T09:14:00Z,149.99,true Renames typed: user_id -> User ID created_at -> Created total_amount_gbp -> Total (£) is_active -> Active Output header: User ID,Created,Total (£),Active 10293,2026-06-01T09:14:00Z,149.99,true
camelCase warehouse extract for a BI dashboard
ExampleA query result in camelCase. Renaming to readable labels means the dashboard's axis titles and column headers are presentable without a transform step in the BI tool.
Input header: customerName,signupDate,lifetimeValueCents,churnRisk Acme Ltd,2025-11-03,248000,0.12 Renames typed: customerName -> Customer signupDate -> Signed Up lifetimeValueCents -> Lifetime Value (£) churnRisk -> Churn Risk Output header: Customer,Signed Up,Lifetime Value (£),Churn Risk Acme Ltd,2025-11-03,248000,0.12 → Note: 248000 is still in cents; relabel only — divide upstream.
Relabel only the cryptic columns
ExampleSome headers are already fine. Leave those boxes blank and only relabel the keys stakeholders would query you about.
Input header: Name,email,plan_tier_code,mrr_cents Renames typed (Name and email left blank): plan_tier_code -> Plan mrr_cents -> MRR (£) Output header: Name,email,Plan,MRR (£) → Headers renamed: 2
Two columns share the key 'value'
ExampleGeneric exports sometimes repeat a key like value. Because rename works by position, each can become a distinct label.
Input header: metric,value,value revenue,12000,0.034 Renames typed (by position): column 2 value -> Amount column 3 value -> Growth Rate Output header: metric,Amount,Growth Rate revenue,12000,0.034
Keep the machine names for the pipeline, relabel a copy
ExampleBest practice for reporting: relabel a copy for humans, keep the original for any system that reads user_id / created_at by name.
Workflow: 1. Keep raw_export.csv (user_id, created_at, ...) for the data pipeline 2. Drop a copy here -> rename to friendly labels 3. Download report.renamed.csv -> send to stakeholders / BI The pipeline still matches raw_export.csv by machine key; humans read report.renamed.csv. Nothing downstream breaks.
Errors and edge cases
Real errors and silent failures sourced from each platform's own documentation. Match the wording to the row, fix what the row says to fix.
Renamed file fed back into a script that matches by key
Pipeline breaksAny downstream job that reads columns by name (a script keyed on user_id, a scheduled load, a dbt model) will fail to find User ID. Use the relabelled CSV for human-facing reporting only, and keep the original machine-named export for the pipeline. Renaming for readability and renaming for system compatibility are different goals — don't conflate them.
Expecting `_cents` to become pounds after renaming
Value unchangedRelabelling lifetime_value_cents to Lifetime Value (£) changes the header, not the data — the cell still holds 248000. The rename never divides or reformats values. Do the unit conversion upstream (a spreadsheet column or a query expression), then relabel. The label promises pounds; make sure the numbers actually are.
Two friendly labels end up identical
Duplicate headersIf you relabel two different keys to the same display name (both to Date, say), the output has two identical headers. Some BI tools and re-imports reject or silently collapse duplicate headers. Give each a distinct label (Created, Updated) — the tool renames by position and won't stop you from creating duplicates.
API export is tab- or pipe-delimited
SupportedPapaParse auto-detects the delimiter, so a .tsv warehouse export or a tab-delimited API dump lists its columns correctly. The download is always comma-delimited CSV. If your BI tool prefers TSV, convert the output afterwards — the rename itself is delimiter-agnostic on input.
JSON-array values inside a cell from a list field
PreservedSome APIs serialise a list property as ["a", "b"] inside one cell. The rename leaves those cells exactly as exported — it only relabels the header. If you need the array split into columns, that's a separate transform (a column-value splitter), not a header rename.
Header row isn't the first row (metadata line above it)
Mis-detected headerIf the export prepends a row like # generated 2026-06-10, the tool reads that as the header. Remove the metadata line first (or clean it with csv-cleaner) so the rename list shows the real API keys.
No BOM on output; Excel mangles a £ symbol in a label
ExpectedThe download is UTF-8 without a byte-order mark, so a Total (£) header is correct bytes. If Excel-on-Windows shows Total (£), that's Excel's encoding guess — open via Data → From Text/CSV and pick UTF-8. The file is correct for any UTF-8-aware tool.
Large warehouse extract exceeds the free limit
Pro overlayA big query result can pass 500 rows or 2 MB, which shows the Pro overlay (the row check runs on the result). Pro raises the limits to 100 MB / 100,000 rows. For one-off reports you can also slice the rows first, relabel, and stitch — but most reporting extracts fit Pro comfortably.
Frequently asked questions
Does renaming headers break downstream processes that read column names?
It can. Any script, dbt model, or scheduled load that matches columns by name (user_id, created_at) won't find User ID. Use the relabelled CSV for human-readable reporting and dashboards only, and keep the original machine-named export for anything programmatic. Treat the friendly version as a presentation copy.
Can I rename just a few columns and leave others unchanged?
Yes. Type a new name only in the boxes you want to change and leave the rest blank — a blank box keeps the column's original key. The Headers renamed count in the result reflects only the columns whose name actually changed, so you can confirm you relabelled exactly what you meant to.
Is there a limit to the number of columns I can rename?
No. Every column in the header row gets its own rename box, so you can relabel a 5-column export or a 200-column warehouse extract. The limits that apply are on rows and file size (2 MB / 500 rows free, 100 MB / 100,000 rows Pro), not on the number of columns.
Will it convert `_cents` or `_ms` values to the right unit?
No — it only renames headers. Relabelling lifetime_value_cents to Lifetime Value (£) changes the header text; the cell still holds the raw cents figure. Do unit conversion upstream (a spreadsheet formula or a query expression), then relabel so the header and the data agree.
Can I put a currency symbol or unit in the header?
Yes. The rename box accepts any text, including £, $, %, and parentheses — so Total (£), Latency (ms), or Conversion (%) all work. The output is UTF-8, so symbols are preserved. Just make sure the underlying values match the unit you've put in the label.
What if two columns have the same machine key?
The tool renames by column position, so two columns both called value are handled independently — you can give each a distinct friendly label. Avoid renaming them to the same display name, though, as duplicate headers can trip up BI tools and re-imports.
Does it accept JSON directly, or only CSV?
Only tabular text: .csv, .tsv, and .txt. If your API returns JSON, convert it to CSV first (many warehouse and API tools offer a CSV export, or use a JSON-to-CSV converter), then drop the CSV here to relabel the headers. PapaParse auto-detects comma vs tab on input.
Are the data values changed at all?
No. The tool rewrites only the first (header) row. Every value below — timestamps, IDs, numbers, JSON-array cells — is passed through byte-for-byte. The result panel shows a Data rows count so you can confirm no rows were added or lost during the relabel.
Does the output add a BOM so labels with £ open cleanly in Excel?
No — the download is UTF-8 with no byte-order mark. Symbols are correct bytes, but Excel-on-Windows may guess the wrong encoding on a double-click and show £. Open via Data → From Text/CSV and select UTF-8, or use Google Sheets / a BI tool, which read UTF-8 directly.
Is my report data uploaded anywhere?
No. PapaParse runs entirely in your browser; the report's rows — which may include customer identifiers — never reach a JAD server. Only a usage counter (no content) is recorded when you're signed in, and you can opt out in account settings. Relabelling adds no exposure of the underlying data.
Can I automate relabelling for a recurring report?
Yes. GET /api/v1/tools/csv-header-rename returns the option schema (a renames map keyed by column index). Pair the @jadapps/runner once and POST your export to 127.0.0.1:9789/v1/tools/csv-header-rename/run. It runs locally, so the data stays on your machine — handy for a scheduled query → relabel → distribute pipeline.
Should I also drop internal columns before sharing?
Often yes. Columns like _internal_flag or etl_batch_id mean nothing to stakeholders. You can leave their rename boxes blank and remove them afterwards with csv-column-remover, or reorder the report with csv-column-reorder. The rename handles labels; those tools handle the column set and order.
Privacy first
Processing runs locally in your browser with PapaParse. No file is uploaded — only metadata counters are saved for signed-in dashboard stats.