Pythonコネクタ API¶

定数¶

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,))

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	有り	ユーザーのパスワード。
application		接続を行うアプリケーションを識別する名前。
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_fetch_use_mp		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 セッションパラメーターが優先されます。. . connect メソッドに client_session_keep_alive=False を渡しても、 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%AppDataLocalSnowflakeCachesocsp_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 アクセストークンに設定する必要があります。 username_password_mfa は MFA トークンキャッシングで認証します。詳細については、 MFA トークンキャッシングを使用して認証中のプロンプトの数を最小限に抑える --- オプション をご参照ください。 OAuth 2.0認証コードフローを使用する場合は OAUTH_AUTHORIZATION_CODE。 OAuth 2.0クライアント認証情報フローを使用する場合は OAUTH_CLIENT_CREDENTIALS。 WORKLOAD_IDENTITY は、 ワークロードIDフェデレーション（WIF） 認証コードを使用して認証します。 値が 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で導入されました。
socket_timeout		ソケットレベルの読み込みと接続リクエストのタイムアウト時間（秒単位）。詳細については、 接続タイムアウトの管理 をご参照ください。
backoff_policy		再試行までの待ち時間を定義するジェネレーター関数の名前。詳細については、 再試行のための接続バックオフポリシーの管理 をご参照ください。
enable_connection_diag		接続性診断レポートを作成するかどうか。デフォルトは False です。
connection_diag_log_path		診断レポートの場所の絶対パス。enable_connection_diag が True の場合のみ使用されます。Defaultは、お使いのオペレーティング・システムのデフォルトの一時ディレクトリで、LinuxやMacでは /tmp です。
connection_diag_allowlist_path		SYSTEM$ALLOWLIST() または SYSTEM$ALLOWLIST_PRIVATELINK() の出力を含む JSON ファイルへの絶対パス。接続で定義されたユーザーがシステム許可リスト関数を実行する権限を持っていない場合、またはアカウント URL への接続に失敗した場合にのみ必要です。
iobound_tpe_limit		preprocess_tpeおよびpostprocessスレッドプール実行部のサイズ (TPEs)。デフォルト値は、ファイル数と CPU コア数のうち小さい方の値です。
unsafe_file_write		GET コマンドを使用して、ステージからダウンロードされたファイルにどのファイルアクセス権を割り当てるかを指定をします。False （デフォルト）は、所有者だけがファイルにアクセスできる権限を 600 に設定します。True は、ファイルのアクセス権を 644 に設定し、所有者には読み取りと書き込みの権限を付与し、それ以外には読み取り専用の権限を付与します。詳細については、 データのダウンロード をご参照ください。
oauth_client_id		Snowflake統合用にIDプロバイダーが提供する client id の値（Snowflakeセキュリティ統合メタデータ）。
oauth_client_secret		IDプロバイダーがSnowflake統合用に提供する client secret の値（Snowflakeセキュリティ統合メタデータ）。
oauth_authorization_url		認証コードをドライバーに提供する ID プロバイダーエンドポイント。SnowflakeをIDプロバイダーとして使用する場合、この値は server または account パラメーターから取得されます。
oauth_token_request_url		ドライバーにアクセストークンを供給する ID プロバイダーのエンドポイント。SnowflakeをIDプロバイダーとして使用する場合、この値は server または account パラメーターから取得されます。
oauth_scope		ID プロバイダー承認リクエストで要求された範囲。デフォルトでは、ロールから派生します。複数のスコープが必要な場合、値はスペースで区切られた複数のスコープのリストでなければなりません。
oauth_redirect_uri		認証コードリダイレクトに使用する URI （Snowflakeセキュリティ統合メタデータ）。デフォルト： http://127.0.0.1:{randomAvailablePort}。
oauth_disable_pkce		Proof Key for Code Exchange (PKCE) を無効にします。これは、悪意のある攻撃者が認証コードを傍受しても、有効なアクセストークンに変更できないようにするセキュリティ機能です。
oauth_enable_refresh_token		実際のアクセストークンが古くなったときに、サイレント再認証を有効にします。認証サーバーによってサポートされ、 client_store_temporary_credential が True に設定されている必要があります。
oauth_enable_single_use_refresh_tokens		シングルユース・更新・トークンのセマンティクスにオプトインするかどうか。
workload_identity_provider		ワークロードIDプロバイダーのプラットフォーム。可能な値は次のとおりです。AWS、 AZURE、 GCP および:codenowrap:OIDC。

属性¶

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 西部（オレゴン）リージョンのアカウントを使用しています。アカウントが別のリージョンにある場合、またはアカウントが別のクラウドプロバイダーを使用している場合は、 アカウントロケーターの後に追加のセグメントを指定する 必要があります。

メソッド¶

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_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])

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_comments が True に設定されている場合、コメントはクエリから削除されます。このジェネレーターは、 SQL ステートメントの実行時に各 Cursor オブジェクトを生成します。

sql_stream がコメント行で終わる場合は、 remove_comments を True に設定する必要があります。

sql_script = """
-- This is first comment line;
select 1;
select 2;
-- This is comment in middle;
-- With some extra comment lines;
select 3;
-- This is the end with last line comment;
"""
sql_stream = StringIO(sql_script)
with con.cursor() as cur:
        for result_cursor in con.execute_stream(sql_stream,remove_comments=True):
            for result in result_cursor:
                print(f"Result: {result}")

Copy

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_valid()¶

目的:

接続がクエリを受信できるほど安定している場合は True を返します。

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 標準で定義されているすべての例外クラス。

メソッド¶

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コネクタは、次のマップを使用し、型コードに基づいて文字列表現を取得します。

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

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

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

メソッド¶

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

属性¶

errno¶

Snowflake DB エラーコード。

msg¶

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

raw_msg¶

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

sqlstate¶

ANSI 準拠の SQL 状態コード

sfqid

Snowflakeクエリ ID。

属性¶

メソッド¶

to_arrow()¶

目的:

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

パラメーター:

なし。

戻り値:

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

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

to_pandas()¶

目的:

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

パラメーター:

なし。

戻り値:

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

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

メソッド¶

なし。

属性¶

name¶

列の名前

type_code¶

内部 型コード。

display_size¶

不使用。internal_sizeと同じ。

internal_size¶

内部データサイズ。

precision¶

数値データの精度。

scale¶

数値データのスケール。

is_nullable¶

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

列挙型¶

class QueryStatus¶

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

列挙型定数	説明
RUNNING	クエリはまだ実行中です。
ABORTING	クエリはサーバー側で中止されています。
SUCCESS	クエリは正常に終了しました。
FAILED_WITH_ERROR	クエリに失敗しました。
QUEUED	クエリは、通常、リソースを待機しているため、実行のキューに入れられています（つまり、まだ実行が開始されていません）。
DISCONNECTED	セッションの接続が切断されています。クエリの状態は間もなく「FAILED_WITH_ERROR」に変わります。
RESUMING_WAREHOUSE	ウェアハウスが起動しており、クエリはまだ実行されていません。
BLOCKED	ステートメントは、別のステートメントによって保持されているロックを待機しています。
NO_DATA	通常、ステートメントがまだ実行を開始していないため、ステートメントに関するデータはまだ利用できません。

関数¶

write_pandas(parameters...)¶

目的:

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

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

パラメーター:

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

パラメーター	必須	説明
conn	有り	Snowflakeデータベースへの接続を保持する Connection オブジェクト。
df	有り	テーブルにコピーされるデータを含む pandas.DataFrame オブジェクト。
table_name	有り	データがコピーされるテーブルの名前。
database		テーブルを含んでいるデータベースの名前。デフォルトでは、関数は、セッションで現在使用されているデータベースに書き込みます。ノート：このパラメーターを指定する場合は、 schema パラメーターも指定する必要があります。
schema		テーブルを含んでいるスキーマの名前。デフォルトでは、関数は、セッションで現在使用されているスキーマのテーブルに書き込みます。
bulk_upload_chunks		このパラメーターを:codenowrap: True に設定すると、:codenowrap: write_pandas 関数の動作が変更され、最初にすべてのデータチャンクをローカルディスクに書き込み、次にチャンクフォルダーのワイルドカードアップロードをステージに実行します。False に設定した場合（デフォルト）、チャンクは1つずつ保存、アップロード、削除されます。
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_sql を呼び出す時は、 method=pd_writer を渡し、データを挿入するメソッドとして pd_writer を使用することを指定します。（独自のコードから pd_writer を呼び出す必要はありません。to_sql メソッドが pd_writer を呼び出し、必要な入力パラメーターを提供します。）

詳細については、次をご参照ください。

• 挿入メソッド ドキュメント。

• pandas ドキュメント。

注釈

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_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)

Copy

データのフェッチ¶

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

データの更新¶

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