CLI reference

Parameters keep values separate from SQL text. Put a {{name}} placeholder in the SQL and repeat --param name:type=value for each value.

SELECT *FROM pump_fun_solana.pump_fun_evt_trade_eventWHERE mint = {{mint}}  AND ts >= {{start_time}}  AND is_buy = {{is_buy}};

query sql \  --file query.sql \  --param 'mint:varchar=TokenAddress' \  --param 'start_time:timestamp=2026-08-01 00:00:00' \  --param 'is_buy:boolean=true'

Quote each argument so spaces and shell metacharacters are passed through. The value is everything after the first = and may itself contain =.

Supported types

Names must match [A-Za-z_][A-Za-z0-9_]* and are case-sensitive. varbinary takes an even-length hexadecimal value, optionally prefixed with 0x.

OnchainQueries always selects the resource class automatically from the shape of the query. There is no flag for choosing one, and automatic selection does not bypass service capacity or query limits. query sql prints the selected class next to the query ID when the query is queued, and query status reports it in the engine field.

The default --transport parquet produces .parquet parts. --transport flight produces Arrow IPC stream files with an .arrow extension.

query sql \  --file query.sql \  --transport flight \  --output ./arrow-results

Both modes write manifest.json and use the same verified download flow. The Flight manifest additionally contains a signed Flight ticket for Arrow Flight clients; ask the operator for the externally reachable Flight endpoint when using that ticket outside the CLI.

OnchainQueries assigns every submitted query an ID. Keep it if you may need to inspect, resume or cancel the query.

query status QUERY_IDquery attach QUERY_ID --output ./resultsquery cancel QUERY_ID

Query states

If query sql is interrupted after submission, the server-side query continues. attach waits for it and downloads the completed results; attaching to a failed, cancelled or expired query returns an error instead. Results expire 24 hours after submission, so attach before the reported expires_at.

query shell reads statements ending in a semicolon, using a continuation prompt until it sees one.

query> SELECT     ->   count(*)     -> FROM pump_fun_solana.pump_fun_evt_trade_event;QUERY_ID    completequery>

Enter \q on its own line to exit; end-of-file also exits. Shell mode always uses the auto engine and parquet transport, does not accept typed parameters, and does not download files — it prints the query ID and terminal state. Use query attach to download a successful shell query.

query sql

query sql --file PATH [--param NAME:TYPE=VALUE ...]           [--engine auto|small|medium|large]           [--transport parquet|flight]           [--output DIRECTORY]

query sql waits until the query reaches a terminal state. It downloads only completed results and exits nonzero on submission, execution or download errors.

Reading from standard input

printf '%s\n' 'SELECT count(*) FROM pump_fun_solana.pump_fun_evt_trade_event;' \  | query sql --file - --output ./results

• invalid API token — run query login with an active query_sk_ key.
• Connection refused, DNS or timeout errors — check that the machine can resolve and reach engine.onchainqueries.com and results.onchainqueries.com over HTTPS. The endpoints are embedded in the release binary and cannot be changed at runtime.
• query limit reached; retry later — the service is at its active-query limit. Wait and resubmit, or contact the operator.
• Parameter errors — every {{name}} needs exactly one matching --param, the type must be supported, and no supplied parameter may go unused.
• every query must bound the time range it reads — add a lower bound on ts to the SELECT that reads the table. In a CTE or subquery the bound belongs inside it, not on the outer query.
• A failed query — run query status and inspect the error field.
• An expired result — server-side results cannot be attached after expiration. Submit the SQL again; files already downloaded are not removed.
• Size or checksum mismatch — rerun query attach with the same query ID. If mismatches continue, preserve the error and contact the operator.