Query Restrictions

This page explains the restrictions, resource limits, and permissions for analytics queries.

Workspace Isolation

Every query is automatically scoped to your workspace. You can only access your own verification data - it’s impossible to view data from other workspaces.

Only SELECT Allowed

Only SELECT queries are permitted. All other SQL statement types return a query_not_supported error. Allowed query patterns:

SELECT statements
WITH (Common Table Expressions)
UNION
Subqueries
Joins
Aggregations
Window functions

Not allowed: INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, GRANT, REVOKE

Table Access Control

Only explicitly allowed analytics tables are accessible. Any attempt to access tables not on the allow list (including system.* or information_schema.*) will return an invalid_table error.

Function Allow List

Only explicitly approved functions are allowed. Any function not on this list will be rejected with an invalid_function error.

Allowed Functions

Aggregates

count, sum, avg, min, max, any, groupArray, groupUniqArray, uniq, uniqExact, quantile, countIf

Date/Time

now, now64, today, toDate, toDateTime, toDateTime64, toStartOfDay, toStartOfWeek, toStartOfMonth, toStartOfYear, toStartOfHour, toStartOfMinute, date_trunc, formatDateTime, fromUnixTimestamp64Milli, toUnixTimestamp64Milli, toIntervalDay, toIntervalWeek, toIntervalMonth, toIntervalYear, toIntervalHour, toIntervalMinute, toIntervalSecond

String

lower, upper, substring, concat, length, trim, startsWith, endsWith

Math

round, floor, ceil, abs

Conditional

if, case, coalesce

Type Conversion

toString, toInt32, toInt64, toFloat64

Array

has, hasAny, hasAll, arrayJoin, arrayFilter, length

If you need a function that’s not listed, please contact us at support@unkey.dev and we’ll review it for inclusion.

Resource Limits

To ensure fair usage and prevent abuse, queries are subject to resource limits:

Execution Limits

Resource	Limit	Purpose
Max execution time	30 seconds	Prevent long-running queries
Max execution time (per window)	1800 seconds (30 min)	Total execution time per hour
Max memory usage	1 GB	Prevent memory exhaustion
Max rows to read	10 million	Limit data scanned
Max result rows	10 million	Limit result set size

Query Quotas

Quota	Limit	Window
Queries per workspace	1000	Per hour

If you need higher limits for your use case, please contact us at support@unkey.dev.

Error Codes

When limits are exceeded, you’ll receive specific error codes:

Error Code	Description	Solution
`query_execution_timeout`	Query took longer than 30 seconds	Add more filters, reduce time range, use aggregated tables
`query_memory_limit_exceeded`	Query used more than 1GB memory	Reduce result set size, add LIMIT clause, use aggregation
`query_rows_limit_exceeded`	Query scanned more than 10M rows	Add time filters, use aggregated tables (hour/day/month)
`query_quota_exceeded`	Exceeded 1000 queries per hour	Wait for quota to reset, optimize query frequency

Authentication

Analytics queries require a root key with specific permissions:

Required Permissions

You need to grant analytics access for per API or for all APIs: Workspace-level access (all APIs):

api.*.read_analytics

Per-API access (specific API):

api.<api_id>.read_analytics

Choose workspace-level for broad access or per-API for fine-grained control.

Root Key Best Practices

Use environment variables - Never hardcode root keys
Rotate keys regularly - Create new keys and revoke old ones
Limit permissions - Only grant read_analytics permission
Use separate keys - Different keys for different services
Monitor usage - Track which keys are making queries

See Getting Started for step-by-step instructions on creating an analytics root key.

Next Steps

Getting Started

Create a root key and run your first query

Query Examples

Explore common query patterns

Schema Reference

Browse available tables and columns

Error Codes

View all error codes and responses

Unkey

Concepts

Features

Migrations

Errors

Query Restrictions

Workspace Isolation