content/shared/influxdb-v2/tools/influxql-shell.md
Use the InfluxQL interactive shell to execute InfluxQL queries with InfluxDB.
InfluxQL queries require a database and retention policy to query data. In InfluxDB {{% current-version %}}, databases and retention policies have been combined and replaced with buckets. To use the InfluxQL to query an InfluxDB {{% current-version %}} bucket, first map your DBRP combinations to an appropriate bucket.
For information about creating DBRP mappings, see Query data with InfluxQL.
The InfluxQL REPL is included in the influx CLI (2.4+).
Download and install the influx CLI.
Use the influx v1 shell command
to start an InfluxQL shell session.
influx v1 shell
The influx v1 shell command requires the following to connect to InfluxDB:
{{% show-in "v2" %}}- InfluxDB host{{% /show-in %}} {{% show-in "cloud,cloud-serverless" %}}InfluxDB Cloud region URL{{% /show-in %}}
Use one of the following methods to provide these credentials to the influx v1 shell command:
{{< tabs-wrapper >}} {{% tabs "small" %}} CLI config (Recommended) Command flags Environment variables {{% /tabs %}} {{% tab-content %}}
<!------------------------------ BEGIN CLI config ----------------------------->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.
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
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.
{{% /tab-content %}} {{% tab-content %}}
<!---------------------------- BEGIN command flags ---------------------------->Use influx v1 shell command flags to provide the required credentials:
influx v1 shell \
--host http://localhost:8086 \
--org example-org \
--token mY5up3Rs3CrE7t0k3N
{{% /tab-content %}} {{% tab-content %}}
<!------------------------ BEGIN environment variables ------------------------>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_HOSTINFLUX_ORG or INFLUX_ORG_IDINFLUX_TOKENexport INFLUX_HOST=http://localhost:8086
export INFLUX_ORG=example-org
export INFLUX_TOKEN=mY5up3Rs3CrE7t0k3N
influx v1 shell
{{% /tab-content %}} {{< /tabs-wrapper >}}
Within the InfluxQL shell, execute any InfluxQL query supported by InfluxDB {{< current-version >}}. For information about what queries are supported see InfluxQL support in InfluxDB {{< current-version >}}.
View the InfluxQL documentation (1.11) for in-depth documentation about the query language.
The InfluxQL shell outputs query results using different display formats.
Use the format helper command to specify which display format to use.
{{< tabs-wrapper >}} {{% tabs %}} table (default) column csv json {{% /tabs %}} {{% tab-content %}}
<!-------------------------------- BEGIN table -------------------------------->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
The table format outputs results in an interactive table format.
{{< img-hd src="/img/influxdb/2-4-influxql-shell-table-format.png" alt="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.
To display values using scientific notation, use the scientific helper command
to toggle scientific notation.
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
{{% /tab-content %}} {{% tab-content %}}
<!-------------------------------- BEGIN column ------------------------------->To use the column format, run the following in the InfluxQL shell.
format column
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
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
{{% /tab-content %}} {{% tab-content %}}
<!--------------------------------- BEGIN csv --------------------------------->To use the csv format, run the following in the InfluxQL shell.
format csv
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
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
{{% /tab-content %}} {{% tab-content %}}
<!--------------------------------- BEGIN json -------------------------------->To use the json format, run the following in the InfluxQL shell.
format json
The csv format displays results in JSON format.
{{% truncate %}}
{
"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
}
]
}
{{% /truncate %}}
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.
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
{{% /tab-content %}} {{< /tabs-wrapper >}}
The InfluxQL shell supports the following helper commands:
Clear session based-settings such as database.
Exit the InfluxQL shell.
Specify the data display format. The InfluxQL supports the following display formats:
-- Display query output using column display
format column
For more information, see Use and configure display formats.
Print the Go gopher.
Print the InfluxQL shell help options.
View the InfluxQL shell history.
Specify the format or precision of timestamps. Use one of the following:
-- Set timestamp precision to seconds
precision s
Toggle "pretty print" for the json display format.
Exit the InfluxQL shell
Toggle scientific number format for the table display format.
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