Use the InfluxQL shell
Use the InfluxQL interactive shell to execute InfluxQL queries with InfluxDB.
- Map database and retention policies to buckets
- Download and install the influx CLI
- Start the InfluxQL shell
- Execute InfluxQL queries
- Use and configure display formats
- InfluxQL shell helper commands
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.
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 \ --activeStart 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_HOSTINFLUX_ORGorINFLUX_ORG_IDINFLUX_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 (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.
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.
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!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.