什么是 Stage？

在 Databend 中，stage 是一个虚拟位置，用于存放数据文件。Stage 中的文件可以直接查询或加载到表中。或者，您可以将表中的数据卸载到 stage 中作为文件。使用 stage 的好处在于，您可以像使用计算机上的文件夹一样方便地访问它，进行数据加载和卸载。就像将文件放入文件夹时，您不一定需要知道它在硬盘上的确切位置一样。当访问 stage 中的文件时，您只需要指定 stage 名称和文件名，例如 @mystage/mydatafile.csv，而不需要指定它在对象存储的 bucket 中的位置。与计算机上的文件夹类似，您可以在 Databend 中根据需要创建任意数量的 stage。但是，需要注意的是，一个 stage 不能包含另一个 stage。每个 stage 都是独立运行的，不包含其他 stage。

使用 stage 加载数据还可以提高上传、管理和过滤数据文件的效率。使用 BendSQL，您可以使用单个命令轻松地将文件上传或下载到 stage。将数据加载到 Databend 时，您可以直接在 COPY INTO 命令中指定一个 stage，允许该命令读取甚至过滤来自该 stage 的数据文件。类似地，当从 Databend 导出数据时，您可以将数据文件转储到 stage 中。

Stage 类型

根据实际存储位置和可访问性，stage 可以分为以下类型：Internal Stage、External Stage 和 User Stage。下表总结了 Databend 中不同 stage 类型的特征，包括它们的存储位置、可访问性和推荐的使用场景：

	User Stage	Internal Stage	External Stage
存储位置	内部对象存储 (Databend)	内部对象存储 (Databend)	外部对象存储 (例如，S3、Azure)
创建方法	自动创建	通过以下方式手动创建：CREATE STAGE stage_name;	通过以下方式手动创建：CREATE STAGE stage_name 's3://bucket/prefix/' CONNECTION=(endpoint_url='x', ...);
访问控制	仅用户可访问	可以与其他用户或角色共享	可以与其他用户或角色共享
删除 Stage	不允许	删除 stage 并清除其中的文件	仅删除 stage；外部位置中的文件将被保留
文件上传	必须将文件上传到 Databend	必须将文件上传到 Databend	无需上传；用于从/向外部存储读取或卸载数据
使用场景	个人/私有数据	团队/共享数据	外部数据集成或卸载
路径格式	@~/	@stage_name/	@stage_name/

Internal Stage

Internal Stage 中的文件实际上存储在 Databend 所在的 对象存储 中。组织内的所有用户都可以访问 Internal Stage，允许每个用户利用该 stage 进行数据加载或导出任务。与创建文件夹类似，创建 stage 时需要指定名称。以下是使用 CREATE STAGE 命令创建 Internal Stage 的示例：

-- 创建一个名为 my_internal_stage 的 internal stage
CREATE STAGE my_internal_stage;

External Stage

通过 External Stage，您可以指定 Databend 所在的 对象存储 之外的对象存储位置。例如，如果您的数据集位于 Google Cloud Storage 容器中，则可以使用该容器创建 External Stage。创建 External Stage 时，您必须提供连接信息，以便 Databend 连接到外部位置。

以下是创建 External Stage 的示例。假设您在名为 databend-doc 的 Amazon S3 bucket 中有数据集：

您可以使用 CREATE STAGE 命令创建一个 External Stage，以将 Databend 连接到该 bucket：

-- 创建一个名为 my_external_stage 的 external stage
CREATE STAGE my_external_stage
    URL = 's3://databend-doc'
    CONNECTION = (
        AWS_KEY_ID = '<YOUR-KEY-ID>',
        AWS_SECRET_KEY = '<YOUR-SECRET-KEY>'
    );

创建 External Stage 后，您可以从 Databend 访问数据集。例如，要列出文件：

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             │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

请注意，外部存储必须是 Databend 支持的对象存储解决方案之一。CREATE STAGE 命令页面提供了有关如何为常用对象存储解决方案指定连接信息的示例。

User Stage

User Stage 可以被认为是一种特殊的 Internal Stage：User Stage 中的文件存储在 Databend 所在的 对象存储 中，但不能被其他用户访问。每个用户都拥有自己的 User Stage，您无需在使用前创建或命名您的 User Stage。此外，您无法删除您的 User Stage。

User Stage 可以作为您的数据文件的便捷存储库，这些数据文件无需与他人共享。要访问您的 User Stage，请使用 @~。例如，要列出您的 stage 中的所有文件：

LIST @~;

管理 Stage

Databend 提供了各种命令来帮助您管理 stage 和其中暂存的文件：

Command	Description	Applies to User Stage	Applies to Internal Stage	Applies to External Stage
CREATE STAGE	创建一个 internal 或 external stage。	No	Yes	Yes
DROP STAGE	移除一个 internal 或 external stage。	No	Yes	Yes
DESC STAGE	显示一个 internal 或 external stage 的属性。	No	Yes	Yes
LIST	返回 stage 中暂存文件的列表。或者，表函数 LIST_STAGE 提供了类似的功能，并增加了获取特定文件信息的灵活性。