PUT¶
クライアントマシン上のローカルディレクトリ/フォルダーから次のSnowflakeステージのいずれかにデータファイルをアップロード(ステージング)します。
内部ステージという名前。
指定されたテーブルの内部ステージ。
現在のユーザーの内部ステージ。
ファイルがステージングされると、ファイル内のデータは COPY INTO <テーブル> コマンドを使用してテーブルにロードできます。
注釈
PUT は、外部ステージへのファイルのアップロードをサポートして いません。ファイルを外部ステージにアップロードするには、クラウドサービスが提供するユーティリティを使用します。
ODBC ドライバー は、次のプラットフォームでホストされているSnowflakeアカウントで PUT をサポートします。
Amazon Web Services( ODBC ドライバーバージョン2.17.5またはそれ以上を使用)。
Google Cloud Platform( ODBC ドライバーバージョン2.21.5またはそれ以上を使用)。
Microsoft Azure(ODBC Driver Version 2.20.2以降を使用)。
構文¶
PUT file://<path_to_file>/<filename> internalStage
[ PARALLEL = <integer> ]
[ AUTO_COMPRESS = TRUE | FALSE ]
[ SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE ]
[ OVERWRITE = TRUE | FALSE ]
条件:
internalStage ::= @[<namespace>.]<int_stage_name>[/<path>] | @[<namespace>.]%<table_name>[/<path>] | @~[/<path>]
必須パラメーター¶
file://path_to_file/filename
クライアントマシン上のデータファイルの URI を指定します。ここで、
path_to_file
は、アップロードするファイルのローカルディレクトリパスです。filename
は、アップロードするファイルの名前です。ディレクトリ内の複数のファイルをアップロードできるように、ワイルドカード文字(*
、?
)がサポートされています。
URI のフォーマットは、クライアントのオペレーティングシステムによって異なります。
- Linux/macOS
パスに最初のスラッシュを含める必要があります(例:
file:///tmp/load
)。ディレクトリパスやファイル名に特殊文字が含まれている場合は、ファイル URI 全体を一重引用符で囲む必要があります。
- Windows
パスにドライブとバックスラッシュを含める必要があります(例:
file://C:\temp\load
)。ディレクトリパスやファイル名に特殊文字が含まれている場合は、ファイル URI 全体を一重引用符で囲む必要があります。区切り文字は、囲まれた URIs にあるスラッシュ(
/
)であることに注意してください(例:load data
という名前のディレクトリを含むWindowsのパスの場合は'file://C:/temp/load data'
)。
internalStage
ファイルをアップロードするSnowflakeの場所を指定します。
@[namespace.]int_stage_name[/path]
指定された名前の内部ステージにファイルがアップロードされます。
@[namespace.]%table_name[/path]
指定したテーブルのステージにファイルがアップロードされます。
@~[/path]
ファイルは現在のユーザーのステージにアップロードされます。
条件:
namespace
は、指定された内部ステージまたはテーブルが存在するデータベースおよび/またはスキーマです。セッション内でデータベースとスキーマが現在使用されている場合、 オプション です。それ以外の場合は必須です。path
は、一連のファイルへのアクセスを制限するクラウドストレージの場所にある、ファイルの大文字と小文字を区別するオプションのパスです(つまり、ファイルの名前は一般的な文字列で開始)。パスは、別のクラウドストレージサービスによって プレフィックス または フォルダー と呼ばれることもあります。
注釈
ステージ名またはパスにスペースまたは特殊文字が含まれている場合は、一重引用符で囲む必要があります(例:
"my stage"
という名前のステージの場合は'@"my stage"'
)。
オプションのパラメーター¶
PARALLEL = integer
ファイルのアップロードに使用するスレッドの数を指定します。アップロードプロセスでは、サイズごとにデータファイルのバッチを分割します。
小さなファイル(圧縮または非圧縮で64 MB 未満)は、個別のファイルとして並列にステージングされます
大きなファイルは自動的にチャンクに分割され、同時にステージングされ、ターゲットステージで再アセンブルされます。1つのスレッドで複数のチャンクをアップロードできます。
スレッドの数を増やすと、大きなファイルをアップロードするときのパフォーマンスが向上します。
サポートされる値:
1
(並列処理なし)から99
(ファイルのアップロードには99スレッドを使用)の整数値。デフォルト:
4
注釈
16 MB (64 MB ではなく)の制限は、以下を含むSnowflakeドライバーの古いバージョンに適用されます。
JDBC ドライバー3.12.1より前のバージョン。
ODBC ドライバー2.20.5より前のバージョン。
Pythonコネクタ2.2.0より前のバージョン。
AUTO_COMPRESS = TRUE | FALSE
Snowflakeがgzipを使用してアップロード中にファイルを圧縮するかどうかを指定します。
TRUE
:ファイルは圧縮されます(まだ圧縮されていない場合)。FALSE
:ファイルは圧縮されません(つまり、ファイルはそのままアップロードされます)。
このオプションは、他の圧縮タイプをサポートしていません。別の圧縮タイプを使用するには、 PUT コマンドを実行する前にファイルを個別に圧縮します。次に、
SOURCE_COMPRESSION
オプションを使用して圧縮タイプを識別します。ローカルフォルダーに、Snowflakeがデータファイルをステージングする前に、圧縮するための十分なスペースがあることを確認します。必要に応じて、オペレーティングシステムで
TEMP
、TMPDIR
またはTMP
環境変数を設定して、追加の空きスペースを含むローカルフォルダーを指すようにします。デフォルト:
TRUE
SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
ステージングされる圧縮済みファイルで使用する圧縮の方法を指定します。
サポートされる値
メモ
AUTO_DETECT
現在は自動検出できない、Brotliで圧縮されたファイルを除き、圧縮アルゴリズムは自動的に検出されます。Brotliで圧縮されたファイルをロードする場合は、
AUTO_DETECT
ではなくBROTLI
を明示的に使用してください。GZIP
BZ2
BROTLI
Brotli圧縮ファイルをロードする場合に使用する必要があります。
ZSTD
Zstandard v0.8(およびそれ以上)がサポートされています。
DEFLATE
Deflate圧縮されたファイル(zlibヘッダー、 RFC1950を使用)。
RAW_DEFLATE
生Deflate圧縮ファイル(ヘッダーなし、 RFC1951)。
NONE
ロードするデータファイルは圧縮されていません。
デフォルト:
AUTO_DETECT
注釈
Snowflakeはこのオプションを使用して、データファイルの圧縮方法を検出します。これにより、データファイルを圧縮解除し、ロード用にデータを抽出できます。ファイルの圧縮には、このオプションを使用 しません 。
他のユーティリティ(lzip、lzma、lzop、xzなど)で圧縮されたファイルのアップロードは現在サポートされていません。
OVERWRITE = TRUE | FALSE
アップロード時にSnowflakeが同じ名前の既存ファイルを上書きするかどうかを指定します。
TRUE
:同じ名前の既存のファイルは上書きされます。FALSE
: 同じ名前の既存のファイルは上書きされません。ステージでの LIST 操作はバックグラウンドで実行されるため、PUT 操作のパフォーマンスに影響を与える可能性があることに注意してください。
同じ名前のファイルがターゲットステージに存在するために、ファイルを PUT しようとして失敗した場合は、次のオプションを使用できます。
既存のファイルから1つ以上のテーブルにデータをロードし、ステージからファイルを削除します。次に、新しいデータまたは更新されたデータを含むファイルをステージに PUT します。
ローカルファイルの名前を変更してから、 PUT 操作を再試行します。
PUT ステートメントで
OVERWRITE = TRUE
に設定します。これは、Snowflakeにまだロードされていない可能性のあるデータでファイルを上書きしても安全である場合にのみ行ってください。
SnowflakeアカウントがGoogle Cloud Platformでホストされている場合、 OVERWRITE パラメーターが TRUE に設定されていると、 PUT ステートメントが認識されないことに注意してください。PUT 操作は 常に、アップロードするローカルファイルでターゲットステージの既存のファイルを上書きします。
次のクライアントは、Amazon Web ServicesまたはMicrosoft AzureでホストされているSnowflakeアカウントの OVERWRITE オプションをサポートしています。
SnowSQL
Snowflake ODBC ドライバー
Snowflake JDBC ドライバー
Python用Snowflakeコネクタ
サポートされている値: TRUE、 FALSE
デフォルト:
FALSE
。
使用上の注意¶
コマンドは、いずれのSnowflakeウェブインターフェイスの Worksheets
ページからも実行できません。代わりに、 SnowSQL クライアント または ドライバー を使用してデータファイルをアップロードするか、特定のSnowflakeクライアントのドキュメントを確認して、このコマンドのサポートを検証します。
ファイルグロビングパターン(ワイルドカードなど)がサポートされています。
このコマンドでは、ファイルが 作成されたり、名前が変更されたりしません 。
データのロードおよびアンロード操作のために内部ステージに格納されているすべてのファイルは、サーバー側で AES-256の強力な暗号化を使用して自動的に暗号化されます。デフォルトでは、Snowflakeは128ビットのキー(オプションで256ビットのキーを構成可能)による追加のクライアント側の暗号化を提供します。詳細については、 内部ステージの暗号化タイプ をご参照ください。
このコマンドは、同じステージにアップロードしようとする重複ファイルを無視します。重複ファイルは、既にステージングされたファイルと同じ名前の変更されていないファイルです。
既にステージングされたファイルを上書きするには、アップロードするファイルをステージング済みのファイルとはコンテンツが異なるように変更する必要があります。これにより、新しくステージングされたファイルの新しいチェックサムが生成されます。
ちなみに
セキュリティ上の理由から、コマンドは設定された時間が経過するとタイムアウトします。これは、大きな非圧縮データファイルを読み込むときに発生する可能性があります。タイムアウトの問題を回避するには、ファイルをアップロードする前に、サポートされている圧縮タイプのいずれかを使用して大きなデータファイルを圧縮することをお勧めします。次に、 SOURCE_COMPRESSION
オプションを使用してファイルの圧縮タイプを指定します。
PARALLEL
オプションの値を増やすことも検討できます。これは、大きなデータファイルをアップロードするときのパフォーマンスに役立ちます。
さらに、データをテーブルにロードするときに(COPY INTO <テーブル> コマンドを使用して)並列操作を利用するには、サイズがおよそ100から250 MB に 圧縮 されたデータファイルを使用することをお勧めします。データファイルが大きい場合は、圧縮してアップロードする前に、サードパーティツールを使用してそれらを小さなファイルに分割することを検討してください。
例¶
/tmp/data
ディレクトリ(Linuxまたは macOS 環境)の mydata.csv
という名前のファイルを my_int_stage
という名前の内部ステージにアップロードします。
PUT file:///tmp/data/mydata.csv @my_int_stage;
/tmp/data
ディレクトリ(Linuxまたは macOS 環境)の orders_001.csv
という名前のファイルを、自動データ圧縮を無効にして orderstiny_ext
テーブルのステージにアップロードします。
PUT file:///tmp/data/orders_001.csv @%orderstiny_ext AUTO_COMPRESS=FALSE;
上記と同じ例ですが、ファイル名にワイルドカード文字を使用して複数のファイルをアップロードします。
PUT file:///tmp/data/orders_*01.csv @%orderstiny_ext AUTO_COMPRESS=FALSE;
自動データ圧縮を有効にして、現在のユーザーのために、 C:\temp\data
ディレクトリ(Windows環境下)の mydata.csv
という名前のファイルをステージにアップロードします。
PUT file://C:\temp\data\mydata.csv @~ AUTO_COMPRESS=TRUE;
前の例と同様ですが、ファイルを C:\temp\load data
ディレクトリからアップロードします(Windows環境内)。
PUT 'file://C:\temp\load data\mydata.csv' @~ AUTO_COMPRESS=TRUE;