SQL Logs API Workflows

Use this page when you need live SQL visibility for stream execution, Data Explorer, SQL Console, file queries, or federated queries.

The current backend sends SQL logs over GET /api/v1/logs/stream, and uses GET or PUT /api/v1/system/sql-logging for capture-mode control. Use SQL logs to debug performance issues, validate generated queries, and understand how the system interacts with your data sources. For stream status, persisted stream logs, and run history, see Logs And Monitoring API Workflows.

Route model

SQL logs currently use these routes:

GET /api/v1/logs/stream for live SQL log delivery over SSE
GET /api/v1/system/sql-logging to read the current SQL capture mode
PUT /api/v1/system/sql-logging to change the current SQL capture mode

Authentication:

/logs/stream is currently exposed as a public SSE route
/system/sql-logging uses the IDE auth path
for API usage outside desktop localhost mode, send X-API-Key and X-Install-ID
in desktop mode on localhost, IDE routes can also work without an API key

Read live SQL logs

Use the shared SSE stream when you need immediate visibility into SQL generated by stream workers, Data Explorer, SQL Console, file queries, or federated queries.

The live stream distinguishes payload families with SSE event names:

Event name	Purpose
`sql`	SQL log payloads
`log`	Structured monitoring logs on the same stream

Example:

curl -N "$API_URL/logs/stream"

Example SQL log payload:

event: sql
data: {"id":"sql_123","connectionId":"conn_postgres_prod","database":"postgres","schema":"public","tableName":"actor","query":"SELECT * FROM public.actor LIMIT 100","purpose":"DATA_QUERY","startedAt":"2026-03-20T09:41:31.000Z","durationMs":18,"rowCount":100}

SQL log fields

Field	Type	Description
`id`	string	Unique log entry identifier
`connectionId`	string	Connection that produced the query
`tabId`	string	UI tab context (omitted for non-UI queries)
`database`	string	Database name
`schema`	string	Schema name (omitted when not applicable)
`tableName`	string	Table being queried (omitted when not applicable)
`query`	string	SQL text (truncated to 100 KB)
`params`	array	Query parameters (omitted when empty)
`purpose`	string	Why the query was executed (see purpose values below)
`startedAt`	string	ISO 8601 timestamp with milliseconds
`durationMs`	number	Execution time in milliseconds
`rowCount`	number	Rows returned or affected
`error`	string	Error message (present only on failure)
`redacted`	boolean	Privacy flag (present only when query was redacted)

Verification:

confirm SQL payloads arrive as event: sql SSE frames
confirm fields such as connectionId, query, purpose, startedAt, durationMs, and rowCount are present
trigger one known stream, explorer, or console action and verify the expected purpose appears

What currently emits SQL logs

Current backend coverage includes:

stream reader or writer SQL operations, especially SCHEMA_CHANGE and DML_OPERATION
database metadata loading and object inspection as SCHEMA_INTROSPECTION
table or view preview reads as DATA_QUERY
exact row counts as COUNT_QUERY
SQL Console statements classified from the SQL itself, including DATA_QUERY, COUNT_QUERY, SCHEMA_CHANGE, and DML_OPERATION
database row inserts, updates, and deletes as DML_OPERATION
file metadata, file preview, file count, file console, and federated console queries as live SQL log events

Current gaps:

/files/summary does not currently emit a separate SQL log event
/files/csv/sniff does not currently emit a separate SQL log event
GET /api/v1/streams/{id}/logs is a persisted stream-run log route, not a live SQL log feed

Purpose values you will see

SQL purpose values in the current backend:

Purpose	Description
`SCHEMA_INTROSPECTION`	Metadata discovery and object inspection
`DATA_QUERY`	Preview reads, filtered reads, and general `SELECT`
`COUNT_QUERY`	Exact row count requests
`SCHEMA_CHANGE`	DDL such as `CREATE`, `ALTER`, or `DROP`
`DML_OPERATION`	Inserts, updates, and deletes
`PLAN_ANALYSIS`	`EXPLAIN` / query plan inspection
`UTILITY`	Connectivity probes, health checks, and unclassified queries

These values are classified from the executed SQL or set explicitly by the backend for stream, explorer, and file operations.

Read the current SQL capture mode

Use GET /api/v1/system/sql-logging when you need to know how much SQL logging the backend is currently emitting.

Example:

curl "$API_URL/system/sql-logging" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Install-ID: $INSTALL_ID"

Example response:

{
  "sqlCaptureMode": "minimal",
  "forwardSQLLogs": true
}

Change the SQL capture mode

Use PUT /api/v1/system/sql-logging when you need to reduce noise or turn on broader SQL visibility.

Example:

curl -X PUT "$API_URL/system/sql-logging" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Install-ID: $INSTALL_ID" \
  -H "Content-Type: application/json" \
  -d '{"sqlCaptureMode":"verbose"}'

Current mode behavior from backend source:

off disables SQL log emission
minimal keeps SQL errors plus SCHEMA_CHANGE and DML_OPERATION
verbose emits all SQL purposes for both stream SQL and IDE SQL activity

forwardSQLLogs is derived automatically from the selected mode.

Verification:

call GET /system/sql-logging before and after the update
in minimal, confirm ordinary preview DATA_QUERY events stop appearing while SQL errors still appear
in verbose, confirm preview and metadata events appear again on /logs/stream

API vs UI

Use the UI Logs view for interactive inspection during stream runs, Data Explorer work, and SQL Console work.

Use the API when you need to stream SQL activity into external tooling, confirm which backend queries a workflow generates during either streaming or interactive work, or change runtime SQL logging behavior programmatically.