Sign in
Onchain

Preflight Blockchain SQL Query

Validate and estimate a read-only ClickHouse query before executing it.

This endpoint runs EXPLAIN ESTIMATE and does not execute the submitted query. It returns:

  • Logical schema plus bounded physical source metadata
  • Partition, sorting, and primary-key expressions
  • Estimated parts, rows, marks, and bytes
  • The final server-bounded SQL and scan budgets
  • Machine-readable guardrail warnings with recommended actions

Use GET /v1/onchain/schema?table=<name> for metadata-only discovery. Preflight accepts the same JSON shape and SQL safety rules as POST /v1/onchain/sql, but missing pruning filters are returned as structured rejection warnings rather than running the query.

The planner rejects address columns wrapped in lower() and transfer-table predicates that combine from and to with OR. Normalize address literals before submission, compare stored lowercase columns directly, and split incoming/outgoing transfer predicates into projection-friendly UNION ALL branches. It also warns when address-hash sharding cannot prune physical data, a leading time ordering key is unbounded, maker/taker UNION branches repeat scans, large joins lack early filters or aggregation, or ANY JOIN lacks independent uniqueness proof. The planner never changes JOIN semantics automatically.

post/gateway/v1/onchain/sql/preflight

Request body

$schemastring uri

A URL to the JSON Schema for this object.

max_rowsinteger

Maximum result rows in the final server-bounded execution plan

sqlstring required

Read-only ClickHouse SELECT/WITH query to validate and estimate without executing it

Example request

{
  "$schema": "https://example.com/schemas/HumaOnchainSQLPreflightInputBody.json",
  "max_rows": 1000,
  "sql": "SELECT block_date, project, apy, tvl_usd FROM agent.ethereum_yields_daily WHERE block_date >= today() - 7 LIMIT 100"
}

Response

OK

$schemastring uri

A URL to the JSON Schema for this object.

Example response

{
  "$schema": "https://example.com/schemas/DataObjectResponseOnchainSQLPreflight.json"
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.