Time Series Queries

Pinot has a "Time Series Engine" that can be used to support any Time Series Query Language, provided an appropriate Time Series Language Plugin is implemented.

Languages such as PromQL, Uber's M3QL, and many more can be implemented using the Plugin. A toy language plugin, intended only for demo/testing purposes, is included in the apache/pinot repo.

Status: The Time Series Engine is in Beta as of Pinot 1.4 and is slated to be Generally Available in Pinot 1.5.

Running Time Series Queries with Quickstart

You can use the time_series Quickstart type to run Pinot with the Time Series Engine enabled. The Quickstart uses the toy language implementation included in the apache/pinot repo.

You can refer to our Quick Start Examples page for more information.

Running Time Series Queries in Production

Assuming you have implemented your own Timeseries Language Plugin, with the code-name "mytsql", you can set the following configurations in each of Controller, Broker and Server configs. The class and series builder factory names are hypothetical. Note that the key of the planner and series builder configs contain the language code.

pinot.timeseries.languages=mytsql
pinot.timeseries.mytsql.logical.planner.class=com.example.mytsql.MyTSLogicalPlanner
pinot.timeseries.mytsql.series.builder.factory=com.example.mytsql.MyTSQLSeriesBuilderFactory

Pinot even allows running multiple Time Series Query Languages. For instance, if you had another query language plugin for promql and you wanted to run it alongside mytsql, the configs would look like:

pinot.timeseries.languages=mytsql,promql
pinot.timeseries.mytsql.logical.planner.class=com.example.mytsql.MyTSLogicalPlanner
pinot.timeseries.mytsql.series.builder.factory=com.example.mytsql.MyTSQLSeriesBuilderFactory
pinot.timeseries.promql.logical.planner.class=com.example.promql.PromQLLogicalPlanner
pinot.timeseries.promql.series.builder.factory=com.example.promql.PromQLSeriesBuilderFactory

Time Series Features

Controller UI

Pinot includes a Time Series Query page in the Controller UI for easy querying and visualization at http://localhost:9000.

Time Series Query UI showing the query editor, time controls, and visualization options

The UI includes a query editor with language selector (compatible with custom language plugins) and visualizes results as both an interactive time series chart and raw JSON. It also displays query statistics and supports explain plans and query options for enhanced control.

Broker-Compatible API

The time series API POST /query/timeseries returns responses in the standard BrokerResponse format, allowing existing Pinot client libraries to work without modification. The response includes familiar query statistics like numDocsScanned, numSegmentsQueried, and totalDocs, along with the same exception handling structure as SQL queries.

Time series data is returned in a ResultTable with the following key columns:

• ts - Array of timestamps for each time bucket

• values - Array of metric values corresponding to each timestamp

• __name__ - Serialized tag key-value pairs identifying the series

• Additional columns for each tag/label in the series

Other Features

• Auth Support - Time series queries support the same authentication and authorization mechanisms as SQL queries (user roles and table-level permissions).

• Query Options - Custom query options can be passed as part of the request to modify query execution behavior (both for your custom plugin and the underlying Pinot engine).

• Query Event Listeners - Time series queries trigger the same query event listeners as SQL queries, enabling logging, auditing, and custom metrics.

• Explain Plans - Explain plans help visualize the logical query plan generated by your custom language plugin.