Query

InfluxDB supports many different tools for querying data, including:

• InfluxDB user interface (UI)
• InfluxDB HTTP API
• influx CLI
• Chronograf
• Grafana
• InfluxDB client libraries

This tutorial walks you through the fundamentals of querying data in InfluxDB and focuses primarily on the two languages you can use to query your time series data:

• Flux: A functional scripting language designed to query and process data from InfluxDB and other data sources.
• InfluxQL: A SQL-like query language designed to query time series data from InfluxDB.

{{% note %}} The examples in this section of the tutorial query the data from written in the Get started writing data section. {{% /note %}}

On this page:

• Query data with Flux
  • Flux query basics
  • Execute a Flux query
• Query data with InfluxQL
  • InfluxQL query basics
  • Execute an InfluxQL query

Query data with Flux

Flux is a functional scripting language that lets you query and process data from InfluxDB and other data sources.

{{% note %}} This is a brief introduction to writing Flux queries. For a more in-depth introduction, see Get started with Flux. {{% /note %}}

Flux query basics

When querying InfluxDB with Flux, there are three primary functions you use:

• from(): Queries data from an InfluxDB bucket.

• range(): Filters data based on time bounds. Flux requires "bounded" queries—queries limited to a specific time range.

• filter(): Filters data based on column values. Each row is represented by r and each column is represented by a property of r. You can apply multiple subsequent filters.

  To see how from() structures data into rows and tables when returned from InfluxDB, view the data written in Get started writing to InfluxDB.

  {{< expand-wrapper >}} {{% expand "Learn more about how filter() works" %}}

filter() reads each row as a record named r. In the r record, each key-value pair represents a column and its value. For example:

r = {
    _time: 2020-01-01T00:00:00Z,
    _measurement: "home",
    room: "Kitchen",
    _field: "temp",
    _value: 21.0,
}

To filter rows, use predicate expressions to evaluate the values of columns. Given the row record above:

(r) => r._measurement == "home" // Returns true
(r) => r.room == "Kitchen" // Returns true
(r) => r._field == "co" // Returns false
(r) => r._field == "co" or r._field == "temp" // Returns true
(r) => r._value <= 20.0 // Returns false

Rows that evaluate to true are included in the filter() output. Rows that evaluate to false are dropped from the filter() output. {{% /expand %}} {{< /expand-wrapper >}}

Pipe-forward operator

Flux uses the pipe-forward operator (|>) to pipe the output of one function as input the next function as input.

Query the example data

The following Flux query returns the co, hum, and temp fields stored in the home measurement with timestamps between 2022-01-01T08:00:00Z and 2022-01-01T20:00:01Z.

from(bucket: "get-started")
    |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T20:00:01Z)
    |> filter(fn: (r) => r._measurement == "home")
    |> filter(fn: (r) => r._field== "co" or r._field == "hum" or r._field == "temp")

Execute a Flux query

Use the InfluxDB UI, influx CLI, or InfluxDB API to execute Flux queries.

{{< tabs-wrapper >}} {{% tabs %}} InfluxDB UI influx CLI InfluxDB API {{% /tabs %}}

{{% tab-content %}}

1. Visit {{% show-in "v2" %}}localhost:8086{{% /show-in %}} {{% show-in "cloud,cloud-serverless" %}}cloud2.influxdata.com{{% /show-in %}} in a browser to log in and access the InfluxDB UI.

2. In the left navigation bar, click Data Explorer.

{{< nav-icon "data-explorer" "v4" >}}

3. The InfluxDB Data Explorer provides two options for querying data with Flux:

   • Query Builder (default): Visual query builder that lets you select the time range, measurement, tags, and fields to query.
   • Script Editor: In-browser code editor for composing and running Flux scripts.

   ---

   Query builder

   To build and execute a Flux query with the query builder:

   1. In the {{% caps %}}FROM{{% /caps %}} column, select the bucket to query. For this tutorial, select the get-started bucket.

   2. In the next filter column, select _measurement from the column dropdown menu, and then select the home measurement.

   3. (Optional) To query a specific field or fields, in the next filter column, select _field from the column dropdown menu, and then select the fields to query. In this tutorial, there are three fields: co, hum, and temp.

   4. (Optional) To query by specific tag values, in the next filter column, select then tag column from the column dropdown menu, and then select the tag values to filter by. In this tutorial, the tag only tag column is room.

   5. (Optional) In the {{% caps %}}Aggregate Function{{% /caps %}} pane, select an aggregate or selector function to use to downsample the data. The default aggregate function is mean.

   6. In the time range dropdown menu, select Custom Time Range, and select the following dates from the date selectors:

      • Start: 2022-01-01 08:00:00

      • Stop: 2022-01-01 20:00:01

        Note the addition of one second to the stop time. In Flux, stop times are exclusive and will exclude points with that timestamp. By adding one second, the query will include all points to 2022-01-01 20:00:00.

   7. Click {{% caps %}}Submit{{% /caps %}} to execute the query with the selected filters and operations and display the result.

   ---

   Script editor

   To write and execute a Flux query with the query builder:

   1. In the Data Explorer, click {{% caps %}}Script Editor{{% /caps %}}.

   2. Write your Flux query in the Script Editor text field.

      Note: You can either hand-write the functions or you can use the function list to the right of the script editor to search for and inject functions.

      1. Use from() and specify the bucket to query with the bucket parameter. For this tutorial, query the get-started bucket.

      2. Use range() to specify the time range to query. The start parameter defines the earliest time to include in results. The stop parameter specifies the latest time (exclusively) to include in results.

         • start: 2022-01-01T08:00:00Z

         • stop: 2022-01-01T20:00:01Z

           Note the addition of one second to the stop time. In Flux, stop times are exclusive and will exclude points with that timestamp. By adding one second, the query will include all points to 2022-01-01 20:00:00.

         If you want to use the start and stop times selected in the time selection dropdown menu, use v.timeRangeStart and v.timeRangeStop as the values for the start and stop parameters.

      3. Use filter() to filter results by the home measurement.

      4. (Optional) Use filter() to filter results by a specific field. In this tutorial, there are three fields: co, hum, and temp.

      5. (Optional) Use filter() to filter results by specific tag values. In this tutorial, there is one tag, room, with two potential values: Living Room or Kitchen.

      jsCopy

      from(bucket: "get-started")
          |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T20:00:01Z)
          |> filter(fn: (r) => r._measurement == "home")
          |> filter(fn: (r) => r._field== "co" or r._field == "hum" or r._field == "temp")
      

   3. Click {{% caps %}}Submit{{% /caps %}} to execute the query with the selected filters and operations and display the result.

{{% /tab-content %}} {{% tab-content %}}

1. If you haven't already, download, install, and configure the influx CLI.

2. Use the influx query command to query InfluxDB using Flux.

   Provide the following:

   • String-encoded Flux query.
   • Connection and authentication credentials

influx query '
from(bucket: "get-started")
    |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T20:00:01Z)
    |> filter(fn: (r) => r._measurement == "home")
    |> filter(fn: (r) => r._field== "co" or r._field == "hum" or r._field == "temp")
'

{{% /tab-content %}} {{% tab-content %}}

To query data from InfluxDB using Flux and the InfluxDB HTTP API, send a request to the InfluxDB API /api/v2/query endpoint using the POST request method.

{{< api-endpoint endpoint="http://localhost:8086/api/v2/query" method="post" api-ref="/influxdb/version/api/#operation/PostQuery" >}}

Include the following with your request:

• Headers:
  • Authorization: Token <INFLUX_TOKEN>
  • Content-Type: application/vnd.flux
  • Accept: application/csv
  • (Optional) Accept-Encoding: gzip
• Query parameters:
  • org: InfluxDB organization name
• Request body: Flux query as plain text

The following example uses cURL and the InfluxDB API to query data with Flux:

curl --request POST \
"$INFLUX_HOST/api/v2/query?org=$INFLUX_ORG&bucket=get-started" \
  --header "Authorization: Token $INFLUX_TOKEN" \
  --header "Content-Type: application/vnd.flux" \
  --header "Accept: application/csv" \
  --data 'from(bucket: "get-started")
    |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T20:00:01Z)
    |> filter(fn: (r) => r._measurement == "home")
    |> filter(fn: (r) => r._field== "co" or r._field == "hum" or r._field == "temp")
  '

{{% note %}} The InfluxDB /api/v2/query endpoint returns query results in annotated CSV. {{% /note %}}

{{% /tab-content %}} {{< /tabs-wrapper >}}

Flux query results

{{< expand-wrapper >}} {{% expand "View Flux query results" %}}

{{% note %}} _start and _stop columns have been omitted. These columns, by default, represent the query time bounds and are added by range(). {{% /note %}}

{{% /expand %}} {{< /expand-wrapper >}}

Query data with InfluxQL

InfluxQL is a SQL-like query language similar to most SQL languages, but specifically designed to query time series data from InfluxDB 0.x and 1.x.

{{% note %}}

Map databases and retention policies to buckets

Because InfluxQL was developed for earlier versions of InfluxDB, it depends on databases and retention policies (DBRP) which have been replaced by buckets in InfluxDB {{< current-version >}}. To use InfluxQL with InfluxDB {{< current-version >}}, first map database and retention policy (DBRP) combinations to an InfluxDB bucket. {{% /note %}}

InfluxQL query basics

When querying InfluxDB with InfluxQL, the most basic query includes the following statements and clauses:

• SELECT: Specify which fields and tags to query.
• FROM: Specify the measurement to query. Use the measurement name or a fully-qualified measurement name which includes the database and retention policy. For example: db.rp.measurement.
• WHERE: (Optional) Filter data based on fields, tags, and time.

The following InfluxQL query returns the co, hum, and temp fields and the room tag stored in the home measurement with timestamps between 2022-01-01T08:00:00Z and 2022-01-01T20:00:00Z.

SELECT co,hum,temp,room FROM "get-started".autogen.home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z'

{{% note %}} These are just the fundamentals of the InfluxQL syntax. For more in-depth information, see the InfluxQL documentation. {{% /note %}}

Execute an InfluxQL query

Use the influx CLI, or InfluxDB API to execute InfluxQL queries.

{{< tabs-wrapper >}} {{% tabs %}} InfluxDB UI influx CLI InfluxDB API {{% /tabs %}}

{{% tab-content %}}

{{% note %}}

The influxdb UI does not support InfluxQL

The InfluxDB {{< current-version >}} UI does not provide a way to query data with InfluxQL. For a user interface that builds and executes InfluxQL queries, consider using Chronograf or Grafana with InfluxDB {{< current-version >}}. {{% /note %}}

{{% /tab-content %}} {{% tab-content %}}

{{< cli/influx-creds-note >}}

1. If you haven't already, download, install, and configure the influx CLI.

2. Use the influx v1 shell command to start an InfluxQL shell and query InfluxDB using InfluxQL. Provide the following:

   • Connection and authentication credentials
   shCopy

   influx v1 shell
   

3. Enter an InfluxQL query and press {{< keybind mac="return" other="Enter ↵" >}}.

   sqlCopy

   SELECT co,hum,temp,room FROM "get-started".autogen.home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z'
   

{{% /tab-content %}} {{% tab-content %}}

To query data from InfluxDB using InfluxQL and the InfluxDB HTTP API, send a request to the InfluxDB API /query 1.X compatibility endpoint using the POST request method.

{{< api-endpoint endpoint="http://localhost:8086/query" method="post" api-ref="/influxdb/version/api/v1/#operation/PostQueryV1" >}}

Include the following with your request:

• Headers:

  • Authorization: Token <INFLUX_TOKEN>
  • Accept: application/json
  • (Optional) Accept-Encoding: gzip

• Query parameters:

  • db: Database to query.

  • rp: Retention policy to query data from.

  • q: InfluxQL query to execute.

  • epoch: (Optional) Return results with Unix timestamps of a specified precision instead of RFC3339 timestamps. The following precisions are available:

    • ns - nanoseconds
    • u or µ - microseconds
    • ms - milliseconds
    • s - seconds
    • m - minutes
    • h - hours

• Request body: Flux query as plain text

The following example uses cURL and the InfluxDB API to query data with InfluxQL:

curl --get "$INFLUX_HOST/query?org=$INFLUX_ORG&bucket=get-started" \
  --header "Authorization: Token $INFLUX_TOKEN" \
  --data-urlencode "db=get-started" \
  --data-urlencode "rp=autogen" \
  --data-urlencode "q=SELECT co,hum,temp,room FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z'"

{{% note %}} The InfluxDB /write 1.x compatibility endpoint returns query results in JSON format. {{% /note %}}

{{% /tab-content %}} {{< /tabs-wrapper >}}

InfluxQL query results

{{< expand-wrapper >}} {{% expand "View InfluxQL query results" %}}

{{% /expand %}} {{< /expand-wrapper >}}

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

Let's move on to more advanced data processing queries and automating queries with InfluxDB tasks.

{{< page-nav prev="/influxdb/version/get-started/write/" next="/influxdb/version/get-started/process/" keepTab=true >}}