> For the complete documentation index, see [llms.txt](https://developer.abacum.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.abacum.ai/essentials/concepts/data-file-format.md).

# Data file format

The columns in each data file, and how the metadata describes them.

Each data endpoint returns two parts:

* `data`: a download link to the file. See [Download links](/essentials/concepts/download-links.md).
* `metadata`: a description of each column in the file.

Models are live, and their structure can change. Read the `metadata` on each call. Do not hard-code the column list.

## Model data files

A model data file has three fixed columns, then one column for each dimension.

| Column                        | Content                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------ |
| `variable_id`                 | The ID of the variable                                                         |
| `time`                        | The date of the value. For a monthly model, this is the last day of the month. |
| `value`                       | The numeric value                                                              |
| One column for each dimension | The dimension item, for example `Engineering`                                  |

Sample file:

```csv
variable_id,time,value,departments_level_1,locations_level_1,locations_level_2
VARIABLE_ID,2023-01-31,10345.00,Engineering,Europe,Spain
```

Three parameters change the columns:

* With `timescale=full`, the file has no `time` column. It holds one value for each variable over the whole period.
* With `dimensions`, the file holds only the dimensions that you list.
* With `enrich=true`, the file holds variable names in place of IDs, and dimension labels in place of dimension names. In the metadata, the `variable_id` entry is named `variable_name`, and the keys of its `variables` map are variable names.

{% hint style="info" %}
The files of a weekly model add one column, `fiscal_week`, right after `time`. It holds the fiscal week and year as a label, for example `W52 2024`. The files of a monthly model do not have this column.
{% endhint %}

## Model data metadata

The `metadata.properties` object describes each column in the file.

| Key                               | Content                                                                                                  |
| --------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `variable_id`                     | A `variables` map. Each key is a variable ID. Each value holds the variable `name` and its `dimensions`. |
| `time`                            | The type of the column: a date string                                                                    |
| `value`                           | The type of the column: a float                                                                          |
| One key for each dimension column | The `label` of the dimension, for example `Department`                                                   |

Sample response:

```json
{
  "data": "https://files.example.com/actuals_data.csv?signature=...",
  "metadata": {
    "properties": {
      "variable_id": {
        "type": "string",
        "variables": {
          "VARIABLE_ID": {
            "name": "Revenue",
            "dimensions": ["departments_level_1", "locations_level_1", "locations_level_2"]
          }
        }
      },
      "time": { "type": "string", "format": "date" },
      "value": { "type": "number", "format": "float" },
      "departments_level_1": { "type": "string", "label": "Department" },
      "locations_level_1": { "type": "string", "label": "Region" },
      "locations_level_2": { "type": "string", "label": "Country" }
    }
  }
}
```

## Dataset data files

| File           | Columns                                                                       | Metadata                                  |
| -------------- | ----------------------------------------------------------------------------- | ----------------------------------------- |
| Raw data       | The original columns from the source, with the type Abacum read for each one  | `properties`, `ingested_at`, `row_count`  |
| Processed data | The date column, each dimension column with its label, and the number columns | `properties`, `processed_at`, `row_count` |