Skip to main content

Query

Returns the results of a SQL read query against the Tableland network.


Endpoint

The /query endpoint supports both GET and POST requests, returning the results of a SQL read query, along with options for formatting the response.

GET /query or POST /query

GET request

The following describes the GET usage with placeholder parameters on a testnet gateway URL:

curl -X GET https://testnets.tableland.network/api/v1/query?format={objects|table}&extract={boolean}&unwrap={boolean}&statement={sql_select_statement} \
-H 'Accept: application/json'

For example, to query the healthbot_80002_1 table with default formatting options:

curl -X GET https://testnets.tableland.network/api/v1/query?statement=select%20%2A%20from%20healthbot_80002_1 \
-H 'Accept: application/json'

POST request

The following describes the POST usage with example parameters on a testnet gateway URL:

curl -L 'https://testnets.tableland.network/api/v1/query' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"statement": "select * from healthbot_80002_1",
"format": "objects",
"extract": false,
"unwrap": false
}'

Parameters

NameInTypeRequiredDescription
statementquerystringtrueThe SQL read query statement
formatquerystringfalseThe requested response format: objects (array of objects) or table (object with columns and rows as properties).
extractquerybooleanfalseWhether to extract the JSON object from the single property of the surrounding JSON object.
unwrapquerybooleanfalseWhether to unwrap the returned JSON objects from their surrounding array.

Responses

StatusMeaningDescriptionSchema
200https://tools.ietf.org/html/rfc7231#section-6.3.1Successful operationInline
400https://tools.ietf.org/html/rfc7231#section-6.5.1Invalid query/statement valueNone
404https://tools.ietf.org/html/rfc7231#section-6.5.4Row Not FoundNone
429https://tools.ietf.org/html/rfc6585#section-4Too Many RequestsNone

Response properties

See the query formatting section for how to transform the response, such as composing a JSON object (e.g., for ERC721 compliance).

Example

curl -X GET https://testnets.tableland.network/api/v1/query?statement=select%20%2A%20from%20healthbot_80002_1 \
-H 'Accept: application/json'

Or:

curl -L 'https://testnets.tableland.network/api/v1/query' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"statement": "select * from healthbot_80002_1"
}'

Returns a successful (200) response:

[
{
"counter": 148247
}
]