Flight SQL を使用したアクセス¶
Virtual DataPort は Arrow Flight SQL プロトコルを実装しているので、このプロトコルを使用してやり取りするクライアントは、その基盤となるプログラミング言語とは関係なく接続できます。
Flight SQL JDBC ドライバーを使用したアクセス¶
JDBC (Java Database Connectivity) は、DBMS を問わず、リレーショナルデータベースに対してステートメントを実行できるようにする Java API です。Flight SQL JDBC ドライバー は、Flight SQL プロトコルを使用する JDBC 実装であり、Flight SQL をサポートする任意のデータベースとやり取りできます。
Flight SQL JDBC ドライバーは、以下の場所から取得します。
Denodo Platform のインストール (
<DENODO_HOME>/tools/client-drivers/jdbc/
) から取得します。
Java のバージョン
ドライバーは JDK 8+ と互換性があります。JDK 9+ では、次の JVM パラメータが必要です。
--add-opens=java.base/java.nio=ALL-UNNAMED
ドライバークラスの名前
このドライバーのクラス名は次のとおりです。
org.apache.arrow.driver.jdbc.ArrowFlightJdbcDriver
接続 URL
データベース URL の構文は次のとおりです。
jdbc:arrow-flight-sql://<hostname>[:<port>][?<paramName>=<paramValue>[&<paramName>=<paramValue>]*]
URI スキームは
jdbc:arrow-flight-sql://
である必要があります。<hostname>
: Flight SQL サービスのホスト名です。<port>
: デフォルトポートは 9994 です。次のプロパティを設定することで変更できます。
com.denodo.vdb.vdbinterface.server.VDBFlightImpl.port=port-value
例:
jdbc:arrow-flight-sql://denodo-server.acme.com:9994?useEncryption=false&catalog=acme_db
注釈
URI の値に !、@、$、などの文字が含まれる場合は、値を URI エンコードする必要があることに注意してください。ドライバーで処理されない URI パラメータは Flight SQL サービスに gRPC ヘッダーとして渡されます。たとえば、前述の URI は、 denodo-server.acme.com
のポート 9994
で実行されている Flight SQL サービスに暗号化なしで接続します。
コネクションパラメータ¶
追加のオプションをクエリパラメータとして渡すことができます。パラメータ名では大文字と小文字が区別されます。サポートされているパラメータは以下のとおりです。
URL のパラメータ |
説明 |
---|---|
autoCommit |
これは、アプリケーションがトランザクションを不用意に開始しないようにする場合に便利です。 このパラメータが true に設定されていても、アプリケーションは トランザクションの期間に対する制限を考慮します。
トランザクションの期間に対する制限の詳細については、『VQL ガイド』の「 Virtual DataPort のトランザクション 」を参照してください。 デフォルト値: |
catalog |
ユーザーがログインするデータベース。 デフォルト値: |
disableCertificateVerification |
TLS が有効な場合にサーバーの証明書を検証するかどうか。 デフォルト値: |
password |
ユーザー/パスワード認証のパスワード。 デフォルト値: |
queryTimeout |
クエリの実行にかけられる最大時間 (ミリ秒)。この時間を超えるとエラーがスローされます。 このパラメータはオプションです。設定されていない場合、クエリのタイムアウトはデフォルト値 (900000 ミリ秒) になります。0 の場合、クエリにタイムアウトは設定されません。 このパラメータを使用すると、すべてのクエリに対してデフォルトのタイムアウトが設定されます。さらに、1 つのクエリのタイムアウトを変更することもできます。その場合、クエリの CONTEXT 句にパラメータ 'QUERYTIMEOUT' = '<value>' を追加します。詳細については、『VQL ガイド』の「 CONTEXT 句 」を参照してください。 デフォルト値: |
timePrecision |
time 型の列に使用する精度。有効な値は デフォルト値: |
timeStampPrecision |
timestamp 型および timestamptz 型の列に使用する精度。有効な値は``milliseconds`` 、 デフォルト値: |
trustStore |
TLS が有効な場合の、証明書ストアのパス。指定されていない場合、デフォルトの Java トラストストア (通常は デフォルト値: |
trustStorePassword |
証明書トラストストアのパスワード。 デフォルト値: |
useEncryption |
TLS を使用するかどうか (デフォルトは暗号化されたコネクション)。 デフォルト値: |
user |
ユーザー/パスワード認証のユーザー名。 デフォルト値: |
useSystemTrustStore |
TLS が有効な場合にシステムの証明書ストアを使用するかどうか。 デフォルト値: |
Flight SQL Python ドライバーを使用したアクセス¶
Python Flight SQL ドライバーを使用すると、ネイティブの Python アプリケーションから Virtual DataPort に接続できます。
このドライバーは、 PEP 249 – Python Database API Specification v2.0 (データベースにアクセスするための API)、および ADBC: Arrow Database Connectivity (Arrow ネイティブデータベースにアクセスするための一連の API) の仕様を実装しています。
コネクションパラメータ¶
サポートされているパラメータは以下のとおりです。
パラメータ |
説明 |
---|---|
adbc.flight.sql.client_option.tls_root_certs |
サーバーの TLS 証明書の検証に使用されるルート証明書を上書きします。 デフォルト値: |
adbc.flight.sql.client_option.tls_skip_verify |
サーバーの TLS 証明書の検証を無効にします。 デフォルト値: |
adbc.flight.sql.rpc.call_header.autoCommit |
これは、アプリケーションがトランザクションを不用意に開始しないようにする場合に便利です。 このパラメータが true に設定されていても、アプリケーションは トランザクションの期間に対する制限を考慮します。
トランザクションの期間に対する制限の詳細については、『VQL ガイド』の「 Virtual DataPort のトランザクション 」を参照してください。 デフォルト値: |
adbc.flight.sql.rpc.call_header.database |
ユーザーがログインするデータベース。 デフォルト値: |
adbc.flight.sql.rpc.call_header.queryTimeout |
クエリの実行にかけられる最大時間 (ミリ秒)。この時間を超えるとエラーがスローされます。 このパラメータはオプションです。設定されていない場合、クエリのタイムアウトはデフォルト値 (900000 ミリ秒) になります。0 の場合、クエリにタイムアウトは設定されません。 このパラメータを使用すると、すべてのクエリに対してデフォルトのタイムアウトが設定されます。さらに、1 つのクエリのタイムアウトを変更することもできます。その場合、クエリの CONTEXT 句にパラメータ 'QUERYTIMEOUT' = '<value>' を追加します。詳細については、『VQL ガイド』の「 CONTEXT 句 」を参照してください。 デフォルト値: |
adbc.flight.sql.rpc.call_header.timePrecision |
timestamp 型および timestamptz 型の列に使用する精度。有効な値は``milliseconds`` 、 デフォルト値: |
adbc.flight.sql.rpc.call_header.timeStampPrecision |
time 型の列に使用する精度。有効な値は デフォルト値: |
password |
ユーザー/パスワード認証のパスワード。 |
user |
ユーザー/パスワード認証のユーザー名。 |
詳細については、 ADBC Flight SQL ドライバーのドキュメント を参照してください。
注¶
fetchallarrow
やfetch_arrow_table
などの ADBC のメソッドをドライバーから使用すると、パフォーマンスが向上します。これらのメソッドは、 Pandas データフレームに変換できる結果を返すことに注意してください。time
型での問題を避けるために、パラメータadbc.flight.sql.rpc.call_header.timePrecision
をmilliseconds
の値で指定することをお勧めします。マイクロ秒
の精度を使用するtime
型はサポートされません。ビューのイントロスペクションを行ったり、その型の列を含むクエリを実行したりすると、エラーが返されます。
例¶
コネクションを開く
from adbc_driver_flightsql.dbapi import connect
def get_connection():
return connect(
"grpc://denodo-server.acme.com:9994",
db_kwargs={
"username": 'user',
"password": 'password',
"adbc.flight.sql.rpc.call_header.database": 'acme_db',
"adbc.flight.sql.rpc.call_header.timePrecision": 'milliseconds',
}
, autocommit=True)
TLS を使用してコネクションを開き、証明書の検証をスキップする
from adbc_driver_flightsql.dbapi import connect
def get_connection():
return connect(
"grpc+tls://denodo-server.acme.com:9994",
db_kwargs={
"username": 'user',
"password": 'password',
"adbc.flight.sql.client_option.tls_skip_verify": 'true',
"adbc.flight.sql.rpc.call_header.database": 'acme_db',
"adbc.flight.sql.rpc.call_header.timePrecision": 'milliseconds',
}
, autocommit=True)
TLS を使用してコネクションを開き、カスタム証明書を指定する
from adbc_driver_flightsql.dbapi import connect
def get_connection():
cert_file = open("/<certificate-route>/my-certificate.crt", "r")
crt = cert_file.read()
cert_file.close()
return connect(
"grpc+tls://denodo-server.acme.com:9994",
db_kwargs={
"username": 'user',
"password": 'password',
"adbc.flight.sql.client_option.tls_root_certs": crt,
"adbc.flight.sql.rpc.call_header.database": 'acme_db',
"adbc.flight.sql.rpc.call_header.timePrecision": 'milliseconds',
}
, autocommit=True)
クエリを実行して結果を Pandas データフレームに変換する例
with conn.cursor() as cur:
cur.execute("SELECT * FROM VIEW")
data = cur.fetchallarrow()
dataframe = data.to_pandas()
print(dataframe.head)