Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

4999 fix headings (#5006) 

* fix(dedicated): Replace expandable code samples with headings (#4999)

* fix(dedicated): Use example measurement name.

* fix(v3): v3 Python client library references, replace expands with headings (#4999)
pull/4994/head^2
Jason Stirnaman 2023-06-30 15:07:55 -05:00 committed by GitHub
parent 3211476eb5
commit ef1958fbe1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 154 additions and 180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
content/influxdb/cloud-dedicated/get-started/query.md
View File

@ -4,7 +4,7 @@ seotitle: Query data | Get started with InfluxDB Cloud Dedicated
list_title: Query data list_title: Query data
description: > description: >
Get started querying data in InfluxDB Cloud Dedicated by learning about SQL and Get started querying data in InfluxDB Cloud Dedicated by learning about SQL and
InfluxQL and using tools like InfluxDB client libraries and Flight SQL clients. InfluxQL, and using tools like InfluxDB client libraries.
menu: menu:
influxdb_cloud_dedicated: influxdb_cloud_dedicated:
name: Query data name: Query data
@ -23,8 +23,7 @@ related:
- **SQL**: Traditional SQL powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) - **SQL**: Traditional SQL powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/)
query engine. The supported SQL syntax is similar to PostgreSQL. query engine. The supported SQL syntax is similar to PostgreSQL.
- **InfluxQL**: An SQL-like query language designed to query time series data from - **InfluxQL**: An SQL-like query language designed to query time series data stored in InfluxDB.
InfluxDB.
This tutorial walks you through the fundamentals of querying data in InfluxDB and This tutorial walks you through the fundamentals of querying data in InfluxDB and
**focuses on using SQL** to query your time series data. **focuses on using SQL** to query your time series data.
@ -45,7 +44,7 @@ The examples in this section of the tutorial query the
{{% cloud-name %}} supports many different tools for querying data, including: {{% cloud-name %}} supports many different tools for querying data, including:
{{< req type="key" text="Covered in this tutorial" color="magenta" >}} {{< req type="key" text="Covered in this tutorial" color="magenta" >}}
- [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req "\* " >}}
- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) - [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
- [Flight SQL clients](?t=Go#execute-an-sql-query){{< req "\* " >}} - [Flight SQL clients](?t=Go#execute-an-sql-query){{< req "\* " >}}
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/) - [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
@ -55,7 +54,7 @@ The examples in this section of the tutorial query the
## SQL query basics ## SQL query basics
InfluxDB Cloud's SQL implementation is powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) The {{% cloud-name %}} SQL implementation is powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/)
query engine which provides an SQL syntax similar to PostgreSQL. query engine which provides an SQL syntax similar to PostgreSQL.
{{% note %}} {{% note %}}
@ -95,16 +94,15 @@ GROUP BY
``` ```
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
##### Example SQL queries #### Example SQL queries
##### Select all data in a measurement
{{< expand-wrapper >}}
{{% expand "Select all data in a measurement" %}}
```sql ```sql
SELECT * FROM measurement SELECT * FROM home
``` ```
{{% /expand %}}
{{% expand "Select all data in a measurement within time bounds" %}} ##### Select all data in a measurement within time bounds
```sql ```sql
SELECT SELECT
* *
@ -114,27 +112,23 @@ WHERE
time >= '2022-01-01T08:00:00Z' time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-01T20:00:00Z' AND time <= '2022-01-01T20:00:00Z'
``` ```
{{% /expand %}}
{{% expand "Select a specific field within relative time bounds" %}} ##### Select a specific field within relative time bounds
```sql ```sql
SELECT temp FROM home WHERE time >= now() - INTERVAL '1 day' SELECT temp FROM home WHERE time >= now() - INTERVAL '1 day'
``` ```
{{% /expand %}}
{{% expand "Select specific fields and tags from a measurement" %}} ##### Select specific fields and tags from a measurement
```sql ```sql
SELECT temp, room FROM home SELECT temp, room FROM home
``` ```
{{% /expand %}}
{{% expand "Select data based on tag value" %}} ##### Select data based on tag value
```sql ```sql
SELECT * FROM home WHERE room = 'Kitchen' SELECT * FROM home WHERE room = 'Kitchen'
``` ```
{{% /expand %}}
{{% expand "Select data based on tag value within time bounds" %}} ##### Select data based on tag value within time bounds
```sql ```sql
SELECT SELECT
* *
@ -145,9 +139,8 @@ WHERE
AND time <= '2022-01-01T20:00:00Z' AND time <= '2022-01-01T20:00:00Z'
AND room = 'Living Room' AND room = 'Living Room'
``` ```
{{% /expand %}}
{{% expand "Downsample data by applying interval-based aggregates" %}} ##### Downsample data by applying interval-based aggregates
```sql ```sql
SELECT SELECT
DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time, DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time,
@ -161,15 +154,13 @@ GROUP BY
room room
ORDER BY room, _time ORDER BY room, _time
``` ```
{{% /expand %}}
{{< /expand-wrapper >}}
### Execute an SQL query ### Execute an SQL query
Get started with one of the following tools for querying data stored in an {{% cloud-name %}} database: Get started with one of the following tools for querying data stored in an {{% cloud-name %}} database:
- **Flight SQL clients**: Use language-specific (Python, Go, etc.) clients to execute queries in your terminal or custom code. - **InfluxDB v3 client libraries**: Use language-specific (Python, Go, etc.) clients to execute queries in your terminal or custom code.
- **influx3 CLI**: Send SQL queries from your terminal command-line. - **influx3 CLI**: Send queries from your terminal command-line.
- **Grafana**: Query InfluxDB v3 with the [FlightSQL Data Source plugin](https://grafana.com/grafana/plugins/influxdata-flightsql-datasource/) and connect and visualize data. - **Grafana**: Query InfluxDB v3 with the [FlightSQL Data Source plugin](https://grafana.com/grafana/plugins/influxdata-flightsql-datasource/) and connect and visualize data.
For this example, use the following query to select all the data written to the For this example, use the following query to select all the data written to the
@ -200,7 +191,7 @@ WHERE
<!--------------------------- BEGIN influx3 CONTENT ---------------------------> <!--------------------------- BEGIN influx3 CONTENT --------------------------->
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
Query InfluxDB v3 using SQL and the `influx3` CLI. Query InfluxDB v3 using SQL and the [`influx3` CLI](https://github.com/InfluxCommunity/influxdb3-python-cli).
The following steps include setting up a Python virtual environment already The following steps include setting up a Python virtual environment already
covered in [Get started writing data](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb). covered in [Get started writing data](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb).
@ -213,20 +204,22 @@ _If your project's virtual environment is already running, skip to step 3._
python -m venv envs/virtual-env python -m venv envs/virtual-env
``` ```
2. Activate the virtual environment. 2. Activate the virtual environment.
```sh ```sh
source ./envs/virtual-env/bin/activate source ./envs/virtual-env/bin/activate
``` ```
3. Install the following dependencies: 3. Install the CLI package (already installed in the [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb)).
{{< req type="key" text="Already installed in the [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" >}} ```sh
pip install influxdb3-python-cli
```
- `pyarrow` {{< req text="\*" color="magenta" >}} Installing `influxdb3-python-cli` also installs the
- `influxdb3-python-cli` {{< req text="\*" color="magenta" >}} [`pyarrow`](https://arrow.apache.org/docs/python/index.html) library for working with Arrow data returned from queries.
4. Create the `config.json` configuration. 4. Create the `config.json` configuration.
<!-- code-placeholders breaks when indented here --> <!-- code-placeholders breaks when indented here -->
```sh ```sh
@ -244,7 +237,7 @@ _If your project's virtual environment is already running, skip to step 3._
read access to the **get-started** database read access to the **get-started** database
- **`ORG_ID`**: any non-empty string (InfluxDB ignores this parameter, but the client requires it) - **`ORG_ID`**: any non-empty string (InfluxDB ignores this parameter, but the client requires it)
5. Enter the `influx3 sql` command and your SQL query statement. 5. Enter the `influx3 sql` command and your SQL query statement.
```sh ```sh
influx3 sql "SELECT * influx3 sql "SELECT *
@ -255,26 +248,23 @@ _If your project's virtual environment is already running, skip to step 3._
`influx3` displays query results in your terminal. `influx3` displays query results in your terminal.
For more information about the `influx3` CLI, see the [`InfluxCommunity/
influxdb3-python-cli
`](https://github.com/InfluxCommunity/influxdb3-python-cli) community repository on GitHub.
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
<!--------------------------- END influx3 CONTENT ---------------------------> <!--------------------------- END influx3 CONTENT --------------------------->
{{% /tab-content %}} {{% /tab-content %}}
{{% tab-content %}} {{% tab-content %}}
<!--------------------------- BEGIN PYTHON CONTENT ----------------------------> <!--------------------------- BEGIN PYTHON CONTENT ---------------------------->
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
To query data from {{% cloud-name %}} using Python, use the Use the `influxdb_client_3` module to integrate {{< cloud-name >}} with your Python code.
[`influxdb_client_3` module](https://github.com/InfluxCommunity/influxdb3-python). This module supports writing data to InfluxDB and querying data using SQL or InfluxQL.
The following steps include setting up a Python virtual environment already The following steps include setting up a Python virtual environment already
covered in [Get started writing data](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb). covered in [Get started writing data](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb).
_If your project's virtual environment is already running, skip to step 3._ _If your project's virtual environment is already running, skip to step 3._
1. In the `influxdb_py_client` module directory you created in the 1. Open a terminal in the `influxdb_py_client` module directory you created in the
[Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb): [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb):
1. Setup your Python virtual environment. 1. To create your Python virtual environment, enter the following command in your terminal:
Inside of your module directory:
```sh ```sh
python -m venv envs/virtual-env python -m venv envs/virtual-env
@ -290,16 +280,17 @@ _If your project's virtual environment is already running, skip to step 3._
{{< req type="key" text="Already installed in the [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" >}} {{< req type="key" text="Already installed in the [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" >}}
- `pyarrow` {{< req text="\*" color="magenta" >}} - `influxdb3-python`{{< req text="\* " color="magenta" >}}: Provides the `influxdb_client_3` module and also installs the [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries.
- `influxdb_client_3` {{< req text="\*" color="magenta" >}} - `pandas`: Provides [pandas modules](https://pandas.pydata.org/) for analyzing and manipulating data.
- `pandas` - `tabulate`: Provides the [`tabulate` function](https://pypi.org/project/tabulate/) for formatting tabular data.
- `tabulate` _(to return formatted tables)_
Enter the following command in your terminal:
```sh ```sh
pip install influxdb_client_3 pandas tabulate pip install influxdb3-python pandas tabulate
``` ```
4. In your terminal or editor, create a new file for your code--for example: `query.py`. 4. In your terminal or editor, create a new file for your code--for example: `query.py`.
2. In `query.py`, enter the following sample code: 2. In `query.py`, enter the following sample code:
@ -307,7 +298,7 @@ _If your project's virtual environment is already running, skip to step 3._
from influxdb_client_3 import InfluxDBClient3 from influxdb_client_3 import InfluxDBClient3
import os import os
# INFLUX_TOKEN is an environment variable you created for your database READ token # INFLUX_TOKEN is an environment variable you assigned to your database READ token string
TOKEN = os.getenv('INFLUX_TOKEN') TOKEN = os.getenv('INFLUX_TOKEN')
client = InfluxDBClient3( client = InfluxDBClient3(

17
content/influxdb/cloud-dedicated/get-started/write.md
View File

@ -74,7 +74,7 @@ Each line of line protocol contains the following elements:
--- ---
_For schema design recommendations, see [InfluxDB schema design](/influxdb/cloud-iox/write-data/best-practices/schema-design/)._ _For schema design recommendations, see [InfluxDB schema design](/influxdb/cloud-dedicated/write-data/best-practices/schema-design/)._
## Construct line protocol ## Construct line protocol
@ -301,7 +301,6 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
<!---------------------------- BEGIN PYTHON CONTENT ---------------------------> <!---------------------------- BEGIN PYTHON CONTENT --------------------------->
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
To write data to {{% cloud-name %}} using Python, use the To write data to {{% cloud-name %}} using Python, use the
[`influxdb_client_3` module](https://github.com/InfluxCommunity/influxdb3-python). [`influxdb_client_3` module](https://github.com/InfluxCommunity/influxdb3-python).
The following steps include setting up a Python virtual environment to scope The following steps include setting up a Python virtual environment to scope
@ -326,15 +325,14 @@ dependencies to your current project.
source ./envs/virtual-env/bin/activate source ./envs/virtual-env/bin/activate
``` ```
4. Install the following dependencies: 4. Install the client library package:
- `pyarrow` ```sh
- `influxdb_client_3` pip install influxdb3-python
```python
pip install pyarrow influxdb_client_3
``` ```
The `influxdb3-python` package provides the `influxdb_client_3` module and also installs the [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries.
5. In your terminal or editor, create a new file for your code--for example: `write.py`. 5. In your terminal or editor, create a new file for your code--for example: `write.py`.
```sh ```sh
@ -345,6 +343,7 @@ dependencies to your current project.
```py ```py
from influxdb_client_3 import InfluxDBClient3 from influxdb_client_3 import InfluxDBClient3
import os
# INFLUX_TOKEN is an environment variable you assigned to your # INFLUX_TOKEN is an environment variable you assigned to your
# database token value. # database token value.
@ -398,7 +397,7 @@ dependencies to your current project.
- **host**: {{% cloud-name %}} cluster hostname (URL without protocol or trailing slash) - **host**: {{% cloud-name %}} cluster hostname (URL without protocol or trailing slash)
- **org**: an empty or arbitrary string (InfluxDB ignores this parameter) - **org**: an empty or arbitrary string (InfluxDB ignores this parameter)
- **token**: an InfluxDB API token with write access to the target database - **token**: an InfluxDB [database token](/influxdb/cloud-dedicated/admin/tokens/) with write access to the target database
- **database**: the name of the {{% cloud-name %}} database to write to - **database**: the name of the {{% cloud-name %}} database to write to
3. Defines a list of line protocol strings where each string represents a data record. 3. Defines a list of line protocol strings where each string represents a data record.

44
content/influxdb/cloud-dedicated/query-data/sql/execute-queries/python.md
View File

@ -1,8 +1,7 @@
--- ---
title: Use Python to query data with SQL title: Use Python to query data with SQL
description: > description: >
Use Python and the `influxdb3-python` library to query data stored in InfluxDB Use the `influxdb_client_3` Python module and SQL to query data stored in InfluxDB.
with SQL.
weight: 101 weight: 101
menu: menu:
influxdb_cloud_dedicated: influxdb_cloud_dedicated:
@ -38,9 +37,8 @@ list_code_example: |
``` ```
--- ---
Use the `influxdb3-python` client library to query data stored in InfluxDB with SQL. Use the InfluxDB `influxdb_client_3` Python client library module and SQL to query data stored in InfluxDB.
The `influxdb3-client` uses Flight SQL to query data from InfluxDB and return Execute queries and retrieve data over the Flight protocol, and then process data using common Python tools.
results in Apache Arrow format.
- [Get started using Python to query InfluxDB](#get-started-using-python-to-query-influxdb) - [Get started using Python to query InfluxDB](#get-started-using-python-to-query-influxdb)
- [Create a Python virtual environment](#create-a-python-virtual-environment) - [Create a Python virtual environment](#create-a-python-virtual-environment)
@ -186,23 +184,26 @@ When a virtual environment is activated, the name displays at the beginning of y
### Install the influxdb3-python library ### Install the influxdb3-python library
The `influxdb_client_3` module provides a simple and convenient way to interact The `influxdb3-python` package provides the `influxdb_client_3` module for integrating {{% cloud-name %}} with your Python code.
with {{< cloud-name >}} using Python. This module supports both writing data to The module supports writing data to InfluxDB and querying data using SQL or InfluxQL.
InfluxDB and querying data using SQL or InfluxQL queries.
{{% note %}} {{% note %}}
_To query data with **InfluxQL** and Python, see _To query data with **InfluxQL** and Python, see
[Use InfluxQL with Python](/influxdb/cloud-dedicated/query-data/influxql/execute-queries/python/)._ [Use InfluxQL with Python](/influxdb/cloud-dedicated/query-data/influxql/execute-queries/python/)._
{{% /note %}} {{% /note %}}
Installing `inflxudb3-python` also installs the Install the following dependencies:
[`pyarrow`](https://arrow.apache.org/docs/python/index.html) library that you'll
use for working with Arrow data returned from queries.
In your terminal, use `pip` to install `influxdb3-python`: {{< req type="key" text="Already installed in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" >}}
- `influxdb3-python` {{< req text="\* " color="magenta" >}}: Provides the `influxdb_client_3` module and also installs the [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries.
- `pandas`: Provides [pandas modules](https://pandas.pydata.org/) for analyzing and manipulating data.
- `tabulate`: Provides the [`tabulate` function](https://pypi.org/project/tabulate/) for formatting tabular data.
Enter the following command in your terminal:
```sh ```sh
pip install influxdb3-python pip install influxdb3-python pandas tabulate
``` ```
With `influxdb3-python` and `pyarrow` installed, you're ready to query and With `influxdb3-python` and `pyarrow` installed, you're ready to query and
@ -210,8 +211,8 @@ analyze data stored in an InfluxDB database.
### Create an InfluxDB client ### Create an InfluxDB client
The following example shows how to use Python with `influxdb3-python` The following example shows how to use Python with the `influxdb_client_3`
and to instantiate a client configured for an InfluxDB database. module to instantiate a client configured for an {{% cloud-name %}} bucket.
In your editor, copy and paste the following sample code to a new file--for In your editor, copy and paste the following sample code to a new file--for
example, `query-example.py`: example, `query-example.py`:
@ -221,6 +222,7 @@ example, `query-example.py`:
# query-example.py # query-example.py
from influxdb_client_3 import InfluxDBClient3 from influxdb_client_3 import InfluxDBClient3
import pandas
# Instantiate an InfluxDBClient3 client configured for your database # Instantiate an InfluxDBClient3 client configured for your database
client = InfluxDBClient3( client = InfluxDBClient3(
@ -236,24 +238,20 @@ Replace the following configuration values:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: - {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Your InfluxDB token with read permissions on the databases you want to query. Your InfluxDB token with read permissions on the databases you want to query.
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
The name of your InfluxDB database. The name of your {{% cloud-name %}} database.
### Execute a query ### Execute a query
To execute an SQL query, call the client's `query(query,language)` method and To execute an SQL query, call the client's [`query(query,language)` method](/influxdb/cloud-dedicated/reference/client-libraries/v3/python/#influxdbclient3query) and
specify the following arguments: specify the following arguments:
- **query**: SQL query string to execute. - **query**: SQL query string to execute.
- **language**: `sql` - **language**: `sql`
#### Syntax {#execute-query-syntax}
```py
query(query: str, language: str)
```
#### Example {#execute-query-example} #### Example {#execute-query-example}
The following example shows how to use SQL to select all fields in a measurement, and then output the results formatted as a Markdown table.
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}} {{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```py ```py
# query-example.py # query-example.py

112
content/influxdb/cloud-serverless/get-started/query.md
View File

@ -3,8 +3,8 @@ title: Get started querying data
seotitle: Query data | Get started with InfluxDB seotitle: Query data | Get started with InfluxDB
list_title: Query data list_title: Query data
description: > description: >
Get started querying data in InfluxDB by learning about SQL, InfluxQL, and Flux and Get started querying data in InfluxDB by learning about SQL and InfluxQL, and
using tools like the InfluxDB UI, `influx` CLI, InfluxDB API, and Flight SQL clients. using tools like the InfluxDB UI, `influx` CLI, InfluxDB API, and InfluxDB client libraries.
menu: menu:
influxdb_cloud_serverless: influxdb_cloud_serverless:
name: Query data name: Query data
@ -23,10 +23,7 @@ related:
- **SQL**: Traditional SQL powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) - **SQL**: Traditional SQL powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/)
query engine. The supported SQL syntax is similar to PostgreSQL. query engine. The supported SQL syntax is similar to PostgreSQL.
- **Flux**: A functional scripting language designed to query and process data - **InfluxQL**: A SQL-like query language designed to query time series data stored in InfluxDB.
from InfluxDB and other data sources.
<!-- - **InfluxQL**: A SQL-like query language designed to query time series data from
InfluxDB. -->
This tutorial walks you through the fundamentals of querying data in InfluxDB and This tutorial walks you through the fundamentals of querying data in InfluxDB and
**focuses on using SQL** to query your time series data. **focuses on using SQL** to query your time series data.
@ -35,8 +32,6 @@ a protocol for interacting with SQL databases using the Arrow in-memory format a
[Flight RPC](https://arrow.apache.org/docs/format/Flight.html) framework. [Flight RPC](https://arrow.apache.org/docs/format/Flight.html) framework.
It leverages the performance of [Apache Arrow](https://arrow.apache.org/) with It leverages the performance of [Apache Arrow](https://arrow.apache.org/) with
the simplicity of SQL. the simplicity of SQL.
<!-- For information about using InfluxQL and Flux, see
[Query data in InfluxDB](/influxdb/cloud-serverless/query-data/). -->
{{% note %}} {{% note %}}
The examples in this section of the tutorial query the [**get-started** bucket](/influxdb/cloud-serverless/get-started/setup/) for data written in the The examples in this section of the tutorial query the [**get-started** bucket](/influxdb/cloud-serverless/get-started/setup/) for data written in the
@ -52,8 +47,7 @@ The examples in this section of the tutorial query the [**get-started** bucket](
- [InfluxDB user interface (UI)](?t=InfluxDB+UI#execute-an-sql-query){{< req "\* " >}} - [InfluxDB user interface (UI)](?t=InfluxDB+UI#execute-an-sql-query){{< req "\* " >}}
- [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req "\* " >}} - [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req "\* " >}}
- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) - [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/)
- [Flight SQL clients](- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/) - [Flight SQL clients](?t=Go#execute-an-sql-query){{< req "\* " >}}
){{< req "\* " >}}
- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/) - [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/) - [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/)
- [Chronograf](/{{< latest "Chronograf" >}}/) - [Chronograf](/{{< latest "Chronograf" >}}/)
@ -62,7 +56,7 @@ The examples in this section of the tutorial query the [**get-started** bucket](
## SQL query basics ## SQL query basics
The InfluxDB SQL implementation is powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) The {{% cloud-name %}} SQL implementation is powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/)
query engine which provides a SQL syntax similar to PostgreSQL. query engine which provides a SQL syntax similar to PostgreSQL.
{{% note %}} {{% note %}}
@ -102,16 +96,15 @@ GROUP BY
``` ```
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
##### Example SQL queries #### Example SQL queries
##### Select all data in a measurement
{{< expand-wrapper >}}
{{% expand "Select all data in a measurement" %}}
```sql ```sql
SELECT * FROM measurement SELECT * FROM home
``` ```
{{% /expand %}}
{{% expand "Select all data in a measurement within time bounds" %}} ##### Select all data in a measurement within time bounds
```sql ```sql
SELECT SELECT
* *
@ -121,27 +114,23 @@ WHERE
time >= '2022-01-01T08:00:00Z' time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-01T20:00:00Z' AND time <= '2022-01-01T20:00:00Z'
``` ```
{{% /expand %}}
{{% expand "Select a specific field within relative time bounds" %}} ##### Select a specific field within relative time bounds
```sql ```sql
SELECT temp FROM home WHERE time >= now() - INTERVAL '1 day' SELECT temp FROM home WHERE time >= now() - INTERVAL '1 day'
``` ```
{{% /expand %}}
{{% expand "Select specific fields and tags from a measurement" %}} ##### Select specific fields and tags from a measurement
```sql ```sql
SELECT temp, room FROM home SELECT temp, room FROM home
``` ```
{{% /expand %}}
{{% expand "Select data based on tag value" %}} ##### Select data based on tag value
```sql ```sql
SELECT * FROM home WHERE room = 'Kitchen' SELECT * FROM home WHERE room = 'Kitchen'
``` ```
{{% /expand %}}
{{% expand "Select data based on tag value within time bounds" %}} ##### Select data based on tag value within time bounds
```sql ```sql
SELECT SELECT
* *
@ -152,9 +141,8 @@ WHERE
AND time <= '2022-01-01T20:00:00Z' AND time <= '2022-01-01T20:00:00Z'
AND room = 'Living Room' AND room = 'Living Room'
``` ```
{{% /expand %}}
{{% expand "Downsample data by applying interval-based aggregates" %}} ##### Downsample data by applying interval-based aggregates
```sql ```sql
SELECT SELECT
DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time, DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time,
@ -168,18 +156,15 @@ GROUP BY
room room
ORDER BY room, _time ORDER BY room, _time
``` ```
{{% /expand %}}
{{< /expand-wrapper >}}
### Execute an SQL query ### Execute an SQL query
Get started with one of the following tools for querying data stored in an {{% cloud-name %}} bucket: Get started with one of the following tools for querying data stored in an {{% cloud-name %}} bucket:
- **InfluxDB UI**: View your schema, build queries using the query editor, and generate data visualizations. - **InfluxDB UI**: View your schema, build queries using the query editor, and generate data visualizations.
- **Flight SQL clients**: Use language-specific (Python, Go, etc.) clients to execute queries in your terminal or custom code. - **InfluxDB v3 client libraries**: Use language-specific (Python, Go, etc.) clients to execute queries in your terminal or custom code.
- **influx3 CLI**: Send SQL queries from your terminal command-line. - **influx3 CLI**: Send queries from your terminal command-line.
- **Grafana**: Query InfluxDB v3 with the [FlightSQL Data Source plugin](https://grafana.com/grafana/plugins/influxdata-flightsql-datasource/) and connect and visualize data. - **Grafana**: Query InfluxDB v3 with the [FlightSQL Data Source plugin](https://grafana.com/grafana/plugins/influxdata-flightsql-datasource/) and connect and visualize data.
- **`influx` CLI**, **InfluxDB API**, and **InfluxDB API v2 client libraries**: Use the InfluxDB `/api/v2/query` endpoint and Flux to execute SQL.
For this example, use the following query to select all the data written to the For this example, use the following query to select all the data written to the
**get-started** bucket between **get-started** bucket between
@ -246,7 +231,7 @@ See [Query in the Data Explorer](/influxdb/cloud-serverless/query-data/execute-q
<!--------------------------- BEGIN influx3 CONTENT ---------------------------> <!--------------------------- BEGIN influx3 CONTENT --------------------------->
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
Query InfluxDB v3 using SQL and the `influx3` CLI. Query InfluxDB v3 using SQL and the [`influx3` CLI](https://github.com/InfluxCommunity/influxdb3-python-cli).
The following steps include setting up a Python virtual environment already The following steps include setting up a Python virtual environment already
covered in [Get started writing data](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb). covered in [Get started writing data](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb).
@ -259,18 +244,20 @@ _If your project's virtual environment is already running, skip to step 3._
python -m venv envs/virtual-env python -m venv envs/virtual-env
``` ```
2. Activate the virtual environment. 2. Activate the virtual environment.
```sh ```sh
source ./envs/virtual-env/bin/activate source ./envs/virtual-env/bin/activate
``` ```
3. Install the following dependencies: 3. Install the CLI package (already installed in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb)).
{{< req type="key" text="Already installed in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" >}} ```sh
pip install influxdb3-python-cli
```
- `pyarrow` {{< req text="\*" color="magenta" >}} Installing `influxdb3-python-cli` also installs the
- `influxdb3-python-cli` {{< req text="\*" color="magenta" >}} [`pyarrow`](https://arrow.apache.org/docs/python/index.html) library for working with Arrow data returned from queries.
4. Create the `config.json` configuration. 4. Create the `config.json` configuration.
@ -309,42 +296,43 @@ influxdb3-python-cli
{{% tab-content %}} {{% tab-content %}}
<!--------------------------- BEGIN PYTHON CONTENT ----------------------------> <!--------------------------- BEGIN PYTHON CONTENT ---------------------------->
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
To query data from {{% cloud-name %}} using Python, use the Use the `influxdb_client_3` client library module to integrate {{< cloud-name >}} with your Python code.
[`influxdb_client_3` module](https://github.com/InfluxCommunity/influxdb3-python). The client library supports writing data to InfluxDB and querying data using SQL or InfluxQL.
The following steps include setting up a Python virtual environment already The following steps include setting up a Python virtual environment already
covered in [Get started writing data](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb). covered in [Get started writing data](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb).
_If your project's virtual environment is already running, skip to step 3._ _If your project's virtual environment is already running, skip to step 3._
1. In the `influxdb_py_client` module directory you created in the 1. Open a terminal in the `influxdb_py_client` module directory you created in the
[Write data section](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb): [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb):
1. Setup your Python virtual environment. 1. To create your Python virtual environment, enter the following command in your terminal:
Inside of your project directory:
```sh ```sh
python -m venv envs/virtual-env python -m venv envs/virtual-env
``` ```
2. Activate the virtual environment. 2. Activate the virtual environment.
```sh ```sh
source ./envs/virtual-env/bin/activate source ./envs/virtual-env/bin/activate
``` ```
3. Install the following dependencies: 3. Install the following dependencies:
{{< req type="key" text="Already installed in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" >}} {{< req type="key" text="Already installed in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" >}}
- `pyarrow` {{< req text="\*" color="magenta" >}} - `influxdb3-python`{{< req text="\* " color="magenta" >}}: Provides the `influxdb_client_3` module and also installs the [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries.
- `influxdb_client_3` {{< req text="\*" color="magenta" >}} - `pandas`: Provides [pandas modules](https://pandas.pydata.org/) for analyzing and manipulating data.
- `pandas` - `tabulate`: Provides the [`tabulate` function](https://pypi.org/project/tabulate/) for formatting tabular data.
- `tabulate` _(to return formatted tables)_
```sh Enter the following command in your terminal:
pip install influxdb_client_3 pandas tabulate
```
4. In your terminal or editor, create a new file for your code--for example: `query.py`. ```sh
pip install influxdb3-python pandas tabulate
```
4. In your terminal or editor, create a new file for your code--for example: `query.py`.
2. In `query.py`, enter the following sample code: 2. In `query.py`, enter the following sample code:
@ -352,7 +340,7 @@ _If your project's virtual environment is already running, skip to step 3._
from influxdb_client_3 import InfluxDBClient3 from influxdb_client_3 import InfluxDBClient3
import os import os
# INFLUX_TOKEN is an environment variable you created for your API token # INFLUX_TOKEN is an environment variable you assigned to your API token string
TOKEN = os.getenv('INFLUX_TOKEN') TOKEN = os.getenv('INFLUX_TOKEN')
client = InfluxDBClient3( client = InfluxDBClient3(
@ -382,7 +370,7 @@ _If your project's virtual environment is already running, skip to step 3._
2. Calls the `InfluxDBClient3()` constructor method with credentials to instantiate an InfluxDB `client` with the following credentials: 2. Calls the `InfluxDBClient3()` constructor method with credentials to instantiate an InfluxDB `client` with the following credentials:
- **host**: {{% cloud-name %}} region hostname (URL without protocol or trailing slash) - **host**: {{% cloud-name %}} region hostname (URL without protocol or trailing slash)
- **token**: an [API token](/influxdb/cloud-serverless/get-started/setup/#create-an-all-access-api-token) with _read_ access to the specified bucket. - **token**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket.
_For security reasons, we recommend setting this as an environment _For security reasons, we recommend setting this as an environment
variable rather than including the raw token string._ variable rather than including the raw token string._
- **database**: the name of the {{% cloud-name %}} bucket to query - **database**: the name of the {{% cloud-name %}} bucket to query

19
content/influxdb/cloud-serverless/get-started/write.md
View File

@ -24,10 +24,11 @@ This tutorial walks you through the fundamental of creating **line protocol** da
InfluxDB provides many different options for ingesting or writing data, including the following: InfluxDB provides many different options for ingesting or writing data, including the following:
- Influx user interface (UI) - Influx user interface (UI)
- InfluxDB HTTP API - InfluxDB HTTP API (v1 and v2)
- `influx` CLI
- Telegraf - Telegraf
- `influx3` data CLI
- InfluxDB client libraries - InfluxDB client libraries
- `influx` CLI
If using tools like Telegraf or InfluxDB client libraries, they can If using tools like Telegraf or InfluxDB client libraries, they can
build the line protocol for you, but it's good to understand how line protocol works. build the line protocol for you, but it's good to understand how line protocol works.
@ -402,15 +403,14 @@ dependencies to your current project.
source ./envs/virtual-env/bin/activate source ./envs/virtual-env/bin/activate
``` ```
4. Install the following dependencies: 4. Install the client library package:
- `pyarrow` ```sh
- `influxdb_client_3` pip install influxdb3-python
```python
pip install pyarrow influxdb_client_3
``` ```
The `influxdb3-python` package provides the `influxdb_client_3` module and also installs the [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries.
5. In your terminal or editor, create a new file for your code--for example: `write.py`. 5. In your terminal or editor, create a new file for your code--for example: `write.py`.
```sh ```sh
@ -421,6 +421,7 @@ dependencies to your current project.
```py ```py
from influxdb_client_3 import InfluxDBClient3 from influxdb_client_3 import InfluxDBClient3
import os
# INFLUX_TOKEN is an environment variable you assigned to your # INFLUX_TOKEN is an environment variable you assigned to your
# API token value. # API token value.
@ -474,7 +475,7 @@ dependencies to your current project.
- **host**: {{% cloud-name %}} region hostname (URL without protocol or trailing slash) - **host**: {{% cloud-name %}} region hostname (URL without protocol or trailing slash)
- **org**: an empty or arbitrary string (InfluxDB ignores this parameter) - **org**: an empty or arbitrary string (InfluxDB ignores this parameter)
- **token**: an InfluxDB [API token](/influxdb/cloud-serverless/get-started/setup/#create-an-all-access-api-token) with write access to the target bucket - **token**: an InfluxDB [API token](/influxdb/cloud-serverless/admin/tokens/) with write access to the target bucket
- **database**: the name of the {{% cloud-name %}} bucket to write to - **database**: the name of the {{% cloud-name %}} bucket to write to
3. Defines a list of line protocol strings where each string represents a data record. 3. Defines a list of line protocol strings where each string represents a data record.

55
content/influxdb/cloud-serverless/query-data/sql/execute-queries/python.md
View File

@ -1,17 +1,16 @@
--- ---
title: Use Python to query data with SQL title: Use Python to query data with SQL
description: > description: >
Use Python and the `influxdb3-python` library to query data stored in InfluxDB Use the `influxdb_client_3` Python module and SQL to query data stored in InfluxDB.
with SQL.
weight: 101 weight: 101
menu: menu:
influxdb_cloud_serverless: influxdb_cloud_serverless:
parent: Execute SQL queries parent: Execute SQL queries
name: Use Python name: Use Python
identifier: query_with_python identifier: query-with-python-sql
influxdb/cloud-serverless/tags: [query, flightsql, python, sql]
aliases: aliases:
- content/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/python/ - content/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/python/
influxdb/cloud-serverless/tags: [query, flightsql, python, sql]
related: related:
- /influxdb/cloud-serverless/query-data/tools/pandas/ - /influxdb/cloud-serverless/query-data/tools/pandas/
- /influxdb/cloud-serverless/query-data/tools/pyarrow/ - /influxdb/cloud-serverless/query-data/tools/pyarrow/
@ -39,9 +38,8 @@ list_code_example: |
``` ```
--- ---
Use the `influxdb3-python` client library to query data stored in InfluxDB with SQL. Use the InfluxDB `influxdb_client_3` Python client library module and SQL to query data stored in InfluxDB.
The `influxdb3-client` uses Flight SQL to query data from InfluxDB and return Execute queries and retrieve data over the Flight protocol, and then process data using common Python tools.
results in Apache Arrow format.
- [Get started using Python to query InfluxDB](#get-started-using-python-to-query-influxdb) - [Get started using Python to query InfluxDB](#get-started-using-python-to-query-influxdb)
- [Create a Python virtual environment](#create-a-python-virtual-environment) - [Create a Python virtual environment](#create-a-python-virtual-environment)
@ -187,23 +185,26 @@ When a virtual environment is activated, the name displays at the beginning of y
### Install the influxdb3-python library ### Install the influxdb3-python library
The `influxdb_client_3` module provides a simple and convenient way to interact The `influxdb3-python` package provides the `influxdb_client_3` module for integrating {{% cloud-name %}} with your Python code.
with {{< cloud-name >}} using Python. This module supports both writing data to The module supports writing data to InfluxDB and querying data using SQL or InfluxQL.
InfluxDB and querying data using SQL or InfluxQL queries.
{{% note %}} {{% note %}}
_To query data with **InfluxQL** and Python, see _To query data with **InfluxQL** and Python, see
[Use InfluxQL with Python](/influxdb/cloud-serverless/query-data/influxql/execute-queries/python/)._ [Use InfluxQL with Python](/influxdb/cloud-serverless/query-data/influxql/execute-queries/python/)._
{{% /note %}} {{% /note %}}
Installing `inflxudb3-python` also installs the Install the following dependencies:
[`pyarrow`](https://arrow.apache.org/docs/python/index.html) library that you'll
use for working with Arrow data returned from queries.
In your terminal, use `pip` to install `influxdb3-python`: {{< req type="key" text="Already installed in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" >}}
- `influxdb3-python` {{< req text="\* " color="magenta" >}}: Provides the `influxdb_client_3` module and also installs the [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries.
- `pandas`: Provides [pandas modules](https://pandas.pydata.org/) for analyzing and manipulating data.
- `tabulate`: Provides the [`tabulate` function](https://pypi.org/project/tabulate/) for formatting tabular data.
Enter the following command in your terminal:
```sh ```sh
pip install influxdb3-python pandas pip install influxdb3-python pandas tabulate
``` ```
With `influxdb3-python` and `pyarrow` installed, you're ready to query and With `influxdb3-python` and `pyarrow` installed, you're ready to query and
@ -211,20 +212,20 @@ analyze data stored in an InfluxDB database.
### Create an InfluxDB client ### Create an InfluxDB client
The following example shows how to use Python with `influxdb3-python` The following example shows how to use Python with the `influxdb_client_3`
and to instantiate a client configured for an InfluxDB database. module to instantiate a client configured for an {{% cloud-name %}} bucket.
In your editor, copy and paste the following sample code to a new file--for In your editor, copy and paste the following sample code to a new file--for
example, `query-example.py`: example, `query-example.py`:
{{% code-placeholders "(DATABASE|ORG)_(NAME|TOKEN)" %}} {{% code-placeholders "(BUCKET|ORG|API)_(NAME|TOKEN)" %}}
```py ```py
# query-example.py # query-example.py
from influxdb_client_3 import InfluxDBClient3 from influxdb_client_3 import InfluxDBClient3
import pandas import pandas
# Instantiate an InfluxDBClient3 client configured for your organization # Instantiate an InfluxDBClient3 client configured for your bucket
client = InfluxDBClient3( client = InfluxDBClient3(
host='cloud2.influxdata.com', host='cloud2.influxdata.com',
org='ORG_NAME' org='ORG_NAME'
@ -245,21 +246,17 @@ Replace the following configuration values:
### Execute a query ### Execute a query
To execute an SQL query, call the client's `query(query,language)` method and To execute an SQL query, call the client's [`query(query,language)` method](/influxdb/cloud-serverless/reference/client-libraries/v3/python/#influxdbclient3query) and
specify the following arguments: specify the following arguments:
- **query**: SQL query string to execute. - **query**: SQL query string to execute.
- **language**: `sql` - **language**: `sql`
#### Syntax {#execute-query-syntax}
```py
query(query: str, language: str)
```
#### Example {#execute-query-example} #### Example {#execute-query-example}
{{% code-placeholders "(DATABASE|ORG)_(NAME|TOKEN)" %}} The following example shows how to use SQL to select all fields in a measurement, and then output the results formatted as a Markdown table.
{{% code-placeholders "(BUCKET|ORG|API)_(NAME|TOKEN)" %}}
```py ```py
# query-example.py # query-example.py
@ -268,8 +265,8 @@ from influxdb_client_3 import InfluxDBClient3
client = InfluxDBClient3( client = InfluxDBClient3(
host='cloud2.influxdata.com', host='cloud2.influxdata.com',
org='ORG_NAME', org='ORG_NAME',
token='DATABASE_TOKEN', token='API_TOKEN',
database='DATABASE_NAME' database='BUCKET_NAME'
) )
# Execute the query and return an Arrow table # Execute the query and return an Arrow table