# CSV Import

This article explains how to import data from CSV files into Model Reef and how to structure CSVs so that they map cleanly to variables and drivers.

You will learn:

* When to use CSV import.
* How to structure CSV files.
* How to map rows and columns to series.
* How CSV import fits alongside PDF and Excel import.

***

## When to use CSV import

CSV import works well when:

* You have simple, tabular data from systems that export CSV only.
* You are pulling data from scripts, code, APIs or data warehouses.
* You can control the column names and layout precisely.
* You want a lightweight, reproducible import format.

If your data is already in well structured Excel sheets, Excel import can be more convenient. CSV is ideal for automated or scripted data pipelines.

***

## Structuring CSV files

CSV files used for import should generally have:

* A single **header row**.
* One **date or period column**.
* One **value column** per series, or one row per series depending on the chosen layout.
* No merged cells or embedded formatting.

Two common patterns are:

### Pattern 1: One series per column

Columns:

* `Period`, `Series A`, `Series B`, `Series C`

Each row represents one period. Each value column represents a different metric or series.

### Pattern 2: One series per row (long format)

Columns:

* `SeriesName`, `Period`, `Value`

Each row represents a single data point for one series at one period. This format is often easier to generate from databases.

Model Reef can work with both, but long format is generally more flexible for programmatic workflows.

***

{% stepper %}
{% step %}

### Uploading CSV files

In the import interface:

* Choose **Import from CSV**.
* Upload one or more CSV files.
* For each file, select the sheet or parsing options if prompted (for example delimiter, encoding).

You will then see a preview of the parsed table.
{% endstep %}

{% step %}

### Identifying date and value fields

For each CSV table you should:

* Mark which column is the **date or period** column.
* Confirm the **format** of the dates (for example `YYYY-MM-DD`, `YYYY-MM`, `YYYY`).
* Mark which columns contain values to import.

If using long format, you will also indicate which column holds the series names or IDs.
{% endstep %}

{% step %}

### Mapping to variables and drivers

Once dates and value fields are identified, you map each value series to:

* A **variable type** (if it is a direct model variable).
* Or a **driver** or Data Library entry (if it is an input series only).
* A **category** and **subcategory** if relevant.
* A **branch** if the data relates to a specific part of the business.
* Appropriate **units** and **frequency**.

You can import:

* Operational drivers such as volumes, prices or conversion rates.
* Financial series such as revenue, COGS or expenses.
* External indices used in formulas or scenarios.
  {% endstep %}

{% step %}

### Updating CSV based data

For recurring CSV imports from the same source, aim to:

* Keep file and column layouts stable.
* Use naming conventions for series that match your model.
* Use the same mapping each time so that updates are seamless.

Over time, you can replace manual CSV uploads with more automated solutions if you wire an API or data pipeline into a scheduled CSV export and import process.
{% endstep %}
{% endstepper %}

***

## Practical tips

* Validate CSV files before import to catch encoding or delimiter issues early.
* Keep separate CSVs per domain (for example financials vs operational metrics) if that makes mapping clearer.
* Document the CSV structure in your team so that future exports follow the same pattern.

***

## Related articles

* [Construction & Contracting](/use-cases/construction-and-contracting.md)
* [Build a Cashflow Early Warning System](/how-tos/dashboards-and-reporting/build-a-cashflow-early-warning-system.md)
* [Actuals Import](/help/xero-integration/actuals-import.md)
* [Accrual Behaviour](/syntax/timing-syntax/accrual-behaviour.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.modelreef.io/help/importing-and-data-inputs/csv-import.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.