Documentation

Perform a basic SQL query

The InfluxDB SQL implementation is powered by the Apache Arrow DataFusion query engine which provides a SQL syntax similar to other relational query languages.

A basic SQL query that queries data from InfluxDB most commonly includes the following clauses:

* Required
  • * SELECT: Specify fields, tags, and calculations to output from a measurement or use the wildcard alias (*) to select all fields and tags from a measurement.
  • * FROM: Specify the measurement to query data from.
  • WHERE: Only return data that meets the specified conditions–for example, falls within a time range, contains specific tag values, or contains a field value outside a specified range.
SELECT
  temp,
  hum,
  room
FROM home
WHERE
  time >= '2022-01-01T08:00:00Z'
  AND time <= '2022-01-01T20:00:00Z'

Result set

If at least one row satisfies the query, InfluxDB Cloud Serverless returns row data in the query result set. An SQL query result set includes columns listed in the query’s SELECT statement.

Basic query examples

Sample data

The following examples use the sample data written in the Get started writing data guide. To run the example queries and return results, write the sample data to your InfluxDB Cloud Serverless bucket before running the example queries.

Query data within time boundaries

  • Use the SELECT clause to specify what columns (tags and fields) to return. To return all tags and fields, use the wildcard alias (*).
  • In the FROM clause, specify the table (measurement) to query.
  • In the WHERE clause, specify time boundaries and other conditions for filtering. Include time-based predicates that compare the value of the time column to a timestamp. Use the AND logical operator to chain multiple predicates together.
SELECT *
FROM home
WHERE
  time >= '2022-01-01T08:00:00Z'
  AND time <= '2022-01-01T12:00:00Z'

Query time boundaries can be relative or absolute.

Query with relative time boundaries

Query with absolute time boundaries

Query data without time boundaries

To query data without time boundaries, don’t include any time-based predicates in your WHERE clause.

Querying data without time bounds can return a large number of rows. The query may take a long time to complete and results may be truncated.

SELECT * FROM home

Query specific fields and tags

To specify columns (fields, tags, or calculations) you want to retrieve, list them in the SELECT clause. Use a comma to separate column names. If the field or tag keys include special characters or spaces or are case-sensitive, wrap the key in double-quotes.

SELECT time, room, temp, hum FROM home

Query fields based on tag values

  • Include the fields you want to query and the tags you want to base conditions on in the SELECT clause.
  • Include predicates in the WHERE clause that compare the tag identifier to a string literal. Use logical operators to chain multiple predicates together and apply multiple conditions.
SELECT * FROM home WHERE room = 'Kitchen'

Query points based on field values

  • Include the fields you want to query in the SELECT clause.
  • Include predicates in the WHERE clause that compare the field identifier to another value. Use logical operators (AND, OR) to chain multiple predicates together and apply multiple conditions.
SELECT co, time FROM home WHERE co >= 10 OR co <= -10

Alias queried fields and tags

To alias or rename fields and tags that you query, pass a string literal after the field or tag identifier in the SELECT clause. You can use the AS clause to define the alias, but it isn’t necessary. The following queries are functionally the same:

SELECT temp 'temperature', hum 'humidity' FROM home

SELECT temp AS 'temperature', hum AS 'humidity' FROM home

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.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following:

InfluxDB Cloud Serverless