Queries
Queries are SQL statements that can be executed against your analytical databases. They form the foundation of data analysis in Slateo. On this page, we'll dive into the different query endpoints you can use to manage queries programmatically. We'll look at how to list, retrieve, execute, and refresh queries.
The query model
The query model contains all the information about SQL queries and their execution results. Each query is associated with an analytical database configuration and can have multiple runs with different results.
Properties
- Name
id- Type
- string
- Description
Unique identifier for the query.
- Name
sql- Type
- string
- Description
The SQL statement to be executed.
- Name
analyticalDatabaseConfigId- Type
- string
- Description
Unique identifier for the analytical database configuration.
- Name
createdBy- Type
- string
- Description
User ID of the query creator.
- Name
createdAt- Type
- timestamp
- Description
Timestamp of when the query was created.
- Name
updatedAt- Type
- timestamp
- Description
Timestamp of when the query was last updated.
- Name
latestRun- Type
- object
- Description
Information about the latest query execution.
- Name
latestRunMetadata- Type
- object
- Description
Metadata about the latest query run including status and statistics.
List all queries
This endpoint allows you to retrieve a paginated list of all your queries. By default, a maximum of twenty queries are shown per page.
Optional parameters
- Name
limit- Type
- integer
- Description
Limit the number of queries returned (max 100, default 20).
- Name
cursor- Type
- string
- Description
Cursor for pagination to get the next set of results.
Request
curl -G https://api.slateo.ai/api/queries \
-H "Authorization: Bearer {token}" \
-d limit=10
Response
{
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"sql": "SELECT * FROM users WHERE created_at > '2024-01-01'",
"analyticalDatabaseConfigId": "db_config_123",
"createdBy": "user_456",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"latestRun": {
"id": "run_789",
"status": "completed",
"runAt": "2024-01-15T10:35:00Z"
}
}
],
"nextCursor": "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9"
}
Retrieve a query
This endpoint allows you to retrieve a query by providing the query ID. The response includes the latest run information and metadata about execution status.
Request
curl https://api.slateo.ai/api/queries/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer {token}"
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"sql": "SELECT * FROM users WHERE created_at > '2024-01-01'",
"analyticalDatabaseConfigId": "db_config_123",
"createdBy": "user_456",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"latestRun": {
"id": "run_789",
"status": "completed",
"runAt": "2024-01-15T10:35:00Z",
"completedAt": "2024-01-15T10:35:30Z"
},
"latestRunMetadata": {
"status": "completed",
"rowsRead": 0,
"rowsWritten": 0
}
}
Get query results
This endpoint allows you to retrieve the cached results of a query execution. The results include the column definitions and row data from the latest successful query run.
Request
curl https://api.slateo.ai/api/queries/550e8400-e29b-41d4-a716-446655440000/result \
-H "Authorization: Bearer {token}"
Response
{
"fields": [
{
"name": "id",
"type": "integer"
},
{
"name": "email",
"type": "string"
},
{
"name": "created_at",
"type": "timestamp"
}
],
"rows": [
[1, "user1@example.com", "2024-01-15T10:00:00Z"],
[2, "user2@example.com", "2024-01-16T11:30:00Z"],
[3, "user3@example.com", "2024-01-17T09:15:00Z"]
],
"rowCount": 3
}
Refresh a query
This endpoint allows you to re-execute a query with the same parameters as the last run. This is useful for getting fresh data or retrying failed queries. The query must not be currently running.
Request
curl -X POST https://api.slateo.ai/api/queries/550e8400-e29b-41d4-a716-446655440000/refresh \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json"
Response
{
"id": "run_890",
"queryId": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"runAt": "2024-01-20T14:30:00Z",
"triggerId": "trigger_123",
"parameterValues": {},
"renderedSql": "SELECT * FROM users WHERE created_at > '2024-01-01'"
}
FAQ
How long are query results cached?
Query results are cached for 24 hours by default. After that, you'll need to refresh the query to get updated results. You can use the refresh endpoint to manually trigger a re-execution at any time.
Can I execute a query without creating it first?
No, queries must be created before they can be executed. However, you can create a query and immediately trigger a refresh in separate API calls.
What happens if a query is already running when I try to refresh it?
The refresh request will fail with an error indicating the query is already running. You'll need to wait for the current execution to complete before triggering another refresh.
How do I know when a query execution is complete?
Check the status field in the latestRun object. Possible values are pending, running, completed, and failed. You can poll the retrieve endpoint to monitor progress.