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
description: >
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:
influxdb_cloud_dedicated:
name: Query data
@ -23,8 +23,7 @@ related:
- **SQL**: Traditional SQL powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/)
query engine. The supported SQL syntax is similar to PostgreSQL.
- **InfluxQL**: An SQL-like query language designed to query time series data from
InfluxDB.
- **InfluxQL**: An SQL-like query language designed to query time series data stored in InfluxDB.
This tutorial walks you through the fundamentals of querying data in InfluxDB and
**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:
{{< 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/)
- [Flight SQL clients](?t=Go#execute-an-sql-query){{< req "\* " >}}
- [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
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.
{{% note %}}
@ -95,16 +94,15 @@ GROUP BY
```
{{% /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
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
SELECT
*
@ -114,27 +112,23 @@ WHERE
time >= '2022-01-01T08: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
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
SELECT temp, room FROM home
```
{{% /expand %}}
{{% expand "Select data based on tag value" %}}
##### Select data based on tag value
```sql
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
SELECT
*
@ -145,9 +139,8 @@ WHERE
AND time <= '2022-01-01T20:00:00Z'
AND room = 'Living Room'
```
{{% /expand %}}
{{% expand "Downsample data by applying interval-based aggregates" %}}
##### Downsample data by applying interval-based aggregates
```sql
SELECT
DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time,
@ -161,15 +154,13 @@ GROUP BY
room
ORDER BY room, _time
```
{{% /expand %}}
{{< /expand-wrapper >}}
### Execute an SQL query
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.
- **influx3 CLI**: Send SQL queries from your terminal command-line.
- **InfluxDB v3 client libraries**: Use language-specific (Python, Go, etc.) clients to execute queries in your terminal or custom code.
- **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.
For this example, use the following query to select all the data written to the
@ -200,7 +191,7 @@ WHERE
<!--------------------------- BEGIN influx3 CONTENT --------------------------->
{{% 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
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
```
2. Activate the virtual environment.
2. Activate the virtual environment.
```sh
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" >}}
- `influxdb3-python-cli` {{< req text="\*" color="magenta" >}}
Installing `influxdb3-python-cli` also installs the
[`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 -->
```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
- **`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
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.
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 %}}
<!--------------------------- END influx3 CONTENT --------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!--------------------------- BEGIN PYTHON CONTENT ---------------------------->
{{% influxdb/custom-timestamps %}}
To query data from {{% cloud-name %}} using Python, use the
[`influxdb_client_3` module](https://github.com/InfluxCommunity/influxdb3-python).
Use the `influxdb_client_3` module to integrate {{< cloud-name >}} with your Python code.
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
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._
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):
1. Setup your Python virtual environment.
Inside of your module directory:
1. To create your Python virtual environment, enter the following command in your terminal:
```sh
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" >}}
- `pyarrow` {{< req text="\*" color="magenta" >}}
- `influxdb_client_3` {{< req text="\*" color="magenta" >}}
- `pandas`
- `tabulate` _(to return formatted tables)_
- `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
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:
@ -307,7 +298,7 @@ _If your project's virtual environment is already running, skip to step 3._
from influxdb_client_3 import InfluxDBClient3
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')
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
@ -301,7 +301,6 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
<!---------------------------- BEGIN PYTHON CONTENT --------------------------->
{{% influxdb/custom-timestamps %}}
To write data to {{% cloud-name %}} using Python, use the
[`influxdb_client_3` module](https://github.com/InfluxCommunity/influxdb3-python).
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
```
4. Install the following dependencies:
4. Install the client library package:
- `pyarrow`
- `influxdb_client_3`
```python
pip install pyarrow influxdb_client_3
```sh
pip install influxdb3-python
```
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`.
```sh
@ -345,6 +343,7 @@ dependencies to your current project.
```py
from influxdb_client_3 import InfluxDBClient3
import os
# INFLUX_TOKEN is an environment variable you assigned to your
# database token value.
@ -398,7 +397,7 @@ dependencies to your current project.
- **host**: {{% cloud-name %}} cluster hostname (URL without protocol or trailing slash)
- **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
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
description: >
Use Python and the `influxdb3-python` library to query data stored in InfluxDB
with SQL.
Use the `influxdb_client_3` Python module and SQL to query data stored in InfluxDB.
weight: 101
menu:
influxdb_cloud_dedicated:
@ -38,9 +37,8 @@ list_code_example: |
```
---
Use the `influxdb3-python` client library to query data stored in InfluxDB with SQL.
The `influxdb3-client` uses Flight SQL to query data from InfluxDB and return
results in Apache Arrow format.
Use the InfluxDB `influxdb_client_3` Python client library module and SQL to query data stored in InfluxDB.
Execute queries and retrieve data over the Flight protocol, and then process data using common Python tools.
- [Get started using Python to query InfluxDB](#get-started-using-python-to-query-influxdb)
- [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
The `influxdb_client_3` module provides a simple and convenient way to interact
with {{< cloud-name >}} using Python. This module supports both writing data to
InfluxDB and querying data using SQL or InfluxQL queries.
The `influxdb3-python` package provides the `influxdb_client_3` module for integrating {{% cloud-name %}} with your Python code.
The module supports writing data to InfluxDB and querying data using SQL or InfluxQL.
{{% note %}}
_To query data with **InfluxQL** and Python, see
[Use InfluxQL with Python](/influxdb/cloud-dedicated/query-data/influxql/execute-queries/python/)._
{{% /note %}}
Installing `inflxudb3-python` also installs the
[`pyarrow`](https://arrow.apache.org/docs/python/index.html) library that you'll
use for working with Arrow data returned from queries.
Install the following dependencies:
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
pip install influxdb3-python
pip install influxdb3-python pandas tabulate
```
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
The following example shows how to use Python with `influxdb3-python`
and to instantiate a client configured for an InfluxDB database.
The following example shows how to use Python with the `influxdb_client_3`
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
example, `query-example.py`:
@ -221,6 +222,7 @@ example, `query-example.py`:
# query-example.py
from influxdb_client_3 import InfluxDBClient3
import pandas
# Instantiate an InfluxDBClient3 client configured for your database
client = InfluxDBClient3(
@ -236,24 +238,20 @@ Replace the following configuration values:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Your InfluxDB token with read permissions on the databases you want to query.
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
The name of your InfluxDB database.
The name of your {{% cloud-name %}} database.
### 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:
- **query**: SQL query string to execute.
- **language**: `sql`
#### Syntax {#execute-query-syntax}
```py
query(query: str, language: str)
```
#### 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)" %}}
```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
list_title: Query data
description: >
Get started querying data in InfluxDB by learning about SQL, InfluxQL, and Flux and
using tools like the InfluxDB UI, `influx` CLI, InfluxDB API, and Flight SQL clients.
Get started querying data in InfluxDB by learning about SQL and InfluxQL, and
using tools like the InfluxDB UI, `influx` CLI, InfluxDB API, and InfluxDB client libraries.
menu:
influxdb_cloud_serverless:
name: Query data
@ -23,10 +23,7 @@ related:
- **SQL**: Traditional SQL powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/)
query engine. The supported SQL syntax is similar to PostgreSQL.
- **Flux**: A functional scripting language designed to query and process data
from InfluxDB and other data sources.
<!-- - **InfluxQL**: A SQL-like query language designed to query time series data from
InfluxDB. -->
- **InfluxQL**: A SQL-like query language designed to query time series data stored in InfluxDB.
This tutorial walks you through the fundamentals of querying data in InfluxDB and
**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.
It leverages the performance of [Apache Arrow](https://arrow.apache.org/) with
the simplicity of SQL.
<!-- For information about using InfluxQL and Flux, see
[Query data in InfluxDB](/influxdb/cloud-serverless/query-data/). -->
{{% 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
@ -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 "\* " >}}
- [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req "\* " >}}
- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/)
- [Flight SQL clients](- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/)
){{< req "\* " >}}
- [Flight SQL clients](?t=Go#execute-an-sql-query){{< req "\* " >}}
- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/)
- [Chronograf](/{{< latest "Chronograf" >}}/)
@ -62,7 +56,7 @@ The examples in this section of the tutorial query the [**get-started** bucket](
## 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.
{{% note %}}
@ -102,16 +96,15 @@ GROUP BY
```
{{% /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
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
SELECT
*
@ -121,27 +114,23 @@ WHERE
time >= '2022-01-01T08: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
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
SELECT temp, room FROM home
```
{{% /expand %}}
{{% expand "Select data based on tag value" %}}
##### Select data based on tag value
```sql
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
SELECT
*
@ -152,9 +141,8 @@ WHERE
AND time <= '2022-01-01T20:00:00Z'
AND room = 'Living Room'
```
{{% /expand %}}
{{% expand "Downsample data by applying interval-based aggregates" %}}
##### Downsample data by applying interval-based aggregates
```sql
SELECT
DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time,
@ -168,18 +156,15 @@ GROUP BY
room
ORDER BY room, _time
```
{{% /expand %}}
{{< /expand-wrapper >}}
### Execute an SQL query
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.
- **Flight SQL clients**: 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.
- **InfluxDB v3 client libraries**: Use language-specific (Python, Go, etc.) clients to execute queries in your terminal or custom code.
- **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.
- **`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
**get-started** bucket between
@ -246,7 +231,7 @@ See [Query in the Data Explorer](/influxdb/cloud-serverless/query-data/execute-q
<!--------------------------- BEGIN influx3 CONTENT --------------------------->
{{% 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
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
```
2. Activate the virtual environment.
2. Activate the virtual environment.
```sh
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" >}}
- `influxdb3-python-cli` {{< req text="\*" color="magenta" >}}
Installing `influxdb3-python-cli` also installs the
[`pyarrow`](https://arrow.apache.org/docs/python/index.html) library for working with Arrow data returned from queries.
4. Create the `config.json` configuration.
@ -309,42 +296,43 @@ influxdb3-python-cli
{{% tab-content %}}
<!--------------------------- BEGIN PYTHON CONTENT ---------------------------->
{{% influxdb/custom-timestamps %}}
To query data from {{% cloud-name %}} using Python, use the
[`influxdb_client_3` module](https://github.com/InfluxCommunity/influxdb3-python).
Use the `influxdb_client_3` client library module to integrate {{< cloud-name >}} with your Python code.
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
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._
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):
1. Setup your Python virtual environment.
Inside of your project directory:
1. To create your Python virtual environment, enter the following command in your terminal:
```sh
python -m venv envs/virtual-env
```
```sh
python -m venv envs/virtual-env
```
2. Activate the virtual environment.
2. Activate the virtual environment.
```sh
source ./envs/virtual-env/bin/activate
```
```sh
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" >}}
- `influxdb_client_3` {{< req text="\*" color="magenta" >}}
- `pandas`
- `tabulate` _(to return formatted tables)_
- `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.
```sh
pip install influxdb_client_3 pandas tabulate
```
Enter the following command in your terminal:
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:
@ -352,7 +340,7 @@ _If your project's virtual environment is already running, skip to step 3._
from influxdb_client_3 import InfluxDBClient3
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')
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:
- **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
variable rather than including the raw token string._
- **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:
- Influx user interface (UI)
- InfluxDB HTTP API
- `influx` CLI
- InfluxDB HTTP API (v1 and v2)
- Telegraf
- `influx3` data CLI
- InfluxDB client libraries
- `influx` CLI
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.
@ -402,15 +403,14 @@ dependencies to your current project.
source ./envs/virtual-env/bin/activate
```
4. Install the following dependencies:
4. Install the client library package:
- `pyarrow`
- `influxdb_client_3`
```python
pip install pyarrow influxdb_client_3
```sh
pip install influxdb3-python
```
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`.
```sh
@ -421,6 +421,7 @@ dependencies to your current project.
```py
from influxdb_client_3 import InfluxDBClient3
import os
# INFLUX_TOKEN is an environment variable you assigned to your
# API token value.
@ -474,7 +475,7 @@ dependencies to your current project.
- **host**: {{% cloud-name %}} region hostname (URL without protocol or trailing slash)
- **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
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
description: >
Use Python and the `influxdb3-python` library to query data stored in InfluxDB
with SQL.
Use the `influxdb_client_3` Python module and SQL to query data stored in InfluxDB.
weight: 101
menu:
influxdb_cloud_serverless:
parent: Execute SQL queries
name: Use Python
identifier: query_with_python
identifier: query-with-python-sql
influxdb/cloud-serverless/tags: [query, flightsql, python, sql]
aliases:
- content/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/python/
influxdb/cloud-serverless/tags: [query, flightsql, python, sql]
related:
- /influxdb/cloud-serverless/query-data/tools/pandas/
- /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.
The `influxdb3-client` uses Flight SQL to query data from InfluxDB and return
results in Apache Arrow format.
Use the InfluxDB `influxdb_client_3` Python client library module and SQL to query data stored in InfluxDB.
Execute queries and retrieve data over the Flight protocol, and then process data using common Python tools.
- [Get started using Python to query InfluxDB](#get-started-using-python-to-query-influxdb)
- [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
The `influxdb_client_3` module provides a simple and convenient way to interact
with {{< cloud-name >}} using Python. This module supports both writing data to
InfluxDB and querying data using SQL or InfluxQL queries.
The `influxdb3-python` package provides the `influxdb_client_3` module for integrating {{% cloud-name %}} with your Python code.
The module supports writing data to InfluxDB and querying data using SQL or InfluxQL.
{{% note %}}
_To query data with **InfluxQL** and Python, see
[Use InfluxQL with Python](/influxdb/cloud-serverless/query-data/influxql/execute-queries/python/)._
{{% /note %}}
Installing `inflxudb3-python` also installs the
[`pyarrow`](https://arrow.apache.org/docs/python/index.html) library that you'll
use for working with Arrow data returned from queries.
Install the following dependencies:
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
pip install influxdb3-python pandas
pip install influxdb3-python pandas tabulate
```
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
The following example shows how to use Python with `influxdb3-python`
and to instantiate a client configured for an InfluxDB database.
The following example shows how to use Python with the `influxdb_client_3`
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
example, `query-example.py`:
{{% code-placeholders "(DATABASE|ORG)_(NAME|TOKEN)" %}}
{{% code-placeholders "(BUCKET|ORG|API)_(NAME|TOKEN)" %}}
```py
# query-example.py
from influxdb_client_3 import InfluxDBClient3
import pandas
# Instantiate an InfluxDBClient3 client configured for your organization
# Instantiate an InfluxDBClient3 client configured for your bucket
client = InfluxDBClient3(
host='cloud2.influxdata.com',
org='ORG_NAME'
@ -245,21 +246,17 @@ Replace the following configuration values:
### 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:
- **query**: SQL query string to execute.
- **language**: `sql`
#### Syntax {#execute-query-syntax}
```py
query(query: str, language: str)
```
#### 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
# query-example.py
@ -268,8 +265,8 @@ from influxdb_client_3 import InfluxDBClient3
client = InfluxDBClient3(
host='cloud2.influxdata.com',
org='ORG_NAME',
token='DATABASE_TOKEN',
database='DATABASE_NAME'
token='API_TOKEN',
database='BUCKET_NAME'
)
# Execute the query and return an Arrow table