> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Import model, field type mapping, refresh cadence, and limits for the CSV File data source in Adriel.

## Introduction

The CSV File connector lets the customer upload `.csv` files directly through the UI as a data source. Additional files can be added later from the data-source settings, as long as they share the same column structure as the original upload. No external service is contacted at any point — every file is parsed and stored in a dedicated cache table inside the platform, and widgets read from that table directly.

As a file-based connector, the available fields are not a fixed catalog — they are the columns of the uploaded file. Column types are inferred automatically on the first upload, and every column becomes usable as both a metric and a breakdown: numeric columns aggregate as metrics, while any column placed in a widget's Breakdowns section groups the results. A typical use case is one-off or low-cadence ingestion — manually curated datasets, mapping tables, conversion targets, or ad-platform exports the customer prefers to drop in by hand rather than wire up through a recurring sync.

To connect this data source, see [How to connect CSV File to Adriel](/data-sources/a-f/csv-files/how-to-connect).

## Data refresh strategy

The CSV File connector does not poll any source. There is no scheduled refresh and no cron — a manual upload is a static snapshot. Data changes only when the customer uploads, replaces, or removes files through the data-source settings.

* **Uploading a new file** appends its rows (or upserts / replaces, depending on the configured update method).
* **Removing a file** deletes its rows from the cache table.
* **A Reset action** drops every file and clears the cache table. There is no undo — re-uploading is the only recovery.

Because there is no source to poll, a scheduled refresh has no effect. New data appears on the dashboard only after a new upload.

## Architecture levels

Data source → cache table → files.

A CSV File data source is a single Postgres cache table (`csv_{assetId}`) populated by one or more files uploaded into it. All files in the data source share one schema: the first upload establishes the column set, and every subsequent upload must match it.

* Under the default **Append** method, every file's rows are added to the same table, tagged with `file_id` and `filename` provenance columns. Removing a file removes its rows.
* Under **Upsert**, rows are merged on a declared primary-key column.
* Under **Replace**, each upload atomically swaps the table contents.

To expose a second, differently-structured dataset, create a second data source.

## Date range limits

There is no platform-imposed date range limit — the date bounds are defined entirely by the file contents. When a column is inferred as a date, it enables date-range filtering on the dashboard. Files without a date column are treated as a single snapshot set on the dashboard.

## Import model

Instead of issuing a query to an external service, the connector runs an upload-and-parse pipeline when a file is added. Each upload is processed in order:

1. **Read** — the uploaded `.csv` is read from disk and parsed; whitespace is trimmed from every cell.
2. **Fix forbidden headers** — reserved names (`file_id`, `filename`, `created_at`, `updated_at`, `channel`, `id`) are prefixed with `csv_` to avoid colliding with system columns.
3. **Normalize headers** — header names are cleaned of special characters and truncated to fit the database column-name limit.
4. **Sanitize for type detection** — values prefixed with a currency symbol (for example `$100`) are converted to numbers so numeric columns are detected correctly.
5. **Validate** — row count, empty cells, and duplicate column names are checked; a file that fails validation is rejected.
6. **Add provenance columns** — `file_id` and `filename` are appended to every row.
7. **Detect column types** — sampled rows are examined to infer each column's type (see [Field type mapping](#field-type-mapping)).
8. **Apply the update method** — Append, Upsert, or Replace.
9. **Clean up** — the uploaded file is deleted from disk after successful ingestion.

Three update methods control how additional uploads merge with existing data:

| Update method    | Behavior                                                                                                             |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| Append (default) | New rows are added to the table; `file_id` and `filename` columns track which file each row came from.               |
| Upsert           | Rows are merged on a declared primary-key column, so re-uploading updates matching rows instead of duplicating them. |
| Replace          | Each upload atomically replaces the entire cache table contents.                                                     |

Only `.csv` is accepted. A header row is required, and encoding is auto-detected. XLSX, TSV, JSON, and other formats are rejected at upload time; customers needing those should use a different file-based connector.

<Note>
  **Identical column structure across files**

  All files uploaded into a single data source must share the same headers and column count. A file whose structure differs from the first upload is rejected. To load a differently-shaped dataset, create a separate CSV File data source.
</Note>

## Field type mapping

The CSV File connector has no fixed metric or breakdown catalog. The available fields are the columns of the uploaded file, and each column's type is inferred **once**, on the first upload, by sampling up to 200 rows. Blank values are skipped during sampling, and a column with no non-blank sampled values defaults to text.

<Note>
  **How to read the columns**

  The **Data type** column uses the platform's ten-value vocabulary: **Number**, **Currency**, **Percentage**, **Ratio**, **Duration**, **Date**, **Text**, **URL**, **Array**, **Boolean**. The **Field role** column indicates whether the column serves as a metric, a breakdown, or both.
</Note>

Each detected column type maps to an Adriel data type as follows.

| Detected column type | Trigger                                                                                                                                                 | Adriel data type | Field role                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------- |
| Number               | All sampled values parse as numeric (currency-symbol prefixes such as `$`, `€`, `¥`, `₩` are stripped and treated as numbers first)                     | Number           | Metric                                                   |
| Date                 | All sampled values parse as an ISO date or datetime                                                                                                     | Date             | Breakdown; enables date-range filtering on the dashboard |
| Boolean              | All sampled values parse as boolean                                                                                                                     | Boolean          | Metric or breakdown                                      |
| Text                 | Anything else, including any column with mixed numeric and non-numeric values                                                                           | Text             | Metric or breakdown                                      |
| Text (name override) | Column name is ID-like (`*_id`, contains `_id_`, matches `id` followed by digits, or is exactly `id`) — stored as text even when the values are numeric | Text             | Breakdown                                                |
| Text (name override) | Column name contains `percent`, `pct`, or `%` — stored as text to preserve formatting                                                                   | Text             | Breakdown                                                |

<Note>
  **Type inference is one-time**

  A column's type is decided on the first upload and persists for the lifetime of the data source. A column inferred as text cannot later be promoted to a numeric metric, even if every subsequent upload contains numbers only. Customers cannot manually override an inferred type after the table is created.
</Note>

### Adriel-added fields

Under the default Append method, Adriel adds two provenance columns on top of the file's own columns so rows can be traced back to their source file.

| Field    | Description                                            | Data type | Column     |
| -------- | ------------------------------------------------------ | --------- | ---------- |
| File ID  | Identifier of the uploaded file each row came from.    | Text      | `file_id`  |
| Filename | Original name of the uploaded file each row came from. | Text      | `filename` |

### Aggregation defaults

Because the schema is free-format, field roles follow the column's inferred type and its placement in the widget:

* **Numeric columns** are treated as metrics and are summed by default when no explicit aggregation is set.
* **Any column placed in a widget's Breakdowns section** groups the results by that column; all other selected columns are treated as metrics for that widget.
* **A date column** drives the dashboard's date-range control.

## Limitations

Based on the current connector:

* **`.csv` only.** XLSX, TSV, JSON, and other extensions are rejected at upload time.
* **Header row required.** Files without a header row cannot be parsed.
* **Identical structure across files.** Every file in a data source must share the same headers and column count; mismatched files are rejected.
* **One-time type inference.** Column types are fixed on the first upload and cannot be changed afterward; a text column cannot be promoted to a numeric metric later.
* **Type detection samples up to 200 rows.** A column whose type only becomes ambiguous beyond the sampled rows may be typed from the sample alone.
* **Reset is destructive.** Reset removes every uploaded file and clears the cache table, with no undo.
* **No scheduled refresh.** There is no source to poll; data changes only on upload, replace, or removal.
* **No deleted-element tracking.** The connector does not surface deleted elements from any source — it only reflects the rows present in the uploaded files.
* **Generic data source.** CSV data is viewed in a generic table and does not combine natively with other connector types unless they share the same breakdowns; use Blend Data settings to combine it with other connectors.

## API references

The CSV File connector contacts no external API. Files are parsed and stored inside the platform, and all queries are answered from the local cache table — there is no outbound HTTP call, authentication step, or third-party endpoint. The only external standard that applies is the CSV file format itself.

* [RFC 4180 — Common Format and MIME Type for CSV Files](https://www.rfc-editor.org/rfc/rfc4180)

## See also

* [How to connect CSV File](/data-sources/a-f/csv-files/how-to-connect) (paired how-to)
* [Custom URL Import data reference](/data-sources/a-f/custom-url-import/data-reference) — fetch CSVs from a URL on a scheduled refresh
* [Amazon S3 data reference](/data-sources/a-f/amazon-s3/data-reference) — for larger or scheduled file batches
* [File from SFTP data reference](/data-sources/a-f/file-from-sftp/data-reference) — pull files from an SFTP server on a schedule