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
セグメントが 必要 です。詳細については、以下をご参照ください。
オブジェクト: 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
(...)¶
-
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のデータ型 |
---|---|
|
NUMBER(38, 0) |
|
NUMBER(38, 0) |
|
NUMBER(38、 <スケール>) |
|
REAL |
|
TEXT |
|
TEXT |
|
BINARY |
|
BINARY |
|
BOOLEAN |
|
DATE |
|
TIME |
|
TIME |
|
TIMESTAMP_NTZ |
|
TIMESTAMP_NTZ |
別のSnowflakeタイプにマッピングする必要がある場合(例: datetime
から TIMESTAMP_LTZ
)、Snowflake データ型と値が続くタプルでSnowflakeデータ型を指定します。例については、 datetimeと TIMESTAMP のバインド をご参照ください。
オブジェクト: Exception
¶
PEP-249 は、エラーまたは警告が発生した場合にPython用Snowflakeコネクタが発生させる例外を定義します。アプリケーションはそれらを適切に処理し、コードの実行を継続するか停止するかを決定する必要があります。
メソッド¶
Exception
オブジェクトに使用できるメソッドはありません。
モジュール: 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 |
タイムゾーンオフセットを含むデータをフェッチし、 |
|
TIMESTAMP_LTZ, TIMESTAMP |
データをフェッチし、 |
|
TIMESTAMP_NTZ |
データをフェッチし、 |
|
DATE |
データをフェッチし、 |
注釈
tzinfo
IANA タイムゾーン名ではなく、 UTC オフセットベースのタイムゾーンオブジェクトです。タイムゾーン名は一致しない場合がありますが、同等のオフセットベースのタイムゾーンオブジェクトは同一と見なされます。
データの更新¶
日付と時刻のデータを更新すると、Pythonデータ型はSnowflakeデータ型に変換されます。
Pythonのデータ型 |
Snowflakeのデータ型 |
動作 |
---|---|---|
datetime |
TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE |
日付時刻オブジェクトを |
struct_time |
TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE |
struct_timeオブジェクトを |
date |
TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE |
日付オブジェクトを |
time |
TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE |
時間オブジェクトを |
timedelta |
TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE |
タイムデルタオブジェクトを |