> ## 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.

# How to connect

> How to connect the CSV File data source to Adriel: upload one or more UTF-8 .csv files directly through the UI and map them into dashboards.

The CSV File data source accepts `.csv` files uploaded directly through the interface. No external service is contacted at any point — uploaded files are parsed and stored in a dedicated cache table. Connecting it brings manually curated datasets, mapping tables, conversion targets, or ad-platform exports into Adriel dashboards without wiring a recurring sync.

## Before you connect

The following are required:

* One or more `.csv` files. Other formats, such as XLSX, are rejected at upload time.
* A consistent column structure across all files in the same data source — the same header names and the same column count.

<Warning>
  Two file requirements must be met before connecting, or the upload is rejected:

  * The file extension is limited to UTF-8 encoded .csv format. If the file is not suitable, change the format or extension in the file settings before connecting.
  * The column header (first row) must not contain empty columns.
</Warning>

## Connect CSV File

<Steps>
  <Step title="Open the data source">
    On the **Data Sources** page, search for **CSV File** and select it.
  </Step>

  <Step title="Name the data source">
    The name field defaults to `default`. Keep it and click **Submit**, or replace it with a distinguishable name for this upload and click **Submit**.
  </Step>

  <Step title="Set optional fields">
    Set an **Alternative Channel Name** to control the display name for the channel. Set a **File Name to Filter** to restrict the data source to files matching a name pattern.
  </Step>

  <Step title="Choose an update method">
    Select how new uploads are merged. **Append** (default) adds rows and stamps them with `file_id` and `filename` provenance. **Upsert** merges on a declared primary-key column. **Replace** swaps the cache table contents with each new upload.
  </Step>

  <Step title="Upload the files">
    Drag and drop one or more `.csv` files into the upload area, or browse to select them. Each file is processed individually — if one upload fails, the others continue. The first upload establishes the column schema and triggers type inference.
  </Step>

  <Step title="Finish">
    Close the settings tab. The connection saves and connects automatically once the uploads complete, and the data source is immediately available for dashboards.
  </Step>
</Steps>

To add or remove files later, open the data source settings from the Connected data sources list, add or delete files, then close the tab — changes save automatically. Every later upload must match the original column structure; files with different headers are rejected, so create a separate CSV File data source for a differing layout.

## What gets imported

Column types are inferred on the first upload from sampled rows. Numeric columns become metrics and text columns become breakdowns. Column names matching `*_id`, `percent`, `pct`, or `%` are forced to text to preserve formatting. Type inference runs once and persists for the lifetime of the data source.

For the complete field list and limits, see the [CSV File data reference](/data-sources/a-f/csv-files/data-reference).

## Troubleshooting

<AccordionGroup>
  <Accordion title="A later upload is rejected with a schema error">
    The file's headers or column count do not match the data source's established schema. Reformat the file to match, or create a separate CSV File data source for the differing layout.
  </Accordion>

  <Accordion title="A column is stored as text but contains only numbers">
    Type inference runs once during the first upload and persists. If the original sample included non-numeric values, or the column name matches an ID or percentage pattern, the column stays text. Re-create the data source after fixing the source file to change the inferred type.
  </Accordion>

  <Accordion title="A browser upload stalls on a large file">
    Browser-based uploads are bounded by browser memory. For files in the high hundreds of megabytes or larger, use Amazon S3, File from SFTP, or Custom URL Import instead.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="CSV File data reference" href="/data-sources/a-f/csv-files/data-reference">
    Fields, type inference, and limits for the CSV File data source.
  </Card>

  <Card title="CSV File FAQs" href="/data-sources/a-f/csv-files/faqs">
    Common questions and expected behaviors for the CSV File data source.
  </Card>

  <Card title="How to connect Custom URL Import" href="/data-sources/a-f/custom-url-import/how-to-connect">
    Pull CSVs from a URL on a schedule instead of uploading by hand.
  </Card>

  <Card title="How to connect Amazon S3" href="/data-sources/a-f/amazon-s3/how-to-connect">
    Connect larger or scheduled file batches from an S3 bucket.
  </Card>
</CardGroup>