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.connect は paramstyle を上書きして、バインド変数の形式を　 "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,))

注釈

バインド変数は、 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`		認証に使用される秘密キー。詳細については、キーペア認証およびキーペアローテーションの使用をご参照ください。
`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=False` を `connect` メソッドに渡しても、 `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、ADFS、またはアカウントに定義されている他のSAML 2.0準拠のIDプロバイダー（IdP）を使用して認証します。
		`https://<Oktaのアカウント名>.okta.com` （つまり、OktaのURLエンドポイント）でネイティブOktaを介して認証します。
		OAuthを使用して認証する `oauth`。また、 `token` パラメーターを指定して、その値を OAuth アクセストークンに設定する必要があります。
		`username_password_mfa` は MFA トークンキャッシングで認証します。詳細については、 MFA トークンキャッシングを使用して認証中のプロンプトの数を最小限に抑える --- オプションをご参照ください。
		値が `snowflake` でない場合、ユーザーとパスワードのパラメーターは IdP のログイン認証情報である必要があります。
`validate_default_parameters`		デフォルトでは、 `False`。 `True` の場合、
		指定されたデータベース、スキーマ、またはウェアハウスのいずれかが存在しない場合、例外を発生させます。
		無効な引数名または間違ったデータ型の引数値が渡された場合は、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で導入されました。

属性¶

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

`account` パラメーターの使用上の注意（`connect` メソッドの場合）¶

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

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

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

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

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

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

この例では、 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()

commit()¶

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

rollback()¶

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

cursor()¶

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

cursor(snowflake.connector.DictCursor)

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

execute_string(sql_text, remove_comments=False, return_cursors=True)¶

目的

文字列として渡された1つ以上の SQL ステートメントを実行します。 remove_comments が True に設定されている場合、コメントはクエリから削除されます。 return_cursors が True に設定されている場合、このメソッドは実行順に 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])

注釈

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)

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

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();

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

execute_stream(sql_stream, remove_comments=False)¶

目的: ストリームオブジェクトとして渡された1つ以上の SQL ステートメントを実行します。 remove_comments が True に設定されている場合、コメントはクエリから削除されます。このジェネレーターは、 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 オブジェクト。クエリ用にこのオブジェクトを取得するには、クエリのステータスの確認をご参照ください。
例: クエリのステータスの確認をご参照ください。

属性¶

messages¶

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

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

errorhandler¶

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

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

errorhandler(connection, cursor, errorclass, errorvalue)

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

オブジェクト： `Cursor`¶

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

メソッド¶

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
次の呼び出しを使用します。
cursor.execute(
    "PUT file://this_directory_path/is_ignored/myfile.csv @mystage",
    file_stream=<io_object>)

戻り値

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

executemany(command, seq_of_parameters)¶

目的

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

パラメーター

command

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

例：
"insert into testy (v1, v2) values (?, ?)"

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)

内部的には、複数の 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()

# ...

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)

# ...

__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')

pd_writer(parameters...)¶

目的

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

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

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

パラメーター

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

パラメーター	必須	説明
`table`	はい	テーブルの `pandas.io.sql.SQLTable` オブジェクト。
`conn`	はい	Snowflakeデータベースへの接続に使用される、 `sqlalchemy.engine.Engine` または `sqlalchemy.engine.Connection` オブジェクト。
`keys`	はい	挿入するデータのテーブル列の名前。
`data_iter`	はい	挿入するデータを含む行の反復子。

例

次の例では、 method=pd_writer を pandas.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)

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

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` の形式の文字列に変換します。タイムゾーンは考慮されません。

Pythonコネクタ API¶

モジュール： snowflake.connector¶

定数¶

関数¶

属性¶

account パラメーターの使用上の注意（connect メソッドの場合）¶

オブジェクト: Connection¶

メソッド¶

属性¶

オブジェクト： Cursor¶

メソッド¶

属性¶

型コード¶

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

オブジェクト： Exception¶

メソッド¶

属性¶

オブジェクト ResultBatch¶

属性¶

rowcount¶

compressed_size¶

uncompressed_size¶

メソッド¶

オブジェクト: ResultMetadata¶

メソッド¶

属性¶

モジュール: snowflake.connector.constants¶

列挙型¶

モジュール： snowflake.connector.pandas_tools¶

関数¶

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

データのフェッチ¶

データの更新¶

モジュール： `snowflake.connector`¶

`account` パラメーターの使用上の注意（`connect` メソッドの場合）¶

オブジェクト: `Connection`¶

オブジェクト： `Cursor`¶

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

オブジェクト： `Exception`¶

オブジェクト `ResultBatch`¶

オブジェクト: `ResultMetadata`¶

モジュール: `snowflake.connector.constants`¶

モジュール： `snowflake.connector.pandas_tools`¶