Documentation

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 Cloud, databases and retention policies have been combined and replaced with buckets. To use the InfluxQL to query an InfluxDB Cloud 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.

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:

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.

    influx config create --config-name <config-name> \
      --host-url http://localhost:8086 \
      --org example-org \
      --token mY5up3Rs3CrE7t0k3N \
      --active
    
  2. Start an InfluxQL shell

    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:

influx v1 shell \
  --host http://localhost:8086 \
  --org example-org \
  --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
export INFLUX_HOST=http://localhost:8086
export INFLUX_ORG=example-org
export INFLUX_TOKEN=mY5up3Rs3CrE7t0k3N

influx v1 shell

Execute InfluxQL queries

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

View the InfluxQL documentation (InfluxDB 1.8) 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.

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.

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.

-- Return results formatted as RFC3339 timestamps
precision rfc3339

-- Return results with second-precision unix timestamps
precision s

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

format column

Column-formatted results

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

name: cpu
time            usage_user          usage_system
----            ----------          ------------
1.62767581e+09  5.476026754935672   2.5629805588360313
1.62767581e+09  0.4999999999972715  0.09999999999990905
1.62767581e+09  18.718718718689555  10.810810810692704
1.62767581e+09  6.500000000090222   3.2000000000343425
1.62767581e+09  4.1999999999336435  1.3999999999778812
1.62767581e+09  7.992007992122577   4.095904095946467
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.

-- Return results formatted as RFC3339 timestamps
precision rfc3339

-- Return results with second-precision unix timestamps
precision s

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

format csv

CSV-formatted results

The csv format displays results in CSV format.

name,time,usage_user,usage_system
cpu,1.62767582e+09,4.207038819798416,3.5194098893833914
cpu,1.62767582e+09,0.19980019980215585,0.19980019980215585
cpu,1.62767582e+09,14.914914914981258,14.114114114162232
cpu,1.62767582e+09,5.805805805828698,4.004004003985887
cpu,1.62767582e+09,2.5025025025339978,1.8018018018273916
cpu,1.62767582e+09,7.299999999874271,5.699999999930733
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.

-- Return results formatted as RFC3339 timestamps
precision rfc3339

-- Return results with second-precision unix timestamps
precision s

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

format json

JSON-formatted results

The csv format displays results in JSON format.

{
    "results": [
        {
            "series": [
                {
                    "columns": [
                        "time",
                        "usage_user",
                        "usage_system"
                    ],
                    "name": "cpu",
                    "values": [
                        [
                            1627675850,
                            4.601935685334947,
                            4.139868872973054
                        ],
                        [
                            1627675850,
                            0.3992015968099201,
                            0.2994011976074401
                        ],
                        [
                            1627675850,
                            7.599999999947613,
                            7.299999999995634
                        ],
                        [
                            1627675850,
                            0.3992015968098205,
                            0.4990019960088718
                        ],
                        [
                            1627675850,
                            9.59040959050348,
                            8.49150849158481
                        ],
                        [
                            1627675850,
                            0.2997002996974768,
                            0.39960039959966437
                        ],
                        [
                            1627675850,
                            9.590409590464631,
                            8.691308691326773
                        ]
                    ]
                }
            ],
            "statement_id": 0
        }
    ]
}

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.

-- Return results formatted as RFC3339 timestamps
precision rfc3339

-- Return results with second-precision unix timestamps
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)
-- Display query output using column display
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)
-- Set timestamp precision to seconds
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.

-- Use the exampledb database
use exampledb

-- Use the exampledb database and examplerp retention policy
use exampledb.examplerp

Was this page helpful?

Thank you for your feedback!


Select your region

Upgrade to InfluxDB Cloud or InfluxDB 2.0!

InfluxDB Cloud and InfluxDB OSS 2.0 ready for production.