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によって提供されるパスコード。
`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` to authenticate using your web browser and Okta, ADFS, or any other SAML 2.0-compliant identity provider (IdP) that has been defined for your account.
		`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`
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 がアカウントで有効になっている場合、アカウント名には追加の privatelink セグメントが必要です。詳細については、 AWS PrivateLink と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 オブジェクトを生成します。

属性¶

messages¶

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

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

errorhandler¶

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

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

errorhandler(connection, cursor, errorclass, errorvalue)

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

オブジェクト： `Cursor`¶

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

メソッド¶

close()

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

execute(operation[, parameters])¶

目的

データベース操作（つまり、クエリまたはコマンド）を準備して実行します。

パラメーター

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

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

戻り値

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

executemany(operation, seq_of_parameters)¶

目的

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

パラメーター

operation

操作は、実行するコードを含む文字列です。文字列には、データのバインドの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 呼び出しをパブリッシュします。

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 の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.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 コマンドの並列パラメーターをご参照ください。

戻り値

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

関数がテーブルにデータを正常に書き込んだ場合、 成功 は、 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 を呼び出す時は、 method=pd_writer を渡し、データを挿入するメソッドとして pd_writer を使用することを指定します。（独自のコードから pd_writer を呼び出す必要はありません。 to_sql メソッドが pd_writer を呼び出し、必要な入力パラメーターを提供します。）

pd_writer 関数は、 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¶

メソッド¶

属性¶

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

関数¶

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

データのフェッチ¶

データの更新¶

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

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

オブジェクト： `Connection`¶

オブジェクト： `Cursor`¶

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

オブジェクト： `Exception`¶

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