Query data in InfluxDB 3 Cloud
InfluxDB 3 Cloud supports both native SQL and InfluxQL for querying data. InfluxQL is
an SQL-like query language designed for InfluxDB v1 and customized for time
series queries.
Flux, the language introduced in InfluxDB v2, is not supported in InfluxDB 3.
Query data with the influxdb3 CLI
To get started querying data in InfluxDB 3 Cloud, use the
influxdb3 query command
and provide the following:
-H, --host: The host URL of the server (default is http://127.0.0.1:8181)-d, --database: (Required) The name of the database to query-l, --language: The query language of the provided query string- SQL or InfluxQL query as a string
If the INFLUXDB3_AUTH_TOKEN environment variable defined in
Set up InfluxDB 3 Cloud
isn’t set in your environment, set it or provide your token using
the -t, --token option in your command.
To query the home sensor sample data you wrote in
Write data to InfluxDB 3 Cloud,
run the following command:
influxdb3 query \
--database DATABASE_NAME
\
"SELECT * FROM home ORDER BY time"
influxdb3 query \
--database DATABASE_NAME
\
--language influxql \
"SELECT * FROM home"
Replace DATABASE_NAME
with the name of the database to query.
To query from a specific time range, use the WHERE clause to designate the
boundaries of your time range.
influxdb3 query \
--database DATABASE_NAME
\
"SELECT * FROM home WHERE time >= now() - INTERVAL '7 days' ORDER BY time"
influxdb3 query \
--database DATABASE_NAME
\
--language influxql \
"SELECT * FROM home WHERE time >= now() - 7d"
Example queries
List tables in a database
Return the average temperature of all rooms
SELECT avg(temp) AS avg_temp FROM home
SELECT MEAN(temp) AS avg_temp FROM home
Return the average temperature of the kitchen
SELECT avg(temp) AS avg_temp FROM home WHERE room = 'Kitchen'
SELECT MEAN(temp) AS avg_temp FROM home WHERE room = 'Kitchen'
Query data from an absolute time range
SELECT
*
FROM
home
WHERE
time >= '2022-01-01T12:00:00Z'
AND time <= '2022-01-01T18:00:00Z'
SELECT
*
FROM
home
WHERE
time >= '2022-01-01T12:00:00Z'
AND time <= '2022-01-01T18:00:00Z'
Query data from a relative time range
SELECT
*
FROM
home
WHERE
time >= now() - INTERVAL '7 days'
SELECT
*
FROM
home
WHERE
time >= now() - 7d
Calculate average humidity in 3-hour windows per room
SELECT
date_bin(INTERVAL '3 hours', time) AS time,
room,
avg(hum) AS avg_hum
FROM
home
GROUP BY
1,
room
ORDER BY
room,
1
SELECT
MEAN(hum) AS avg_hum
FROM
home
WHERE
time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-01T20:00:00Z'
GROUP BY
time(3h),
room
Other tools are available for querying data in InfluxDB 3 Cloud, including
the following:
Query using the API
Query using the API
InfluxDB 3 supports Flight (gRPC) APIs and an HTTP API.
To query your database using the HTTP API, send a request to the /api/v3/query_sql or /api/v3/query_influxql endpoints.
In the request, specify the database name in the db parameter
and a query in the q parameter.
You can pass parameters in the query string or inside a JSON object.
Use the format parameter to specify the response format: pretty, jsonl, parquet, csv, and json. Default is json.
Example: Query passing URL-encoded parameters
The following example sends an HTTP GET request with a URL-encoded SQL query:
curl -G "https://instance-id.enterprise.influxdb.io/api/v3/query_sql" \
--header 'Authorization: Bearer AUTH_TOKEN
' \
--data-urlencode "db=DATABASE_NAME
" \
--data-urlencode "q=select * from cpu limit 5"
Replace the following placeholders with your values:
DATABASE_NAME: the name of the database to queryAUTH_TOKEN: your database token
with permission to query the specified database
Example: Query passing JSON parameters
The following example sends an HTTP POST request with parameters in a JSON payload:
curl https://instance-id.enterprise.influxdb.io/api/v3/query_sql \
--data '{"db": "DATABASE_NAME
", "q": "select * from cpu limit 5"}'
Replace the following placeholders with your values:
DATABASE_NAME: the name of the database to queryAUTH_TOKEN: your database token
with permission to query the specified database
Query using the Python client
Query using the Python client
Use the InfluxDB 3 Python library to interact with the database and integrate with your application.
We recommend installing the required packages in a Python virtual environment for your specific project.
To get started, install the influxdb3-python package.
pip install influxdb3-python
From here, you can connect to your database with the client library using just the host and **database name:
from influxdb_client_3 import InfluxDBClient3
client = InfluxDBClient3(
token='AUTH_TOKEN
',
host='https://instance-id.enterprise.influxdb.io',
database='DATABASE_NAME
'
)
Replace the following placeholders with your values:
DATABASE_NAME: the name of the database to queryAUTH_TOKEN: your database token
with permission to query the specified database
The following example shows how to query using SQL, and then
use PyArrow to explore the schema and process results.
To authorize the query, the example retrieves the database token
from the INFLUXDB3_AUTH_TOKEN environment variable.
from influxdb_client_3 import InfluxDBClient3
import os
client = InfluxDBClient3(
token=os.environ.get('INFLUXDB3_AUTH_TOKEN'),
host='https://instance-id.enterprise.influxdb.io',
database='servers'
)
# Execute the query and return an Arrow table
table = client.query(
query="SELECT * FROM cpu LIMIT 10",
language="sql"
)
print("\n#### View Schema information\n")
print(table.schema)
print("\n#### Use PyArrow to read the specified columns\n")
print(table.column('usage_active'))
print(table.select(['host', 'usage_active']))
print(table.select(['time', 'host', 'usage_active']))
print("\n#### Use PyArrow compute functions to aggregate data\n")
print(table.group_by('host').aggregate([]))
print(table.group_by('cpu').aggregate([('time_system', 'mean')]))
For more information about the Python client library, see the
influxdb3-python repository
in GitHub.
SQL vs InfluxQL
InfluxDB 3 Cloud supports two query languages–SQL and InfluxQL.
While these two query languages are similar, there are important differences to
consider.
SQL
The InfluxDB 3 SQL implementation provides a full-featured SQL query engine
powered by Apache DataFusion. InfluxDB extends
DataFusion with additional time series-specific functionality and supports the
complex SQL queries, including queries that use joins, unions, window functions,
and more.
InfluxQL
InfluxQL is a SQL-like query language built for InfluxDB v1 and supported in
InfluxDB 3 Cloud. Its syntax and functionality is similar SQL, but specifically
designed for querying time series data. InfluxQL does not offer the full range
of query functionality that SQL does.
If you are migrating from previous versions of InfluxDB, you can continue to use
InfluxQL and the established InfluxQL-related APIs you have been using.
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 3 Cloud and this documentation.
To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.
