Overview
CSV is the right Lens source when your data does not have a live API or warehouse behind it. Exports from an ad platform, a finance spreadsheet, a partner report, or a one-off pull all fit naturally as files you upload by hand. Lens treats a CSV table as two separate things: the configuration, which is the column mapping you set once, and the content, which is the set of files you upload over time.
The folder model is what keeps those two concerns apart. Every file you upload lands in a storage folder that belongs to this one table. The mapping never changes when you add a file, and adding a file never disturbs the files already there. A sync simply reads whatever is currently in the folder and loads it into ClickHouse. This is different from a "replace the whole table on every upload" model, and it is why you can keep adding monthly exports to the same table without losing last month's data.
Create the CSV table
Open Lens > Tables, click Add Table, and choose CSV. Give the table a clear name, something like "Monthly Partner Spend" rather than "csv1", because the name is how you will find it on boards later. Save the table to create the record.
At this point the table exists but has no mapping and no data. That is expected. You set up the structure first, then add content. Keeping the two steps separate means you can fix a mapping mistake without re-uploading files, and you can add files later without touching the mapping.
Map your columns
On the table setup screen, map each column from your CSV to a role. A dimension is a grouping you slice by, such as date, channel, campaign, or region. A metric is a number you add up, such as sessions, clicks, or spend. Lens uses these roles to know what to group on and what to sum when a board queries the table.
Pick a clear date column. The date is what anchors rows over time and what Lens uses to update a period when you upload a newer file. If your file has a column that is really an identifier rather than a number to total, map it as a dimension, not a metric. Getting roles right here saves confusion later when a tile shows a sum that should have been a label.
Keep your column headers consistent from one upload to the next. Lens matches the headers in each file to the mapping you configured, so a renamed header in a later file will not line up.
Upload data
Open the table and click Upload Data. Drag one or more CSV files into the drop zone at once, or click to browse. Each file uploads into the table's folder under a unique name, so a new upload adds to the folder rather than overwriting what is already there. When the files finish uploading, Lens runs a sync that scans the folder and ingests any new files it finds.
Because uploads accumulate, you can build a table up over time. Drop in January's export now and February's next month, and the table holds both. There is no need to combine files yourself before uploading, and no need to re-upload old files that are already in the folder.
Re-upload to update
To refresh a period you have already loaded, upload a newer file that covers those dates. Rows are keyed by their date and dimension values, so the newer data for a given day replaces the older version for that same day. Days that are not in your new file are left exactly as they were. This makes it safe to correct a bad export: upload the fixed file for the affected dates and only those dates change.
Clear data when needed
Use Clear Data when you need to reset the table. There are two options. Clear synced data removes the rows from ClickHouse but keeps your uploaded files in the folder, so the next sync re-ingests them. This is useful if you want to re-process the same files, for example after changing the mapping.
Clear data and uploaded files goes further. It removes the rows and also deletes the files from the folder, so the table starts completely empty. Use this when you want a clean slate and intend to re-upload from scratch. This is the option to reach for if you accumulated files you no longer want counted.
If you clear only the synced data and then upload more files, the next sync ingests both the kept files and the new ones. If your row count looks higher than you expect, that is usually because old files are still in the folder. Use "Clear data and uploaded files" to truly reset.
Troubleshooting
Row count looks too high after several uploads
The folder holds every file you have uploaded, and the sync loads all of them. If you uploaded overlapping or duplicate files, the rows deduplicate by date and dimension values, but a count taken right after a sync can briefly look high while the background merge finishes. Give it a moment, then recount. If the number is still wrong, check whether old files are still in the folder and clear data and uploaded files to reset.
A copied table shows the original table's data
A copied CSV table gets its own empty folder, so it should not show the source table's files. If you copied a table before this behavior was in place and it still points at the original, re-create the copy. New copies start empty and you upload fresh files into them.
Dimensions show blank after a sync
This almost always means a header in the uploaded file does not match the column you mapped. Open the file, confirm the header names match the mapping exactly, re-save as UTF-8 comma-delimited, and re-upload. Excel in some locales saves semicolon-delimited files, which will not parse as expected.