CSV

A CSV Source can be built two ways — by uploading a file, or by pointing Akuko at a public URL. They look almost identical while you are setting them up, and they behave differently afterwards. Which one you want depends on a single question: does this data change?

	Upload a file	Public URL
Keeping it current	Replace the file by hand	Refresh on a schedule
Measures created for you	count, plus Sum, Average, Minimum and Maximum for every numeric column	count only
Where the data lives	A Parquet file on S3, read by ClickHouse	Loaded into a ClickHouse table once it is large enough

If your data is a one-off extract, upload it. If it is a file somebody republishes — an export that lands at the same address every week — connect the URL and let Akuko re-read it.

Before you start

Akuko reads the file's structure once, at the start, and builds the Source from what it finds. Three things about your file decide whether that goes well:

• The first row must be the header row. It is always treated as one. There is no setting for a file that starts with data, or one with a title line above the header.

• Column names should be distinct once punctuation is stripped — see below. Headers that collide after rewriting are not rejected; the second one gets a number added to it. Total Cases and total cases arrive as total_cases and total_cases_1, and nothing records which was which.

You cannot set the delimiter or the character encoding. Both are detected from the file.

Uploading a file

1. In a Space, open Sources and choose New Source.
2. Name the Source and choose CSV as the type.
3. Upload your file.

Akuko converts the file to Parquet, stores it, reads its columns and builds the Source. When that finishes, the Dimensions, Measures, Geometries, Cube and Query panels appear.

An uploaded CSV gets a generous set of measures to start from: the count measure — Number of records — plus a Sum, Average, Minimum and Maximum for every column that came through as a number.

Connecting a public URL

1. In a Space, open Sources and choose New Source.
2. Name the Source and choose CSV as the type.
3. Enter the URL of the CSV file.

The URL has to be reachable by Akuko without credentials. A link that works in your browser because you are signed in — a private Google Drive or SharePoint file, say — will not work here.

A URL-backed CSV starts with the count measure only. To get the same set an uploaded file would have given you, use Generate Measures in the Measures panel; see Measures.

Once the Source exists, a Refresh Schedule panel appears in its Settings, where you can have Akuko re-read the URL Every so many hours, Daily or Weekly. See Sources.

What Akuko does to your columns

Every column name is rewritten. It is lowercased, spaces become underscores, accents are flattened, and most punctuation is dropped rather than replaced. A name starting with a digit gets an underscore in front of it. Nothing preserves the original.

In your file	In Akuko
Total Cases (2024)	total_cases_2024
Date of visit	date_of_visit
% positive	positive
2nd dose	_2nd_dose
Région	region

That name is what queries use, and it cannot be changed afterwards. What you can change is the Label — the name people actually see on charts and tables. Setting readable labels on the dimensions you plan to use is worth doing early; see Dimensions.

A column of dates without times becomes text, not a date. Akuko recognises a timestamp but not a plain date, so 2024-01-15 arrives as a string dimension — which cannot be used for time filtering or grouped by month. Include a time component in the file (2024-01-15T00:00:00) and the column arrives as a time dimension.

Rows Akuko cannot read are dropped silently

If a row does not match the structure of the file — too few columns, too many, or a value that will not parse as the type of its column — that row is discarded and the import continues. A four-row file with one short row and one long row imports as two rows, without an error.

caution

You are not told how many rows were dropped. There is no warning and no count. Upload 10,000 rows, get 9,300, and nothing on the page says so.

Check the row count after importing: put the Number of records measure into the Query panel and compare it against what you expected. A shortfall means rows were dropped, and the file is where to look.

Replacing the data

An uploaded file is replaced from the Connection panel in the Source's Settings, using the Update button.

A URL-backed Source re-reads its URL — on the schedule you set, or immediately with the Refresh button in Settings.

Either way, Akuko reads the new file against the Source that already exists rather than starting fresh, and the two paths differ in what survives:

• Re-reading a URL keeps your edits. A dimension you retyped or relabelled stays as you left it.
• Replacing an uploaded file re-reads the columns from the file. A dimension in the new file goes back to the type and SQL derived from it, so edits to those dimensions are overwritten.
• In both cases, columns that are no longer in the file stay in the Source. They are not removed, and they will fail when queried. Delete them by hand from the Dimensions panel.
• In both cases, measures are kept as they are — including the automatic ones. Replacing an uploaded file does not generate measures for columns that are new.

tip

If a Post still shows the old numbers after a refresh, use Clear cache in the Source's Settings and reload the Post.

When an import fails

Every structural problem with a CSV surfaces as the same message:

Failed to get source dimensions from csv file

It does not say which row or which column, so it is worth checking the usual causes directly: the file is not really CSV; the header row is missing; two column names collide once rewritten; the URL is not publicly reachable.

The most reliable way to find the problem is to cut the file down — the first hundred rows, then the first ten — until it imports. Whatever you removed last is the problem.

Checking the result

Use the Query panel on the Source before building a Post on it. Select a few dimensions and the Number of records measure, then Run query. This is the quickest way to confirm the row count is what you expected, the dates arrived as dates, and the numbers arrived as numbers.

The panel returns 5000 rows by default. That is a limit on what the panel displays, not on what the Source holds.