Stage 概述
在 TiDB Cloud Lake 中，stage 是一个用于存放数据文件的虚拟位置。stage 中的文件可以直接查询，也可以加载到表中。或者，你也可以将表中的数据以文件形式卸载到 stage 中。使用 stage 的优势在于，你可以像访问计算机上的文件夹一样方便地对其进行数据加载和卸载。就像把文件放进文件夹时，你不一定需要知道它在硬盘上的确切位置一样，访问 stage 中的文件时，你只需要指定 stage 名称和文件名，例如 @mystage/mydatafile.csv，而不需要指定它在对象存储 bucket 中的具体位置。与计算机上的文件夹类似，你可以在 TiDB Cloud Lake 中根据需要创建任意数量的 stage。不过需要注意的是，一个 stage 不能包含另一个 stage。每个 stage 都是独立运行的，不会包含其他 stage。
使用 stage 进行数据加载还可以提升数据文件上传、管理和筛选的效率。借助 LakeSQL，你可以通过一条命令轻松地将文件上传到 stage，或从 stage 下载文件。将数据加载到 TiDB Cloud Lake 时，你可以在 COPY INTO 命令中直接指定 stage，使该命令能够从该 stage 中读取数据文件，甚至对其进行筛选。同样地，从 TiDB Cloud Lake 导出数据时，你也可以将数据文件转储到 stage 中。
stage 类型
根据实际存储位置和可访问性，stage 可分为以下几种类型：Internal Stage、External Stage 和 User Stage。下表总结了 TiDB Cloud Lake 中不同 stage 类型的特征，包括其存储位置、可访问性以及推荐使用场景：
Internal Stage
Internal Stage 中的文件实际上存储在 TiDB Cloud Lake 所在的对象存储中。Internal Stage 可供你所在组织内的所有用户访问，因此每个用户都可以将该 stage 用于数据加载或导出任务。与创建文件夹类似，创建 stage 时需要指定名称。下面是使用 CREATE STAGE 命令创建 Internal Stage 的示例：
-- Create an internal stage named my_internal_stage
CREATE STAGE my_internal_stage;
External Stage
External Stage 允许你指定一个位于 TiDB Cloud Lake 所在位置之外的对象存储位置。例如，如果你的数据集位于 Google Cloud Storage 容器中，你可以基于该容器创建一个 External Stage。创建 External Stage 时，你必须提供连接信息，以便 TiDB Cloud Lake 连接到该外部位置。
下面是创建 External Stage 的示例。假设你的数据集位于名为 lake-doc 的 Amazon S3 bucket 中。
你可以使用 CREATE STAGE 命令创建一个 External Stage，将 TiDB Cloud Lake 连接到该 bucket：
-- 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>'
);
创建 External 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 命令页面提供了如何为常用对象存储解决方案指定连接信息的示例。
User Stage
User Stage 可以视为一种特殊类型的 Internal Stage：User Stage 中的文件存储在 TiDB Cloud Lake 所在的对象存储中，但其他用户无法访问。每个用户开箱即有自己的 User Stage，使用前无需创建或命名。此外，你也不能删除自己的 User Stage。
对于不需要与他人共享的数据文件，User Stage 可以作为一个方便的仓库。要访问你的 User Stage，请使用 @~。例如，列出你的 stage 中的所有文件：
LIST @~;
使用 PATTERN 过滤 stage 中的文件
读取、列出、删除或检查 stage 中文件的命令和函数都可以使用 PATTERN 通过正则表达式筛选文件。对于 stage 位置，PATTERN 匹配的是 @<stage_name>[/<path>] 之后的文件路径部分，而不是完整的 stage URI。
例如，对于 @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 及其中暂存的文件：