---
title: Query data in InfluxDB 3 Enterprise
description: Learn how to get started querying data in InfluxDB 3 Enterprise using native SQL or InfluxQL with the influxdb3 CLI and other tools.
url: https://docs.influxdata.com/influxdb3/enterprise/get-started/query/
estimated_tokens: 9791
product: InfluxDB 3 Enterprise
version: enterprise
---

# Query data in InfluxDB 3 Enterprise

InfluxDB 3 Enterprise 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](#query-data-with-the-influxdb3-cli)
    -   [Example queries](#example-queries)
-   [Other tools for executing queries](#other-tools-for-executing-queries)
-   [SQL vs InfluxQL](#sql-vs-influxql)
    -   [SQL](#sql)
    -   [InfluxQL](#influxql)
-   [Optimize queries](#optimize-queries)
    -   [Last values cache](#last-values-cache)
    -   [Distinct values cache](#distinct-values-cache)
-   [File indexes](#file-indexes)

## Query data with the influxdb3 CLI

To get started querying data in InfluxDB 3 Enterprise, use the [`influxdb3 query` command](/influxdb3/enterprise/reference/cli/influxdb3/query/) 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` *(default)*
    -   `influxql`
-   SQL or InfluxQL query as a string

If the `INFLUXDB3_AUTH_TOKEN` environment variable defined in [Set up InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/setup/#set-your-token-for-authorization) 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 Enterprise](/influxdb3/enterprise/get-started/write/#write-data-using-the-cli), run the following command:

<!-- Tabbed content: Select one of the following options -->

**SQL:**

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

**InfluxQL:**

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

<!-- End tabbed content -->

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

<!-- Tabbed content: Select one of the following options -->

**SQL:**

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

**InfluxQL:**

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

<!-- End tabbed content -->

### Example queries

[](#list-tables-in-a-database)

List tables in a database

<!-- Tabbed content: Select one of the following options -->

**SQL:**

```sql
SHOW TABLES
```

**InfluxQL:**

```sql
SHOW MEASUREMENTS
```

<!-- End tabbed content -->

[](#return-the-average-temperature-of-all-rooms)

Return the average temperature of all rooms

<!-- Tabbed content: Select one of the following options -->

**SQL:**

```sql
SELECT avg(temp) AS avg_temp FROM home
```

**InfluxQL:**

```sql
SELECT MEAN(temp) AS avg_temp FROM home
```

<!-- End tabbed content -->

[](#return-the-average-temperature-of-the-kitchen)

Return the average temperature of the kitchen

<!-- Tabbed content: Select one of the following options -->

**SQL:**

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

**InfluxQL:**

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

<!-- End tabbed content -->

[](#query-data-from-an-absolute-time-range)

Query data from an absolute time range

<!-- Tabbed content: Select one of the following options -->

**SQL:**

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

**InfluxQL:**

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

<!-- End tabbed content -->

[](#query-data-from-a-relative-time-range)

Query data from a relative time range

<!-- Tabbed content: Select one of the following options -->

**SQL:**

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

**InfluxQL:**

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

<!-- End tabbed content -->

[](#calculate-average-humidity-in-3-hour-windows-per-room)

Calculate average humidity in 3-hour windows per room

<!-- Tabbed content: Select one of the following options -->

**SQL:**

```sql
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
```

**InfluxQL:**

```sql
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
```

<!-- End tabbed content -->

## Other tools for executing queries

Other tools are available for querying data in InfluxDB 3 Enterprise, including the following:

[](#query-using-the-api)

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:

```bash
curl -G "http://localhost:8181/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 query
-   `AUTH_TOKEN`: your [database token](/influxdb3/enterprise/admin/tokens/) 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:

```bash
curl http://localhost:8181/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 query
-   `AUTH_TOKEN`: your [database token](/influxdb3/enterprise/admin/tokens/) with permission to query the specified database

[](#query-using-the-python-client)

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.

```bash
pip install influxdb3-python
```

From here, you can connect to your database with the client library using just the **host** and \*\*database name:

```python
from influxdb_client_3 import InfluxDBClient3

client = InfluxDBClient3(
    token='AUTH_TOKEN',
    host='http://localhost:8181',
    database='DATABASE_NAME'
)
```

Replace the following placeholders with your values:

-   `DATABASE_NAME`: the name of the database to query
-   `AUTH_TOKEN`: your [database token](/influxdb3/enterprise/admin/tokens/) 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](/influxdb3/enterprise/admin/tokens/)

from the `INFLUXDB3_AUTH_TOKEN` environment variable.

```python
from influxdb_client_3 import InfluxDBClient3
import os

client = InfluxDBClient3(
    token=os.environ.get('INFLUXDB3_AUTH_TOKEN'),
    host='http://localhost:8181',
    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](https://github.com/InfluxCommunity/influxdb3-python) in GitHub.

[](#query-using-influxdb-3-explorer)

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 InfluxDB 3 Enterprise instance. For more information, see how to [install InfluxDB 3 Explorer](/influxdb3/explorer/install/) using Docker and get started querying your data.

## SQL vs InfluxQL

InfluxDB 3 Enterprise 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](https://datafusion.apache.org/). 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.

-   [SQL query guides](/influxdb3/enterprise/query-data/sql/)
-   [SQL reference](/influxdb3/enterprise/reference/sql/)
-   [Apache DataFusion SQL reference](https://datafusion.apache.org/user-guide/sql/index.html)

### InfluxQL

InfluxQL is a SQL-like query language built for InfluxDB v1 and supported in InfluxDB 3 Enterprise. 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.

-   [InfluxQL query guides](/influxdb3/enterprise/query-data/influxql/)
-   [InfluxQL reference](/influxdb3/enterprise/reference/influxql/)
-   [InfluxQL feature support](/influxdb3/enterprise/reference/influxql/feature-support/)

## Optimize queries

InfluxDB 3 Enterprise provides the following optimization options to improve specific kinds of queries:

-   [Last values cache](#last-values-cache)
-   [Distinct values cache](#distinct-values-cache)
-   [File indexes](#file-indexes)

### Last values cache

The InfluxDB 3 Enterprise 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:

-   [Manage a last values cache](/influxdb3/enterprise/admin/last-value-cache/)
-   [Query the last values cache](/influxdb3/enterprise/admin/last-value-cache/query/)

### Distinct values cache

The InfluxDB 3 Enterprise 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:

-   [Manage a distinct values cache](/influxdb3/enterprise/admin/distinct-value-cache/)
-   [Query the distinct values cache](/influxdb3/enterprise/admin/distinct-value-cache/query/)

### File indexes

InfluxDB 3 Enterprise 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](/influxdb3/enterprise/admin/file-index/).

[Write data](/influxdb3/enterprise/get-started/write/) [Processing engine](/influxdb3/enterprise/get-started/process/)

#### Related

-   [Query data in InfluxDB 3 Enterprise](/influxdb3/enterprise/query-data/)
-   [SQL reference documentation](/influxdb3/enterprise/reference/sql/)
-   [Apache DataFusion SQL reference](https://datafusion.apache.org/user-guide/sql/index.html)
-   [InfluxQL reference documentation](/influxdb3/enterprise/reference/influxql/)