Documentation

InfluxDB OSS v2

Use the InfluxQL shell

This page documents an earlier version of InfluxDB OSS. InfluxDB 3 Core is the latest stable version.

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.

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.

    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 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.

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
InfluxQL

Was this page helpful?

Thank you for your feedback!

© 2025 InfluxData, Inc.

What is your InfluxDB OSS URL?

Customize your InfluxDB OSS URL and we’ll update code examples for you.

Default
Custom

For more information, see InfluxDB OSS URLs.

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

New in InfluxDB 3.5

Key enhancements in InfluxDB 3.5 and the InfluxDB 3 Explorer 1.3.

See the Blog Post

InfluxDB 3.5 is now available for both Core and Enterprise, introducing custom plugin repository support, enhanced operational visibility with queryable CLI parameters and manual node management, stronger security controls, and general performance improvements.

InfluxDB 3 Explorer 1.3 brings powerful new capabilities including Dashboards (beta) for saving and organizing your favorite queries, and cache querying for instant access to Last Value and Distinct Value caches—making Explorer a more comprehensive workspace for time series monitoring and analysis.

For more information, check out:

InfluxDB Docker latest tag changing to InfluxDB 3 Core

On February 3, 2026, the latest tag for InfluxDB Docker images will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments.

If using Docker to install and run InfluxDB, the latest tag will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments. For example, if using Docker to run InfluxDB v2, replace the latest version tag with a specific version tag in your Docker pull command–for example:

docker pull influxdb:2