Guides

Bring data in

You have data in a file, a spreadsheet, a Google Sheet, or a warehouse. This guide shows each way to get it onto a dashboard, and how to keep it fresh.

Each way ends with a datasource: a named set of rows saved into the dashboard. Charts and tables read those saved rows. Viewers read them too, and never touch your file, your sheet, or your accounts.

This guide describes arkush.app. An org install offers more paths, such as a BigQuery query that runs as a service account. Those sections carry the note Org installs only.

Make a dashboard

Data goes onto a dashboard that you can edit. Any signed-in person can make a new one. Use a desktop or tablet window: a window the size of a phone shows no New dashboard button.

Select arkush at the top left of the header. The Dashboards page opens.
Select New dashboard.

An empty dashboard opens with the mode switch in the header on Edit. The canvas shows the Start your dashboard walk: one step for each way to add data that you can take now, such as Upload a file and Connect BigQuery. When you are signed in, the dashboard saves itself to your account after your first change.

Drop a file on the canvas

This path is the fastest. arkush reads CSV, Excel, JSON, and Parquet files. A CSV file that Excel on Windows saved imports too: arkush reads text that is not UTF-8 as Windows-1252.

Open your dashboard, and set the mode switch in the header to Edit. If you have no dashboard yet, see Make a dashboard.
Drop the file anywhere on the canvas. The Data workspace opens with the file read. If the canvas cannot take the file, a notice says why and what to do first.
Look at the file in the Data workspace. One tile per column shows its values, how many are missing, and the type the column is read as. Change a type with the picker on its tile. If some rows of a CSV file have more or fewer fields than the header, a note counts those rows and names the first one. To keep every value, correct those rows in the file and choose the file again.
Select Create datasource.

The file becomes a datasource, and a table bound to it appears where you dropped the file. A notice states the row count. On an empty dashboard, the same import is the first step of the Start your dashboard walk: Upload a file opens the file picker. After the dashboard has data, the walk shows Add more data, which opens the same picker.

Check each column before you create the datasource. Here a store number is an identifier, so its type changes from Whole number to Text.

An Excel workbook imports the same way. A workbook with several sheets also shows a Sheet picker. Pick the sheet before you select Create datasource.

When the file has more than 50,000 rows

The Data workspace opens with the file already read and the true row count shown. A datasource holds at most 50,000 rows, so the workspace gives you a SQL query over the file. The result of the query becomes the datasource.

Keep the starter query to take the first 50,000 rows. To summarize all the rows instead, pick a starter from Insert a transform. Its starters use your own columns: group and count, count by month, top 10, and more.
Select Run query.
Make sure that the preview shows the rows you want.
Select Create datasource.

The query half of the import editor for 60,000 pasted rows. The facts line reads 'Pasted data · 60,000 rows · 4 columns · read as CSV'. Under it are the Insert a transform picker, the starter query SELECT * FROM data LIMIT 50000, and the Run query and Create datasource buttons. — Over the limit, here with 60,000 pasted rows, the editor shows the true row count and the starter query. The result of the query becomes the datasource.

Paste rows from a spreadsheet

You can paste copied cells. You do not need a file.

Copy the rows in Excel or Google Sheets.
Select the Data icon in the icon rail at the right edge of the screen to open the Data panel.
Select New. The Data workspace opens, with the editor under the data.
Select Import as the source.
Paste into the Or paste your data here. box.
Read the facts line: the row count, the columns, and how the app read the text.
Type a name in Name. Pasted rows have no file name, so the datasource takes this name.
Select Create datasource.

Paste the rows, read the column tiles, name the datasource, and create it.

Each column has a tile, with the type the app read in a picker. If the app read a column as the wrong type, for example a date as text, pick the correct type on its tile. The tile counts the values that do not convert to the type you pick.

To show the new datasource, select Chart in the edit-mode header, or add a table from the Add menu beside it.

The Data workspace. Its bar holds Canvas, the Columns, Rows, and Model views, and the dashboard name. The datasources weekly and campaigns are listed on the left, with weekly selected. On the right are the facts of weekly and one tile per column, each with its most common values and a count of distinct values. — The Data workspace. Columns shows one tile per column. Rows shows the rows, and Model shows how the datasources depend on each other.

Connect a Google Sheet or a file at an address

Data at an address becomes a datasource: a Google Sheet, or a CSV, JSON, or Parquet file that Google hosts. On arkush.app, your browser reads it, and the server reads nothing at an address. A file on another host does not read from its address: download the file and bring it in with Import. The Sheets/URL source states what the server reads.

Open the Data panel and select New.
Select Sheets/URL as the source.
Paste the address. For a Google Sheet, copy the link while the tab you want is open, because the link names the tab. The field shows what the app recognized: the source, the sheet tab, and the table name your SQL reads.
For a Google Sheet, check Read with. On arkush.app, it reads Your browser. See What each address needs for the read that fits your sheet.
Write the SQL. Start with SELECT * FROM sheet, and narrow the query after you see the columns.
Select Create datasource.

The new datasource appears in the list of datasources, with its rows. The canvas shows no chart yet. To show the rows, select Chart in the edit-mode header, or add a table from the Add menu beside it.

A pasted sheet address. The field states what the app read from it, and Read with states who reads the sheet. On the server in this clip, only your browser reads it, so Read with offers no choice.

What each address needs

Read with states who reads a Google Sheet. On arkush.app, it shows Your browser and offers no choice, because the server reads nothing at an address.

Google Sheets has two ways to open a sheet to others, and each one gets a different read. Sharing by link is Share → General access → Anyone with the link. Publishing is File → Share → Publish to web.

A Google Sheet shared as “anyone with the link” reads in your browser. Keep Read with on your browser. No Google window opens.
A Google Sheet that is not shared by link reads in your browser with your own Google account. Keep Read with on your browser. A sheet that only you can see works. This Google connection is separate from your sign-in to arkush, so it works when you sign in with GitHub too: it lets the app read the sheet. The first read opens a Google window, where you sign in to Google if Google asks. The window then shows that sheet. Select the sheet once, and the app gets access to that one file only. Under Read with, a row names the Google account that reads the sheet, with Connect Google account or Disconnect.
A sheet that your browser reads refreshes only when a person selects Refresh. The schedule never runs it.
A file at an address that Google does not host does not read on arkush.app. Download the file and bring it in with Import.

The server reads an address

Org installs only

An org install can let its server read addresses, from the hosts that the people who run it name. There, Read with also offers This server's Google account, the Google account that the server itself uses.

A published CSV or a published sheet needs no credential. Set Read with to This server's Google account for a sheet. The server gets the file, and the refresh schedule keeps it fresh. Any editor can use this path.
A host that the server does not allow makes the run fail. The message names what works instead: read the sheet in your browser, or download the file and bring it in with Import.
A server that reads no addresses says so in the Sheets/URL source. Some of these servers also read no private sheet. There, the source says so and offers no Google connection. Share the sheet by link, or download a copy and bring it in with Import.

A private Google Sheet on the schedule

Org installs only

On an org install, the server can read a private sheet with its own Google account, so the schedule keeps the sheet fresh. Only a person with the analyst right can set up this read. The people who run the org install give that right to named people. The app shows no list of your rights. Without the right, Read with starts on your browser, and a server read of a private sheet fails with a message that names what works instead.

Share the sheet with the server's Google account. The app does not show that account's address: get it from the people who run the org install.
Set Read with to This server's Google account. The server then reads the sheet on the schedule.

Query BigQuery with your own account

Write SQL against the warehouse and save the result. The query runs as you, with your own Google account, in your browser, and bills your own Google Cloud project. This path needs a signed-in account. The Google connection is separate from your sign-in to arkush, so you can sign in with GitHub and still query BigQuery with a Google account. On an empty dashboard, Connect BigQuery in the Start your dashboard walk opens this path.

Open the Data panel and select New.
Select BigQuery as the source.
Write the SQL, or select a table in the table browser for a starter query.
Select Run in BigQuery. You do not need to connect first. The first run asks you to sign in with Google, and asks for read-only access to BigQuery only.
Make sure that the preview shows the rows you want.
Select Create datasource.

The connection row above the SQL shows which Google account the queries run as, with Connect and Disconnect. Each query bills to a billing project that you choose in the Billing project field of the BigQuery connection group, at the top of the BigQuery form. On arkush.app, the group opens and asks you to choose one before the first run. On an org install, the group can start on a default project that the org install sets, and you can pick another.

If your Google account has no Google Cloud project, the list is empty. Create a project in the Google Cloud console, then connect again. Google bills the project for each query, except within the free limits of Google's BigQuery sandbox. Public datasets, such as bigquery-public-data, read under any project you bill. If a run says your account can't start a query in the project, pick a project where your account can run queries: one you own, or one where you hold the BigQuery Job User role.

NOTE — Your Google sign-in stays on your machine. The app never writes it into the dashboard, and never sends it to the server.

A query under your own Google account refreshes only when a person selects Refresh. No schedule runs it, and an agent works from the rows of its last refresh.

Query BigQuery as a service account

Org installs only

On an org install, a query that the schedule or an agent refreshes runs on the server, as a service account. Each org install registers its own service accounts, and some register none. To use an account, you need the Service Account User role on that account in Google Cloud. The people who manage that Google Cloud project grant the role there. With the role, the BigQuery source shows a Runs as field on a dashboard saved to the server.

Open the Data panel and select New.
Select BigQuery as the source. Runs as already names an account.
Write the SQL, or select a table in Browse tables for a starter query. The browser lists the tables that the account can read.
Select Create datasource. The server saves the query, runs it as the account, and saves the rows as the datasource's data.

The server runs only a saved query. To change the query, edit it and select Save and run. To run a query with your own Google account instead, set Runs as to Your own Google account. The query then runs in your browser, and the schedule never runs it.

If you hold the role on no registered account, the field does not show, and the query runs as you. The Findings panel names each scheduled datasource that runs as a person. The link on the finding opens that datasource at its Runs as field.

A datasource runs as an account you cannot use

A service account is a Google account for a program, which an org install registers so that its server runs queries. A dashboard that came from an org install, for example as an imported file, can hold a datasource that names a service account. That account does not run for you. Runs as shows the account, a note that says why it does not run for you, and one other choice: Your own Google account.

Open the datasource in the Data panel.
In Runs as, select Your own Google account.
Select Run in BigQuery. The query runs in your browser.
Select Save snapshot to keep the rows.

Refresh on the datasource names the same step.

Query a database

Org installs only

A query can run on a PostgreSQL database that your arkush server connects to. This path depends on your arkush server: the people who run it register each database, and most servers register none. The query runs on the server as a service account, so you need the Service Account User role on an account that the database admits. Read Query BigQuery as a service account for how the role is granted.

Open the Data panel and select New.
Select Database as the source. The source shows only on a server that registered a database.
Select the database in Database.
Select the account in Runs as.
Write the SQL in PostgreSQL. The editor does not check it as you type, and it has no table browser.
Select Create datasource. The server saves the query, runs it on the database as the account, and saves the rows as the datasource's data.

The query runs read-only, and a result over 50,000 rows is refused. Aggregate or filter in the SQL. Query parameters do not apply here: write the values into the SQL. The schedule can refresh the datasource.

If the run refuses, the message names the step. When the database refuses the account, the people who run your arkush server make the account a user of the database. When a table is refused, tell the people who run your arkush server. They ask the owner of the database to give the account read access to the table.

Store a file for reuse

An import copies rows into one dashboard. The files store keeps the original file instead: many dashboards can read it, and a replacement reaches all of them. The store needs a signed-in account, and it holds CSV, JSON, and Parquet files.

Upload from the Datasources page. Select arkush at the top left of the header. Then select the Datasources tab. The Uploaded files section is at the end of the page. Select Upload file, and pick the file. Its columns and rows show before anything is stored. Check them, then select Upload.
Keep the original while you import. If the file is within the limits, turn on Keep the original file in Uploaded files. Over the row limit, the reduce flow stores the original as one of its steps.

A picked file in the Uploaded files section, targets-2026.csv, marked 1 KB and not uploaded yet. It reads 6 rows, 3 columns, read as CSV. The columns quarter, channel, and target are listed with their kinds, and the six rows show in a table. Upload and Cancel are at the bottom. — A picked file waits for **Upload**. The server stores nothing until you select it.

To make a datasource that reads a stored file:

Open the Data panel and select New.
Select Import as the source.
In Or use an uploaded file, pick the file. Its columns and rows show.
Keep the starter SQL, or write SQL that reduces the file.
Select Create datasource.

A datasource built on a stored file keeps its reduction SQL. A refresh runs that SQL again, on the server, over the current bytes of the file. When someone replaces the file with Replace file on the file's own page, every dashboard that reads it shows File changed until its next refresh.

A file is private to you. On arkush.app it stays private, because only the people who run arkush.app add shares. On an org install, you share it from its page. A refresh needs access to the file itself as well as to the dashboard. The server sets a space limit per person. The section shows your usage, and at the limit an upload fails until you delete a file.

Keep the data fresh

Charts read saved rows. New numbers arrive only when a datasource refreshes. Opening the dashboard runs no query.

One datasource: select Refresh beside it in the Data panel. The stored query runs again, and the new rows replace the old rows. You stay on the canvas, and a notice says how many rows arrived or why the run failed.
Every datasource at once: with several query datasources, Refresh all is at the top of the list. It runs each datasource in turn. A failure does not stop the others, and the report names each datasource that failed.
Imported rows: imported rows have no query. To change them, open the datasource and select Replace data.
On a schedule: a schedule refreshes a datasource that the server runs, then the derived views that read it. On arkush.app, the server runs no query, no sheet and no file at an address, so a schedule re-runs only derived views over the rows that are already saved. New rows from BigQuery, a sheet or a file arrive when you select Refresh. On an org install, a query as a service account and a sheet or a file that the server reads run on the schedule too. Where a dashboard has such a datasource, select Schedule… in the Scheduled refresh section of the Data panel. Set the cadence as a cron expression: five values for the minute, the hour, the day of the month, the month and the day of the week. 0 7 * * 1 runs every Monday at 07:00. Set a timezone. The next run shows before you select Save schedule. The schedule repeats only a query that a person, or an agent that the person connected, already ran on the server. A query that never ran, a query you changed, and data that did not come from a server run are paused, and the section names each one with its cause. Run it once, and the schedule continues from there. A query under your own Google sign-in runs only in your browser, so the schedule never runs it. If a scheduled refresh stops, the owner and the person it runs as get an entry in their inbox, the bell icon in the header, that names the datasource. The Scheduled refresh section also names each stopped datasource. Where the server recorded why, an editor reads the reason there. Run the datasource once to resume its schedule.

Set a schedule: 0 7 * * 1 runs every Monday at 07:00 in the timezone you set.

The header shows a freshness chip, such as "Data: 2 h ago", with the age of the oldest saved data. Editors and viewers see the same chip. Select the chip to open the Data panel. With a schedule set, the chip turns amber when a run is overdue.

The header with the freshness chip, Data: 2 d ago, beside the dashboard name. The Data panel is open beside the dashboard, with Open Data workspace and two datasources, each with its row count and its import age. — The Data panel, opened from the freshness chip in the header.

The limits

Each limit has the same fix: make the data smaller.

50,000 rows per datasource. A BigQuery run over the cap shows its preview and says that Save keeps only the first rows. An imported file over the cap goes to the reduce flow. In both cases, aggregate or filter until the whole result fits.
512 MB per imported file. The app checks the size before it reads the file.

The limits keep a dashboard fast to open and safe to share. Every viewer reads saved rows, and no viewer runs a query.