Use the Firebolt REST API to execute queries on engines programmatically. Learn how to use the API, including authentication, working with engines and executing queries. A service account is required to access the API. Learn about managing programmatic access to Firebolt.
Create a service account and associate it with a user
Create a service account with organization administrator privilege,
i.e., the service account property_is_organization_admin_ must be true.
Next, create a user with role privileges you would like to have the service account
and associate the service account with the user.
Use tokens for authentication
To authenticate Firebolt using the service accounts with the properties
as described above via Firebolt’s REST API, send the following request
to receive an authentication token:
curl -X POST --location 'https://id.app.firebolt.io/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'audience=https://api.firebolt.io' \
--data-urlencode "client_id=${service_account_id}" \
--data-urlencode "client_secret=${service_account_secret}"
| Property | Data type | Description |
|---|
| client_id | TEXT | The service account ID. |
| client_secret | TEXT | The service account secret. |
{
"access_token":"access_token_value",
"token_type":"Bearer",
"expires_in":86400
}
- The
access_token is a unique token that authorizes your API requests that acts as a temporary key to access resources or perform actions. You can use this token to authenticate with Firebolt’s platform until it expires.
- The
token_type is Bearer, which means that the access token must be included in an authorization header of your API requests using the format: Authorization: Bearer <access_token>.
- The token
expires_in indicates the number of seconds until the token expires.
Use the returned access_token to authenticate with Firebolt.
To run a query using the API, you must first obtain the URL of the engine you want to run on.
Get the account gateway URL
Use the following endpoint to return the account gateway URL for <account name>.
curl https://api.app.firebolt.io/web/v3/account/<account name>/engineUrl \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <access token>'
https://api.app.firebolt.io/web/v3/account/my-account/engineUrl
Response
{
"engineUrl":"<prefix>.api.us-east-1.app.firebolt.io"
}
information_schema.engines) and for DDL that does not target a specific user engine.
Get a user engine URL
Get a user engine URL by running the following query against the information_schema.engines table:
SELECT url
FROM information_schema.engines
WHERE engine_name='<engine_name>'
curl --location 'https://<account gateway URL>/query' \
--header 'Authorization: Bearer <access token>' \
--data 'SELECT url FROM information_schema.engines WHERE engine_name='\''my_engine'\'''
Execute a query on a user engine
Use the following endpoint to run a query on a user engine:
curl --location 'https://<user engine URL>&database=<database name>' \
--header 'Authorization: Bearer <access token>' \
--data '<SQL query>'
| Property | Data type | Description |
|---|
| user engine URL | TEXT | The user engine URL (retrieved here) |
| database name | TEXT | The database to run the query |
| SQL query | TEXT | Any valid SQL query |
Queries are per request. To run multiple statement queries, separate queries each into one request.
API limits
Request Size Limits
By default, Firebolt enforces a request size limit of 2 MiB per query on user engines. If you exceed this limit, you will get an error like:
413: Request body is larger than configured limit of 20971520 bytes. Please contact support if you need to send larger queries to support your workload
- Requests above 2 MiB will not be retried internally after transient network errors.
- Requests above 2 MiB will not be included in online upgrade verification.
