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	はい	アカウントの名前（Snowflakeが提供）。詳細については、 使用上の注意 （このトピック内）をご参照ください。
user	はい	ユーザーのログイン名。
password	はい	ユーザーのパスワード。
region		廃止 代わりに、 account パラメーターの一部として地域を指定します。このパラメーターの説明は、下位互換性のみを目的としています。
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		デフォルトでは、 False。 True に設定すると、ユーザーからのアクティビティがない場合でもセッションを無期限にアクティブに保ちます。 close メソッドを呼び出してスレッドを適切に終了してください。そうしないと、プロセスがハングする可能性があります。
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 アクセストークンに設定する必要があります。
		値が snowflake でない場合、ユーザーとパスワードのパラメーターは IdP のログイン認証情報である必要があります。
validate_default_parameters		デフォルトでは、 False。 True の場合、
		指定されたデータベース、スキーマ、またはウェアハウスのいずれかが存在しない場合、例外を発生させます。
		無効な引数名または間違ったデータ型の引数値が渡された場合は、stderrに警告を出力します。
paramstyle		pyformat クライアント側のバインドのデフォルト。サーバー側バインドのバインド変数形式を変更するには、 qmark または numeric を指定します。
timezone		デフォルトでは、 None。Snowflakeパラメーター TIMEZONE が優先されます。有効なタイムゾーン（例： America/Los_Angeles）に設定して、セッションのタイムゾーンを設定します。

属性

Error, Warning, ...

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

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

• パラメーターは、接続するSnowflakeアカウントを指定するもので、 必須 です。

• パラメーターの一部としてSnowflakeドメイン名（snowflakecomputing.com）を含め ない でください。Snowflakeはアカウント名にドメイン名を自動的に追加して、必要な接続を作成します。

• 完全なアカウント名には、アカウントがホストされている 地域 および クラウドプラットフォーム を識別する 追加 のセグメントが含まれている場合があります。

  地域別のアカウント名の例

  アカウント名が xy12345 の場合、

  クラウドプラットフォーム/地域	完全なアカウント名
  AWS
  US 西部（オレゴン）	xy12345
  US 東部（オハイオ）	xy12345.us-east-2.aws
  US 東部（バージニア北部）	xy12345.us-east-1
  US 東部（商業組織、バージニア政府北部）	xy12345.us-east-1-gov.aws
  カナダ（中部）	xy12345.ca-central-1.aws
  ヨーロッパ（ロンドン）	xy12345.eu-west-2.aws
  EU （アイルランド）	xy12345.eu-west-1
  EU （フランクフルト）	xy12345.eu-central-1
  アジア太平洋（東京）	xy12345.ap-northeast-1.aws
  アジア太平洋（ムンバイ）	xy12345.ap-south-1.aws
  アジア太平洋（シンガポール）	xy12345.ap-southeast-1
  アジア太平洋（シドニー）	xy12345.ap-southeast-2
  GCP
  US 中央部1（アイオワ）	xy12345.us-central1.gcp
  ヨーロッパ西部2（ロンドン）	xy12345.europe-west2.gcp
  ヨーロッパ西部4（オランダ）	xy12345.europe-west4.gcp
  Azure
  西 US 2（ワシントン）	xy12345.west-us-2.azure
  東 US 2（バージニア）	xy12345.east-us-2.azure
  US 政府バージニア	xy12345.us-gov-virginia.azure
  カナダ中央部（トロント）	xy12345.canada-central.azure
  西ヨーロッパ（オランダ）	xy12345.west-europe.azure
  スイス北部（チューリッヒ）	xy12345.switzerland-north.azure
  東南アジア（シンガポール）	xy12345.southeast-asia.azure
  オーストラリア東部（ニューサウスウェールズ）	xy12345.australia-east.azure

  重要

  次のいずれかの条件に該当する場合、完全なアカウント名は、上記の例の構造とは異なります。

  • Snowflake Editionが VPS の場合、アカウント名の詳細については Snowflakeサポート にお問い合わせください。

  • アカウントで AWS PrivateLink またはAzure Private Linkが有効になっている場合、アカウント名には、地域セグメントの代わりに privatelink セグメントが 必要 です。詳細については、以下をご参照ください。

    • AWS PrivateLink とSnowflake

    • Azure Private LinkとSnowflake

オブジェクト: 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()

目的

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

execute(command[, parameters])

目的

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

パラメーター

command

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

parameters

オプションのパラメーターはリストまたは辞書として提供でき、コマンド内の変数にバインドされます。バインディングパラメーターの詳細については、 データのバインド をご参照ください。どのPythonデータ型がどの SQL データ型にマッピングされるかの詳細については、 qmark および numeric バインドのデータ型マッピング をご覧ください。

戻り値

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

executemany(command, seq_of_parameters)

目的

データベースコマンドを準備し、 seq_of_parameters で見つかったすべてのパラメーターシーケンスに対して実行します。

パラメーター

command

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

例：

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

seq_of_parameters

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

戻り値

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

例

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 オブジェクトの参照を返します。

例

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

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

7つの値のシーケンスを返す読み取り専用属性：

値	説明
name	列名。
type_code	内部型コード。
display_size	（使用されていない。internal_sizeと同じ。）
internal_size	内部データサイズ。
precision	数値データの精度。
scale	数値データのスケール。
null_ok	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 属性は列のメタデータを返します。 type_code は列のデータ型を表し、次のマップを使用して文字列表現を取得します。

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。

モジュール： 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 場合は、識別子をサーバーに送信する前にコネクタが 識別子を二重引用符で囲む ことを防ぎます。デフォルトでは、コネクタは識別子を二重引用符で囲みます。

戻り値

(成功, チャンク数, 行数, 出力) のタプルを返します。

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

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

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

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