You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by li...@apache.org on 2024/07/10 23:09:54 UTC
(arrow-adbc) branch main updated: docs: describe Flight SQL driver options (#2002)
This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/main by this push:
new 579a59759 docs: describe Flight SQL driver options (#2002)
579a59759 is described below
commit 579a597598660d311f42aa3a0c30d59fb5a9bb2b
Author: David Li <li...@gmail.com>
AuthorDate: Thu Jul 11 08:09:50 2024 +0900
docs: describe Flight SQL driver options (#2002)
Fixes #1980.
---
docs/source/driver/flight_sql.rst | 109 +++++++++++++++++++++++++++++++++++---
1 file changed, 101 insertions(+), 8 deletions(-)
diff --git a/docs/source/driver/flight_sql.rst b/docs/source/driver/flight_sql.rst
index bac793cad..58ada357e 100644
--- a/docs/source/driver/flight_sql.rst
+++ b/docs/source/driver/flight_sql.rst
@@ -103,6 +103,8 @@ the :cpp:class:`AdbcDatabase`.
.. tab-item:: Python
:sync: python
+ .. note:: For detailed examples, see :doc:`../python/recipe/flight_sql`.
+
.. code-block:: python
from adbc_driver_flightsql import DatabaseOptions
@@ -123,8 +125,6 @@ the :cpp:class:`AdbcDatabase`.
) as conn:
pass
- For more examples, see :doc:`../python/recipe/flight_sql`.
-
.. tab-item:: Go
:sync: go
@@ -203,25 +203,43 @@ Client Options
--------------
The options used for creating the Flight RPC client can be customized.
-These options map 1:1 with the options in FlightClientOptions:
+
+.. note:: Many of these options simply wrap a gRPC option. For more details
+ about what these options do, consult the `gRPC documentation
+ <https://pkg.go.dev/google.golang.org/grpc>`_.
+
+``adbc.flight.sql.client_option.authority``
+ Override gRPC's ``:authority`` pseudo-header.
+
+ Python: :attr:`adbc_driver_flightsql.DatabaseOptions.AUTHORITY`
``adbc.flight.sql.client_option.mtls_cert_chain``
The certificate chain to use for mTLS.
+ Python: :attr:`adbc_driver_flightsql.DatabaseOptions.MTLS_CERT_CHAIN`
+
``adbc.flight.sql.client_option.mtls_private_key``
The private key to use for mTLS.
+ Python: :attr:`adbc_driver_flightsql.DatabaseOptions.MTLS_PRIVATE_KEY`
+
``adbc.flight.sql.client_option.tls_override_hostname``
Override the hostname used to verify the server's TLS certificate.
-``adbc.flight.sql.client_option.tls_skip_verify``
- Disable verification of the server's TLS certificate. Value
- should be ``true`` or ``false``.
+ Python: :attr:`adbc_driver_flightsql.DatabaseOptions.TLS_OVERRIDE_HOSTNAME`
``adbc.flight.sql.client_option.tls_root_certs``
Override the root certificates used to validate the server's TLS
certificate.
+ Python: :attr:`adbc_driver_flightsql.DatabaseOptions.TLS_ROOT_CERTS`
+
+``adbc.flight.sql.client_option.tls_skip_verify``
+ Disable verification of the server's TLS certificate. Value
+ should be ``true`` or ``false``.
+
+ Python: :attr:`adbc_driver_flightsql.DatabaseOptions.TLS_SKIP_VERIFY`
+
``adbc.flight.sql.client_option.with_block``
.. warning:: This option is deprecated as gRPC itself has deprecated the
underlying option.
@@ -234,12 +252,22 @@ These options map 1:1 with the options in FlightClientOptions:
defaults to 16 MiB since Flight services tend to return larger
reponse payloads. Should be a positive integer number of bytes.
+ Python: :attr:`adbc_driver_flightsql.DatabaseOptions.WITH_MAX_MSG_SIZE`
+
+``adbc.flight.sql.authorization_header``
+ Directly specify the value of the ``authorization`` header to send on all
+ requests.
+
+ Python: :attr:`adbc_driver_flightsql.DatabaseOptions.AUTHORIZATION_HEADER`
+
``adbc.flight.sql.rpc.with_cookie_middleware``
Enable or disable middleware that processes and handles "set-cookie"
metadata headers returned from the server and sends "Cookie" headers
back from the client. Value should be ``true`` or ``false``. Default
is ``false``.
+ Python: :attr:`adbc_driver_flightsql.DatabaseOptions.WITH_COOKIE_MIDDLEWARE`
+
Custom Call Headers
-------------------
@@ -251,6 +279,8 @@ to :cpp:class:`AdbcDatabase`, :cpp:class:`AdbcConnection`, and
Add the header ``<HEADER NAME>`` to outgoing requests with the given
value.
+ Python: :attr:`adbc_driver_flightsql.ConnectionOptions.RPC_CALL_HEADER_PREFIX`
+
.. warning:: Header names must be in all lowercase.
Distributed Result Sets
@@ -271,12 +301,34 @@ All partitions are fetched in parallel. A limited number of batches
are queued per partition. Data is returned to the client in the order
of the partitions.
-The queue size can be changed by setting an option on the
-:cpp:class:`AdbcStatement`:
+Some behavior can be configured on the :cpp:class:`AdbcStatement`:
``adbc.rpc.result_queue_size``
The number of batches to queue per partition. Defaults to 5.
+ Python: :attr:`adbc_driver_flightsql.StatementOptions.QUEUE_SIZE`
+
+Incremental Execution
+---------------------
+
+By setting :c:macro:`ADBC_STATEMENT_OPTION_INCREMENTAL`, you can use
+nonblocking execution with this driver. This changes the behavior of
+:func:`AdbcStatementExecutePartitions` only. When enabled, ExecutePartitions
+will return every time there are new partitions (in Flight SQL terms, when
+there are new FlightEndpoints) from the server, instead of blocking until the
+query is complete.
+
+Some behavior can be configured on the :cpp:class:`AdbcStatement`:
+
+``adbc.flight.sql.statement.exec.last_flight_info``
+ Get the serialized bytes for the most recent ``FlightInfo`` returned by
+ the service. This is a low-level option intended for advanced usage. It
+ is most useful when incremental execution is enabled, for inspecting the
+ latest server response without waiting for
+ :func:`AdbcStatementExecutePartitions` to return.
+
+ Python: :attr:`adbc_driver_flightsql.StatementOptions.LAST_FLIGHT_INFO`
+
Metadata
--------
@@ -299,6 +351,41 @@ information that ADBC does not have.)
.. TODO: code samples
+Sessions
+--------
+
+The driver exposes Flight SQL session support via options on the connection.
+There is no explicit command to start a new session; it is expected that the
+server itself will manage this. (You will most likely need to enable cookie
+support as described above.) There is no explicit command to close a session;
+this is always issued when the connection is closed.
+
+``adbc.flight.sql.session.options``
+ Get all options as a JSON blob.
+
+ Python: :attr:`adbc_driver_flightsql.ConnectionOptions.OPTION_SESSION_OPTIONS`
+
+``adbc.flight.sql.session.option.``
+ Get or set a string/numeric session option.
+
+ Python: :attr:`adbc_driver_flightsql.ConnectionOptions.OPTION_SESSION_OPTION_PREFIX`
+
+``adbc.flight.sql.session.optionerase.``
+ Erase a session option.
+
+ Python: :attr:`adbc_driver_flightsql.ConnectionOptions.OPTION_ERASE_SESSION_OPTION_PREFIX`
+
+``adbc.flight.sql.session.optionbool.``
+ Get or set a boolean session option.
+
+ Python: :attr:`adbc_driver_flightsql.ConnectionOptions.OPTION_BOOL_SESSION_OPTION_PREFIX`
+
+``adbc.flight.sql.session.optionstringlist.``
+ Get or set a string list session option. The contents should be a
+ serialized JSON list.
+
+ Python: :attr:`adbc_driver_flightsql.ConnectionOptions.OPTION_STRING_LIST_SESSION_OPTION_PREFIX`
+
Timeouts
--------
@@ -314,6 +401,8 @@ The options are as follows:
For example, this controls the timeout of the underlying Flight
calls that fetch more data as a result set is consumed.
+ Python: :attr:`adbc_driver_flightsql.ConnectionOptions.TIMEOUT_FETCH`
+
``adbc.flight.sql.rpc.timeout_seconds.query``
A timeout (in floating-point seconds) for any API calls that
execute a query. This corresponds to Flight ``GetFlightInfo``
@@ -322,6 +411,8 @@ The options are as follows:
For example, this controls the timeout of the underlying Flight
calls that implement :func:`AdbcStatementExecuteQuery`.
+ Python: :attr:`adbc_driver_flightsql.ConnectionOptions.TIMEOUT_QUERY`
+
``adbc.flight.sql.rpc.timeout_seconds.update``
A timeout (in floating-point seconds) for any API calls that
upload data or perform other updates.
@@ -329,6 +420,8 @@ The options are as follows:
For example, this controls the timeout of the underlying Flight
calls that implement bulk ingestion, or transaction support.
+ Python: :attr:`adbc_driver_flightsql.ConnectionOptions.TIMEOUT_UPDATE`
+
There is also a timeout that is set on the :cpp:class:`AdbcDatabase`:
``adbc.flight.sql.rpc.timeout_seconds.connect``