カテゴリ:

DML コマンド - データのロード

PUT

クライアントマシン上のローカルディレクトリ/フォルダーから次のSnowflakeステージのいずれかにデータファイルをアップロード(ステージング)します。

  • 内部ステージという名前。

  • 指定されたテーブルの内部ステージ。

  • 現在のユーザーの内部ステージ。

ファイルがステージングされると、ファイル内のデータは COPY INTO <テーブル> コマンドを使用してテーブルにロードできます。

注釈

  • PUT は、外部ステージへのファイルのアップロードをサポートして いません。ファイルを外部ステージにアップロードするには、クラウドサービスが提供するユーティリティを使用します。

  • 次のSnowflakeクライアントは PUT をサポートしていません。

    • Go Snowflakeドライバー

    • .NET ドライバー

    • Node.jsドライバー

  • 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以降を使用)。

こちらもご参照ください。

GETLISTREMOVE

構文

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://ファイルへのパス/ファイル名

クライアントマシン上のデータファイルの URI を指定します。ここで、

  • ファイルへのパス は、アップロードするファイルへのローカルディレクトリパスです。ファイルがクライアントマシンのルートディレクトリ(またはサブディレクトリ)にある場合:

    Linux/Mac

    パスに最初のスラッシュを含める必要があります(例: file:///tmp/load)。

    Windows

    パスにドライブとバックスラッシュを含める必要があります(例: file://C:\temp\load)。

  • ファイル名 は、アップロードするファイルの名前です。ディレクトリ内の複数のファイルをアップロードできるように、ワイルドカード文字(*?)がサポートされています。

URI は単一引用符で囲むことができます。これにより、ディレクトリ名やファイル名にスペースを含む特殊文字を使用できます。ただし、ドライブとパスの区切り文字は、サポートされているすべてのオペレーティングシステムのスラッシュ(/)です(例: load data という名前のディレクトリを含むWindowsのパスの場合は 'file://C:/temp/load data')。

internalStage

ファイルをアップロードするSnowflakeの場所を指定します。

@[名前空間.]内部ステージ名[/パス]

指定された名前の内部ステージにファイルがアップロードされます。

@[名前空間.]%テーブル名[/パス]

指定したテーブルのステージにファイルがアップロードされます。

@~[/パス]

ファイルは現在のユーザーのステージにアップロードされます。

条件:

  • 名前空間 は、指定された内部ステージまたはテーブルが存在するデータベースまたはスキーマ、あるいはその両方です。セッション内でデータベースとスキーマが現在使用されている場合、 オプション です。それ以外の場合は必須です。

  • パス は、一連のファイルへのアクセスを制限するクラウドストレージの場所にある、ファイルの大文字と小文字を区別するオプションのパスです(つまり、ファイルの名前は一般的な文字列で開始)。パスは、別のクラウドストレージサービスによって プレフィックス または フォルダー と呼ばれることもあります。

文字列は一重引用符で囲むことができます。これにより、場所名にスペースを含む特殊文字を使用できます(例: "my stage" という名前のステージに '@"my stage"')。

オプションのパラメーター

PARALLEL = 整数

ファイルのアップロードに使用するスレッドの数を指定します。アップロードプロセスでは、サイズごとにデータファイルのバッチを分割します。

  • 小さなファイル(圧縮または非圧縮で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がデータファイルをステージングする前に、圧縮するための十分なスペースがあることを確認します。必要に応じて、オペレーティングシステムで TEMPTMPDIR または 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 :同じ名前の既存のファイルは上書きされません。

ファイルを PUT しようとしても、同じ名前のファイルが既にステージに存在するためできない場合、次のいずれかを実行できます。

  • 既存のファイルのデータがロードされるまで待ってから、 PUTを再試行してください。

  • PUT するファイルの名前を変更します。

  • OVERWRITE = TRUE を設定します。これは、Snowflakeにまだロードされていない可能性のあるデータでファイルを上書きしても安全である場合にのみ行ってください。

次のプラットフォームは、 OVERWRITE オプションをサポートしています。

  • Amazon AWS

  • Microsoft Azure

GCP 、Google Cloud Platformは、 OVERWRITE=FALSE をサポートしていません。 GCP では、同じ名前のファイルが存在し、 OVERWRITE がfalseに設定されている場合でも、 PUT コマンドは常にファイルをアップロードします。

次のドライバーとコネクタは OVERWRITE オプションをサポートしています。

  • Snowflake ODBC ドライバー。

  • Snowflake JDBC ドライバー。

  • Snowflake Pythonコネクタ。

OVERWRITE オプションは、 SnowSQLでもサポートされています。

サポートされている値: TRUE、 FALSE

デフォルト: FALSE

使用上の注意

  • コマンドは、Snowflake ウェブインターフェイスの Worksheets Worksheet tab ページから実行できません。代わりに、 SnowSQL クライアントを使用してデータファイルをアップロードするか、特定のSnowflakeクライアントのドキュメントを確認して、このコマンドのサポートを検証してください。

  • ファイルグロビングパターン(ワイルドカードなど)がサポートされています。

  • このコマンドは、ファイルを作成または名前変更 しません 。指定された内部ステージのプレフィックス(ある場合)は、新しいファイルではなく、既存のファイル用です。

  • アップロードされたファイルは、128ビットまたは256ビットキーで自動的に暗号化されます。 CLIENT_ENCRYPTION_KEY_SIZE アカウントパラメーターは、ファイルの暗号化に使用されるサイズキーを指定します。

  • このコマンドは、同じステージにアップロードしようとする重複ファイルを無視します。このコンテキストでは、重複ファイルは、既にステージングされたファイルと同じ名前の変更されていないファイルです。

    既にステージングされたファイルを上書きするには、アップロードするファイルをステージング済みのファイルとは異なるように変更する必要があります。これにより、新しくステージングされたファイルの新しいチェックサムが生成されます。

ちなみに

セキュリティ上の理由から、コマンドは設定された時間が経過するとタイムアウトします。これは、大きな非圧縮データファイルを読み込むときに発生する可能性があります。タイムアウトの問題を回避するには、ファイルをアップロードする前に、サポートされている圧縮タイプのいずれかを使用して大きなデータファイルを圧縮することをお勧めします。次に、 SOURCE_COMPRESSION オプションを使用してファイルの圧縮タイプを指定します。

PARALLEL オプションの値を増やすことも検討できます。これは、大きなデータファイルをアップロードするときのパフォーマンスに役立ちます。

さらに、データをテーブルにロードするときに( COPY INTO <テーブル> コマンドを使用して)並列操作を利用するには、サイズがおよそ10から100 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;