Use the InfluxQL shell

Use the InfluxQL interactive shell to execute InfluxQL queries with InfluxDB.

Map database and retention policies to buckets

InfluxQL queries require a database and retention policy to query data. In InfluxDB 2.7, databases and retention policies have been combined and replaced with buckets. To use the InfluxQL to query an InfluxDB 2.7 bucket, first map your DBRP combinations to an appropriate bucket.

For information about creating DBRP mappings, see Query data with InfluxQL.

Download and install the influx CLI

The InfluxQL REPL is included in the influx CLI (2.4+). Download and install the influx CLI.

Start the InfluxQL shell

Use the influx v1 shell command to start an InfluxQL shell session.

  1. influx v1 shell

Configure your InfluxDB connection

The influx v1 shell command requires the following to connect to InfluxDB:

Use one of the following methods to provide these credentials to the influx v1 shell command:

CLI config (Recommended) Command flags Environment variables

The influx CLI lets your configure and store multiple sets of connection credentials to use with commands. Each set of credentials is a CLI config. Use CLI configs to provide required credentials to the influx v1 shell command.

  1. Create a new CLI config and set it to active.

    1. influx config create --config-name <config-name> \
    2.   --host-url http://localhost:8086 \
    3.   --org example-org \
    4.   --token mY5up3Rs3CrE7t0k3N \
    5.   --active

  2. Start an InfluxQL shell

    1. influx v1 shell

All influx commands use credentials provided by the active CLI config. For more information about managing CLI configs, see the influx config documentation.

Use influx v1 shell command flags to provide the required credentials:

  1. influx v1 shell \
  2.   --host http://localhost:8086 \
  3.   --org example-org \
  4.   --token mY5up3Rs3CrE7t0k3N

Use environment variables to provided the required credentials. The influx CLI will automatically use the following environment variables for required credentials if the environment variables are set:

  • INFLUX_HOST
  • INFLUX_ORG or INFLUX_ORG_ID
  • INFLUX_TOKEN
  1. export INFLUX_HOST=http://localhost:8086
  2. export INFLUX_ORG=example-org
  3. export INFLUX_TOKEN=mY5up3Rs3CrE7t0k3N
  5. influx v1 shell

Execute InfluxQL queries

Within the InfluxQL shell, execute any InfluxQL query supported by InfluxDB 2.7. For information about what queries are supported see InfluxQL support in InfluxDB 2.7.

View the InfluxQL documentation (1.11) for in-depth documentation about the query language.

Use and configure display formats

The InfluxQL shell outputs query results using different display formats. Use the format helper command to specify which display format to use.

table (default) column csv json

The InfluxQL shell uses the table display format by default. If using another display format and you want to switch back to the table format, run the following in the InfluxQL shell.

  1. format table

Table-formatted results

The table format outputs results in an interactive table format.

InfluxQL shell table display format

Results are paginated. Use shift + up/down arrow to navigate between pages. Use q to exit out of the interactive table display.

Configure the table display format

Use scientific notation

To display values using scientific notation, use the scientific helper command to toggle scientific notation.

Specify timestamp precision or format

To specify the precision or format of timestamps returned in results, use the precision helper command.

  1. -- Return results formatted as RFC3339 timestamps
  2. precision rfc3339
  4. -- Return results with second-precision unix timestamps
  5. precision s

To use the column format, run the following in the InfluxQL shell.

  1. format column

Column-formatted results

The column format displays results in a text-based column format.

  1. name: cpu
  2. time            usage_user          usage_system
  3. ----            ----------          ------------
  4. 1.62767581e+09  5.476026754935672   2.5629805588360313
  5. 1.62767581e+09  0.4999999999972715  0.09999999999990905
  6. 1.62767581e+09  18.718718718689555  10.810810810692704
  7. 1.62767581e+09  6.500000000090222   3.2000000000343425
  8. 1.62767581e+09  4.1999999999336435  1.3999999999778812
  9. 1.62767581e+09  7.992007992122577   4.095904095946467
  10. 1.62767581e+09  0.3000000000054934  0.1000000000010732

Configure the column display format

Specify timestamp precision

To specify the precision or format of timestamps returned in results, use the precision helper command.

  1. -- Return results formatted as RFC3339 timestamps
  2. precision rfc3339
  4. -- Return results with second-precision unix timestamps
  5. precision s

To use the csv format, run the following in the InfluxQL shell.

  1. format csv

CSV-formatted results

The csv format displays results in CSV format.

  1. name,time,usage_user,usage_system
  2. cpu,1.62767582e+09,4.207038819798416,3.5194098893833914
  3. cpu,1.62767582e+09,0.19980019980215585,0.19980019980215585
  4. cpu,1.62767582e+09,14.914914914981258,14.114114114162232
  5. cpu,1.62767582e+09,5.805805805828698,4.004004003985887
  6. cpu,1.62767582e+09,2.5025025025339978,1.8018018018273916
  7. cpu,1.62767582e+09,7.299999999874271,5.699999999930733
  8. cpu,1.62767582e+09,0.09999999999647116,0.0999999999987449

Configure the CSV display format

Specify timestamp precision

To specify the precision or format of timestamps returned in results, use the precision helper command.

  1. -- Return results formatted as RFC3339 timestamps
  2. precision rfc3339
  4. -- Return results with second-precision unix timestamps
  5. precision s

To use the json format, run the following in the InfluxQL shell.

  1. format json

JSON-formatted results

The csv format displays results in JSON format.

  1. {
  2.     "results": [
  3.         {
  4.             "series": [
  5.                 {
  6.                     "columns": [
  7.                         "time",
  8.                         "usage_user",
  9.                         "usage_system"
  10.                     ],
  11.                     "name": "cpu",
  12.                     "values": [
  13.                         [
  14.                             1627675850,
  15.                             4.601935685334947,
  16.                             4.139868872973054
  17.                         ],
  18.                         [
  19.                             1627675850,
  20.                             0.3992015968099201,
  21.                             0.2994011976074401
  22.                         ],
  23.                         [
  24.                             1627675850,
  25.                             7.599999999947613,
  26.                             7.299999999995634
  27.                         ],
  28.                         [
  29.                             1627675850,
  30.                             0.3992015968098205,
  31.                             0.4990019960088718
  32.                         ],
  33.                         [
  34.                             1627675850,
  35.                             9.59040959050348,
  36.                             8.49150849158481
  37.                         ],
  38.                         [
  39.                             1627675850,
  40.                             0.2997002996974768,
  41.                             0.39960039959966437
  42.                         ],
  43.                         [
  44.                             1627675850,
  45.                             9.590409590464631,
  46.                             8.691308691326773
  47.                         ]
  48.                     ]
  49.                 }
  50.             ],
  51.             "statement_id": 0
  52.         }
  53.     ]
  54. }

Configure the JSON display format

Pretty print JSON output

By default, the json display format returns an unformatted JSON string. To format the JSON, use the pretty helper command to toggle JSON pretty printing.

Specify timestamp precision

To specify the precision or format of timestamps returned in results, use the precision helper command.

  1. -- Return results formatted as RFC3339 timestamps
  2. precision rfc3339
  4. -- Return results with second-precision unix timestamps
  5. precision s

InfluxQL shell helper commands

The InfluxQL shell supports the following helper commands:

clear

Clear session based-settings such as database.

exit

Exit the InfluxQL shell.

format

Specify the data display format. The InfluxQL supports the following display formats:

  • csv
  • json
  • column
  • table (default)
  1. -- Display query output using column display
  2. format column

For more information, see Use and configure display formats.

gopher

Print the Go gopher.

help

Print the InfluxQL shell help options.

history

View the InfluxQL shell history.

precision

Specify the format or precision of timestamps. Use one of the following:

  • rfc3339
  • h
  • m
  • s
  • ms
  • u
  • ns (default)
  1. -- Set timestamp precision to seconds
  2. precision s

pretty

Toggle “pretty print” for the json display format.

quit

Exit the InfluxQL shell

scientific

Toggle scientific number format for the table display format.

use

Set the database and retention policy (optional) to use for queries.

  1. -- Use the exampledb database
  2. use exampledb
  4. -- Use the exampledb database and examplerp retention policy
  5. use exampledb.examplerp

InfluxQL