Skip to main content
Queries are SQL statements that fetch data from your database. They power the components in your apps by providing data to display and transform.

​
Creating a query

  1. Open the Queries tab in the app editor
  2. Click “New Query”
  3. Select a connection
  4. Write your SQL query
  5. Click “Run” to test
  6. Save your query

​
Writing SQL

Telemetry supports standard PostgreSQL SQL syntax. Write queries just like you would in any SQL client. 
-- Basic select
SELECT * FROM users LIMIT 100;

-- With filters
SELECT * FROM orders
WHERE status = 'pending'
ORDER BY created_at DESC;

-- With joins
SELECT
  orders.id,
  orders.total,
  users.name as customer_name
FROM orders
JOIN users ON orders.user_id = users.id;

-- Aggregations
SELECT
  DATE(created_at) as date,
  COUNT(*) as order_count,
  SUM(total) as revenue
FROM orders
GROUP BY DATE(created_at)
ORDER BY date DESC;

​
Query execution

Queries are executed when the app loads. Query results are stored in state and can be accessed in component transforms using query(slug).

​
Using queries in components

After creating a query, you can use it in code mode transforms: 
function transform(): { headers: string[]; rows: RowObject[] } {
  const data = query('users-query');

  return {
    headers: data.columns,
    rows: data.rows,
  };
}
The query() function returns:
PropertyTypeDescription
columnsstring[]Column names from the query
rowsobject[]Array of row data
countnumberNumber of rows returned
executedAtstringISO timestamp of last execution

​
State

Query results are automatically stored in the app’s state system. This means:
  • Results are available immediately in transforms via query(slug)
  • Results persist across component re-renders
  • Results are cached in IndexedDB with a 10-minute TTL
See the State page for details on how data flows through your app.

​
Best practices

​
Security

  • Never interpolate user input directly into SQL strings
  • Limit permissions on your database user
  • Use read-only users for dashboards

​
Performance

  • Add LIMIT clauses to prevent loading too much data
  • Use WHERE clauses to filter at the database level
  • Create indexes on frequently queried columns
  • Avoid SELECT * — only select columns you need

​
Organization

  • Give queries descriptive names (used as slugs in code)
  • Add comments to complex queries

​
Preview results

Use the “Run” button in the query editor to preview results before saving. This helps you verify your query returns the expected data.