Use Python to query data - Influxdb

Use the InfluxDB influxdb_client_3 Python client library module and SQL or InfluxQL to query data stored in InfluxDB. Execute queries and retrieve data over the Flight+gRPC protocol, and then process data using common Python tools.

Get started using Python to query InfluxDB
Create a Python virtual environment
Query InfluxDB

Get started using Python to query InfluxDB

This guide assumes the following prerequisites:

an {{% product-name %}} bucket with data to query
an API token with read access to the database

To learn how to set up InfluxDB and write data, see the Setup instructions in the Get Started tutorial.

Create a Python virtual environment

This guide follows the recommended practice of using Python virtual environments. If you don't want to use virtual environments and you have Python installed, continue to Query InfluxDB. Python virtual environments keep the Python interpreter and dependencies for your project self-contained and isolated from other projects.

To install Python and create a virtual environment, choose one of the following options:

Python venv: The venv module comes standard in Python as of version 3.5.
Anaconda® Distribution: A Python/R data science distribution that provides Python and the conda package and environment manager.

{{< tabs-wrapper >}} {{% tabs "small" %}} venv Anaconda {{% /tabs %}} {{% tab-content %}}

Install Python

Follow the Python installation instructions to install a recent version of the Python programming language for your system.
Check that you can run python and pip commands. pip is a package manager included in most Python distributions.

In your terminal, enter the following commands:
sh
```
python --version
```
sh
```
pip --version
```
Depending on your system, you may need to use version-specific commands--for example.
sh
```
python3 --version
```
sh
```
pip3 --version
```
If neither pip nor pip<PYTHON_VERSION> works, follow one of the Pypa.io Pip installation methods for your system.

Create a project virtual environment {#venv-install}

Create a directory for your Python project and change to the new directory--for example:
sh
```
mkdir ./PROJECT_DIRECTORY && cd $_
```
Use the Python venv module to create a virtual environment--for example:
sh
```
python -m venv envs/virtualenv-1
```
venv creates the new virtual environment directory in your project.
To activate the new virtual environment in your terminal, run the source command and pass the path of the virtual environment activate script:
sh
```
source envs/VIRTUAL_ENVIRONMENT_NAME/bin/activate
```
For example:
sh
```
source envs/virtualenv-1/bin/activate
```

Install Anaconda {#conda-install}

Follow the Anaconda installation instructions for your system.
Check that you can run the conda command:
sh
```
conda
```
Use conda to create a virtual environment--for example:
sh
```
conda create --prefix envs/virtualenv-1 
```
conda creates a virtual environment in a directory named ./envs/virtualenv-1.
To activate the new virtual environment, use the conda activate command and pass the directory path of the virtual environment:
sh
```
conda activate envs/VIRTUAL_ENVIRONMENT_NAME
```
For example:
sh
```
conda activate ./envs/virtualenv-1
```

When a virtual environment is activated, the name displays at the beginning of your terminal command line--for example:

(virtualenv-1) $ PROJECT_DIRECTORY

Install the influxdb3-python library

The influxdb3-python package provides the influxdb_client_3 module for integrating {{% product-name %}} with your Python code. The module supports writing data to InfluxDB and querying data using SQL or InfluxQL.

Install the following dependencies:

{{% req type="key" text="Already installed in the Write data section" color="magenta" %}}

influxdb3-python {{< req text="* " color="magenta" >}}: Provides the influxdb_client_3 module and also installs the pyarrow package for working with Arrow data returned from queries.
pandas: Provides pandas modules for analyzing and manipulating data.
tabulate: Provides the tabulate function for formatting tabular data.

Enter the following command in your terminal:

pip install influxdb3-python pandas tabulate

With influxdb3-python and pyarrow installed, you're ready to query and analyze data stored in an InfluxDB database.

Create an InfluxDB client

The following example shows how to use Python with the influxdb_client_3 module to instantiate a client configured for an {{% product-name %}} bucket.

In your editor, copy and paste the following sample code to a new file--for example, query-example.py.

# query-example.py

from influxdb_client_3 import InfluxDBClient3

# Instantiate an InfluxDBClient3 client configured for your bucket
client = InfluxDBClient3(
    host='{{< influxdb/host >}}',
    token='API_TOKEN',
    database='BUCKET_NAME',
    timeout=30  # Set default timeout to 30 seconds for serverless
)

{{< expand-wrapper >}} {{% expand "<span class='req'>Important</span>: If using Windows, specify the Windows certificate path" %}}

If using a non-POSIX-compliant operating system (such as Windows), specify the root certificate path when instantiating the client.

In your terminal, install the Python certifi package.
sh
```
pip install certifi
```
In your Python code, import certifi and call the certifi.where() method to retrieve the certificate path.
When instantiating the client, pass the flight_client_options.tls_root_certs=<ROOT_CERT_PATH> option with the certificate path.

The following code sample shows how to use the Python certifi package and client library options to pass the certificate path:

{{% code-placeholders "BUCKET_NAME|API_TOKEN" %}} {{< code-callout "flight_client_options|tls_root_certs|(cert\b)" >}}

from influxdb_client_3 import InfluxDBClient3, flight_client_options
import certifi

fh = open(certifi.where(), "r")
cert = fh.read()
fh.close()

client = InfluxDBClient3(
host="{{< influxdb/host >}}",
token='API_TOKEN',
database='BUCKET_NAME',
flight_client_options=flight_client_options(
tls_root_certs=cert))
...

For more information, see influxdb_client_3 query exceptions.

Replace the following configuration values:

database: the name of the {{% product-name %}} bucket to query
token: an API token with read access to the specified bucket. Store this in a secret store or environment variable to avoid exposing the raw token string.

Execute a query

To execute a query, call the following client method:

query(query,language) method

and specify the following arguments:

query: A string. The SQL or InfluxQL query to execute.
language: A string ("sql" or "influxql"). The query language.

Example {#execute-query-example}

The following example shows how to use SQL or InfluxQL to select all fields in a measurement, and then use PyArrow functions to extract metadata and aggregate data.

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

# query-example.py

from influxdb_client_3 import InfluxDBClient3

client = InfluxDBClient3(
    host='{{< influxdb/host >}}',
    token='API_TOKEN',
    database='BUCKET_NAME'
)

# Execute the query and return an Arrow table
table = client.query(
    query="SELECT * FROM home",
    language="sql",
    timeout=10  # Override default timeout for simple queries (10 seconds)
)

print("\n#### View Schema information\n")
print(table.schema)
print(table.schema.names)
print(table.schema.types)
print(table.field('room').type)
print(table.schema.field('time').metadata)

print("\n#### View column types (timestamp, tag, and field) and data types\n")
print(table.schema.field('time').metadata[b'iox::column::type'])
print(table.schema.field('room').metadata[b'iox::column::type'])
print(table.schema.field('temp').metadata[b'iox::column::type'])

print("\n#### Use PyArrow to read the specified columns\n")
print(table.column('temp'))
print(table.select(['room', 'temp']))
print(table.select(['time', 'room', 'temp']))

print("\n#### Use PyArrow compute functions to aggregate data\n")
print(table.group_by('hum').aggregate([]))
print(table.group_by('room').aggregate([('temp', 'mean')]))

# query-example.py

from influxdb_client_3 import InfluxDBClient3

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

# Execute the query and return an Arrow table
table = client.query(
    query="SELECT * FROM home",
    language="influxql",
    timeout=10  # Override default timeout for simple queries (10 seconds)
)

print("\n#### View Schema information\n")
print(table.schema)
print(table.schema.names)
print(table.schema.types)
print(table.field('room').type)
print(table.schema.field('time').metadata)

print("\n#### View column types (timestamp, tag, and field) and data types\n")
print(table.schema.field('time').metadata[b'iox::column::type'])
print(table.schema.field('room').metadata[b'iox::column::type'])
print(table.schema.field('temp').metadata[b'iox::column::type'])

print("\n#### Use PyArrow to read the specified columns\n")
print(table.column('temp'))
print(table.select(['room', 'temp']))
print(table.select(['time', 'room', 'temp']))

print("\n#### Use PyArrow compute functions to aggregate data\n")
print(table.group_by('hum').aggregate([]))
print(table.group_by('room').aggregate([('temp', 'mean')]))

Replace the following configuration values:

database: the name of the {{% product-name %}} bucket to query
token: an API token with read access to the specified bucket. Store this in a secret store or environment variable to avoid exposing the raw token string.

Next, learn how to use Python tools to work with time series data: