Query Management

Monitor active queries in real time, review query history, and cancel long-running queries. Full visibility into your query workload for debugging and capacity planning.

Overview

Query management provides:

• Active query monitoring — See all currently running queries with their duration, SQL, and resource usage
• Query history — Review recently completed queries with execution details
• Query cancellation — Cancel long-running or runaway queries on demand
• Diagnostic details — View parallel execution status and partition counts per query

Both query endpoints are tracked: POST /api/v1/query and POST /api/v1/query/arrow (the Arrow endpoint since v26.09.2). Every tracked query returns its id in the X-Arc-Query-ID response header, which is the id the endpoints below take.

Configuration

TOML

[query_management]
enabled = true
history_size = 100           # Number of completed queries to keep in history

Environment variables

ARC_QUERY_MANAGEMENT_ENABLED=true
ARC_QUERY_MANAGEMENT_HISTORY_SIZE=100

API reference

All query management endpoints require admin authentication.

List active queries

View all currently running queries:

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/queries/active

Response:

{
  "success": true,
  "data": [
    {
      "id": "q-abc123",
      "sql": "SELECT * FROM production.sensors WHERE timestamp > NOW() - INTERVAL '1 hour'",
      "status": "running",
      "token_name": "grafana-readonly",
      "remote_addr": "10.0.1.50:54321",
      "started_at": "2026-02-13T10:30:00Z",
      "duration_ms": 2500,
      "is_parallel": true,
      "partition_count": 4
    },
    {
      "id": "q-def456",
      "sql": "SELECT COUNT(*) FROM analytics.events GROUP BY event_type",
      "status": "running",
      "token_name": "dashboard-token",
      "remote_addr": "10.0.1.51:54322",
      "started_at": "2026-02-13T10:30:01Z",
      "duration_ms": 1200,
      "is_parallel": false,
      "partition_count": 1
    }
  ]
}

View query history

Review recently completed queries:

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/queries/history

Response:

{
  "success": true,
  "data": [
    {
      "id": "q-ghi789",
      "sql": "SELECT AVG(temperature) FROM production.sensors GROUP BY device_id",
      "status": "completed",
      "token_name": "analytics-token",
      "remote_addr": "10.0.1.52:54323",
      "started_at": "2026-02-13T10:29:00Z",
      "duration_ms": 850,
      "is_parallel": true,
      "partition_count": 3
    }
  ]
}

Get query details

Inspect a specific query by ID:

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/queries/q-abc123

Cancel a query

Stop a long-running or runaway query. The id comes from the X-Arc-Query-ID response header of the query, or from the active list above:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/queries/q-abc123

Response:

{
  "success": true,
  "data": {
    "message": "Query cancelled",
    "id": "q-abc123"
  }
}

The cancelled request itself ends with an error. On POST /api/v1/query/arrow a cancel that lands while DuckDB is still executing returns 500 with Query cancelled and no Arrow body, because the Arrow result is materialized before streaming starts; a cancel during the streaming phase ends the stream early with the Arc-Stream-Truncated trailer. Either way the query is recorded as cancelled in history.

Use cases

Debugging slow queries

1. Check active queries to find long-running operations
2. Review the SQL and execution details
3. Cancel if the query is consuming excessive resources
4. Optimize the query and retry

# Find queries running longer than expected
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/queries/active

# Cancel a specific runaway query
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/queries/q-abc123

Capacity planning

Review query history to understand workload patterns:

• Which tokens generate the most queries?
• What are typical query durations?
• How many queries run in parallel?
• Are queries hitting multiple partitions (indicating large time ranges)?

Incident response

During performance incidents:

1. List active queries to identify the cause
2. Cancel offending queries immediately
3. Review history to understand what changed
4. Apply query governance policies to prevent recurrence

Best practices

1. Set an appropriate history size — The default (100) works for most deployments. Increase it if you need more historical context for debugging.

2. Monitor active queries in dashboards — Poll the active queries endpoint from your monitoring system to detect long-running queries early.

3. Combine with query governance — Use governance policies to prevent runaway queries automatically, and query management for visibility and manual intervention.

4. Review parallel query patterns — Queries with high partition counts span large time ranges. Consider adding time bounds to improve performance.

Next steps

• Query Governance — Automatically enforce rate limits and quotas
• Audit Logging — Track query patterns for compliance