User guide

Cloud Certainty SQLark is a web console for Amazon Athena that runs in your organisation's own AWS account. You write and run SQL against the AWS Glue Data Catalog, keep and share queries, chart results and build dashboards, across the AWS accounts and Regions your administrator connected.

Open the portal URL your administrator gave you and sign in with your company account. You see the databases and workgroups an administrator granted you; what you may do with each depends on your permissions:

Permissions are granted per AWS account (connection), Region, workgroup and database, so you may be able to query a database in one workgroup and only browse it in another. Buttons for actions you can't take are greyed out, and their tooltip says why.

Some features depend on your organisation's plan (Starter, Team, Business or Enterprise). A feature the plan doesn't include shows a plan badge, for example Team or Business. This guide notes the plan next to each such feature.

The top bar has Workspace, Saved queries, Dashboards, History, Snapshots and, for administrators, Administration. The footer has a theme switch (System, Light, Dark).

#Signing in

SQLark uses your organisation's sign-in: AWS IAM Identity Center, another SAML or OIDC identity provider, or SQLark's own user pool with multi-factor authentication. Your administrator chose one when installing SQLark (Identity providers).

The first time you sign in you may see no databases at all: nobody sees anything until an administrator gives them a grant. Ask your SQLark administrator for access, naming the AWS account, the workgroup and the databases you need.

#Workspace

Workspace is where you write and run SQL. It has a schema browser on the left, the editor in the middle and the results below.

#Tabs

Each tab is one query with its own SQL, datasource and results. Open a new tab with + and close one with its ×. Opening a saved query, or a query from History, opens it in a tab, and a tab with unsaved changes is marked.

#Datasource

The datasource picker above the editor decides where the query runs:

The catalogue is always the AWS Glue Data Catalog (AwsDataCatalog) of the connection and Region. Federated catalogues and Amazon S3 Tables catalogues are not supported yet.

A query can read tables from any database you may query in the chosen workgroup: write other_db.table_name for tables outside the default database.

#Editor

The editor is a full SQL editor with Athena (Trino) syntax highlighting, bracket matching, multiple cursors, find and replace, and autocomplete:

• Autocomplete suggests SQL keywords, Athena functions and types, the time macros, the databases you may browse, the tables of the default database, and the columns of the tables in your statement. Type database. to see its tables, and table. or an alias followed by . to see its columns. Partition columns are marked partition.
• Errors: when Athena reports a line and column, the editor underlines the place.
• Variables that aren't defined are underlined with a warning; they are sent as typed (see Variables).
• Format (or Shift+Alt+F) lays out the selection, or the whole SQL, with upper-case keywords.

#Keyboard shortcuts

On a Mac, use ⌘ where the table says Ctrl (except Ctrl+Space) and Option for Alt.

#One statement at a time

A tab can hold many statements, separated by ;. Ctrl+Enter runs only the selection or the statement under the cursor. If what you run contains more than one statement, SQLark refuses it with "Run one statement at a time." A single trailing ; is fine.

SQLark looks at the first keyword of the statement (after comments and brackets):

• Read statements: SELECT, WITH, VALUES, TABLE, SHOW, DESCRIBE, DESC, EXPLAIN and USE. They need query.
• Write statements: everything else, including CREATE, CREATE TABLE AS, INSERT, UPDATE, DELETE, MERGE, ALTER, DROP, MSCK, UNLOAD, OPTIMIZE, VACUUM, PREPARE, EXECUTE, DEALLOCATE, and EXPLAIN ANALYZE of a write statement. They need ddl on the workgroup and the datasource's database, a connection with the Full access level, and the Team plan or above. Write statements are recorded in the audit log.

AWS enforces this too: a query session for someone without ddl has no permission to change the Glue Data Catalog and can write only to the workgroup's result location.

#Running a query

Choose Run or press Ctrl+Enter. The query runs in Athena; the status shows Queued, Running, then Succeeded, Failed or Cancelled. You can keep working in other tabs, or close the browser: the query keeps running, and you find it in History.

When the query ends, the status bar shows:

A failed query shows Athena's error message; when it names a position, the editor underlines it.

Cancel stops a running query. Athena still bills a cancelled query for the data it had scanned.

#Estimated cost

The estimate follows Athena's pricing: the data scanned, rounded up to the next megabyte with a minimum of 10 MB, multiplied by the price per terabyte your administrator set ($5 per TB by default, Athena's list price in most Regions). For example, a query that scans 3.2 GB costs about $0.016, and a query that scans 4 KB is billed as 10 MB, about $0.00005. Athena doesn't charge for failed queries or for statements such as CREATE EXTERNAL TABLE and ALTER TABLE ADD PARTITION. Your AWS bill is the record.

#Reuse results

With Reuse results on, running the same SQL on the same datasource again within the reuse age (60 minutes by default; your administrator sets it) costs nothing:

1. If you ran exactly that SQL on that datasource within the reuse age, and it is still running or succeeded, SQLark shows that run again and starts nothing. This only ever returns your own runs, so nobody sees results they couldn't have produced themselves.
2. Otherwise SQLark starts a new query and asks Athena to reuse a recent result of the same query in that workgroup, if it has one. Athena checks your permissions on the tables again and charges nothing for a reused result. Athena can't reuse results in workgroups with results managed by Athena, for Lake Formation governed tables or tables with row and column filters, for queries on more than 20 tables, or for queries with non-deterministic functions; then the query simply runs.

Turn Reuse results off to make Athena read the data again, for example right after new data arrived.

#Results

The grid shows the columns with their Athena types, and NULL for missing values. Results can be very large, so the browser holds one page at a time:

• Pages. Choose 100, 500, 1,000 (the default) or 5,000 rows per page. The pager shows "Page N of M" and "Rows X to Y of Z" (the total comes from Athena's statistics), with first, previous, next and last, and Go to page. Pages you have seen open instantly; jumping far ahead reads through the result with a progress bar you can cancel.
• Search and filters. The search box highlights matches on the page. Each column has a filter for its type: text (contains, equals, starts with, regular expression, empty), numbers (equal, greater or less than, between), times (before, after, between) and booleans. Active filters show as chips. Columns hides and shows columns. Search, sorting and filters apply to the page on screen; Apply to the whole result in Athena runs the query again with them as WHERE and ORDER BY, after showing the SQL and the estimated extra scan.
• Right-click a cell (or Shift+F10 on the focused cell) to copy the value or the row, to filter the page to that value or exclude it, or to Add to WHERE clause with =, <>, >, <, IS NULL or IS NOT NULL. Select several cells of a column (Ctrl or Shift) to add IN (...). The condition goes into the statement in the editor (one undo step); when the column is an alias or an expression, the statement is wrapped as SELECT * FROM (...) AS q WHERE ... instead.
• Right-click a column header to sort, filter or hide it, or to Order by or Group by it in Athena (SELECT col, count(*) AS rows FROM (...) q GROUP BY 1 ORDER BY 2 DESC).

Choose a visualisation to chart the result.

With download:

• Download CSV downloads the complete result file Athena wrote, however large, through a link that is valid for at most 15 minutes. The file is named sqlark-<date>-<time>-<first characters of the query id>.csv. You can download the results of your own queries only, and every download is recorded in the audit log. In a workgroup whose results are managed by Athena there is no file to download: SQLark says "Results of this workgroup are managed by Athena: export them from the results grid."
• Export saves the page on screen as CSV, TSV, JSON or Markdown, or copies it to the clipboard.

Results can be opened again later, from History, as long as Athena still has them: the SQLark workgroup keeps result files for 30 days by default, and workgroups with results managed by Athena keep them for 24 hours.

#Schema browser

The left side of the workspace lists the databases you may browse in the chosen connection and Region, and under each database its tables and views with their columns:

• Each table shows its type (table, view, Iceberg), its data format (Parquet, ORC, JSON, CSV, Avro, Iceberg) and its columns with their types and comments. Partition columns are listed separately and marked as partitions.
• Choose a table for its details: the S3 location, the SerDe and its parameters, input and output formats, compression, the table properties, the SQL of a view, the number of partitions (the first 1,000 are counted) and the first 50 partitions with their values and locations.
• Insert a database, table or column name into the editor at the cursor from its menu.
• Type in the filter box to find a table or column.

The catalogue is shared by everyone in your organisation and cached for 5 minutes, so it opens quickly even for large catalogues. Refresh reads it from AWS again (if the cached copy is more than 30 seconds old). A database with more than 2,000 tables shows the first 2,000, and says so.

#History

History lists the queries you ran through SQLark, newest first, from the workspace, saved queries, dashboards and variables. Filter by Source (Editor, Saved query, Dashboard, Variable) and Status. Each entry shows the SQL (long statements are shortened in the list), the datasource, the status, the time, the data scanned, the duration, the estimated cost and who ran it.

Open an entry to see the full SQL, its statistics and, while Athena still keeps them, its results; or open it in a new workspace tab to run it again.

History is kept for your plan's history days: 30 on Starter, 90 on Team, 365 on Business and 730 on Enterprise, across every workgroup, Region and account. The Athena console keeps 45 days per workgroup and doesn't say who ran a query. History covers queries started through SQLark only, not those from the Athena console or other tools.

Administrators also see Everyone: every query run through SQLark on a chosen day (UTC), by everyone.

#Saved queries

Save a query from the workspace with Save (Ctrl+S). A saved query keeps its name, a description, its datasource, its SQL, its variables and up to 10 visualisations.

Saved queries lists Mine and Shared, newest change first.

• Folders and tags. Put a query in a folder (a path such as finance/monthly) and give it up to 20 tags, then filter the list by folder, tag or name.
• Private or shared. A private query is visible to you and administrators. A shared query (Team and above) is visible to everyone signed in. Sharing a query shares its SQL, never your permissions or your results: whoever runs it needs their own grants on its workgroup and database. Only the owner or an administrator can change or delete it; others can Save as a copy of their own.
• Last run. Each saved query shows its last run: status, time, data scanned, duration and who ran it.
• Versions. Every save keeps the previous content as a version: the latest 5 on Starter, 25 on Team, 50 on Business and 100 on Enterprise. Versions lists them with who saved them and when; Compare shows the differences with the current SQL, and Restore saves an old version as the newest one.
• Conflicts. If someone else saved the query after you opened it, your save is refused rather than overwriting their change. Reload the query and apply your change again, or Save as a copy.

Your plan sets how many saved queries each person may own: 50 on Starter, 500 on Team, 2,000 on Business and unlimited on Enterprise.

#Visualisations

Choose a visualisation above the results to chart them. A saved query can keep up to 10 visualisations of its result, and each dashboard panel has one.

SQLark picks sensible columns from the result: the first time or category column for the x axis and the numeric columns as values. Change them under Fields: the x axis, the value columns, and Group by, which turns long data (time, key, value) into one series per key. When no value columns are ticked, a time series draws the numbers on the same scale as the largest one and says which it left out, so a count of items is never a flat line under revenue in dollars. A chart keeps the 8 largest series and folds the rest into "Other", and automatic grouping never uses an id-like column with more than 50 different values.

#Charts of large results

A chart is not limited to the page of rows on screen:

• Loaded rows: when the result has up to 50,000 rows, SQLark reads them all for the chart (with a progress bar you can cancel).
• Aggregate in Athena: for larger results, the chart runs an aggregation over your statement, for example the sum of amount_usd per day, so it shows all of the data in about 1,000 points. Choose the aggregate per value (sum, average, minimum, maximum, count). The chart SQL, the estimated extra scan and the reuse setting are shown; each window's result is kept in memory.

Time charts show their time window: drag across the chart to zoom in, use Earlier, Later, Zoom in, Zoom out and Reset (or the arrow keys, +, - and 0), or drag the window on the overview strip above the chart. With Aggregate in Athena, moving the window runs the aggregation again for that window with finer buckets. If your statement uses a time macro such as $__timeFilter, moving the window runs your statement again for the new range, which with a partition filter reads only that range.

Options every chart shares:

• Unit (number, short such as 1.2K, count, bytes, percent from 0 to 100 or from 0.0 to 1.0, milliseconds, seconds, US dollars) and decimals.
• Min and max for the axis or gauge, empty to follow the data.
• Thresholds: a base colour and steps (for example red from 80), used by stat, gauge and table cells and optionally drawn on time series.
• Colour: by palette, by thresholds or one colour; you can fix the colour of a series by its name so it doesn't change between charts.
• Legend: shown or hidden, below or to the right, with optional last, minimum, maximum, mean and total values. Click a series in the legend to show only it; Ctrl or ⌘ click to add or remove one.
• Tooltip: all series at the pointer, the nearest one only, or none.

Options per type:

#Dashboards

Dashboards lists Mine and Shared. A dashboard is a grid of panels with variables and a time range.

• Panels. Choose Add panel, write SQL for it (or pick a saved query: the panel then always runs that query's current SQL and datasource) and choose a visualisation. Drag panels to move them and drag a corner to resize them on the 24-column grid. A dashboard has at most 60 panels.
• Rows group panels under a heading that can be collapsed.
• Text panels show Markdown, for headings, notes and links.
• Repeat. A panel can repeat for each selected value of a variable: one copy per value, with the variable set to that value in each copy.
• Time range. The time picker at the top sets the range for every panel that uses a time macro. Choose a quick range or type one: now-6h to now is the last six hours, and /d rounds down to the start of the day, so now-7d/d to now is the last seven days starting at midnight. Absolute dates and times work too.
• Auto-refresh runs the panels again every 10 s, 30 s, 1 m, 5 m, 15 m, 30 m, 1 h, 2 h or 1 d, but not faster than your plan allows: every 5 minutes on Starter, 1 minute on Team, 30 seconds on Business and 10 seconds on Enterprise. Auto-refresh pauses while the browser tab is hidden.
• Kiosk mode shows the dashboard full screen without menus, for a wall display. Press Esc to leave it.
• JSON. Export downloads the dashboard as JSON; Import creates a dashboard from such a file, for example to copy one between installations.
• Versions work as for saved queries: compare, restore, and the same number kept per plan.
• Private or shared as for saved queries (shared on Team and above). Your plan sets how many dashboards each person may own: 5 on Starter, 50 on Team, 500 on Business and unlimited on Enterprise.

Every panel runs with the permissions of the person viewing the dashboard. A shared dashboard shows each viewer only what their own grants allow; a panel on a database they can't query shows an error instead of data.

#How panels run

The browser runs at most 4 panels at once, so a large dashboard doesn't use up your account's Athena capacity. If Athena says too many queries are running, SQLark waits and tries again on its own.

Panels reuse results like the editor's Reuse results option, for the reuse age your administrator set unless the panel sets its own. Opening or refreshing a dashboard whose SQL hasn't changed within that time costs nothing. A panel whose SQL doesn't depend on the time range therefore shows the same result until the reuse age has passed; set the panel's reuse to 0 if it must read new data on every refresh. Panels that use time macros get new SQL whenever the range moves.

Each panel reads up to 10,000 rows by default (up to 50,000 if you raise it).

#Variables

Variables make a query or dashboard interactive: a dropdown or text box above the editor or the dashboard, whose value is put into the SQL before it runs. A saved query or dashboard has at most 20 variables.

• Multi-value lets the viewer pick several values; Include All adds an All option. With Custom all value set, All puts that value into the SQL instead of the list of every value.
• A query variable can refresh on load or when the time range changes, so it can use time macros itself.
• Hide hides the label, or the whole control.
• Names start with a letter or _ and contain letters, digits and _.

Reference a variable as $name or ${name}. For a single value, the value goes in as it is, so put quotes around it yourself: WHERE status = '$status'. For several values, or All, it becomes a quoted list, so use IN: WHERE region IN ($region). Add a format to choose how values are written:

Variables are filled in by your browser before the query is sent, and the query then runs with your own permissions, exactly as if you had typed the values. A variable never grants access to anything. A variable that isn't defined is left as typed (and underlined in the editor).

#Macros

Macros put the dashboard's time range into your SQL, so a panel reads only the data it needs. They work in the workspace too, where a time picker appears as soon as the SQL uses one. All times are in UTC.

The examples assume the range 7 October 2026 00:00 to 14 October 2026 09:30 UTC, except the interval macros, which assume the last 24 hours.

A typical time series panel on a table partitioned by a dt string such as 2026/10/14:

SELECT $__timeGroup(event_time, '$__interval') AS time,
       status,
       count(*) AS requests
FROM web_logs
WHERE $__partitionFilter(dt, 'yyyy/MM/dd')
  AND $__timeFilter(event_time)
  AND region IN ($region)
GROUP BY 1, 2
ORDER BY 1

The partition filter lets Athena skip every partition outside the range, which is what keeps the scan (and the cost) small; the time filter then trims the edges.

#Snapshots

Team and above. A snapshot is a frozen copy of a result, or of a whole dashboard with the results of its panels, that you can send as a link. Use it to share what you found with someone who can't run the query themselves.

A snapshot is readable by everyone signed in to SQLark, whether or not they have grants on its data. Creating one shares that data with your whole organisation, and SQLark asks you to confirm before it does.

• From a result: choose Snapshot under a successful read query of your own. You need download on its workgroup and database.
• From a dashboard: choose Snapshot on the dashboard. It copies the dashboard as it is now, with its time range and variable values, and the results of every panel. Each panel's result must come from your own successful run, with download on it.
• Give it a title, an optional description and how many days it should last (up to the maximum your administrator set, 30 days by default). It expires on its own after that and is then gone.
• SQLark copies the rows itself, from Athena: up to 10,000 rows in total on Team, 50,000 on Business and 100,000 on Enterprise.

Snapshots lists the snapshots you created, with their expiry; open one to copy its link, or Delete it at any time. Administrators can see and delete everyone's. Every snapshot created or deleted is recorded in the audit log. Viewers still need to sign in, and your organisation's IP allowlist applies to them.

#When something is refused