Documentationbreadcrumb arrow Pluginsbreadcrumb arrow Amazon Timestreambreadcrumb arrow Query editor
Grafana Cloud Enterprise Open source
Last reviewed: April 28, 2026

Amazon Timestream query editor

The Amazon Timestream query editor lets you write SQL queries against your Timestream databases. It includes a code editor with IntelliSense, macros for dynamic values, and configurable output formats.

Before you begin

Key concepts

The following terms are used throughout the query editor documentation.

TermDescription
DatabaseA top-level Timestream container that organizes tables.
TableA collection of time-series records within a database.
MeasureA named metric or value in a Timestream table, such as cpu_utilization or temperature.
MacroA placeholder in a query that Grafana replaces with a dynamic value at execution time.

Query editor fields

The query editor provides the following fields and controls.

FieldDescription
DatabaseThe Timestream database to query. Populates the $__database macro. Falls back to the default database set in the data source configuration.
TableThe table within the selected database. Populates the $__table macro. The table list updates when you change the database.
MeasureThe measure within the selected table. Populates the $__measure macro. The measure list updates when you change the database or table.
Wait for all queriesWhen enabled, the plugin fetches all paginated result pages before returning data. Enable this for alerting queries.
Format asControls the output format: Table (default) or Time Series. Time-series queries must return times in ascending order using ORDER BY time ASC.
Sample queriesA drop-down of pre-built queries to help you get started. Selecting a sample replaces the current query.

Write a query

Use the SQL editor to write Timestream SQL queries. The editor supports IntelliSense for column names, table names, and macros. Press Ctrl+Space to trigger auto-complete suggestions.

To run a query, press Ctrl+Enter or click Run query.

Basic query example

The following query selects all records from the configured database and table within the dashboard time range:

SQL 
SELECT *
FROM $__database.$__table
WHERE $__timeFilter
ORDER BY time ASC
LIMIT 100

Macros

Use macros in your queries to insert dynamic values like time ranges, intervals, and configured defaults. The query engine replaces macros with their computed values before sending the query to Timestream.

MacroDescription
$__databaseThe database selected in the query editor, or the default database from the data source configuration.
$__tableThe table selected in the query editor, or the default table from the data source configuration.
$__measureThe measure selected in the query editor, or the default measure from the data source configuration.
$__timeFilterAn expression that limits results to the dashboard time range, for example time BETWEEN from_milliseconds(1234) AND from_milliseconds(5678).
$__timeFromThe start of the dashboard time range in milliseconds.
$__timeToThe end of the dashboard time range in milliseconds.
$__intervalA Timestream duration literal representing the calculated interval for the panel width, for example 60000ms.
$__interval_msSame as $__interval. A Timestream duration literal representing the calculated interval in milliseconds.
$__interval_raw_msThe calculated interval as a plain integer in milliseconds, for example 60000.
$__now_msThe current time in milliseconds.

Macro example

The following query combines several macros to aggregate data into dashboard-appropriate intervals:

SQL 
SELECT
  bin(time, $__interval_ms) AS binned_time,
  measure_name,
  avg(measure_value::double) AS avg_value
FROM $__database.$__table
WHERE $__timeFilter
  AND measure_name = '$__measure'
GROUP BY bin(time, $__interval_ms), measure_name
ORDER BY binned_time ASC

This query uses $__database, $__table, and $__measure to reference the selections in the query editor, $__timeFilter to scope results to the dashboard time range, and $__interval_ms to group data into intervals that match the panel width.

Plugin macros vs Grafana global variables

The macros listed in the table (such as $__timeFrom and $__timeTo) are plugin macros that the backend expands before sending the query to Timestream. They return raw millisecond values.

Grafana also provides global variables ($__from, $__to) that support custom formatting. These are expanded by the frontend before the query reaches the backend. You can use them in Timestream queries when you need a specific time format:

SQL 
SELECT *
FROM $__database.$__table
WHERE time >= from_iso8601_timestamp('${__from:date:iso}')
  AND time <= from_iso8601_timestamp('${__to:date:iso}')

Common Grafana time variable formats:

VariableOutput exampleDescription
${__from:date:iso}2024-01-15T08:00:00.000ZISO 8601 format, useful with Timestream’s from_iso8601_timestamp().
${__from:date:seconds}1705305600Unix timestamp in seconds.
${__from}1705305600000Unix timestamp in milliseconds (default).

Note

Use $__timeFilter instead of manually constructing time range filters when possible. It handles the time range conversion correctly and is less error-prone than formatting time variables yourself.

For the full list of global variable formats, refer to Global variables.

Sample queries

The query editor includes built-in sample queries you can select from the Sample queries drop-down. These queries use macros and adapt to your selected database and table.

Sample queryDescription
Show databasesLists all databases in the Timestream instance.
Show tablesLists tables in the selected database.
Describe tableDescribes the schema of the selected table.
Show measurementsLists all measures in the selected table.
First 10 rowsReturns the first 10 rows from the selected table.

Use cases

The following examples demonstrate common query patterns for Timestream data.

Aggregate metrics over time

Use bin() with $__interval_ms to group data into intervals that match the panel resolution. This is the most common pattern for time-series visualizations.

SQL 
SELECT
  bin(time, $__interval_ms) AS binned_time,
  instance_name,
  avg(measure_value::double) AS avg_cpu
FROM $__database.$__table
WHERE $__timeFilter
  AND measure_name = 'cpu_utilization'
GROUP BY bin(time, $__interval_ms), instance_name
ORDER BY binned_time ASC

Compare metrics across dimensions

Group by a dimension column to compare values across hosts, regions, or other attributes in a single panel.

SQL 
SELECT
  bin(time, $__interval_ms) AS binned_time,
  hostname,
  max(measure_value::double) AS peak_memory,
  avg(measure_value::double) AS avg_memory
FROM $__database.$__table
WHERE $__timeFilter
  AND measure_name = 'memory_utilization'
GROUP BY bin(time, $__interval_ms), hostname
ORDER BY binned_time ASC

Explore table schema

Use Timestream’s metadata queries to discover available data before building visualizations.

SQL 
SHOW MEASURES FROM $__database.$__table
SQL 
DESCRIBE $__database.$__table

Query the latest values

Use $__now_ms and $__timeFrom to build custom time-range logic, for example, to find the most recent reading per sensor.

SQL 
SELECT
  sensor_id,
  measure_name,
  time,
  measure_value::double AS value
FROM $__database.$__table
WHERE time BETWEEN from_milliseconds($__timeFrom) AND from_milliseconds($__now_ms)
  AND measure_name = 'temperature'
ORDER BY time DESC
LIMIT 10

IoT multi-measure queries

Query multiple measure values from multi-measure records in a single query.

SQL 
SELECT
  bin(time, $__interval_ms) AS binned_time,
  device_id,
  avg(temperature) AS avg_temp,
  avg(humidity) AS avg_humidity
FROM $__database.$__table
WHERE $__timeFilter
GROUP BY bin(time, $__interval_ms), device_id
ORDER BY binned_time ASC

Optimize query performance and cost

Amazon Timestream charges based on the amount of data scanned by queries. Poorly optimized dashboards with frequent refreshes and broad queries can lead to significant costs. The following practices help minimize data scanned and reduce your Timestream bill.

Filter by measure name

Always include a measure_name filter in the WHERE clause. Timestream partitions data by measure name, so filtering on it dramatically reduces the volume of data scanned.

SQL 
-- Costly: scans all measures in the table
SELECT * FROM $__database.$__table WHERE $__timeFilter

-- Optimized: scans only the cpu_utilization partition
SELECT * FROM $__database.$__table
WHERE $__timeFilter AND measure_name = 'cpu_utilization'

Narrow the time range

Use the shortest time range that meets your needs. Timestream separates data into memory and magnetic storage tiers based on age, and wider time ranges may scan both.

  • Set dashboard time ranges to the minimum necessary (for example, “Last 1 hour” instead of “Last 7 days”).
  • Use $__timeFilter to automatically scope queries to the dashboard time range.

Use aggregation with bin()

Aggregate data with bin() and $__interval_ms instead of returning raw data points. This reduces the number of rows returned and aligns data to the panel resolution.

SQL 
-- Returns potentially millions of raw rows
SELECT time, measure_value::double FROM $__database.$__table WHERE $__timeFilter

-- Returns one row per interval per series
SELECT bin(time, $__interval_ms) AS t, avg(measure_value::double) AS value
FROM $__database.$__table
WHERE $__timeFilter AND measure_name = 'cpu_utilization'
GROUP BY bin(time, $__interval_ms)
ORDER BY t ASC

Reduce dashboard refresh frequency

Each dashboard refresh re-executes all panel queries. Set the auto-refresh interval to an appropriate frequency for your use case (for example, every 30 seconds or every minute instead of every 5 seconds).

Reuse query results across panels

If multiple panels display different aspects of the same data, query the data once and reuse the results:

  • Dashboard data source: Use the built-in Dashboard data source to reference results from another panel, avoiding duplicate queries to Timestream.
  • Transformations: Apply transformations to reshape a single query’s results for different visualizations.

Enable query caching

In Grafana Enterprise and Grafana Cloud, enable query caching to avoid re-running identical queries within a configurable time window.