Insert data
Inserts one row (or server-normalized payload) into the target table selected by `X-Athena-Client` or a direct PostgreSQL URI header (`x-pg-uri` preferred). The optional `X-Athena-Insert-Window` header can enable request-scoped batching for Postgres-backed inserts. Conflict responses (409) are typically raised for unique/constraint violations. Direct URI requests are executed inline (gateway deferred queue bypassed).
Header Parameters
Optional Postgres insert batching window in milliseconds (1–60000).
When non-zero, enables or overrides gateway.insert_execution_window_ms for this request.
The handler blocks until the window elapses and the row is flushed; under load, connection
hold time can increase by up to this value. Ignored when X-Athena-Deadpool-Enable requests
deadpool, when update_body is present, or for non-Postgres clients.
1 <= value <= 60000Registered Athena client name. Optional when direct PostgreSQL URI headers are provided.
Preferred direct PostgreSQL URI (postgres://... or jdbc:postgresql://...).
Compatibility direct PostgreSQL URI header.
Compatibility direct PostgreSQL URI header.
Request Body
application/json
Optional schema override for PostgreSQL-backed insert execution.
Response Body
application/json
curl -X PUT "https://athena-cluster.com/gateway/insert" \ -H "X-Company-Id: string" \ -H "X-Organization-Id: string" \ -H "Content-Type: application/json" \ -d '{ "table_name": "app_events", "insert_body": { "event_type": "user_login", "user_id": "u_123", "source": "dashboard" } }'{
"status": "success",
"message": "Row inserted",
"data": {
"table_name": "app_events"
}
}Fetch data POST
Fetches rows from a table or view using structured conditions, optional pagination, sort instructions, and optional post-processing (`group_by`, `time_granularity`, aggregation options). Notes: - Route selection supports `X-Athena-Client` or direct PostgreSQL URI headers (`x-pg-uri` preferred). - Direct URI auth bypass is allowed when URI credentials include both username and password. - Direct URI requests always execute inline (deferred gateway queue is skipped). - Optional `schema_name` targets a non-default schema. When provided, `table_name` must not already be schema-qualified. - PostgreSQL-backed fetch execution accepts canonical nested `select` payloads and compatibility `select` strings. - Schema-qualified base tables such as `public.chat_subscriptions` are supported. - Relation-side schema qualification such as `users:athena.users(id,username,image)` is supported. - Legacy `columns` + `conditions` payloads remain supported and are still the right shape for wildcard/simple fetches and non-PostgreSQL gateway fetch backends. - Structured fetch auth checks apply to every referenced table in the nested tree when API-key enforcement is enabled. - Relation joins resolve from foreign-key metadata first; ambiguous edges should provide `foreign_key`. - Unsupported in this release: top-level AST request bodies (`operation` / `from` / `fields`), relation `on` shapes, and schema-qualified relation selectors combined with `via`. - `X-Strip-Nulls` can be used to remove null-valued fields from response payloads. - Cache behavior may include `X-Athena-Cached`, `X-Athena-Cache-Outcome`, and `X-Athena-Cache-Source` headers.
Execute SQL POST
Executes raw SQL against the Athena client selected by `X-Athena-Client`. PostgreSQL clients may also be targeted with a direct PostgreSQL URI header (`x-pg-uri` preferred). This route is intended for advanced workflows where structured gateway payloads are insufficient. Use carefully with parameterized SQL on the caller side when constructing dynamic queries. Direct URI requests execute inline (deferred queue bypassed). Optional `schema_name` sets a schema-local search_path (`schema_name, public`) for PostgreSQL execution only.