--- title: "Execute a batch query" method: POST path: "/query" tags: ["odf-query"] --- # Execute a batch query `POST /query` ### Regular Queries This endpoint lets you execute arbitrary SQL that can access multiple datasets at once. Example request body: ```json { "query": "select event_time, from, to, close from \"kamu/eth-to-usd\"", "limit": 3, "queryDialect": "SqlDataFusion", "dataFormat": "JsonAoA", "schemaFormat": "ArrowJson" } ``` Example response: ```json { "output": { "data": [ ["2024-09-02T21:50:00Z", "eth", "usd", 2537.07], ["2024-09-02T21:51:00Z", "eth", "usd", 2541.37], ["2024-09-02T21:52:00Z", "eth", "usd", 2542.66] ], "dataFormat": "JsonAoA", "schema": {"fields": ["..."]}, "schemaFormat": "ArrowJson" } } ``` ### Verifiable Queries [Cryptographic proofs](https://docs.kamu.dev/node/commitments) can be also requested to hold the node **forever accountable** for the provided result. Example request body: ```json { "query": "select event_time, from, to, close from \"kamu/eth-to-usd\"", "limit": 3, "queryDialect": "SqlDataFusion", "dataFormat": "JsonAoA", "schemaFormat": "ArrowJson", "include": ["proof"] } ``` Currently, we support verifiability by ensuring that queries are deterministic and fully reproducible and signing the original response with Node's private key. In future more types of proofs will be supported. Example response: ```json { "input": { "query": "select event_time, from, to, close from \"kamu/eth-to-usd\"", "queryDialect": "SqlDataFusion", "dataFormat": "JsonAoA", "include": ["Input", "Proof", "Schema"], "schemaFormat": "ArrowJson", "datasets": [{ "id": "did:odf:fed0119d20360650afd3d412c6b11529778b784c697559c0107d37ee5da61465726c4", "alias": "kamu/eth-to-usd", "blockHash": "f1620708557a44c88d23c83f2b915abc10a41cc38d2a278e851e5dc6bb02b7e1f9a1a" }], "skip": 0, "limit": 3 }, "output": { "data": [ ["2024-09-02T21:50:00Z", "eth", "usd", 2537.07], ["2024-09-02T21:51:00Z", "eth", "usd", 2541.37], ["2024-09-02T21:52:00Z", "eth", "usd", 2542.66] ], "dataFormat": "JsonAoA", "schema": {"fields": ["..."]}, "schemaFormat": "ArrowJson" }, "subQueries": [], "commitment": { "inputHash": "f1620e23f7d8cdde7504eadb86f3cdf34b3b1a7d71f10fe5b54b528dd803387422efc", "outputHash": "f1620e91f4d3fa26bc4ca0c49d681c8b630550239b64d3cbcfd7c6c2d6ff45998b088", "subQueriesHash": "f1620ca4510738395af1429224dd785675309c344b2b549632e20275c69b15ed1d210" }, "proof": { "type": "Ed25519Signature2020", "verificationMethod": "did:key:z6MkkhJQPHpA41mTPLFgBeygnjeeADUSwuGDoF9pbGQsfwZp", "proofValue": "uJfY3_g03WbmqlQG8TL-WUxKYU8ZoJaP14MzOzbnJedNiu7jpoKnCTNnDI3TYuaXv89vKlirlGs-5AN06mBseCg" } } ``` A client that gets a proof in response should perform [a few basic steps](https://docs.kamu.dev/node/commitments#response-validation) to validate the proof integrity. For example making sure that the DID in `proof.verificationMethod` actually corresponds to the node you're querying data from and that the signature in `proof.proofValue` is actually valid. Only after this you can use this proof to hold the node accountable for the result. A proof can be stored long-term and then disputed at a later point using your own node or a 3rd party node you can trust via the [`/verify`](#tag/odf-query/POST/verify) endpoint. See [commitments documentation](https://docs.kamu.dev/node/commitments) for details. ## Request body - QueryRequest - `dataFormat` 'JsonAoS' | 'JsonSoA' | 'JsonAoA' - `datasets` DatasetState[], nullable — Optional information used to affix an alias to the specific [`odf::DatasetID`] and reproduce the query at a specific state in time - `alias` string, required — Alias to be used in the query - `blockHash` string - `id` string, required - `include` Include[] — What information to include - `limit` integer — Pagination: limits number of records in response to N - `query` string, required — Query string - `queryDialect` 'SqlDataFusion' | 'SqlFlink' | 'SqlRisingWave' | 'SqlSpark' - `schemaFormat` 'ArrowJson' | 'OdfJson' | 'OdfYaml' | 'Parquet' | 'ParquetJson' - `skip` integer — Pagination: skips first N records ## Response `200` - QueryResponse - `commitment` Commitment - `inputHash` string, required - `outputHash` string, required - `subQueriesHash` string, required - `input` QueryRequest - `dataFormat` 'JsonAoS' | 'JsonSoA' | 'JsonAoA' - `datasets` DatasetState[], nullable — Optional information used to affix an alias to the specific [`odf::DatasetID`] and reproduce the query at a specific state in time - `alias` string, required — Alias to be used in the query - `blockHash` string - `id` string, required - `include` Include[] — What information to include - `limit` integer — Pagination: limits number of records in response to N - `query` string, required — Query string - `queryDialect` 'SqlDataFusion' | 'SqlFlink' | 'SqlRisingWave' | 'SqlSpark' - `schemaFormat` 'ArrowJson' | 'OdfJson' | 'OdfYaml' | 'Parquet' | 'ParquetJson' - `skip` integer — Pagination: skips first N records - `output` Outputs, required - `data` unknown, required - `dataFormat` 'JsonAoS' | 'JsonSoA' | 'JsonAoA', required - `schema` Schema - `schemaFormat` 'ArrowJson' | 'OdfJson' | 'OdfYaml' | 'Parquet' | 'ParquetJson' - `proof` Proof - `proofValue` string, required - `type` 'Ed25519Signature2020', required - `verificationMethod` string, required - `subQueries` SubQuery[], nullable — Information about processing performed by other nodes as part of this operation - `commitment` Commitment, required - `inputHash` string, required - `outputHash` string, required - `subQueriesHash` string, required - `input` QueryRequest, required - `dataFormat` 'JsonAoS' | 'JsonSoA' | 'JsonAoA' - `datasets` DatasetState[], nullable — Optional information used to affix an alias to the specific [`odf::DatasetID`] and reproduce the query at a specific state in time - `alias` string, required — Alias to be used in the query - `blockHash` string - `id` string, required - `include` Include[] — What information to include - `limit` integer — Pagination: limits number of records in response to N - `query` string, required — Query string - `queryDialect` 'SqlDataFusion' | 'SqlFlink' | 'SqlRisingWave' | 'SqlSpark' - `schemaFormat` 'ArrowJson' | 'OdfJson' | 'OdfYaml' | 'Parquet' | 'ParquetJson' - `skip` integer — Pagination: skips first N records - `proof` Proof, required - `proofValue` string, required - `type` 'Ed25519Signature2020', required - `verificationMethod` string, required - `subQueries` object, required — Information about processing performed by other nodes as part of this operation ## Changes - **2025-08-03** `411fe35264fd` — 6 warning, 2 info - added the new `OdfJson` enum value to the `input/schemaFormat` response property for the response status `200` - added the new `OdfJson` enum value to the `output/schemaFormat` response property for the response status `200` - added the new `OdfJson` enum value to the `subQueries/items/input/schemaFormat` response property for the response status `200` - added the new `OdfYaml` enum value to the `input/schemaFormat` response property for the response status `200` - …4 more - **2025-07-29** `9aea0047e18e` — 2 breaking, 8 info - removed the enum value `OdfJson` of the request property `schemaFormat` - removed the enum value `OdfYaml` of the request property `schemaFormat` - removed the `EcdsaSecp256k1Signature2019` enum value from the `proof/type` response property for the response status `200` - removed the `EcdsaSecp256k1Signature2019` enum value from the `subQueries/items/proof/type` response property for the response status `200` - …6 more [Change history](https://skmtc.dev/kamu-data/apis/kamu-rest-api/changes/query/post.md) --- [API](https://skmtc.dev/kamu-data/apis/kamu-rest-api.md) · [All operations](https://skmtc.dev/kamu-data/apis/kamu-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kamu-data/kamu-rest-api/revisions/249ce4c8fd2f/schema)