Plain-text files and table design

Convert Data to CSV by Choosing Rows, Columns and Value Rules

Design a CSV export by defining record granularity, column order and value representations, then verify an order-line example and document information loss.

By Uddhav Gopani, FounderPublished 27 September 2026Updated 29 September 2026

Convert Data to CSV by Choosing Rows, Columns and Value Rules

To convert data into CSV, first choose a rectangular table: one defined kind of record per row and one field per column. Then write those field values with a CSV-aware serializer. Data from nested objects, relational tables or formatted documents needs a mapping decision before it can fit that table without ambiguity.

Define the meaning of one row

Consider two orders: order 0017 contains two products, while order 0028 contains one. If each row represents an order, the product list does not fit naturally into a single ordinary field. If each row represents an order line, repeat the order identifier and give each line its own identifier.

That choice affects how the CSV can be analyzed. Counting rows in an order-line file counts lines, not orders. Document the row meaning so that a recipient does not mistake a syntactically correct export for a differently structured dataset.

Use an order-line table

OrderID,LineID,Product,Quantity
0017,1,Blue folder,2
0017,2,Green folder,1
0028,1,Archive box,3

This example contains three lines belonging to two orders. OrderID and LineID together identify each line. The product names remain separate from their quantities, and the leading zeros in the order identifiers remain part of the field text.

The quantity total is six items: two blue folders, one green folder and three archive boxes. That total is a useful independent reconciliation check. A row count of three and a distinct-order count of two answer different questions and should not be substituted for each other.

Choose stable columns and ordering

Write down each column’s name, meaning and expected representation. Use the same order for every row and export. If a new optional field appears in one source record, decide whether it requires a new column for the whole table rather than appending a value to just that record.

Column names should be unambiguous for the receiving program. Two source objects may both contain a field called name; flattening them into duplicate Name headers loses context. Names such as CustomerName and ProductName can preserve that distinction when the destination permits those headers.

Represent values intentionally

Decide how to serialize dates, booleans, decimal quantities and missing values. An identifier containing only digits should remain an identifier. A date should use a representation agreed with the destination instead of an ambiguous regional display copied from a formatted report.

CSV does not automatically preserve rich types, formulas or a distinction between every kind of missing value. If both null and an empty string are written as an empty field, that distinction is lost. Use an explicit convention or a different interchange format when the distinction is required for correct use.

Handle collections without accidental duplication

For a record containing several addresses and several phone numbers, expanding both lists into rows can create a combination of every address with every phone. That multiplication may imply relationships that the source never asserted. Separate related CSV tables with stable identifiers can be clearer than forcing all collections into one sheet.

If a recipient explicitly accepts a serialized JSON value inside a CSV field, that can retain a nested structure, but the recipient must then parse that field separately. It is not the same as having ordinary flat columns. Document the nested-field rule and test embedded quotation marks carefully.

Let the writer handle CSV punctuation

After mapping values to the table, use a CSV writer that knows the selected delimiter and quoting convention. A product named North, East folder contains a comma that must remain within one field. Manually joining values with commas would split it into two apparent columns.

Agree on text encoding, header presence and record endings with the receiving system. Keep those file-level decisions separate from the data model. A change from semicolons to commas changes serialization; a change from one row per order to one row per line changes the meaning of the table.

Check the export against the source

Compare record counts, distinct identifiers and appropriate totals. For the example, verify three order lines, two distinct orders and a quantity sum of six. Also inspect one identifier with a leading zero and one value containing punctuation or non-ASCII text.

Reparse the generated CSV and compare field values with the mapped table. This catches serialization problems, while the source reconciliation checks the earlier mapping. A passing parser alone cannot detect that a line was attached to the wrong order or omitted during flattening.

Include the small data contract

Provide the recipient with the row definition, column meanings and missing-value conventions alongside the file. Note any deliberate information loss, such as omitted formatting or flattened nested structures. Keep the original data so those choices can be revisited.

Finally, test a small import using the destination’s intended column types. A successful file upload does not establish that identifiers or dates were interpreted correctly. The export is reliable when the mapping, serialization and receiving interpretation all describe the same records.