はじめに¶

本ドキュメントでは、GridDB PythonAPIのSQLインタフェースについて説明します。

GridDB PythonAPIのSQLインタフェースは、JPype DBAPI2(OSS)を利用してJDBCドライバにアクセスし、 DBAPI2仕様に準拠した操作を提供します。

また、検索結果が大量ヒット時のデータ取得を高速化するために、Apache Arrow(OSS)の 利用方法についても説明します。

※ DBAPI2: PEP 249 – Python Database API Specification v2.0

https://peps.python.org/pep-0249/

• Python言語標準のDBアクセス用のAPI仕様

※ JPype:

https://jpype.readthedocs.io/en/latest/index.html

• Python からJNI(Java Native Interface)経由で Java アクセスを提供するソフト(OSS)

※ JPype DBAPI2:

https://jpype.readthedocs.io/en/latest/dbapi2.html

• JPype内のモジュールの1つ。JDBCドライバ上にDBAPI仕様による操作（実装）を提供するソフト(OSS)

※ Apahe Arrow:

https://arrow.apache.org/

• Apacheプロジェクトの1つ。効率的なデータ交換のために設計された、カラム指向のデータフォーマット、ソフト(OSS)

インストール¶

# pip install JPype1-1.5.0-cp###-cp###-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

# pip install JPype1-1.5.0-cp###-cp###-win_amd64.whl

# pip install pyarrow-16.0.0-cp###-cp###-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

# pip install pyarrow-16.0.0-cp###-cp###-win_amd64.whl

# rpm –ivh griddb-ee-python-lib-X.X.X-linux.x86_64.rpm

# dpkg –i griddb-ee-python-lib_X.X.X_amd64.deb

# export _JAVA_OPTIONS="--add-opens=java.base/java.nio=ALL-UNNAMED"

基本編¶

import jpype
import jpype.dbapi2
jpype.startJVM(classpath=['/usr/share/java/gridstore-jdbc.jar'])

url = "jdbc:gs://127.0.0.1:20001/myCluster/public"
conn = jpype.dbapi2.connect(url, driver="com.toshiba.mwcloud.gs.sql.Driver",
        driver_args={"user":"admin", "password":"admin"})

jdbc:gs://(multicastAddress):(portNo)/(clusterName)/(databaseName)

jdbc:gs://(nodeAddress):(portNo)/(clusterName)/(databaseName)

jdbc:gs:///(clusterName)/(databaseName)?notificationMember=(notificationMember)

jdbc:gs:///(clusterName)/(databaseName)?notificationProvider=(notificationProvider)

curs = conn.cursor()
curs.execute("CREATE TABLE IF NOT EXISTS Sample ( id integer PRIMARY KEY, value string )")
curs.execute("INSERT INTO Sample values (0, 'test0')")
curs.execute("INSERT INTO Sample values (1, 'test1')")
curs.execute("SELECT * from Sample where id > 0")
print(curs.fetchall())

curs = conn.cursor()
curs.execute("INSERT INTO Sample values (?, ?)", (0, 'test0'))

curs = conn.cursor()
data = [ (0, 'test0'), (1, 'test1'), (2, 'test2') ]
curs.executemany("INSERT INTO Sample values (?, ?)", data)

curs.execute("SELECT * from Sample where id > 0")
curs.fetchone()

curs.execute("SELECT * from Sample where id > 0")
curs.fetchmany(10)

curs.execute("SELECT * from Sample where id > 0")
curs.fetchall()

応用編¶

JPype DBAPI2のカスタマイズ機能を使うことで、以下の操作が可能となります。

• TIMESTAMP型のナノ秒精度でのデータ取得

• int/float型でのデータ取得

• BLOB型のデータ設定

JPype DBAPI2をカスタマイズするために、Adapters/Convertersを使うことになります。

• Adapters：パラメータを設定するときに、Python型からJava型に変換するために使用されます。

• Converters：検索結果が生成されるとコンバータを使用して、Java型をPython型に変換し直すことができます。

import jpype.imports
import java.sql.Timestamp

conn._converters[java.sql.Timestamp] = jpype.dbapi2._nop

conn._converters[jpype.JByte] = int
conn._converters[jpype.JShort] = int
conn._converters[jpype.JInt] = int
conn._converters[jpype.JLong] = int
conn._converters[jpype.JFloat] = float
conn._converters[jpype.JDouble] = float

import jpype.imports
from javax.sql.rowset.serial import SerialBlob

conn._adapters[bytes] = SerialBlob
jpype.dbapi2._default_setters[SerialBlob] = jpype.dbapi2.BLOB

import jpype.imports
from javax.sql.rowset.serial import SerialBlob

conn._adapters[jpype.JArray(jpype.JByte)] = SerialBlob
jpype.dbapi2._default_setters[SerialBlob] = jpype.dbapi2.BLOB

結果取得の高速化¶

検索結果が大量になる場合、結果取得に時間がかかります。 Apache Arrowを使って結果取得することで、処理時間が短縮される場合があります。 Apache Arrowを使った結果取得の方法には2通りあります。

• 全件一括取得

• 全件分割取得

・JVM起動時のclasspathにJava処理用のjarファイル(/usr/share/java/gridstore-arrow-jdbc.jar)のパスを追加します。

※ Windows系のOSの場合は、コピーしたjarファイルのパスを指定してください。

(Arrow JDBC Adapter)

JPype経由で以下のJavaクラスを利用します。

(PyArrow - Apache Arrow Python bindings)

また、以下のPython上のArrow用オブジェクトを利用します。

import pyarrow.jvm
from org.apache.arrow.adapter.jdbc import JdbcToArrow
from org.apache.arrow.memory import RootAllocator

ra = RootAllocator(sys.maxsize)

result_set = curs.resultSet

it = JdbcToArrow.sqlToArrowVectorIterator(result_set, ra)
while it.hasNext():
    root = it.next()
    if root.getRowCount() == 0:
        break
    x = pyarrow.jvm.record_batch(root)
    print(x)

import pyarrow.jvm
from org.apache.arrow.adapter.jdbc import JdbcToArrowConfigBuilder, JdbcToArrow
from org.apache.arrow.memory import RootAllocator

ra = RootAllocator(sys.maxsize)

config_builder = JdbcToArrowConfigBuilder()
config_builder.setAllocator(ra)
config_builder.setTargetBatchSize(2) # 分割して取得する件数を設定
pyarrow_jdbc_config = config_builder.build()

result_set = curs.resultSet

it = JdbcToArrow.sqlToArrowVectorIterator(result_set, pyarrow_jdbc_config)
while it.hasNext():
    root = it.next()
    if root.getRowCount() == 0:
        break
    x = pyarrow.jvm.record_batch(root)
    print(x)

JPype DBAPI2のAPIリファレンス¶

Connection Objects¶

class dbapi2.Connection¶

接続により、JDBC データベースへのアクセスが提供されます。

接続は管理され、Python の with ステートメントの一部として使用できます。 接続は、ガベージ コレクションされたとき、with ステートメントのスコープ の終了時、または手動で閉じられたときに自動的に閉じられます。 接続が閉じられると、データベースを使用するすべての操作でエラーが発生します。

property autocommit¶

自動コミット動作を制御するプロパティ。【JPype DBAPI2仕様】

True/Falseの設定操作は可能ですが変更はできません。常にTrueを返します。【GridDB仕様】

Type:

bool

close()¶

(.__del__() が呼び出されるたびにではなく、)すぐに接続を閉じます。

この時点から接続は使用できなくなります。 接続で何らかの操作を行おうとすると、Error (またはサブクラス) 例外が発生します。 接続を使用しようとしているすべてのカーソルオブジェクトにも同じことが適用されます。

commit()¶

コミット

未サポートです。実行するとエラーになります。【GridDB仕様】

property connection¶

この Python Connectionオブジェクトをサポートする JDBC Connectionオブジェクトを取得します。【JPype DBAPI2仕様】

これを使用して、DBAPIドライバの範囲外にある追加のメタデータやその他の機能を取得できます。

cursor()¶

新しいカーソル オブジェクトを返します。

rollback()¶

ロールバック

未サポートです。実行するとエラーになります。【GridDB仕様】

property typeinfo¶

このドライバでサポートされているタイプのリスト。【JPype DBAPI2仕様】

これはドライバの機能を確認するのに役立ちます。

Type:

list

Cursor Objects¶

class dbapi2.Cursor¶

カーソルはクエリを実行し、結果を取得するために使用されます。

一部は PreparedStatement、一部は ResultSet で、カーソルは両方の組み合わせです。 JDBCのresultSetオブジェクトには resultSetプロパティでアクセスできます。

カーソルは管理され、Python の with ステートメントの一部として使用できます。 カーソルは、ガベージ コレクションされたとき、with ステートメントのスコープの終了時、 または手動で閉じられたときに自動的に閉じます。 カーソルが閉じられると、データベースを使用するすべての操作でエラーが発生します。

property arraysize¶

.fetchmany()メソッドで取得する行数を指定します。

この読み取り/書き込み属性は、.fetchmany()メソッドで一度に取得する行数を指定します。 デフォルトでは1に設定され、一度に1行取得することを意味します。

callproc(procname, parameters=())¶

ストアド プロシージャを呼び出します。

未サポートです。実行するとエラーになります。【GridDB仕様】

close()¶

(__del__ が呼び出されるたびに閉じるのではなく、)すぐにカーソルを閉じます。

この時点からカーソルは使用できなくなります。 カーソルを使用して何らかの操作を行おうとすると、Error (またはサブクラス) 例外が発生します。

property description¶

[読み取り専用属性] descriptionは7項目のシーケンスのシーケンスです。【JPype DBAPI2仕様】

これらの各シーケンスには、1 つの結果列を記述する情報が含まれています。

• 名前(name):列名

• タイプコード(type_code):列のデータ型

• 表示サイズ(display_size):常に131072【GridDB仕様】

• 内部サイズ(internal_size):常に131072【GridDB仕様】

• 精度(precision):TIMESTAMP型の場合は3(ミリ秒精度)または6(マイクロ秒精度)または9(ナノ秒精度)、他の型の場合は0【GridDB仕様】

• スケール(scale):常に0【GridDB仕様】

• isNullable(null_ok):カラムにNULL値を許可する定数ResultSetMetaData.columnNullable(=1)、またはカラムにNULL値を許可しない定数columnNoNulls(=0)【GridDB仕様】

これは、最後のクエリによって結果セット(ResultSet)が生成された場合にのみ使用できます。

execute(operation, parameters=None)¶

データベース操作 (クエリまたはコマンド) を準備して実行します。

パラメータはシーケンスとして提供され、操作内の変数にバインドされます。 変数は qmark 表記、すなわち「?」記号で指定されます。【JPype DBAPI2仕様】 JDBC はマッピング スタイルのパラメータをサポートしていません。

ステートメントを実行すると行数が更新されます。ステートメントに結果セットがない場合、 行数は -1 になります。ステートメントは複数の結果セットを生成する場合があります。 複数の結果セットを走査するには、nextset()メソッドを使用します。

パラメータ:

operation (str): 実行されるステートメント。

parameters (list, optional): ステートメントのパラメータのリスト。 パラメータの数はステートメントで要求される数と一致する必要があります。 一致しない場合はエラーが発生します。

返り値:

このカーソル。

executemany(operation, seq_of_parameters)¶

データベース操作 (クエリまたはコマンド) を準備し、 シーケンス seq_of_parameters で見つかったすべてのパラメータシーケンス またはマッピングに対してそれを実行します。

.execute() と同じコメントがこのメソッドにも適用されます。

パラメータ:

operation (str): 実行されるステートメント。

seq_of_parameters (list, optional): ステートメントのパラメータのリストのリスト。 パラメータの数は、ステートメントで要求される数と一致する必要があります。 一致しない場合は、エラーが発生します。

返り値:

このカーソル。

fetchall()¶

クエリ結果のすべての（残りの）行を取得し、 それらをシーケンスのシーケンス（タプルのリストなど）として返します。 カーソルの arraysize 属性がこの操作のパフォーマンスに影響を与える 可能性があることに注意してください。

前回の.execute*()呼び出しで結果セットが生成されなかった場合、 またはまだ呼び出しが発行されていない場合は、エラー (またはサブクラス) 例外が発生します 。

fetchmany(size=None)¶

複数の結果を取得します。

クエリ結果の次の行セットを取得し、シーケンスのシーケンス (タプルのリストなど) を返します。 使用可能な行がなくなった場合は、空のシーケンスが返されます。

呼び出しごとに取得する行数はsizeパラメータで指定します。 指定しない場合は、カーソルのarraysize属性によって取得する行数が決定されます。 メソッドは、sizeパラメータで指定された行数をできるだけ多く取得しようとします。 指定された行数が利用できないために取得できない場合は、返される行数が少なくなる場合があります。

前回の.execute*()呼び出しで結果セットが生成されなかった場合、 またはまだ呼び出しが発行されていない場合は、エラー (またはサブクラス) 例外が発生します 。

fetchone()¶

クエリ結果セットの次の行を取得し、単一のシーケンスを返します。 データがなくなった場合は None を返します。

.execute*() への以前の呼び出しで結果セットが生成されなかった場合、 またはまだ呼び出しが発行されていなかった場合は、 エラー (またはサブクラス) 例外が発生します。

property lastrowid¶

最後に挿入された行の ID を取得します。

未サポートです。実行するとエラーになります。【GridDB仕様】

nextset()¶

このカーソル内の次の結果セットを取得します。

未サポートです。常にNoneを返します。【GridDB仕様】

property parameters¶

[読み取り専用属性] parametersは6項目のシーケンスのシーケンスです。【JPype DBAPI2仕様】

これらの各シーケンスには、1 つの結果列を記述する情報が含まれています。 現GridDBでは全て常に同じ値を返します。【GridDB仕様】

• タイプ名(type_name):常に"UNKNOWN"【GridDB仕様】

• JDBCタイプ(jdbc_type):常にOTHER【GridDB仕様】

• パラメータモード(parameter_mode) (1=入力、2=入力/出力、4=出力): 常に1【GridDB仕様】

• 精度(precision): 常に0【GridDB仕様】

• スケール(scale): 常に0【GridDB仕様】

• isNullable(null_ok): 常に1【GridDB仕様】

これは、execute の後にのみ使用できます。【GridDB仕様】

property resultSet¶

[読み取り専用属性] JDBCのResultSetオブジェクトを取得します。【JPype DBAPI2仕様】

オブジェクトは、次の``execute*()``メソッド呼び出し時に閉じられます

property rowcount¶

[読み取り専用属性] UPDATE や INSERT などの DML ステートメントの場合に、 最後の .execute*() が影響を与えた行数を返します。【JPype DBAPI2仕様】

カーソルに対して .execute*() が実行されていない場合、 または最後の操作の行数がインターフェイスによって判別できない場合、 属性は -1 になります。JDBC は SELECT から返される行数の取得をサポートしていないため、 SELECT ステートメントの後の行数は -1 になります。

setinputsizes(sizes)¶

これは、.execute*() を呼び出す前に使用して、 操作のパラメータのメモリ領域を事前に定義できます。

サイズはシーケンスとして指定されます。つまり、入力パラメータごとに1つの項目です。 項目は、使用される入力に対応する Type Object であるか、 文字列パラメータの最大長を指定する整数である必要があります。 項目が None の場合、その列に対して事前定義されたメモリ領域は予約されません (これは、大きな入力に対して事前定義された領域を回避するのに役立ちます)。

このメソッドは、.execute*() メソッドが呼び出される前に使用されます。

(未実装)【JPype DBAPI2仕様】

setoutputsize(size, column=None)¶

大きな列 (LONG、BLOB など) のフェッチ用の列バッファ サイズを設定します。

列は結果シーケンスのインデックスとして指定されます。 列を指定しないと、カーソル内のすべての大きな列のデフォルト サイズが設定されます。

(未実装)【JPype DBAPI2仕様】

SQL Type Constructor¶

dbapi2.Timestamp(year, month, day, hour, minute, second, nano=0)¶

この関数は、タイムスタンプ値を保持するオブジェクトを生成します。

ナノ秒精度の値を指定できます。【JPype DBAPI2仕様】

dbapi2.TimestampFromTicks(ticks)¶

この関数は、指定された ticks 値 (エポックからの秒数) から タイムスタンプ値を保持するオブジェクトを生成します。

dbapi2.Binary(data)¶

この関数は、バイナリ (長い) 文字列値を保持できるオブジェクトを生成します。

データ型の対応関係¶

サンプルコード一覧¶

サンプルコードの一覧は以下の通りです。

作業フォルダにサンプルコードと/usr/share/java上のJarファイルをコピーして、ご利用ください。

• gridstore-jdbc.jar

• gridstore-arrow-jdbc.jar

※ Windows系のOSの場合は、startJVMメソッドのclasspath部分にコピーしたjarファイルのパスを指定してください。