158 lines
6.0 KiB
Markdown
158 lines
6.0 KiB
Markdown
The [Python `flightsql-dbapi` Flight SQL DBAPI library](https://github.com/influxdata/flightsql-dbapi) integrates with Python applications using SQL to query data stored in an {{% product-name %}} database. The `flightsql-dbapi` library uses the [Flight SQL protocol](https://arrow.apache.org/docs/format/FlightSql.html) to query and retrieve data.
|
|
|
|
> [!Note]
|
|
> #### Use InfluxDB 3 client libraries
|
|
>
|
|
> We recommend using the [`influxdb3-python` Python client library](/influxdb3/version/reference/client-libraries/v3/python/) for integrating InfluxDB 3 with your Python application code.
|
|
>
|
|
> [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) wrap Apache Arrow Flight clients
|
|
> and provide convenient methods for [writing](/influxdb3/version/write-data/api-client-libraries/), [querying](/influxdb3/version/query-data/execute-queries/), and processing data stored in {{% product-name %}}.
|
|
> Client libraries can query using SQL or InfluxQL.
|
|
|
|
## Installation
|
|
|
|
The [`flightsql-dbapi`](https://github.com/influxdata/flightsql-dbapi) Flight SQL library for Python provides a
|
|
[DB API 2](https://peps.python.org/pep-0249/) interface and
|
|
[SQLAlchemy](https://www.sqlalchemy.org/) dialect for
|
|
[Flight SQL](https://arrow.apache.org/docs/format/FlightSql.html).
|
|
Installing `flightsql-dbapi` also installs the [`pyarrow`](https://arrow.apache.org/docs/python/index.html) library that you'll use for working with Arrow data.
|
|
|
|
In your terminal, use `pip` to install `flightsql-dbapi`:
|
|
|
|
```sh
|
|
pip install flightsql-dbapi
|
|
```
|
|
|
|
## Importing the module
|
|
|
|
The `flightsql-dbapi` package provides the `flightsql` module. From the module, import the `FlightSQLClient` class method:
|
|
|
|
```py
|
|
from flightsql import FlightSQLClient
|
|
```
|
|
|
|
- `flightsql.FlightSQLClient` class: an interface for [initializing
|
|
a client](#initialize-a-client) and interacting with a Flight SQL server.
|
|
|
|
## API reference
|
|
|
|
- [Class FlightSQLClient](#class-flightsqlclient)
|
|
- [Syntax](#syntax)
|
|
- [Initialize a client](#initialize-a-client)
|
|
- [Instance methods](#instance-methods)
|
|
- [FlightSQLClient.execute](#flightsqlclientexecute)
|
|
- [Syntax](#execute-query-syntax)
|
|
- [Example](#execute-query-example)
|
|
- [FlightSQLClient.do_get](#flightsqlclientdo_get)
|
|
- [Syntax](#retrieve-data-syntax)
|
|
- [Example](#retrieve-data-example)
|
|
|
|
## Class FlightSQLClient
|
|
|
|
Provides an interface for [initializing
|
|
a client](#initialize-a-client) and interacting with a Flight SQL server.
|
|
|
|
### Syntax
|
|
|
|
```py
|
|
__init__(self, host=None, token=None, metadata=None, features=None)
|
|
```
|
|
|
|
Initializes and returns a `FlightSQLClient` instance for interacting with the server.
|
|
|
|
## Initialize a client
|
|
|
|
The following example shows how to use Python with `flightsql-dbapi`
|
|
and the _DB API 2_ interface to instantiate a Flight SQL client configured for an InfluxDB database.
|
|
|
|
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
|
|
```py
|
|
from flightsql import FlightSQLClient
|
|
|
|
# Instantiate a FlightSQLClient configured for a database
|
|
client = FlightSQLClient(host='{{< influxdb/host >}}',
|
|
token='DATABASE_TOKEN',
|
|
metadata={'database': 'DATABASE_NAME'},
|
|
features={'metadata-reflection': 'true'})
|
|
```
|
|
{{% /code-placeholders %}}
|
|
|
|
Replace the following:
|
|
|
|
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: an
|
|
{{% product-name %}} [database token](/influxdb3/version/admin/tokens/#database-tokens)
|
|
with read permissions on the databases you want to query
|
|
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of your {{% product-name %}} [database](/influxdb3/version/admin/databases/)
|
|
|
|
### Instance methods
|
|
|
|
### FlightSQLClient.execute
|
|
|
|
Sends a Flight SQL RPC request to execute the specified SQL Query.
|
|
|
|
#### Syntax {#execute-query-syntax}
|
|
|
|
```py
|
|
execute(query: str, call_options: Optional[FlightSQLCallOptions] = None)
|
|
```
|
|
|
|
#### Example {#execute-query-example}
|
|
|
|
```py
|
|
# Execute the query
|
|
info = client.execute("SELECT * FROM home")
|
|
```
|
|
|
|
The response contains a `flight.FlightInfo` object that contains metadata and an `endpoints: [...]` list. Each endpoint contains the following:
|
|
|
|
- A list of addresses where you can retrieve query result data.
|
|
- A `ticket` value that identifies the data to [retrieve](#retrieve-data-example).
|
|
|
|
### FlightSQLClient.do_get
|
|
|
|
Passes a Flight ticket (obtained from a `FlightSQLClient.execute` response) and retrieves Arrow data identified by the ticket.
|
|
Returns a `pyarrow.flight.FlightStreamReader` for streaming the data.
|
|
|
|
#### Syntax {#retrieve-data-syntax}
|
|
|
|
```py
|
|
do_get(ticket, call_options: Optional[FlightSQLCallOptions] = None)
|
|
```
|
|
|
|
#### Example {#retrieve-data-example}
|
|
|
|
The following sample shows how to use Python with `flightsql-dbapi` and `pyarrow` to query InfluxDB and retrieve data.
|
|
|
|
```py
|
|
from flightsql import FlightSQLClient
|
|
|
|
# Instantiate a FlightSQLClient configured for a database
|
|
client = FlightSQLClient(host='{{< influxdb/host >}}',
|
|
token='DATABASE_TOKEN',
|
|
metadata={'database': 'DATABASE_NAME'},
|
|
features={'metadata-reflection': 'true'})
|
|
|
|
# Execute the query to retrieve FlightInfo
|
|
info = client.execute("SELECT * FROM home")
|
|
|
|
# Extract the token for retrieving data
|
|
ticket = info.endpoints[0].ticket
|
|
|
|
# Use the ticket to request the Arrow data stream.
|
|
# Return a FlightStreamReader for streaming the results.
|
|
reader = client.do_get(ticket)
|
|
|
|
# Read all data to a pyarrow.Table
|
|
table = reader.read_all()
|
|
|
|
print(table)
|
|
```
|
|
|
|
`do_get(ticket)` returns a [`pyarrow.flight.FlightStreamReader`](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightStreamReader.html) for streaming Arrow [record batches](https://arrow.apache.org/docs/python/data.html#record-batches).
|
|
|
|
To read data from the stream, call one of the following `FlightStreamReader` methods:
|
|
|
|
- `read_all()`: Read all record batches as a [`pyarrow.Table`](https://arrow.apache.org/docs/python/generated/pyarrow.Table.html).
|
|
- `read_chunk()`: Read the next RecordBatch and metadata.
|
|
- `read_pandas()`: Read all record batches and convert them to a [`pandas.DataFrame`](https://pandas.pydata.org/docs/reference/frame.html).
|