Pythonコネクタ API

Python用Snowflakeコネクタは、Pythonデータベース API v2.0仕様(PEP-249)を実装しています。このトピックでは、標準の API およびSnowflake固有の拡張機能について説明します。

このトピックの内容:

モジュール: snowflake.connector

メインモジュールは snowflake.connector で、 Connection オブジェクトを作成し、 Error クラスを提供します。

定数

apilevel

サポートされている API レベルを示す文字列定数。コネクタは API "2.0" をサポートします。

threadsafety

インターフェイスがサポートするスレッドセーフティのレベルを示す整数定数。Python用Snowflakeコネクタは、レベル 2 をサポートします。これは、スレッドがモジュールと接続を共有できることを示しています。

paramstyle

インターフェイスで予期されるパラメーターマーカーの形式の型を示す文字列定数。コネクタはデフォルトで "pyformat" 型をサポートします。これはPython拡張フォーマットコード(例: ...WHERE name=%s または ...WHERE name=%(name)s)に適用されます。 Connection.connectparamstyle を上書きして、バインド変数の形式を  "qmark"  または  "numeric" に変更できます。変数はそれぞれ  ?  または  :N です。

例:

format: .execute("... WHERE my_column = %s", (value,))
pyformat: .execute("... WHERE my_column = %(name)s", {"name": value})
qmark: .execute("... WHERE my_column = ?", (value,))
numeric: .execute("... WHERE my_column = :1", (value,))
Copy

注釈

バインド変数は、 paramstyle"pyformat" または "format" の場合はクライアント側で発生し、 "qmark" または "numeric" の場合はサーバー側で発生します。現在、コネクタは複数の実行の後に続く SQL テキストのコンパイルをサポートしていないため、パフォーマンスまたは機能の点でこれらのオプションに大きな違いはありません。代わりに、 "qmark" および "numeric" オプションは、他のドライバーのクエリテキストの互換性と一致します(つまり、 JDBC、 ODBC、Go Snowflake Driver)、変数形式 ? または :N のサーバー側バインドをサポートします。

関数

connect(parameters...)
目的

データベースへの接続を作成するためのコンストラクター。 Connection オブジェクトを返します。

デフォルトでは、自動コミットモードは 有効 です(つまり、接続を閉じると、すべての変更がコミットされる)。トランザクションが必要な場合は、 BEGIN コマンドを使用してトランザクションを開始し、 COMMIT または ROLLBACK を使用して変更をコミットまたはロールバックします。

パラメーター

有効な入力パラメーターは次のとおりです。

パラメーター

必須

説明

account

はい

使用するアカウント識別子。アカウント識別子には snowflakecomputing.com サフィックスが含まれて いません. . 詳細と例については、 使用上の注意 (このトピック内)をご参照ください。

user

はい

ユーザーのログイン名。

password

はい

ユーザーのパスワード。

region

廃止 このパラメーターの説明は、下位互換性のみを目的としています。

host

使用されなくなりました ホスト名。内部でのみ使用されます(つまり、設定の必要なし)。

port

使用されなくなりました ポート番号(デフォルトでは 443)。内部でのみ使用されます(つまり、設定の必要なし)。

database

使用するデフォルトのデータベースの名前。ログイン後、 USE DATABASE を使用してデータベースを変更できます。

schema

データベースに使用するデフォルトのスキーマの名前。ログイン後、 USE SCHEMA を使用してスキーマを変更できます。

role

使用する既定のロールの名前。ログイン後、 USE ROLE を使用してロールを変更できます。

warehouse

使用するデフォルトのウェアハウスの名前。ログイン後、 USE WAREHOUSE を使用してウェアハウスを変更できます。

passcode_in_password

デフォルトでは、 False 。ログインパスワードに MFA (多要素認証)パスコードが埋め込まれている場合は、 True に設定します。

passcode

ログインで MFA (多要素認証)を使用するときにDuoによって提供されるパスコード。

private_key

認証に使用される秘密キー。詳細については、 キーペア認証とキーペアローテーションの使用 をご参照ください。

private_key_file

指定したユーザーの秘密キーファイルへのパスを指定します。 キーペア認証とキーペアローテーションの使用 をご参照ください。

private_key_file_pwd

指定されたユーザーの秘密キーファイルを復号化するためのパスフレーズを指定します。 キーペア認証とキーペアローテーションの使用 をご参照ください。

autocommit

デフォルトでは None 。Snowflakeパラメーター AUTOCOMMIT が優先されます。セッションで自動コミットモードを有効または無効にするには、それぞれ True または False に設定します。

client_prefetch_threads

結果セットのダウンロードに使用されるスレッドの数(デフォルトでは 4)。値を大きくするとフェッチのパフォーマンスは向上しますが、より多くのメモリが必要になります。

client_session_keep_alive

セッションを無期限に(ユーザーからのアクティビティがない場合でも)アクティブに保つには、これを True に設定します。これを True に設定する場合は、 close メソッドを呼び出してスレッドを適切に終了してください。そうしないと、プロセスがハングする可能性があります。

デフォルト値は、使用しているコネクタのバージョンによって異なります。

  • バージョン2.4.6以降: デフォルトでは None. 値が None の場合は、 CLIENT_SESSION_KEEP_ALIVE セッションパラメーターが優先されます。 . . セッションパラメーターを上書きするには、この引数に True または False を渡します。

  • バージョン2.4.5以前: デフォルトでは False. 値が False の場合は(値を明示的に指定するか、引数を省略することにより)、 CLIENT_SESSION_KEEP_ALIVE セッションパラメーターが優先されます。 . . client_session_keey_alive=Falseconnect メソッドに渡しても、 CLIENT_SESSION_KEEP_ALIVE セッションパラメーターの値 TRUE は上書き されません

login_timeout

ログイン用秒単位のタイムアウト。デフォルトでは、60秒。 HTTP 応答が「成功」の場合、タイムアウトの長さの後にログインリクエストは放棄されます。

network_timeout

他のすべての操作のタイムアウト(秒)。デフォルトでは、なし/無限。 HTTP 応答が「成功」ではない場合、一般的なリクエストは、タイムアウトの長さの後に放棄されます。

ocsp_response_cache_filename

URI OCSP 応答キャッシュファイル用。デフォルトでは、 OCSP 応答キャッシュファイルはキャッシュディレクトリに作成されます。

  • Linux: ~/.cache/snowflake/ocsp_response_cache

  • macOS: ~/Library/Caches/Snowflake/ocsp_response_cache

  • Windows: %USERPROFILE%\AppData\Local\Snowflake\Caches\ocsp_response_cache

別のディレクトリでファイルを見つけるには、 URI でパスとファイル名を指定します(例: file:///tmp/my_ocsp_response_cache.txt)。

authenticator

Snowflakeの認証方式:

  • snowflake (デフォルト)は、内部Snowflake認証方式を使用します。

  • externalbrowser は、ウェブブラウザーとOkta、AD FS、またはアカウントに定義されている他の SAML 2.0準拠のIDプロバイダー(IdP)を使用して認証します。

  • https://<Oktaのアカウント名>.okta.com (つまり、OktaのURLエンドポイント)でネイティブOktaを介して認証します。

  • OAuthを使用して認証する oauth。また、 token パラメーターを指定して、その値を OAuth アクセストークンに設定する必要があります。

値が snowflake でない場合、ユーザーとパスワードのパラメーターは IdP のログイン認証情報である必要があります。

validate_default_parameters

デフォルトでは、 FalseTrue の場合、

  • 指定されたデータベース、スキーマ、またはウェアハウスのいずれかが存在しない場合、例外を発生させます。

  • 無効な引数名または間違ったデータ型の引数値が渡された場合は、stderrに警告を出力します。

paramstyle

pyformat クライアント側のバインドのデフォルト。サーバー側バインドのバインド変数形式を変更するには、 qmark または numeric を指定します。

timezone

デフォルトでは、 None。Snowflakeパラメーター TIMEZONE が優先されます。有効なタイムゾーン(例: America/Los_Angeles)に設定して、セッションのタイムゾーンを設定します。

arrow_number_to_decimal

デフォルトでは False で、これは NUMBER 列の値が倍精度浮動小数点数(float64)として返されることを意味します。 . . これを True に設定すると、 fetch_pandas_all() メソッドおよび fetch_pandas_batches() メソッドを呼び出すときに、 DECIMAL 列の値が10進数(decimal.Decimal)として返されます。 . . このパラメーターは、Python用Snowflakeコネクタのバージョン2.4.3で導入されました。

socket_timeout

ソケットレベルの読み込みと接続リクエストのタイムアウト時間(秒単位)。詳細については、 接続タイムアウトの管理 をご参照ください。

backoff_policy

再試行までの待ち時間を定義するジェネレーター関数の名前。詳細については、 再試行のための接続バックオフポリシーの管理 をご参照ください。

属性

Error, Warning, ...

Pythonデータベース API 標準で定義されているすべての例外クラス。Python用Snowflakeコネクタは、属性 msgerrnosqlstatesfqid、および raw_msg を提供します。

account パラメーターの使用上の注意(connect メソッドの場合)

必須 account パラメーターには、使用する アカウント識別子 を指定します。

アカウント識別子には snowflakecomputing.com ドメイン名が含まれて いない ことに注意してください。Snowflakeは、接続の作成時にこれを自動的に追加します。

次の例では、組織 myorganizationmyaccount を指定する、 アカウント識別子 を使用しています。

ctx = snowflake.connector.connect(
    user='<user_name>',
    password='<password>',
    account='myorganization-myaccount',
    ... )
Copy

次の例では、アカウント識別子として アカウントロケーター xy12345 を使用しています。

ctx = snowflake.connector.connect(
    user='<user_name>',
    password='<password>',
    account='xy12345',
    ... )
Copy

この例では、 AWS US 西部(オレゴン)リージョンのアカウントを使用しています。アカウントが別のリージョンにある場合、またはアカウントが別のクラウドプロバイダーを使用している場合は、 アカウントロケーターの後に追加のセグメントを指定する 必要があります。

オブジェクト: Connection

Connection オブジェクトは、データベース接続をアクティブに保つための接続およびセッション情報を保持します。閉じた場合、またはセッションの有効期限が切れた場合、後続の操作は失敗します。

メソッド

autocommit(True|False)
目的

自動コミットモードを有効または無効にします。デフォルトでは、自動コミットは有効になっています(True)。

close()
目的

接続を閉じます。接続を閉じたときにトランザクションがまだ開いている場合、変更は ロールバック されます。

接続を閉じると、サーバーからアクティブなセッションが明示的に削除されます。そうでない場合、アクティブセッションは最終的にサーバーから削除されるまで継続し、同時クエリの数が制限されます。

例:

# context manager ensures the connection is closed
with snowflake.connector.connect(...) as con:
    con.cursor().execute(...)

# try & finally to ensure the connection is closed.
con = snowflake.connector.connect(...)
try:
    con.cursor().execute(...)
finally:
    con.close()
Copy
commit()
目的

自動コミットが無効になっている場合、現在のトランザクションをコミットします。自動コミットが有効になっている場合、このメソッドは無視されます。

rollback()
目的

自動コミットが無効になっている場合、現在のトランザクションをロールバックします。自動コミットが有効になっている場合、このメソッドは無視されます。

cursor()
目的

Cursor オブジェクトを作成するためのコンストラクター。 fetch*() 呼び出しからの戻り値は、単一のシーケンスまたはシーケンスのリストになります。

cursor(snowflake.connector.DictCursor)
目的

DictCursor オブジェクトを作成するためのコンストラクター。 fetch*() 呼び出しからの戻り値は、単一のディクショナリまたはディクショナリオブジェクトのリストです。これは、結果から列名で値をフェッチするのに便利です。

execute_string(sql_text, remove_comments=False, return_cursors=True)
目的

文字列として渡された1つ以上の SQL ステートメントを実行します。 remove_commentsTrue に設定されている場合、コメントはクエリから削除されます。 return_cursorsTrue に設定されている場合、このメソッドは実行順に Cursor オブジェクトのシーケンスを返します。

この例では、単一の文字列で複数のコマンドを実行し、返されるカーソルのシーケンスを使用しています。

cursor_list = connection1.execute_string(
    "SELECT * FROM testtable WHERE col1 LIKE 'T%';"
    "SELECT * FROM testtable WHERE col2 LIKE 'A%';"
    )

for cursor in cursor_list:
   for row in cursor:
      print(row[0], row[1])
Copy

注釈

1つの文字列で複数の SQL ステートメントを許可する execute_string() などのメソッドは、 SQL インジェクション攻撃に対して脆弱です。ユーザーデータが検証されている場合を除き、文字列の連結やPythonの format() 関数といった関数の使用による、 SQL とユーザーのデータを組み合わせた SQL ステートメントの動的作成は避けてください。以下の例で問題を示します。

# "Binding" data via the format() function (UNSAFE EXAMPLE)
value1_from_user = "'ok3'); DELETE FROM testtable WHERE col1 = 'ok1'; select pi("
sql_cmd = "insert into testtable(col1) values('ok1'); "                  \
          "insert into testtable(col1) values('ok2'); "                  \
          "insert into testtable(col1) values({col1});".format(col1=value1_from_user)
# Show what SQL Injection can do to a composed statement.
print(sql_cmd)

connection1.execute_string(sql_cmd)
Copy

動的に構成されたステートメントは次のようになります(読みやすくするために改行を追加)。

insert into testtable(col1) values('ok1');
insert into testtable(col1) values('ok2');
insert into testtable(col1) values('ok3');
DELETE FROM testtable WHERE col1 = 'ok1';
select pi();
Copy

信頼できないユーザーが入力した文字列の SQL ステートメントを組み合わせる場合、文字列を作成するよりもデータをステートメントにバインドする方が安全です。 execute_string() メソッドはバインドパラメーターを受け取らないため、パラメーターをバインドするには Cursor.execute() または Cursor.executemany() を使用します。

execute_stream(sql_stream, remove_comments=False)
目的

ストリームオブジェクトとして渡された1つ以上の SQL ステートメントを実行します。 remove_commentsTrue に設定されている場合、コメントはクエリから削除されます。このジェネレーターは、 SQL ステートメントの実行時に各 Cursor オブジェクトを生成します。

get_query_status(query_id)
目的

クエリのステータスを返します。

パラメーター

query_id

クエリの ID。 Snowflakeクエリ ID の取得 をご参照ください。

戻り値

クエリのステータスを表す QueryStatus オブジェクトを返します。

クエリのステータスの確認 をご参照ください。

get_query_status_throw_if_error(query_id)
目的

クエリのステータスを返します。クエリの結果がエラーの場合、このメソッドは ProgrammingError を発生します( execute() メソッドの場合と同様)。

パラメーター

query_id

クエリの ID。 Snowflakeクエリ ID の取得 をご参照ください。

戻り値

クエリのステータスを表す QueryStatus オブジェクトを返します。

クエリのステータスの確認 をご参照ください。

is_still_running(query_status)
目的

クエリステータスがクエリがまだ完了していないか、まだ処理中であることを示している場合は、 True を返します。

パラメーター

query_status

クエリのステータスを表す QueryStatus オブジェクト。クエリ用にこのオブジェクトを取得するには、 クエリのステータスの確認 をご参照ください。

クエリのステータスの確認 をご参照ください。

is_an_error(query_status)
目的

クエリステータスがクエリでエラーが発生したことを示している場合は、 True を返します。

パラメーター

query_status

クエリのステータスを表す QueryStatus オブジェクト。クエリ用にこのオブジェクトを取得するには、 クエリのステータスの確認 をご参照ください。

クエリのステータスの確認 をご参照ください。

属性

expired

接続のマスタートークンの有効期限が切れているかどうかを追跡します。

messages

この接続の基礎となるデータベースから受信したすべてのメッセージのシーケンス(例外クラス、例外値)を含むリストオブジェクト。

リストは、メソッドの呼び出しによって自動的にクリアされます。

errorhandler

エラー条件が満たされた場合に呼び出すエラーハンドラーを参照する読み取り/書き込み属性。

ハンドラーは、次の引数を受け入れるPython呼び出し可能ハンドラーでなければなりません。

errorhandler(connection, cursor, errorclass, errorvalue)

Error, Warning, ...

Pythonデータベース API 標準で定義されているすべての例外クラス。

オブジェクト: Cursor

Cursor オブジェクトは、実行およびフェッチ操作のデータベースカーソルを表します。各カーソルには descriptionrowcount の独自の属性があり、カーソルが分離されます。

メソッド

close()
目的

カーソルオブジェクトを閉じます。

describe(command [, parameters][, timeout][, file_stream])
目的

データベースコマンドを実行 することなく、結果セットに関するメタデータを返します。これにより、クエリの実行後に description 属性で使用できるものと同じメタデータが返されます。

このメソッドは、Python用Snowflakeコネクタのバージョン2.4.6で導入されました。

パラメーター

execute() メソッドのパラメーターをご参照ください。

戻り値

結果セットの列を説明する ResultMetadata オブジェクトのリストを返します。

列のメタデータの取得 をご参照ください。

execute(command [, parameters][, timeout][, file_stream])
目的

データベースコマンドを準備して実行します。

パラメーター

command

実行する SQL ステートメントを含む文字列。

parameters

(オプション) SQL ステートメントで バインドデータ にパラメーターを使用した場合は、これらのパラメーターにバインドする必要がある変数のリストまたはディクショナリにこれを設定します。

変数のPythonデータ型を対応する列の SQL データ型にマッピングする方法の詳細については、 qmark および numeric バインドのデータ型マッピング をご参照ください。

timeout

(オプション)クエリが完了するのを待機する秒数。この時間が経過してもクエリが完了しない場合は、クエリを中止する必要があります。

file_stream

(オプション) PUT コマンドを実行する場合は、このパラメーターを使用して、ファイルシステム上のファイルではなく、メモリ内のファイルのようなオブジェクト(例: Python open() 関数から返されたI/Oオブジェクト)をアップロードできます。このパラメーターをそのI/Oオブジェクトに設定します。

PUT コマンドでデータファイルに URI を指定する場合、

  • 任意のディレクトリパスを使用できます。URI で指定したディレクトリパスは無視されます。

  • ファイル名には、ステージ上に作成するファイルの名前を指定します。

たとえば、ファイルストリームから次の名前のファイルにファイルをアップロードするには、

@mystage/myfile.csv
Copy

次の呼び出しを使用します。

cursor.execute(
    "PUT file://this_directory_path/is_ignored/myfile.csv @mystage",
    file_stream=<io_object>)
Copy
戻り値

Cursor オブジェクトの参照を返す。

executemany(command, seq_of_parameters)
目的

データベースコマンドを準備し、これを seq_of_parameters で見つかったすべてのパラメーターシーケンスに対して実行する。このメソッドは、 バッチ挿入操作の実行 に使用できます。

パラメーター

command

コマンドは、実行するコードを含む文字列です。文字列には、 データのバインド の1つ以上のプレースホルダー(疑問符など)を含める必要があります。

例:

"insert into testy (v1, v2) values (?, ?)"
Copy

seq_of_parameters

これは、リストまたはタプルのシーケンス(リストまたはタプル)でなければなりません。シーケンスの例については、以下のサンプルコードをご参照ください。

戻り値

Cursor オブジェクトの参照を返す。

# This example uses qmark (question mark) binding, so
# you must configure the connector to use this binding style.
from snowflake import connector
connector.paramstyle='qmark'

stmt1 = "create table testy (V1 varchar, V2 varchar)"
cs.execute(stmt1)

# A list of lists
sequence_of_parameters1 = [ ['Smith', 'Ann'], ['Jones', 'Ed'] ]
# A tuple of tuples
sequence_of_parameters2 = ( ('Cho', 'Kim'), ('Cooper', 'Pat') )

stmt2 = "insert into testy (v1, v2) values (?, ?)"
cs.executemany(stmt2, sequence_of_parameters1)
cs.executemany(stmt2, sequence_of_parameters2)
Copy

内部的には、複数の execute メソッドが呼び出され、最後の execute 呼び出しからの結果セットが残ります。

注釈

executemany メソッドは、単一のパラメーター化された SQL ステートメントを実行し、複数のバインド値を渡すためにのみ使用できます。

1回の execute 呼び出しでセミコロンにより区切られた、複数の SQL ステートメントの実行はサポートされていません。代わりに、ステートメントごとに個別の execute 呼び出しを発行します。

execute_async(...)
目的

非同期実行用のデータベースコマンドを準備して送信します。 非同期クエリの実行 をご参照ください。

パラメーター

このメソッドは、 execute() メソッドと同じパラメーターを使用します。

戻り値

Cursor オブジェクトの参照を返す。

非同期クエリの例 をご参照ください。

fetch_arrow_all()
目的

このメソッドは、カーソル内のすべての行をフェッチし、 PyArrow テーブルにロードします。

パラメーター

なし。

戻り値

結果セットのすべての行を含む PyArrow テーブルを返します。

行がない場合は、Noneを返します。

Python用Snowflakeコネクタを使用して結果をフェッチするワークロードの分散 をご参照ください。

fetch_arrow_batches()
目的

このメソッドは、カーソル内の行のサブセットを取得し、 PyArrow テーブルに配信します。

パラメーター

なし。

戻り値

結果セットの行のサブセットを含む PyArrow テーブルを返します。

取得する行がもうない場合はNoneを返します。

Python用Snowflakeコネクタを使用して結果をフェッチするワークロードの分散 をご参照ください。

get_result_batches()
目的

結果セットから行のサブセットをフェッチするために使用できる ResultBatch オブジェクトのリストを返します。

パラメーター

なし。

戻り値

ResultBatch オブジェクトのリストを返します。クエリの実行が完了していない場合は、 None を返します。

Python用Snowflakeコネクタを使用して結果をフェッチするワークロードの分散 をご参照ください。

get_results_from_sfqid(query_id)
目的

非同期クエリまたは以前に送信された同期クエリの結果を取得します。

パラメーター

query_id

クエリの ID。 Snowflakeクエリ ID の取得 をご参照ください。

クエリ ID を使用したクエリの結果の取得 をご参照ください。

fetchone()
目的

クエリ結果セットの次の行をフェッチし、使用可能なデータがなくなったときに単一のシーケンス/ディクショナリまたは None を返します。

fetchmany([size=cursor.arraysize])
目的

クエリ結果セットの次の行をフェッチし、シーケンス/ディクショナリのリストを返します。使用可能な行がなくなると、空のシーケンスが返されます。

fetchall()
目的

クエリ結果セットのすべてまたは残りの行をフェッチし、シーケンス/ディクショナリのリストを返します。

fetch_pandas_all()
目的

このメソッドは、カーソル内のすべての行をフェッチし、Pandas DataFrame にロードします。

パラメーター

なし。

戻り値

結果セットのすべての行を含む DataFrame を返します。Pandasデータフレームの詳細については、 Pandas DataFrame ドキュメント をご参照ください。

行がない場合は、Noneを返します。

使用上の注意
  • このメソッドは、Pandasのread_sql()メソッドを完全に置き換えるものではありません。このメソッドは、 SELECT クエリからデータを取得し、Pandas DataFrame にデータを格納するための迅速な方法を提供します。

  • 現在、このメソッドは SELECT ステートメントに対してのみ機能します。

ctx = snowflake.connector.connect(
          host=host,
          user=user,
          password=password,
          account=account,
          warehouse=warehouse,
          database=database,
          schema=schema,
          protocol='https',
          port=port)

# Create a cursor object.
cur = ctx.cursor()

# Execute a statement that will generate a result set.
sql = "select * from t"
cur.execute(sql)

# Fetch the result set from the cursor and deliver it as the pandas DataFrame.
df = cur.fetch_pandas_all()

# ...
Copy
fetch_pandas_batches()
目的

このメソッドは、カーソル内の行のサブセットを取得し、Pandas DataFrame に配信します。

パラメーター

なし。

戻り値

結果セットの行のサブセットを含む DataFrame を返します。Pandasデータフレームの詳細については、 Pandas DataFrame ドキュメント をご参照ください。

取得する行がもうない場合はNoneを返します。

使用上の注意
  • 結果セット内の行数、さらにメソッド呼び出しで指定された行数に応じて、メソッドを複数回呼び出すことが必要になる場合があります。または、すべてが単一バッチに収まるときは、すべての行を返す場合があります。

  • このメソッドは、Pandasのread_sql()メソッドを完全に置き換えるものではありません。このメソッドは、 SELECT クエリからデータを取得し、Pandas DataFrame にデータを格納するための迅速な方法を提供します。

  • 現在、このメソッドは SELECT ステートメントに対してのみ機能します。

ctx = snowflake.connector.connect(
          host=host,
          user=user,
          password=password,
          account=account,
          warehouse=warehouse,
          database=database,
          schema=schema,
          protocol='https',
          port=port)

# Create a cursor object.
cur = ctx.cursor()

# Execute a statement that will generate a result set.
sql = "select * from t"
cur.execute(sql)

# Fetch the result set from the cursor and deliver it as the pandas DataFrame.
for df in cur.fetch_pandas_batches():
    my_dataframe_processing_function(df)

# ...
Copy
__iter__()

自己を返し、カーソルを反復プロトコルと互換にします。

属性

description

結果セットの列に関するメタデータを返す読み取り専用属性。

この属性は、 execute() メソッドを呼び出してクエリを実行した後に設定されます。(バージョン2.4.6以降では、 describe() メソッドを呼び出すことにより、クエリを実行せずにこのメタデータを取得できます。)

この属性は、次のいずれかに設定されます。

  • バージョン2.4.5以前: この属性は、タプルのリストに設定されます。

  • バージョン2.4.6以降: この属性は、 ResultMetadata オブジェクトのリストに設定されます。

各タプルまたは ResultMetadata オブジェクトには、結果セットの列を説明するメタデータが含まれています。メタデータには、インデックスによって、またはバージョン2.4.6以降では ResultMetadata オブジェクト属性によって、アクセスできます。

値のインデックス

ResultMetadata 属性

説明

0

name

列名。

1

type_code

内部 型コード

2

display_size

(使用されていない。internal_sizeと同じ。)

3

internal_size

内部データサイズ。

4

precision

数値データの精度。

5

scale

数値データのスケール。

6

is_nullable

True 列に NULL 値が許可されている場合、または False

この属性の取得例については、 列のメタデータの取得 をご参照ください。

rowcount

最後に生成された execute の行数を返す読み取り専用属性。 execute が実行されていない場合の値は、 -1 または None です。

sfqid

最後に実行された execute または execute_async のSnowflakeクエリ ID を返す読み取り専用属性。

arraysize

一度にフェッチする行数を fetchmany() で指定する読み取り/書き込み属性。デフォルトは 1 で、一度に1行ずつフェッチします。

connection

カーソルが作成された Connection オブジェクトへの参照を返す読み取り専用属性。

messages

カーソルの基になるデータベースから受信したすべてのメッセージのシーケンス(例外クラス、例外値)を含むリストオブジェクト。

リストは、 fetch*() 呼び出しを除くメソッド呼び出しによって自動的にクリアされます。

errorhandler

エラー条件が満たされた場合に呼び出すエラーハンドラーを参照する読み取り/書き込み属性。

ハンドラーは、次の引数を受け入れるPython呼び出し可能ハンドラーでなければなりません。

errorhandler(connection, cursor, errorclass, errorvalue)

型コード

Cursor オブジェクトでは、 description 属性と description() メソッドが、結果セットで列を説明するタプルのリストを提供します(または、バージョン2.4.6以降では、 ResultMetadata オブジェクト)。

タプルでは、インデックス 1 の値(ResultMetadata オブジェクトの type_code 属性)は列のデータ型を表します。Python用Snowflakeコネクタは、次のマップを使用し、型コードに基づいて文字列表現を取得します。

type_code

文字列表現

データ型

0

FIXED

NUMBER/INT

1

REAL

REAL

2

TEXT

VARCHAR/STRING

3

DATE

DATE

4

TIMESTAMP

TIMESTAMP

5

VARIANT

VARIANT

6

TIMESTAMP_LTZ

TIMESTAMP_LTZ

7

TIMESTAMP_TZ

TIMESTAMP_TZ

8

TIMESTAMP_NTZ

TIMESTAMP_TZ

9

OBJECT

OBJECT

10

ARRAY

ARRAY

11

BINARY

BINARY

12

TIME

TIME

13

BOOLEAN

BOOLEAN

qmark および numeric バインドのデータ型マッピング

paramstyle"qmark" または "numeric" の場合、PythonからSnowflakeデータ型への次のデフォルトマッピングが使用されます。

Pythonのデータ型

Snowflakeのデータ型

int

NUMBER(38, 0)

long

NUMBER(38, 0)

decimal

NUMBER(38、 <スケール>)

float

REAL

str

TEXT

unicode

TEXT

bytes

BINARY

bytearray

BINARY

bool

BOOLEAN

date

DATE

time

TIME

timedelta

TIME

datetime

TIMESTAMP_NTZ

struct_time

TIMESTAMP_NTZ

別のSnowflakeタイプにマッピングする必要がある場合(例: datetime から TIMESTAMP_LTZ)、Snowflake データ型と値が続くタプルでSnowflakeデータ型を指定します。例については、 datetimeと TIMESTAMP のバインド をご参照ください。

オブジェクト: Exception

PEP-249 は、エラーまたは警告が発生した場合にPython用Snowflakeコネクタが発生させる例外を定義します。アプリケーションはそれらを適切に処理し、コードの実行を継続するか停止するかを決定する必要があります。

メソッド

Exception オブジェクトに使用できるメソッドはありません。

属性

errno

Snowflake DB エラーコード。

msg

エラーコード、 SQL 状態コードおよびクエリ IDを含むエラーメッセージ。

raw_msg

エラーメッセージ。エラーコードなし、 SQL 状態コードまたはクエリ ID は含まれています。

sqlstate

ANSI 準拠の SQL 状態コード

sfqid

Snowflakeクエリ ID。

オブジェクト ResultBatch

ResultBatch オブジェクトは、結果セット内の行のサブセットを取得する関数をカプセル化します。 複数のワーカーまたはノードに結果をフェッチする作業を分散する には、 カーソル オブジェクトで get_result_batches() メソッドを呼び出して、 ResultBatch オブジェクトのリストを取得し、これらのオブジェクトを処理するために異なるワーカーまたはノードに配布します。

属性

rowcount

結果バッチ内の行数を返す読み取り専用属性。

compressed_size

結果バッチ内のデータサイズ(圧縮されている場合)を返す読み取り専用属性。

uncompressed_size

結果バッチ内のデータサイズ(非圧縮)を返す読み取り専用属性。

メソッド

to_arrow()
目的

このメソッドは、 ResultBatch オブジェクトの行を含む PyArrow テーブルを返します。

パラメーター

なし。

戻り値

ResultBatch オブジェクトの行を含む PyArrow テーブルを返します。

行がない場合は、Noneを返します。

to_pandas()
目的

このメソッドは、 ResultBatch オブジェクトの行を含むPandas DataFrame を返します。

パラメーター

なし。

戻り値

ResultBatch オブジェクトの行を含むPandas DataFrame を返します。

行がない場合は、空のPandas DataFrame を返します。

オブジェクト: ResultMetadata

ResultMetadata オブジェクトは、結果セットの列に関するメタデータを表します。これらのオブジェクトのリストは、 Cursor オブジェクトの description 属性と description メソッドによって返されます。

このオブジェクトは、Python用Snowflakeコネクタのバージョン2.4.6で導入されました。

メソッド

なし。

属性

name

列の名前

type_code

内部 型コード

display_size

不使用。internal_sizeと同じ。

internal_size

内部データサイズ。

precision

数値データの精度。

scale

数値データのスケール。

is_nullable

True 列に NULL 値が許可されている場合、または False

モジュール: snowflake.connector.constants

snowflake.connector.constants モジュールは、 API で使用する定数を定義します。

列挙型

class QueryStatus

非同期クエリのステータスを表します。この列挙型には次の定数があります。

列挙型定数

説明

RUNNING

クエリはまだ実行中です。

ABORTING

クエリはサーバー側で中止されています。

SUCCESS

クエリは正常に終了しました。

FAILED_WITH_ERROR

クエリに失敗しました。

QUEUED

クエリは、通常、リソースを待機しているため、実行のキューに入れられています(つまり、まだ実行が開始されていません)。

DISCONNECTED

セッションの接続が切断されています。クエリの状態は間もなく「FAILED_WITH_ERROR」に変わります。

RESUMING_WAREHOUSE

ウェアハウスが起動しており、クエリはまだ実行されていません。

BLOCKED

ステートメントは、別のステートメントによって保持されているロックを待機しています。

NO_DATA

通常、ステートメントがまだ実行を開始していないため、ステートメントに関するデータはまだ利用できません。

モジュール: snowflake.connector.pandas_tools

snowflake.connector.pandas_tools モジュールは、 Pandasデータ分析ライブラリ を操作するための関数を提供します。

関数

write_pandas(parameters...)
目的

Pandas DataFrame をSnowflakeデータベースのテーブルに書き込みます。

データをテーブルに書き込むために、関数はデータをParquetファイルに保存し、 PUT コマンドを使用してこれらのファイルを一時ステージにアップロードし、 COPY INTO <テーブル> コマンドを使用してデータをファイルからテーブルにコピーします。一部の関数パラメーターを使用して、 PUT および COPY INTO <テーブル> ステートメントの実行方法を制御できます。

パラメーター

有効な入力パラメーターは次のとおりです。

パラメーター

必須

説明

conn

はい

Snowflakeデータベースへの接続を保持する Connection オブジェクト。

df

はい

テーブルにコピーされるデータを含む pandas.DataFrame オブジェクト。

table_name

はい

データがコピーされるテーブルの名前。

database

テーブルを含んでいるデータベースの名前。デフォルトでは、関数は、セッションで現在使用されているデータベースに書き込みます。ノート:このパラメーターを指定する場合は、 schema パラメーターも指定する必要があります。

schema

テーブルを含んでいるスキーマの名前。デフォルトでは、関数は、セッションで現在使用されているスキーマのテーブルに書き込みます。

chunk_size

一度に挿入する要素の数。デフォルトでは、関数はすべての要素を一度に1つのチャンクで挿入します。

compression

Parquetファイルに使用する圧縮アルゴリズム。圧縮率を上げるには "gzip" を指定し、圧縮速度を上げるには "snappy" を指定します。デフォルトでは、関数は "gzip" を使用します。

on_error

エラーの処理方法を指定します。これを ON_ERROR コピーオプション に記載されている文字列値のいずれかに設定します。デフォルトでは、関数は "ABORT_STATEMENT" を使用します。

parallel

Parquetファイルを一時ステージにアップロードする時に使用するスレッドの数。使用されるデフォルトのスレッド数とスレッド数の選択に関するガイドラインについては、 PUT コマンドの並列パラメーター をご参照ください。

quote_identifiers

False 場合は、識別子をサーバーに送信する前にコネクタが 識別子を二重引用符で囲む ことを防ぎます。デフォルトでは、コネクタは識別子を二重引用符で囲みます。

戻り値

(success, num_chunks, num_rows, output) のタプルを返します。

  • 関数がテーブルにデータを正常に書き込んだ場合、 success は、 True です。

  • num_chunks は、関数がコピーしたデータのチャンクの数です。

  • num_rows は、関数が挿入した行の数です。

  • output は、 COPY INTO <テーブル> コマンドの出力です。

次の例では、Pandas DataFrame のデータを「顧客」という名前のテーブルに書き込みます。

import pandas
from snowflake.connector.pandas_tools import write_pandas

# Create the connection to the Snowflake database.
cnx = snowflake.connector.connect(...)

# Create a DataFrame containing data about customers
df = pandas.DataFrame([('Mark', 10), ('Luke', 20)], columns=['name', 'balance'])

# Write the data from the DataFrame to the table named "customers".
success, nchunks, nrows, _ = write_pandas(cnx, df, 'customers')
Copy
pd_writer(parameters...)
目的

pd_writer は、Snowflakeデータベースにデータを挿入するための 挿入メソッド です。

pandas.DataFrame.to_sqlPandasドキュメント を参照)を呼び出すときに、データを挿入するメソッドとして pd_writer を使用することを指定するために method=pd_writer を渡します。(独自のコードから pd_writer を呼び出す必要はありません。 to_sql メソッドが pd_writer を呼び出し、必要な入力パラメーターを提供します。)

注釈

pandas DataFrame の列名に小文字しか含まれていない場合は、列名を二重引用符で囲む必要があることに注意してください。そうしないと、コネクタは ProgrammingError を発生します。

snowflake-sqlalchemy ライブラリはテーブルを作成する際に小文字の列名を引用符で囲みませんが、 pd_writer はデフォルトで列名を引用符で囲みます。この問題は、 COPY INTO コマンドでは列名を引用符で囲むことを想定しているために発生します。

今後の改善は snowflake-sqlalchemy ライブラリで行われる予定です。

例:

import pandas as pd
from snowflake.connector.pandas_tools import pd_writer

sf_connector_version_df = pd.DataFrame([('snowflake-connector-python', '1.0')], columns=['NAME', 'NEWEST_VERSION'])

# Specify that the to_sql method should use the pd_writer function
# to write the data from the DataFrame to the table named "driver_versions"
# in the Snowflake database.
sf_connector_version_df.to_sql('driver_versions', engine, index=False, method=pd_writer)

# When the column names consist of only lower case letters, quote the column names
sf_connector_version_df = pd.DataFrame([('snowflake-connector-python', '1.0')], columns=['"name"', '"newest_version"'])
sf_connector_version_df.to_sql('driver_versions', engine, index=False, method=pd_writer)
Copy

pd_writer 関数は、 write_pandas() 関数を使用して、 DataFrame のデータをSnowflakeデータベースに書き込みます。

パラメーター

有効な入力パラメーターは次のとおりです。

パラメーター

必須

説明

table

はい

テーブルの pandas.io.sql.SQLTable オブジェクト。

conn

はい

Snowflakeデータベースへの接続に使用される、 sqlalchemy.engine.Engine または sqlalchemy.engine.Connection オブジェクト。

keys

はい

挿入するデータのテーブル列の名前。

data_iter

はい

挿入するデータを含む行の反復子。

次の例では、 method=pd_writerpandas.DataFrame.to_sql メソッドに渡し、次に pd_writer 関数を呼び出してPandas DataFrame のデータをSnowflakeデータベースに書き込みます。

import pandas
from snowflake.connector.pandas_tools import pd_writer

# Create a DataFrame containing data about customers
df = pandas.DataFrame([('Mark', 10), ('Luke', 20)], columns=['name', 'balance'])

# Specify that the to_sql method should use the pd_writer function
# to write the data from the DataFrame to the table named "customers"
# in the Snowflake database.
df.to_sql('customers', engine, index=False, method=pd_writer)
Copy

日付およびタイムスタンプのサポート

Snowflakeは複数の DATE および TIMESTAMP データ型をサポートし、Snowflakeコネクタでは、更新およびフェッチ操作のためにネイティブの datetime および date オブジェクトをバインドできます。

データのフェッチ

日付と時刻のデータをフェッチすると、Snowflakeのデータ型はPythonのデータ型に変換されます。

Snowflakeデータ型

Pythonのデータ型

動作

TIMESTAMP_TZ

日付時刻 および タイムゾーン情報

タイムゾーンオフセットを含むデータをフェッチし、 tzinfo オブジェクトを含む datetime に変換します。

TIMESTAMP_LTZ, TIMESTAMP

日付時刻 および タイムゾーン情報

データをフェッチし、 datetime オブジェクトに変換し、 TIMESTAMP_TYPE_MAPPING セッションパラメーターに基づいて tzinfo を添付します。

TIMESTAMP_NTZ

日付時刻

データをフェッチし、 datetime オブジェクトに変換します。タイムゾーン情報はオブジェクトに添付されません。

DATE

date

データをフェッチし、 date オブジェクトに変換します。タイムゾーン情報はオブジェクトに添付されません。

注釈

tzinfo IANA タイムゾーン名ではなく、 UTC オフセットベースのタイムゾーンオブジェクトです。タイムゾーン名は一致しない場合がありますが、同等のオフセットベースのタイムゾーンオブジェクトは同一と見なされます。

データの更新

日付と時刻のデータを更新すると、Pythonデータ型はSnowflakeデータ型に変換されます。

Pythonのデータ型

Snowflakeデータ型

動作

datetime

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

日付時刻オブジェクトを YYYY-MM-DD HH24:MI:SS.FF TZH:TZM 形式の文字列に変換し、更新します。タイムゾーンオフセットが指定されていない場合、文字列は YYYY-MM-DD HH24:MI:SS.FF の形式になります。ユーザーは、 datetime オブジェクトに tzinfo を設定する責任があります。

struct_time

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

struct_timeオブジェクトを YYYY-MM-DD HH24:MI:SS.FF TZH:TZM の形式の文字列に変換し、更新します。タイムゾーン情報は、 UTC からのタイムゾーンオフセットを含む time.timezone から取得されます。ユーザーは、 time.timezone の TZ 環境変数を設定する責任があります。

date

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

日付オブジェクトを YYYY-MM-DD の形式の文字列に変換します。タイムゾーンは考慮されません。

time

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

時間オブジェクトを HH24:MI:SS.FF の形式の文字列に変換します。タイムゾーンは考慮されません。

timedelta

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

タイムデルタオブジェクトを HH24:MI:SS.FF の形式の文字列に変換します。タイムゾーンは考慮されません。