Query References
Query references (query refs) are bookmarks that point to specific queries and provide permalinks for sharing. They can include visualizations, parameters, and metadata. On this page, we'll dive into the different query reference endpoints you can use to manage query bookmarks programmatically. We'll look at how to list, create, retrieve, update, and delete query references.
The query reference model
The query reference model contains information about bookmarked queries, including their short IDs for permalinks, associated visualizations, and parameters. Query refs can point to different versions of queries through links.
Properties
- Name
id- Type
- string
- Description
Unique identifier for the query reference.
- Name
shortId- Type
- string
- Description
Short identifier used for permalinks (e.g., "abc123").
- Name
title- Type
- string
- Description
Human-readable title for the query reference.
- Name
description- Type
- string
- Description
Optional description of what the query reference does.
- Name
isOptimistic- Type
- boolean
- Description
Whether this is a temporary reference pending query creation.
- Name
createdBy- Type
- string
- Description
User ID of the query reference creator.
- Name
createdAt- Type
- timestamp
- Description
Timestamp of when the query reference was created.
- Name
updatedAt- Type
- timestamp
- Description
Timestamp of when the query reference was last updated.
- Name
currentQuery- Type
- object
- Description
The current query that this reference points to.
- Name
visualization- Type
- object
- Description
Visualization configuration if one exists.
- Name
parameters- Type
- array
- Description
Array of parameter definitions for the query.
List all query references
This endpoint allows you to retrieve a paginated list of all your query references. By default, a maximum of twenty query references are shown per page.
Optional parameters
- Name
limit- Type
- integer
- Description
Limit the number of query references 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/refs \
-H "Authorization: Bearer {token}" \
-d limit=10
Response
{
"items": [
{
"id": "qref_123",
"shortId": "abc123",
"title": "Weekly Active Users",
"description": "Analysis of weekly active users across different cohorts",
"isOptimistic": false,
"createdBy": "user_456",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"currentQuery": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"sql": "SELECT DATE_TRUNC('week', created_at) as week, COUNT(DISTINCT user_id) as active_users FROM events GROUP BY 1"
}
}
],
"nextCursor": "eyJpZCI6InFyZWZfMTIzIn0"
}
Retrieve a query reference
This endpoint allows you to retrieve a query reference by its short ID. This is the same short ID used in permalinks. The response includes the current query, visualization config, and parameters.
Request
curl https://api.slateo.ai/api/queries/refs/abc123 \
-H "Authorization: Bearer {token}"
Response
{
"id": "qref_123",
"shortId": "abc123",
"title": "Weekly Active Users",
"description": "Analysis of weekly active users across different cohorts",
"isOptimistic": false,
"createdBy": "user_456",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"currentQuery": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"sql": "SELECT DATE_TRUNC('week', created_at) as week, COUNT(DISTINCT user_id) as active_users FROM events WHERE created_at >= {{start_date}} GROUP BY 1"
},
"visualization": {
"type": "line",
"jsxConfig": "...",
"marginConfig": {
"top": 20,
"right": 30,
"bottom": 40,
"left": 50
}
},
"parameters": [
{
"name": "start_date",
"displayName": "Start Date",
"type": "date-picker",
"defaultValue": "2024-01-01",
"description": "The start date for the analysis"
}
]
}
Create a query reference
This endpoint allows you to create a new query reference that points to an existing query. The query must exist before you can create a reference to it. A unique short ID will be generated automatically.
Required attributes
- Name
queryId- Type
- string
- Description
The UUID of the query to create a reference for.
Request
curl -X POST https://api.slateo.ai/api/queries/refs \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"queryId": "550e8400-e29b-41d4-a716-446655440000"}'
Response
{
"id": "qref_789",
"shortId": "xyz789",
"title": "Untitled Query Reference",
"description": null,
"isOptimistic": false,
"createdBy": "user_456",
"createdAt": "2024-01-20T14:30:00Z",
"updatedAt": "2024-01-20T14:30:00Z",
"currentQuery": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"sql": "SELECT * FROM users WHERE created_at > '2024-01-01'"
}
}
Update a query reference
This endpoint allows you to update the metadata of a query reference, such as its title and description. The short ID and query association cannot be changed through this endpoint.
Optional attributes
- Name
title- Type
- string
- Description
New title for the query reference.
- Name
description- Type
- string
- Description
New description for the query reference. Set to null to remove.
Request
curl -X PUT https://api.slateo.ai/api/queries/refs/abc123 \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"title": "Monthly Active Users", "description": "Updated analysis of monthly active users"}'
Response
{
"id": "qref_123",
"shortId": "abc123",
"title": "Monthly Active Users",
"description": "Updated analysis of monthly active users",
"isOptimistic": false,
"createdBy": "user_456",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T15:45:00Z",
"currentQuery": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"sql": "SELECT DATE_TRUNC('month', created_at) as month, COUNT(DISTINCT user_id) as active_users FROM events GROUP BY 1"
}
}
Delete a query reference
This endpoint allows you to soft delete a query reference. The reference will be marked as deleted but the underlying query and historical data will be preserved. The permalink will no longer be accessible.
Request
curl -X DELETE https://api.slateo.ai/api/queries/refs/abc123 \
-H "Authorization: Bearer {token}"
Response
{
"id": "qref_123",
"shortId": "abc123",
"title": "Weekly Active Users",
"description": "Query to track weekly active users",
"queryId": "query_456",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"deletedAt": "2024-01-21T12:00:00Z"
}
FAQ
What's the difference between a query and a query reference?
A query is the SQL statement and its execution history. A query reference is a bookmark that points to a query and provides a shareable permalink, along with optional visualizations and parameters.
Can I change the short ID of a query reference?
No, the short ID is automatically generated when you create a query reference and cannot be changed. If you need a different short ID, you'll need to create a new query reference.
What happens to permalinks when I delete a query reference?
When you delete a query reference, the permalink will no longer be accessible. The underlying query and its data are preserved, but the short ID will return a 404 error.
Can multiple query references point to the same query?
Yes, you can create multiple query references that point to the same underlying query. This is useful for creating different views or sharing the same query with different parameters or visualizations.