Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
docs-v2/content/shared/influxdb3-get-started/query.md

14 KiB
Raw Blame History

{{% product-name %}} 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.

{{% show-in "core" %}} {{< product-name >}} limits query time ranges to approximately 72 hours (both recent and historical) to ensure query performance. For more information about the 72-hour limitation, see the update on InfluxDB 3 Core’s 72-hour limitation. {{% /show-in %}}

[!Note] 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 {{% product-name %}}, 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: ({{% req %}}) The name of the database to query
  • -l, --language: The query language of the provided query string
    • sql (default)
    • influxql
  • SQL or InfluxQL query as a string

[!Important] If the INFLUXDB3_AUTH_TOKEN environment variable defined in Set up {{% product-name %}} 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 {{% product-name %}}, run the following command:

{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} SQL InfluxQL {{% /code-tabs %}} {{% code-tab-content %}}

influxdb3 query \
  --database DATABASE_NAME \
  "SELECT * FROM home ORDER BY time"

{{% /code-tab-content %}} {{% code-tab-content %}}

influxdb3 query \
  --database DATABASE_NAME \
  --language influxql \
  "SELECT * FROM home"

{{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

{{% /code-placeholders %}}

Replace {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}} 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.

{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} SQL InfluxQL {{% /code-tabs %}} {{% code-tab-content %}}

influxdb3 query \
  --database DATABASE_NAME \
  "SELECT * FROM home WHERE time >= now() - INTERVAL '7 days' ORDER BY time"

{{% /code-tab-content %}} {{% code-tab-content %}}

influxdb3 query \
  --database DATABASE_NAME \
  --language influxql \
  "SELECT * FROM home WHERE time >= now() - 7d"

{{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

{{% /code-placeholders %}}

Example queries

{{< expand-wrapper >}} {{% expand "List tables in a database" %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} SQL InfluxQL {{% /code-tabs %}} {{% code-tab-content %}}

SHOW TABLES

{{% /code-tab-content %}} {{% code-tab-content %}}

SHOW MEASUREMENTS

{{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

{{% /expand %}} {{% expand "Return the average temperature of all rooms" %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} SQL InfluxQL {{% /code-tabs %}} {{% code-tab-content %}}

SELECT avg(temp) AS avg_temp FROM home

{{% /code-tab-content %}} {{% code-tab-content %}}

SELECT MEAN(temp) AS avg_temp FROM home

{{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

{{% /expand %}} {{% expand "Return the average temperature of the kitchen" %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} SQL InfluxQL {{% /code-tabs %}} {{% code-tab-content %}}

SELECT avg(temp) AS avg_temp FROM home WHERE room = 'Kitchen'

{{% /code-tab-content %}} {{% code-tab-content %}}

SELECT MEAN(temp) AS avg_temp FROM home WHERE room = 'Kitchen'

{{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

{{% /expand %}} {{% expand "Query data from an absolute time range" %}}

{{% influxdb/custom-timestamps %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} SQL InfluxQL {{% /code-tabs %}} {{% code-tab-content %}}

SELECT
  *
FROM
  home
WHERE
  time >= '2022-01-01T12:00:00Z'
  AND time <= '2022-01-01T18:00:00Z'

{{% /code-tab-content %}} {{% code-tab-content %}}

SELECT
  *
FROM
  home
WHERE
  time >= '2022-01-01T12:00:00Z'
  AND time <= '2022-01-01T18:00:00Z'

{{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

{{% /influxdb/custom-timestamps %}}

{{% /expand %}} {{% expand "Query data from a relative time range" %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} SQL InfluxQL {{% /code-tabs %}} {{% code-tab-content %}}

SELECT
  *
FROM
  home
WHERE
  time >= now() - INTERVAL '7 days'

{{% /code-tab-content %}} {{% code-tab-content %}}

SELECT
  *
FROM
  home
WHERE
  time >= now() - 7d

{{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

{{% /expand %}} {{% expand "Calculate average humidity in 3-hour windows per room" %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} SQL InfluxQL {{% /code-tabs %}} {{% code-tab-content %}}

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

{{% /code-tab-content %}} {{% code-tab-content %}}

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

{{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

{{% /expand %}} {{< /expand-wrapper >}}

Other tools for executing queries

Other tools are available for querying data in {{% product-name %}}, including the following:

{{< expand-wrapper >}} {{% expand "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:

{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}

curl -G "http://{{< influxdb/host >}}/api/v3/query_sql" \
  --header 'Authorization: Bearer AUTH_TOKEN' \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "q=select * from cpu limit 5"

{{% /code-placeholders %}}

Replace the following placeholders with your values:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: the name of the database to query
  • {{% code-placeholder-key %}}AUTH_TOKEN{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}}
Example: Query passing JSON parameters

The following example sends an HTTP POST request with parameters in a JSON payload:

{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}

curl http://{{< influxdb/host >}}/api/v3/query_sql \
  --data '{"db": "DATABASE_NAME", "q": "select * from cpu limit 5"}'

{{% /code-placeholders %}}

Replace the following placeholders with your values:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: the name of the database to query
  • {{% code-placeholder-key %}}AUTH_TOKEN{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}}

{{% /expand %}}

{{% expand "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:

{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}

from influxdb_client_3 import InfluxDBClient3

client = InfluxDBClient3(
    token='AUTH_TOKEN',
    host='http://{{< influxdb/host >}}',
    database='DATABASE_NAME'
)

{{% /code-placeholders %}}

Replace the following placeholders with your values:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: the name of the database to query
  • {{% code-placeholder-key %}}AUTH_TOKEN{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}}

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 {{% token-link "database" %}} 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='http://{{< influxdb/host >}}',
    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.

{{% /expand %}}

{{% expand "Query using InfluxDB 3 Explorer" %}}

Query using InfluxDB 3 Explorer

You can use the InfluxDB 3 Explorer web-based interface to query and visualize data, and administer your {{% product-name %}} instance. For more information, see how to install InfluxDB 3 Explorer using Docker and get started querying your data.

{{% /expand %}} {{< /expand-wrapper >}}

SQL vs InfluxQL

{{% product-name %}} 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 {{% product-name %}}. 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.

Optimize queries

{{% product-name %}} provides the following optimization options to improve specific kinds of queries:

Last values cache

The {{% product-name %}} last values cache (LVC) stores the last N values in a series or column hierarchy in memory. This gives the database the ability to answer these kinds of queries in under 10 milliseconds. For information about configuring and using the LVC, see:

Distinct values cache

The {{% product-name %}} distinct values cache (DVC) stores distinct values for specified columns in a series or column hierarchy in memory. This is useful for fast metadata lookups, which can return in under 30 milliseconds. For information about configuring and using the DVC, see:

{{% show-in "enterprise" %}}

File indexes

{{% product-name %}} lets you customize how your data is indexed to help optimize query performance for your specific workload, especially workloads that include single-series queries. Define custom indexing strategies for databases or specific tables. For more information, see Manage file indexes.

{{% /show-in %}}

{{% page-nav prev="/influxdb3/version/get-started/write/" prevText="Write data" next="/influxdb3/version/get-started/process/" nextText="Processing engine" %}}