Query History

Gnok records every query with its full execution lifecycle and performance metrics. Query history is available for debugging slow queries, cost attribution across users and workloads, compliance auditing, and capacity planning.

Query Lifecycle

Every query passes through a series of status transitions:

Status	Description
queued	Query has been received and is waiting for resources (admission control)
running	Query is actively executing across coordinator and workers
completed	Query finished successfully and returned results
failed	Query terminated with an error (parse failure, execution error, OOM, etc.)
cancelled	Query was cancelled by the user, a timeout, or the query killer

Record Schema

Each query history record contains the following fields:

Field	Type	Description
query_id	string	Unique identifier for the query
status	string	Current lifecycle status
sql	string	The SQL text that was submitted
user_id	string	Authenticated user who submitted the query
tenant_id	string	Organization the query belongs to
query_type	string	Statement type: select, insert, update, delete, ddl, etc.
resource_group	string	Resource group path the query was admitted to (e.g., /root/interactive)
priority	integer	Execution priority (higher = more important)
queued_at	timestamp	When the query was received
started_at	timestamp	When execution began (null if cancelled before running)
ended_at	timestamp	When the query reached a terminal status
duration_ms	integer	Wall-clock execution time in milliseconds
rows_produced	integer	Number of result rows returned
bytes_scanned	integer	Total bytes read from storage
fragments	integer	Number of distributed fragments executed
error_message	string	Error details (for failed queries)
cu_consumed	float	Compute units consumed (warehouse size CU rate * execution time)

Querying History

REST API

In Studio, use History. Calling the HTTP API from outside Studio isn't self-service yet; email support@gnok.io to set up client connectivity. query.example.com below is a placeholder.

List Query History

GET /api/query-history

Query parameters:

Parameter	Type	Default	Description
limit	integer	50	Maximum records to return (max 500)
offset	integer	0	Pagination offset
status	string	(all)	Filter by status: completed, failed, cancelled
user_id	string	(all)	Filter by user ID
query_type	string	(all)	Filter by query type: select, insert, etc.

Example: list recent failed queries

curl -s 'https://query.example.com/api/query-history?status=failed&limit=50' \
  -H "Authorization: Bearer $TOKEN" | jq

Response:

[
  {
    "queryId": "a1b2c3d4-...",
    "status": "failed",
    "sql": "SELECT * FROM nonexistent_table",
    "userId": "alice",
    "tenantId": "acme-corp",
    "queryType": "select",
    "resourceGroup": "/root/interactive",
    "priority": 50,
    "queuedAt": "2026-03-27T10:15:00Z",
    "startedAt": "2026-03-27T10:15:00Z",
    "endedAt": "2026-03-27T10:15:00Z",
    "durationMs": 12,
    "rowsProduced": 0,
    "bytesScanned": 0,
    "fragments": 0,
    "errorMessage": "Table 'nonexistent_table' not found in schema 'public'",
    "cuConsumed": 0.0
  }
]

Get a Specific Query

GET /api/query-history/{query_id}

curl -s 'https://query.example.com/api/query-history/a1b2c3d4-...' \
  -H "Authorization: Bearer $TOKEN" | jq

SQL Interface

Query history is also available through the SQL SHOW command:

-- List recent queries (default limit 50)
SHOW QUERY HISTORY;

-- With filters
SHOW QUERY HISTORY LIMIT 100;

Use Cases

Debugging Slow Queries

Identify the slowest queries over a time period to prioritize optimization efforts:

curl -s 'https://query.example.com/api/query-history?status=completed&limit=100' \
  -H "Authorization: Bearer $TOKEN" \
  | jq 'sort_by(-.durationMs) | .[0:10] | .[] | {queryId, sql, durationMs, bytesScanned}'

Cost Attribution

Sum compute units consumed per user for chargeback:

curl -s 'https://query.example.com/api/query-history?limit=500' \
  -H "Authorization: Bearer $TOKEN" \
  | jq 'group_by(.userId) | map({user: .[0].userId, total_cu: (map(.cuConsumed // 0) | add)})'

Audit Trail

Query history provides a record of every SQL statement executed against the system, including the authenticated user, timestamp, and result status. This supports compliance requirements for data access auditing.

Capacity Planning

Analyze query patterns over time to identify peak usage periods, resource-intensive workloads, and opportunities to right-size warehouse capacity.

Storage and Retention

History availability and retention are managed by Gnok for your account. Use Studio History to inspect available records; arrange any required exports or longer retention through your administrator and support@gnok.io.