---
title: Use Python to query data
description: Use the influxdb_client_3 Python 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.
url: https://docs.influxdata.com/influxdb3/cloud-serverless/query-data/execute-queries/client-libraries/python/
estimated_tokens: 3104
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/cloud-serverless/query-data/execute-queries/client-libraries/python/
date: '2026-05-15T15:46:14-06:00'
lastmod: '2026-05-15T15:46:14-06:00'
---

* SQL
* InfluxQL

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](#get-started-using-python-to-query-influxdb)
* [Create a Python virtual environment](#create-a-python-virtual-environment)
  * [Install Python](#install-python)
  * [Create a project virtual environment](#venv-install)
  * [Install Anaconda](?t=Anaconda#conda-install)

* [Query InfluxDB](#query-influxdb)
  * [Install the influxdb3-python library](#install-the-influxdb3-python-library)
  * [Create an InfluxDB client](#create-an-influxdb-client)
  * [Execute a query](#execute-a-query)

## Get started using Python to query InfluxDB

This guide assumes the following prerequisites:

* an InfluxDB Cloud Serverless [bucket](/influxdb3/cloud-serverless/admin/buckets/) with data to query
* an [API token](/influxdb3/cloud-serverless/admin/tokens/) with *read* access to the database

To learn how to set up InfluxDB and write data, see the [Setup instructions](/influxdb3/cloud-serverless/get-started/setup/) 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](#query-influxdb).
Python [virtual environments](https://docs.python.org/3/library/venv.html) 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](?t=venv#venv-install): The [`venv` module](https://docs.python.org/3/library/venv.html) comes standard in Python as of version 3.5.

* [Anaconda® Distribution](?t=Anaconda#conda-install): A Python/R data science distribution that provides Python and the **conda** package and environment manager.

  [venv]()[Anaconda]()

  ### Install Python ###

  1. Follow the [Python installation instructions](https://wiki.python.org/moin/BeginnersGuide/Download)to install a recent version of the Python programming language for your system.

  2. 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:

     ```
     python --version
     ```

     ```
     pip --version
     ```

     Depending on your system, you may need to use version-specific commands–for example.

     ```
     python3 --version
     ```

     ```
     pip3 --version
     ```

     If neither `pip` nor `pip<PYTHON_VERSION>` works, follow one of the [Pypa.io Pip installation](https://pip.pypa.io/en/stable/installation/) methods for your system.

  ### Create a project virtual environment ###

  1. Create a directory for your Python project and change to the new directory–for example:

     ```
     mkdir ./PROJECT_DIRECTORY && cd $_
     ```

  2. Use the Python `venv` module to create a virtual environment–for example:

     ```
     python -m venv envs/virtualenv-1
     ```

     `venv` creates the new virtual environment directory in your project.

  3. To activate the new virtual environment in your terminal, run the `source` command and pass the path of the virtual environment `activate` script:

     ```
     source envs/VIRTUAL_ENVIRONMENT_NAME/bin/activate
     ```

     For example:

     ```
     source envs/virtualenv-1/bin/activate
     ```

  ### Install Anaconda ###

  1. Follow the [Anaconda installation instructions](https://docs.continuum.io/anaconda/install/) for your system.

  2. Check that you can run the `conda` command:

     ```
     conda
     ```

  3. Use `conda` to create a virtual environment–for example:

     ```
     conda create --prefix envs/virtualenv-1
     ```

     `conda` creates a virtual environment in a directory named `./envs/virtualenv-1`.

  4. To activate the new virtual environment, use the `conda activate` command and pass the directory path of the virtual environment:

     ```
     conda activate envs/VIRTUAL_ENVIRONMENT_NAME
     ```

     For example:

     ```
     conda activate ./envs/virtualenv-1
     ```

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

```sh
(virtualenv-1) $ PROJECT_DIRECTORY
```

## Query InfluxDB

1. [Install the influxdb3-python library](#install-the-influxdb3-python-library)
2. [Create an InfluxDB client](#create-an-influxdb-client)
3. [Execute a query](#execute-a-query)

### Install the influxdb3-python library

The `influxdb3-python` package provides the `influxdb_client_3` module for integrating InfluxDB Cloud Serverless with your Python code.
The module supports writing data to InfluxDB and querying data using SQL or InfluxQL.

Install the following dependencies:

\* Already installed in the [Write data section](/influxdb3/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb)

* `influxdb3-python` \*: 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 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 InfluxDB Cloud Serverless bucket.

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

```py
# query-example.py

from influxdb_client_3 import InfluxDBClient3

# Instantiate an InfluxDBClient3 client configured for your bucket
client = InfluxDBClient3(
    host='cloud2.influxdata.com',
    token='API_TOKEN',
    database='BUCKET_NAME',
    timeout=30  # Set default timeout to 30 seconds for serverless
)
```

[](#important-if-using-windows-specify-the-windows-certificate-path)

Important: 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.

1. In your terminal, install the Python `certifi` package.

   ```
   pip install certifi
   ```

2. In your Python code, import `certifi` and call the `certifi.where()` method to retrieve the certificate path.

3. 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:

```py
from influxdb_client_3 import InfluxDBClient3, flight_client_options
import certifi

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

client = InfluxDBClient3(
    host="cloud2.influxdata.com",
    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](/influxdb3/cloud-serverless/reference/client-libraries/v3/python/#query-exceptions).

Replace the following configuration values:

* **`database`**: the name of the [InfluxDB Cloud Serverless bucket](/influxdb3/cloud-serverless/admin/buckets/) to query
* **`token`**: an [API token](/influxdb3/cloud-serverless/admin/tokens/) 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](/influxdb3/cloud-serverless/reference/client-libraries/v3/python/#influxdbclient3query)

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

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.

#### SQL ####

```py
# query-example.py

from influxdb_client_3 import InfluxDBClient3

client = InfluxDBClient3(
    host='cloud2.influxdata.com',
    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')]))
```

```py
# query-example.py

from influxdb_client_3 import InfluxDBClient3

client = InfluxDBClient3(
    host='cloud2.influxdata.com',
    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 [InfluxDB Cloud Serverless bucket](/influxdb3/cloud-serverless/admin/buckets/) to query
* **`token`**: an [API token](/influxdb3/cloud-serverless/admin/tokens/) 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:

* [Use PyArrow](/influxdb3/cloud-serverless/process-data/tools/pyarrow/)
* [Use pandas](/influxdb3/cloud-serverless/process-data/tools/pandas/)

#### Related

* [Python client library for InfluxDB 3](/influxdb3/cloud-serverless/reference/client-libraries/v3/python/)
* [Use pandas to analyze and visualize data](/influxdb3/cloud-serverless/process-data/tools/pandas/)
* [Use the PyArrow library to analyze data](/influxdb3/cloud-serverless/process-data/tools/pyarrow/)
* [Query data with InfluxQL](/influxdb3/cloud-serverless/query-data/influxql/)
* [Query data with SQL](/influxdb3/cloud-serverless/query-data/sql/)
* [InfluxQL reference documentation](/influxdb3/cloud-serverless/reference/influxql/)
* [SQL reference documentation](/influxdb3/cloud-serverless/reference/sql/)
* [Query timeout best practices](/influxdb3/cloud-serverless/query-data/troubleshoot-and-optimize/query-timeout-best-practices/)