Documentation

Get started querying data

InfluxDB Cloud Dedicated supports multiple query languages:

  • SQL: Traditional SQL powered by the Apache Arrow DataFusion query engine. The supported SQL syntax is similar to PostgreSQL.
  • InfluxQL: An SQL-like query language designed to query time series data stored in InfluxDB.

This tutorial walks you through the fundamentals of querying data in InfluxDB and focuses on using SQL to query your time series data. The InfluxDB SQL implementation is built using Arrow Flight SQL, a protocol for interacting with SQL databases using the Arrow in-memory format and the Flight RPC framework. It leverages the performance of Apache Arrow with the simplicity of SQL.

The examples in this section of the tutorial query the get-started database for data written in the Get started writing data section.

Tools to execute queries

InfluxDB Cloud Dedicated supports many different tools for querying data, including:

* Covered in this tutorial

/api/v2/query not supported

The /api/v2/query API endpoint and associated tooling, such as the influx CLI and InfluxDB v2 client libraries, aren’t supported in InfluxDB Cloud Dedicated.

SQL query basics

The InfluxDB Cloud Dedicated SQL implementation is powered by the Apache Arrow DataFusion query engine which provides an SQL syntax similar to PostgreSQL.

This is a brief introduction to writing SQL queries for InfluxDB. For more in-depth details, see Query data with SQL.

InfluxDB SQL queries most commonly include the following clauses:

* Required
  • * SELECT: Identify specific fields and tags to query from a measurement or use the wildcard alias (*) to select all fields and tags from a measurement.
  • * FROM: Identify the measurement to query. If coming from an SQL background, an InfluxDB measurement is the equivalent of a relational table.
  • WHERE: Only return data that meets defined conditions such as falling within a time range, containing specific tag values, etc.
  • GROUP BY: Group data into SQL partitions and apply an aggregate or selector function to each group.
-- Return the average temperature and humidity within time bounds from each room
SELECT
  avg(temp),
  avg(hum),
  room
FROM
  home
WHERE
  time >= '2025-01-20T08:00:00Z'
  AND time <= '2025-01-20T20:00:00Z'
GROUP BY
  room
  • Copy
  • Fill window

Example SQL queries

Select all data in a measurement
SELECT * FROM home
  • Copy
  • Fill window
Select all data in a measurement within time bounds
SELECT
  *
FROM
  home
WHERE
  time >= '2025-01-20T08:00:00Z'
  AND time <= '2025-01-20T20:00:00Z'
  • Copy
  • Fill window
Select a specific field within relative time bounds
SELECT temp FROM home WHERE time >= now() - INTERVAL '1 day'
  • Copy
  • Fill window
Select specific fields and tags from a measurement
SELECT temp, room FROM home
  • Copy
  • Fill window
Select data based on tag value
SELECT * FROM home WHERE room = 'Kitchen'
  • Copy
  • Fill window
Select data based on tag value within time bounds
SELECT
  *
FROM
  home
WHERE
  time >= '2025-01-20T08:00:00Z'
  AND time <= '2025-01-20T20:00:00Z'
  AND room = 'Living Room'
  • Copy
  • Fill window
Downsample data by applying interval-based aggregates
SELECT
  DATE_BIN(INTERVAL '1 hour', time, '2025-01-20T00:00:00Z') as _time,
  room,
  selector_max(temp, time)['value'] AS 'max temp'
FROM
  home
GROUP BY
  _time,
  'max temp',
  room
ORDER BY room, _time
  • Copy
  • Fill window

Execute an SQL query

Get started with one of the following tools for querying data stored in an InfluxDB Cloud Dedicated database:

  • influxctl CLI: Query data from your command-line using the influxctl CLI.
  • influx3 CLI: Query data from your terminal command-line using the Python-based influx3 CLI.
  • InfluxDB 3 client libraries: Use language-specific (Python, Go, etc.) clients to execute queries in your terminal or custom code.
  • Grafana: Use the FlightSQL Data Source plugin, to query, connect, and visualize data.

For this example, use the following query to select all the data written to the get-started database between 2025-01-20T08:00:00Z and 2025-01-20T20:00:00Z.

SELECT
  *
FROM
  home
WHERE
  time >= '2025-01-20T08:00:00Z'
  AND time <= '2025-01-20T20:00:00Z'
  • Copy
  • Fill window

Some examples in this getting started tutorial assume your InfluxDB credentials (URL and token) are provided by environment variables.

Query InfluxDB 3 using SQL and the influx3 CLI.

The following steps include setting up a Python virtual environment already covered in Get started writing data. If your project’s virtual environment is already running, skip to step 3.

  1. Create a directory for your project and change into it:

    mkdir -p influx3-query-example && cd influx3-query-example 
    
    • Copy
    • Fill window
  2. To create and activate a Python virtual environment, run the following command:

    python -m venv envs/virtual-env && . envs/virtual-env/bin/activate
    
    • Copy
    • Fill window
  3. Install the CLI package (already installed in the Write data section).

    pip install influxdb3-python-cli
    
    • Copy
    • Fill window

    Installing influxdb3-python-cli also installs the pyarrow library for working with Arrow data returned from queries.

  4. Create the config.json configuration.

    influx3 config create \
      --name="config-dedicated" \
      --database="get-started" \
      --host="cluster-id.a.influxdb.io" \
      --token="DATABASE_TOKEN" \
      --org="ORG_ID"
    
    • Copy
    • Fill window

    Replace the following:

    • DATABASE_TOKEN: a database token with read access to the get-started database
    • ORG_ID: any non-empty string (InfluxDB ignores this parameter, but the client requires it)
  5. Enter the influx3 sql command and your SQL query statement.

    influx3 sql "SELECT *
                FROM home
                WHERE time >= '2025-01-20T08:00:00Z'
                AND time <= '2025-01-20T20:00:00Z'"
    
    • Copy
    • Fill window

influx3 displays query results in your terminal.

Query results

View query results

Congratulations! You’ve learned the basics of querying data in InfluxDB with SQL. For a deep dive into all the ways you can query InfluxDB Cloud Dedicated, see the Query data in InfluxDB section of documentation.


Was this page helpful?

Thank you for your feedback!


The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

InfluxDB 3 Open Source Now in Public Alpha

InfluxDB 3 Open Source is now available for alpha testing, licensed under MIT or Apache 2 licensing.

We are releasing two products as part of the alpha.

InfluxDB 3 Core, is our new open source product. It is a recent-data engine for time series and event data. InfluxDB 3 Enterprise is a commercial version that builds on Core’s foundation, adding historical query capability, read replicas, high availability, scalability, and fine-grained security.

For more information on how to get started, check out: