Data reference

​

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 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).
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: 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.

​

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. Each detected column type maps to an Adriel data type as follows.

​

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.

​

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

​

See also

• How to connect CSV File (paired how-to)
• Custom URL Import data reference — fetch CSVs from a URL on a scheduled refresh
• Amazon S3 data reference — for larger or scheduled file batches
• File from SFTP data reference — pull files from an SFTP server on a schedule