stage の概要
TiDB Cloud Lake では、stage はデータファイルが存在する仮想的な場所です。stage 内のファイルは直接クエリすることも、テーブルにロード (load) することもできます。あるいは、テーブルからデータをファイルとして stage にアンロード (unload) することもできます。stage を使用する利点は、コンピュータ上のフォルダと同じような手軽さで、データのロードやアンロードのためにアクセスできることです。フォルダにファイルを置くときと同様に、ハードディスク上の正確な保存場所を必ずしも知っている必要はありません。stage 内のファイルにアクセスする際は、オブジェクトストレージのバケット内での場所を指定する代わりに、@mystage/mydatafile.csv のように、stage 名とファイル名だけを指定すれば十分です。コンピュータ上のフォルダと同様に、TiDB Cloud Lake では必要な数だけ stage を作成できます。ただし、stage の中に別の stage を含めることはできない点に注意してください。各 stage は独立して動作し、他の stage を内包しません。
データのロードに stage を利用すると、データファイルのアップロード、管理、フィルタリングの効率も向上します。LakeSQL を使用すると、1 つのコマンドで stage へのファイルのアップロードや、stage からのファイルのダウンロードを簡単に行えます。TiDB Cloud Lake にデータをロードする際は、COPY INTO コマンドで stage を直接指定でき、その stage からデータファイルを読み取り、さらにフィルタリングすることも可能です。同様に、TiDB Cloud Lake からデータをエクスポートする際は、データファイルを stage にダンプできます。
stage の種類
実際の保存場所とアクセス性に基づいて、stage は内部 stage、外部 stage、ユーザー stage の 3 種類に分類できます。次の表は、TiDB Cloud Lake における各種類の stage の特徴を、保存場所、アクセス性、推奨される利用シナリオの観点からまとめたものです。
内部 stage
内部 stage 内のファイルは、実際には TiDB Cloud Lake が存在するオブジェクトストレージに保存されます。内部 stage は組織内のすべてのユーザーが利用でき、各ユーザーは自分のデータロードやエクスポート作業にその stage を使用できます。フォルダを作成するのと同様に、stage を作成する際には名前の指定が必要です。以下は、CREATE STAGE コマンドを使用して内部 stage を作成する例です。
-- Create an internal stage named my_internal_stage
CREATE STAGE my_internal_stage;
外部 stage
外部 stage を使用すると、TiDB Cloud Lake が存在する場所の外部にあるオブジェクトストレージの場所を指定できます。たとえば、Google Cloud Storage コンテナにデータセットがある場合、そのコンテナを使って外部 stage を作成できます。外部 stage を作成する際には、TiDB Cloud Lake がその外部ロケーションに接続するための接続情報を指定する必要があります。
以下は外部 stage を作成する例です。ここでは、lake-doc という名前の Amazon S3 バケットにデータセットがあるとします。
CREATE STAGE コマンドを使用して、TiDB Cloud Lake をそのバケットに接続する外部 stage を作成できます。
-- Create an external stage named my_external_stage
CREATE STAGE my_external_stage
URL = 's3://lake-doc'
CONNECTION = (
ACCESS_KEY_ID = '<YOUR-KEY-ID>',
SECRET_ACCESS_KEY = '<YOUR-SECRET-KEY>'
);
外部 stage を作成すると、TiDB Cloud Lake からそのデータセットにアクセスできます。たとえば、ファイルを一覧表示するには次のようにします。
LIST @my_external_stage;
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ name │ size │ md5 │ last_modified │ creator │
├───────────────┼────────┼────────────────────────────────────┼───────────────────────────────┼──────────────────┤
│ Inventory.csv │ 57585 │ "0cd02fb636a22ba9f4ae4d24555a7d68" │ 2024-03-17 21:22:38.000 +0000 │ NULL │
│ Products.csv │ 42987 │ "570e5cbf6a4b6e7e9a258094192f4784" │ 2024-03-17 21:22:38.000 +0000 │ NULL │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
外部ストレージは、TiDB Cloud Lake がサポートするオブジェクトストレージソリューションのいずれかである必要がある点に注意してください。CREATE STAGE コマンドのページには、一般的によく使われるオブジェクトストレージソリューション向けの接続情報の指定例が記載されています。
ユーザー stage
ユーザー stage は、特殊な種類の内部 stage と考えることができます。ユーザー stage 内のファイルは TiDB Cloud Lake が存在するオブジェクトストレージに保存されますが、他のユーザーからアクセスできません。各ユーザーには最初から専用のユーザー stage が用意されており、使用前に作成したり名前を付けたりする必要はありません。また、ユーザー stage を削除することもできません。
ユーザー stage は、他のユーザーと共有する必要のないデータファイルを保存するための便利な保管場所として利用できます。ユーザー stage にアクセスするには、@~ を使用します。たとえば、自分の stage 内のすべてのファイルを一覧表示するには次のようにします。
LIST @~;
PATTERN を使用した stage ファイルのフィルタリング
stage 内のファイルを読み取り、一覧表示し、削除し、または調査するコマンドや関数では、PATTERN を使用して正規表現でファイルをフィルタリングできます。stage のロケーションに対しては、PATTERN は完全な stage URI ではなく、@<stage_name>[/<path>] の後ろに続くファイルパス部分に対してマッチします。
たとえば、@sales_stage/raw/ に対して、stage ファイル @sales_stage/raw/year=2025/month=01/sales_20250101.parquet は year=2025/month=01/sales_20250101.parquet としてマッチされます。
LIST @sales_stage/raw/ PATTERN = 'year=2025/month=01/.*[.]parquet';
stage パス配下のすべての .log ファイルにマッチさせるには、次のような正規表現を使用します。
LIST @my_stage PATTERN = '.*[.]log';
stage の管理
TiDB Cloud Lake には、stage およびその中に stage されたファイルを管理するためのさまざまなコマンドが用意されています。