Pythonコネクタ API

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

このトピックの内容:

モジュール: snowflake.connector

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

定数

apilevel

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

threadsafety

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

paramstyle

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

例:

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

注釈

バインド変数は、 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

デフォルトでは、 FalseTrue に設定すると、ユーザーからのアクティビティがない場合でもセッションを無期限にアクティブに保ちます。 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

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

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

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

paramstyle

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

timezone

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

属性

Error, Warning, ...

Pythonデータベース API 標準で定義されているすべての例外クラス。Python用Snowflakeコネクタは、属性 msgerrnosqlstatesfqid、および 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_commentsTrue に設定されている場合、コメントはクエリから削除されます。 return_cursorsTrue に設定されている場合、このメソッドは実行順に Cursor オブジェクトのシーケンスを返します。

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

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

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

注釈

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

属性

messages

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

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

errorhandler

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

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

errorhandler(connection, cursor, errorclass, errorvalue)

Error, Warning, ...

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

オブジェクト: Cursor

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

メソッド

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_writerpandas.DataFrame.to_sql メソッドに渡し、次に pd_writer 関数を呼び出してPandas DataFrame のデータをSnowflakeデータベースに書き込みます。

import pandas
from snowflake.connector.pandas_tools import pd_writer

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

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

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

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