Bulk analytics Core API (internal)

Engineering-only HTTP surface on Core API for scripts, IDE extensions, and operators. Same trust boundary as tools/agentic-cli: cluster network access and HEAT_API_TOKEN / HEAT_API_KEY Bearer auth when enabled.

This is not published on the v2 public API.

Base path

/api/bulk-analytics

Primary handle

Bulk writer nodeInstanceId for a system-bulk-tabular-writer node. Database name: bulk_ni_{nodeInstanceId}.

Discovery

Method	Path	Description
`GET`	`/writers?sessionId={guid}`	List bulk writers in a session
`GET`	`/writers/{nodeInstanceId}`	Writer summary, database size, table count, optional ingest catalog

Inspect (no SQL body)

Method	Path	Description
`GET`	`/writers/{nodeInstanceId}/catalog`	`heatBulkWriterCatalogV1` from writer current output
`GET`	`/writers/{nodeInstanceId}/tables`	Live tables with `n_live_tup` and `pg_total_relation_size`
`GET`	`/writers/{nodeInstanceId}/tables/{tableName}`	Column metadata (`information_schema` + catalog `valueKind` when available)
`GET`	`/writers/{nodeInstanceId}/tables/{tableName}/preview?limit=100`	`SELECT * … LIMIT n` (JSON default; `Accept: text/csv` for CSV)

Query

POST /writers/{nodeInstanceId}/query


{
  "sql": "EXPLAIN ANALYZE SELECT COUNT(*) FROM \"csv_abc\"",
  "maxRows": 10000,
  "outputFormat": "auto",
  "commandTimeoutSeconds": 60
}

Field	Notes
`sql`	Required. Read-only policy below.
`maxRows`	Default 10000, max 100000
`outputFormat`	`auto`, `json`, or `csv` (single result set only for CSV)
`commandTimeoutSeconds`	Default 60, max 120

Response: JSON BulkAnalyticsTabularOutputV1 envelope (tables.result) or text/csv when outputFormat is csv/auto with one result set, or Accept: text/csv.

SQL policy (API)

Broader than the system-bulk-analytics-query runner node (which allows only SELECT / WITH):

Allowed	Examples
`SELECT`, `WITH … SELECT`	`SELECT * FROM "csv_abc" LIMIT 10`
`EXPLAIN`, `EXPLAIN ANALYZE`	Query planning
`SHOW`	`SHOW search_path`
Catalog introspection	`SELECT … FROM information_schema.columns`

Blocked
DML/DDL (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `CREATE`, `ALTER`, …)
`SET`, `RESET`, `COPY`, `CALL`, `DO`, …
Multiple statements (`;` in body)
`SELECT … INTO`

No psql backslash commands; use HTTP inspect endpoints instead.

Errors

Status	Meaning
`400`	Invalid SQL, table name, or request body
`404`	Unknown writer, missing database, missing catalog/output
`503`	Analytics Postgres or DataSource `HEAT Bulk Analytics DB` unavailable

Example flow


export CORE_API="https://core-api.example"
export TOKEN="$HEAT_API_TOKEN"
 
# List writers in a session
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$CORE_API/api/bulk-analytics/writers?sessionId=SESSION_GUID"
 
# Writer summary
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$CORE_API/api/bulk-analytics/writers/42"
 
# Tables and column describe
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$CORE_API/api/bulk-analytics/writers/42/tables"
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$CORE_API/api/bulk-analytics/writers/42/tables/csv_abc"
 
# Ad-hoc query (JSON)
curl -sS -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sql":"SELECT COUNT(*) FROM \"csv_abc\""}' \
  "$CORE_API/api/bulk-analytics/writers/42/query"
 
# CSV download
curl -sS -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Accept: text/csv" \
  -d '{"sql":"SELECT * FROM \"csv_abc\" LIMIT 100","outputFormat":"csv"}' \
  "$CORE_API/api/bulk-analytics/writers/42/query" -o preview.csv

Implementation

Validator: BulkAnalyticsApiSqlValidator (API only)
Service: BulkAnalyticsApiService
Controller: BulkAnalyticsController
Postgres: IBulkAnalyticsPostgresClient introspection and TryExecuteAdHocSqlAsync