diff --git a/docs/cn/guides/20-cloud/10-using-databend-cloud/01-warehouses.md b/docs/cn/guides/20-cloud/10-using-databend-cloud/01-warehouses.md index b3975eb5fe..c0f9f91ce3 100644 --- a/docs/cn/guides/20-cloud/10-using-databend-cloud/01-warehouses.md +++ b/docs/cn/guides/20-cloud/10-using-databend-cloud/01-warehouses.md @@ -8,173 +8,166 @@ import CheckboxSVG from '@site/static/img/icon/checkbox.svg' import EllipsisSVG from '@site/static/img/icon/ellipsis.svg' import { Button } from 'antd' -计算集群是 Databend Cloud 的重要组成部分。计算集群代表一组计算资源，包括 CPU、内存和本地缓存。您必须运行计算集群来执行 SQL 任务，例如： +计算集群（Warehouse）是 Databend Cloud 的核心组件。它代表了一组计算资源，包含 CPU、内存以及本地缓存。您需要启动计算集群来执行各类 SQL 任务，例如： - 使用 SELECT 语句查询数据 -- 使用 INSERT、UPDATE 或 DELETE 语句修改数据 -- 使用 COPY INTO 命令将数据加载到表中 +- 使用 INSERT、UPDATE 或 DELETE 修改数据 +- 使用 COPY INTO 将数据加载到表中 -运行计算集群会产生费用。更多信息请参见 [计算集群定价](/guides/products/dc/pricing#warehouse-pricing)。 +使用计算集群会产生费用。更多详情请参阅 [计算集群定价](/guides/products/dc/pricing#warehouse-pricing)。 ## 计算集群规格 -在 Databend Cloud 中，计算集群有多种规格可供选择，每种规格都由其能处理的最大并发查询数量定义。创建计算集群时，您可以从以下规格中选择： +Databend Cloud 提供多种规格的计算集群，不同规格决定了其能够处理的最大并发查询数。在创建计算集群时，您可以选择以下规格： -| 规格 | 推荐使用场景 | -| --------------------- | ---------------------------------------------------------------------------------- | -| XSmall | 最适合简单任务，如测试或运行轻量级查询。适用于小型数据集 (约 50GB)。 | -| Small | 非常适合运行常规报告和中等工作负载。适用于中等规模数据集 (约 200GB)。 | -| Medium | 非常适合处理更复杂查询和更高并发的团队。适用于较大数据集 (约 1TB)。 | -| Large | 非常适合运行大量并发查询的组织。适用于大型数据集 (约 5TB)。 | -| XLarge | 专为具有高并发的企业级工作负载而构建。适用于超大型数据集 (超过 10TB)。 | -| nXLarge | n=2,3,4,5,6 [联系我们](https://www.databend.cn/contact-us/) | -| Multi-Cluster Scaling | 自动扩展和收缩以匹配您的工作负载，提供最具成本效益的方式来根据您的需求提高并发性。 | +| 规格 | 推荐使用场景 | +| :--- | :--- | +| XSmall | 适用于简单的测试任务或轻量级查询。适合小型数据集（约 50GB）。 | +| Small | 适合运行常规报表和中等负载的任务。适合中型数据集（约 200GB）。 | +| Medium | 适合团队进行复杂查询和较高并发的操作。适合较大数据集（约 1TB）。 | +| Large | 适合需要处理大量并发查询的组织。适合大型数据集（约 5TB）。 | +| XLarge | 专为具有超高并发的企业级工作负载设计。适合超大型数据集（超过 10TB）。 | +| nXLarge | n=2,3,4,5,6 [联系我们](https://www.databend.cn/contact-us/) | +| Multi-Cluster Scaling | 根据工作负载自动进行扩缩容（Scale Out/In），提供最具成本效益的高并发支持。 | -为了选择合适的计算集群规格，Databend 建议从较小的规格开始。较小的计算集群执行 SQL 任务可能比中型或大型计算集群需要更长时间。如果您发现查询执行时间过长 (例如几分钟)，请考虑扩展到中型或大型计算集群以获得更快的结果。 +建议从较小的规格开始尝试。较小的计算集群执行 SQL 任务的时间可能会比中型或大型集群稍长。如果发现查询耗时过长（例如数分钟），可以考虑升级到 Medium 或 Large 规格以获得更快的结果。 ## 管理计算集群 {#managing} -一个组织可以拥有任意数量的计算集群。**计算集群** 页面显示您组织中的所有计算集群，并允许您管理它们。请注意，只有 `account_admin` 可以创建或删除计算集群。 +一个组织可以按需创建多个计算集群。**计算集群** 页面展示了您组织下的所有计算集群，并提供管理功能。请注意，只有 `account_admin` 权限的用户才能创建或删除计算集群。 ### 暂停 / 恢复计算集群 -暂停的计算集群不会消耗任何积分。您可以通过点击计算集群上的 或 按钮手动暂停或恢复计算集群。但是，计算集群可以在以下场景中自动暂停或恢复： +处于暂停状态的计算集群不会消耗积分（Credits）。您可以通过点击计算集群上的 或 按钮来手动暂停或恢复。此外，计算集群在以下情况会自动变更状态： -- 如果没有活动，计算集群可以根据其自动暂停设置自动暂停。 -- 当您选择暂停的计算集群来执行 SQL 任务时，计算集群将自动恢复。 +- **自动暂停**：如果在设定时间内没有活动，计算集群将根据自动暂停设置自动停止。 +- **自动恢复**：当您选择一个已暂停的计算集群执行 SQL 任务时，它会自动启动。 -### 执行批量操作 +### 批量操作 -您可以对计算集群执行批量操作，包括批量重启、批量暂停、批量恢复和批量删除。为此，请通过勾选计算集群列表中的复选框 来选择要进行批量操作的计算集群，然后点击省略号按钮 进行所需的操作。 +您可以对计算集群执行批量操作，包括批量启动、暂停、恢复和删除。在计算集群列表中勾选复选框 选中目标集群，然后点击省略号按钮 选择相应的操作即可。 ![alt text](@site/static/img/cloud/bulk.gif) ### 最佳实践 -为了有效管理您的计算集群并确保最佳性能和成本效益，请考虑以下最佳实践。这些指导原则将帮助您为各种工作负载和环境调整、组织和优化您的计算集群： +为了高效管理计算集群并确保最佳的性能与成本效益，请参考以下建议。这些原则将帮助您针对不同的工作负载和环境调整、组织和优化计算集群： - **选择合适的规格** + - **开发与测试**：使用较小的规格（XSmall, Small）。 + - **生产环境**：选择较大的规格（Medium, Large, XLarge）。 - - 对于 **开发和测试**，使用较小的计算集群 (XSmall、Small)。 - - 对于 **生产环境**，选择较大的计算集群 (Medium、Large、XLarge)。 +- **资源隔离** + - **读写分离**：为 **数据加载** 和 **查询执行** 使用独立的计算集群。 + - **环境隔离**：为 **开发**、**测试** 和 **生产** 环境创建不同的计算集群。 -- **分离计算集群** +- **数据加载建议** + - 较小的计算集群（Small, Medium）通常足以处理数据加载任务。 + - 通过优化文件大小和文件数量来提升性能。 - - 为 **数据加载** 和 **查询执行** 使用单独的计算集群。 - - 为 **开发**、**测试** 和 **生产** 环境创建不同的计算集群。 - -- **数据加载提示** - - - 较小的计算集群 (Small、Medium) 适用于数据加载。 - - 优化文件大小和文件数量以提高性能。 - -- **优化成本和性能** - - - 避免运行简单查询如 `SELECT 1` 以最小化积分使用。 - - 使用批量加载 (`COPY`) 而不是单独的 `INSERT` 语句。 - - 监控长时间运行的查询并优化它们以提高性能。 +- **优化成本与性能** + - 避免运行如 `SELECT 1` 这样简单的查询，以减少不必要的积分消耗。 + - 使用批量加载 (`COPY`) 而非单条 `INSERT` 语句。 + - 监控长耗时查询并进行优化。 - **自动暂停** + - 启用自动暂停功能，在计算集群空闲时节省成本。 - - 启用自动暂停以在计算集群空闲时节省积分。 - -- **对频繁查询禁用自动暂停** - - - 对于频繁或重复查询，保持计算集群活跃以维护缓存并避免延迟。 - -- **使用自动扩展 (仅限商业版和专用版计划)** +- **高频查询禁用自动暂停** + - 对于频繁或重复执行的查询，保持计算集群处于活跃状态，以利用缓存并避免启动延迟。 - - Multi-cluster scaling 根据工作负载需求自动调整资源。 +- **使用自动扩展（仅限商业版和专用版）** + - 利用 Multi-Cluster Scaling 根据工作负载需求自动调整资源。 -- **监控和调整使用情况** - - 定期检查计算集群使用情况，并根据需要调整规格以平衡成本和性能。 +- **监控与调整** + - 定期审查计算集群的使用情况，并根据需要调整规格，以在成本和性能之间找到平衡。 ## 计算集群访问控制 -Databend Cloud 允许您通过为计算集群分配特定角色来使用基于角色的控制管理计算集群访问，这样只有具有该角色的用户才能访问计算集群。 +Databend Cloud 支持基于角色的访问控制（RBAC）。您可以为计算集群分配特定角色，只有拥有该角色的用户才能访问。 :::note -计算集群访问控制默认 _未_ 启用。要启用它，请转到 **Support** > **Create New Ticket** 并提交请求。 +计算集群访问控制默认**未启用**。如需开启，请前往 **Support** > **Create New Ticket** 提交申请。 ::: -要为计算集群分配角色，请在计算集群创建或修改过程中的 **Advanced Options** 中选择所需的角色： +在创建或修改计算集群时，您可以在 **Advanced Options** 中选择需要分配的角色： ![alt text](@site/static/img/documents/warehouses/warehouse-role.png) -- 两个 [内置角色](../../56-security/access-control/02-roles.md#built-in-roles) 可供选择，您也可以使用 [CREATE ROLE](/sql/sql-commands/ddl/user/user-create-role) 命令创建其他角色。有关 Databend 角色的更多信息，请参见 [角色](../../56-security/access-control/02-roles.md)。 -- 没有分配角色的计算集群默认为 `public` 角色，允许所有用户访问。 -- 您可以使用 [GRANT](/sql/sql-commands/ddl/user/grant) 命令将角色授予用户 (Databend Cloud 登录邮箱或 SQL 用户)，或者在邀请用户加入您的组织时分配角色。更多信息请参见 [邀请新成员](00-organization.md#inviting-new-members)。此示例将角色 `manager` 授予邮箱为 `name@example.com` 的用户，允许访问分配给 `manager` 角色的任何计算集群： +- 您可以选择两个 [内置角色](../../56-security/access-control/02-roles.md#built-in-roles)，也可以使用 [CREATE ROLE](/sql/sql-commands/ddl/user/user-create-role) 命令创建自定义角色。更多信息请参阅 [角色](../../56-security/access-control/02-roles.md)。 +- 未分配角色的计算集群默认为 `public` 角色，允许所有用户访问。 +- 您可以使用 [GRANT](/sql/sql-commands/ddl/user/grant) 命令将角色授予用户（Databend Cloud 登录邮箱或 SQL 用户），或者在邀请用户加入组织时直接分配角色。详情请参阅 [邀请新成员](00-organization.md#inviting-new-members)。以下示例将 `manager` 角色授予邮箱 `name@example.com`，使其能够访问所有分配给 `manager` 角色的计算集群： ```sql title='示例：' GRANT ROLE manager to 'name@example.com'; ``` -## Multi-Cluster 计算集群 +## 多集群计算集群 (Multi-Cluster Warehouses) -Multi-cluster 计算集群根据工作负载需求通过添加或删除集群来自动调整计算资源。它确保高并发和性能，同时通过根据需要扩展或收缩来优化成本。 +多集群计算集群能够根据工作负载需求，通过增加或减少集群数量来自动调整计算资源。它在确保高并发和高性能的同时，通过按需扩缩容来优化成本。 :::note -多集群功能仅适用于 Databend Cloud 商业版和专用版用户。 +多集群功能仅对 Databend Cloud **商业版 (Business)** 和 **专用版 (Dedicated)** 用户开放。 ::: ### 工作原理 -默认情况下，计算集群由单个计算资源集群组成，根据其大小可以处理最大数量的并发查询。当为计算集群启用多集群功能时，它允许动态添加多个集群 (由 **最大集群数** 设置定义) 来处理超出单个集群容量的工作负载。 +默认情况下，一个计算集群由单个计算资源集群组成，其处理并发查询的能力受限于其规格大小。当启用多集群功能后，系统可以动态添加多个集群（数量上限由 **Max Clusters** 设置），以应对超出单个集群处理能力的工作负载。 -当并发查询数量超过计算集群的容量时，会添加额外的集群来处理额外的负载。如果需求持续增长，会逐个添加更多集群。随着查询需求的减少，超过 **自动暂停** 持续时间且无活动的集群会自动关闭。 +当并发查询数超过当前容量时，系统会自动增加一个集群来分担负载。如果需求持续增长，集群将逐个增加。随着查询需求减少，闲置时间超过 **Auto Suspend** 设定时长的集群将自动关闭。 ![alt text](@site/static/img/cloud/multi-cluster-how-it-works.png) ### 启用多集群 -您可以在创建计算集群时启用多集群功能，并设置计算集群可以扩展到的最大集群数量。请注意，如果为计算集群启用了多集群功能，**自动暂停** 持续时间必须设置为至少 15 分钟。 +您可以在创建计算集群时启用多集群功能，并设置最大集群数（Max Clusters）。请注意，如果启用了多集群功能，**自动暂停（Auto Suspend）** 时间必须至少设置为 15 分钟。 ![alt text](@site/static/img/cloud/multi-cluster.png) ### 费用计算 -多集群计算集群根据特定时间间隔内使用的活跃集群数量进行计费。 +多集群计算集群的计费基于特定时间段内实际使用的活跃集群数量。 -例如，对于价格为每小时 $1 的 XSmall 计算集群，如果从 13:00 到 14:00 活跃使用一个集群，从 14:00 到 15:00 活跃使用两个集群，那么从 13:00 到 15:00 产生的总费用为 $3 ((1 个集群 × 1 小时 × $1) + (2 个集群 × 1 小时 × $1))。 +例如，对于一个价格为每小时 $1 的 XSmall 计算集群：如果 13:00 到 14:00 期间有一个集群活跃，而 14:00 到 15:00 期间有两个集群活跃，则 13:00 到 15:00 的总费用为 $3（(1 集群 × 1 小时 × $1) + (2 集群 × 1 小时 × $1)）。 -## 连接到计算集群 {#connecting} +## 连接计算集群 {#connecting} -连接到计算集群提供了在 Databend Cloud 中运行查询和分析数据所需的计算资源。当从应用程序或 SQL 客户端访问 Databend Cloud 时，此连接是必需的。 +连接到计算集群是运行查询和分析数据的前提。当您通过应用程序或 SQL 客户端访问 Databend Cloud 时，需要建立此连接。 -### 连接方法 +### 连接方式 -Databend Cloud 支持多种连接方法以满足您的特定需求。有关详细的连接说明，请参阅 [SQL 客户端文档](/guides/sql-clients/)。 +Databend Cloud 支持多种连接方式以满足不同需求。详细说明请参阅 [SQL 客户端文档](/guides/sql-clients/)。 -#### SQL 客户端和工具 +#### SQL 客户端与工具 -| 客户端 | 类型 | 最适用于 | 主要功能 | -| ------------------------------------------ | ------------ | -------------------- | ---------------------------------- | -| **[BendSQL](/guides/sql-clients/bendsql)** | 命令行 | 开发者、脚本 | 原生 CLI、丰富格式化、多种安装选项 | -| **[DBeaver](/guides/sql-clients/jdbc)** | GUI 应用程序 | 数据分析、可视化查询 | 内置驱动程序、跨平台、查询构建器 | +| 客户端 | 类型 | 适用场景 | 主要特点 | +| :--- | :--- | :--- | :--- | +| **[BendSQL](/guides/sql-clients/bendsql)** | 命令行 | 开发人员、脚本自动化 | 原生 CLI，丰富的格式化支持，多种安装选项 | +| **[DBeaver](/guides/sql-clients/jdbc)** | GUI 应用 | 数据分析、可视化查询 | 内置驱动，跨平台，图形化查询构建器 | -#### 开发者驱动程序 +#### 开发者驱动 (Drivers) -| 语言 | 驱动程序 | 使用场景 | 文档 | -| ----------- | ----------------- | -------------- | ----------------------------------------------------- | -| **Go** | Golang Driver | 后端应用程序 | [Golang 指南](/guides/sql-clients/developers/golang) | -| **Python** | Python Connector | 数据科学、分析 | [Python 指南](/guides/sql-clients/developers/python) | -| **Node.js** | JavaScript Driver | Web 应用程序 | [Node.js 指南](/guides/sql-clients/developers/nodejs) | -| **Java** | JDBC Driver | 企业应用程序 | [JDBC 指南](/guides/sql-clients/developers/jdbc) | -| **Rust** | Rust Driver | 系统编程 | [Rust 指南](/guides/sql-clients/developers/rust) | +| 语言 | 驱动程序 | 用例 | 文档 | +| :--- | :--- | :--- | :--- | +| **Go** | Golang Driver | 后端应用 | [Golang 开发指南](/guides/sql-clients/developers/golang) | +| **Python** | Python Connector | 数据科学、分析 | [Python 开发指南](/guides/sql-clients/developers/python) | +| **Node.js** | JavaScript Driver | Web 应用 | [Node.js 开发指南](/guides/sql-clients/developers/nodejs) | +| **Java** | JDBC Driver | 企业级应用 | [JDBC 开发指南](/guides/sql-clients/developers/jdbc) | +| **Rust** | Rust Driver | 系统编程 | [Rust 开发指南](/guides/sql-clients/developers/rust) | ### 获取连接信息 -要获取计算集群的连接信息： +获取计算集群连接信息的步骤如下： -1. 在 **概览** 页面上点击 **连接**。 -2. 选择您希望连接的数据库和计算集群。连接信息将根据您的选择进行更新。 -3. 连接详细信息包括一个名为 `cloudapp` 的 SQL 用户和一个随机生成的密码。Databend Cloud 不存储此密码。请务必复制并安全保存。如果您忘记了密码，请点击 **重置** 生成新密码。 +1. 在 **Overview**（概览）页面点击 **Connect**（连接）。 +2. 选择您要连接的 Database（数据库）和 Warehouse（计算集群）。连接信息将根据您的选择自动更新。 +3. 连接详情包含一个名为 `cloudapp` 的系统生成 SQL 用户及其随机密码。Databend Cloud 不会存储此密码，请务必复制并妥善保存。如遗忘，可点击 **Reset** 生成新密码。 ![alt text](@site/static/img/documents_cn/warehouses/databend_cloud_dsn.gif) ### 连接字符串格式 -当您点击 **连接** 时，Databend Cloud 会自动生成您的连接字符串： +点击 **Connect** 时，Databend Cloud 会自动生成连接字符串： ``` databend://:@.gw..default.databend.com:443/?warehouse= @@ -182,27 +175,27 @@ databend://:@.gw..default.databend.com:443/< 其中： -- ``：默认为 `cloudapp` -- ``：点击 **重置** 查看或更改 -- ``、``：您的账户信息 (显示在连接详细信息中) -- ``：选定的数据库 (显示在连接详细信息中) -- ``：选定的计算集群 (显示在连接详细信息中) +- ``：默认为 `cloudapp`。 +- ``：点击 **重置** 查看或更改。 +- ``、``：您的账户信息（显示在连接详情中）。 +- ``：已选的数据库。 +- ``：已选的计算集群。 -### 为计算集群访问创建 SQL 用户 +### 创建 SQL 用户 -除了默认的 `cloudapp` 用户外，您还可以创建额外的 SQL 用户以获得更好的安全性和访问控制： +除默认的 `cloudapp` 用户外，您可以创建额外的 SQL 用户以实现更细粒度的安全管控： ```sql -- 创建新的 SQL 用户 CREATE USER warehouse_user1 IDENTIFIED BY 'StrongPassword123'; --- 授予数据库的所有权限 --- 此用户可以访问数据库中的所有表 +-- 授予数据库所有权限 +-- 该用户将可以访问 my_database 中的所有表 GRANT ALL ON my_database.* TO warehouse_user1; ``` -有关更多详细信息，请参阅 [CREATE USER](/sql/sql-commands/ddl/user/user-create-user) 和 [GRANT](/sql/sql-commands/ddl/user/grant) 文档。 +更多详情请参阅 [CREATE USER](/sql/sql-commands/ddl/user/user-create-user) 和 [GRANT](/sql/sql-commands/ddl/user/grant) 文档。 ### 连接安全性 -默认情况下，所有到 Databend Cloud 计算集群的连接都使用 TLS 加密。对于需要额外安全性的企业用户，可以使用 [AWS PrivateLink](/guides/cloud/advanced/private-link) 在您的 VPC 和 Databend Cloud 之间建立私有连接。 +默认情况下，所有连接到 Databend Cloud 计算集群的流量均使用 TLS 加密。对于安全性要求更高的企业用户，可以使用 [AWS PrivateLink](/guides/cloud/advanced/private-link) 在您的 VPC 和 Databend Cloud 之间建立私有连接。 diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/index.md index b5717ea875..c4cef225a7 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/index.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/index.md @@ -31,7 +31,8 @@ title: 存储阶段（Stage） - [使用 Stage](/guides/load-data/stage/) - [从 Stage 加载数据](/guides/load-data/load/stage) - [查询和转换](/guides/load-data/transform/querying-stage) +- [文件格式 (DDL)](/sql/sql-commands/ddl/file-format/) :::note Databend 中的 Stage 用作临时存储位置，用于存放需加载到表或从表卸载的数据文件。 -::: \ No newline at end of file +::: diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/13-file-format/01-ddl-create-file-format.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/13-file-format/01-ddl-create-file-format.md index cf09ab6e02..4739e5c1ce 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/13-file-format/01-ddl-create-file-format.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/13-file-format/01-ddl-create-file-format.md @@ -17,8 +17,36 @@ CREATE [ OR REPLACE ] FILE FORMAT [ IF NOT EXISTS ] FileFormatOpti 关于 `FileFormatOptions` 的详细信息，请参考 [输入 & 输出文件格式](../../../00-sql-reference/50-file-format-options.md)。 -## 示例 +## 使用文件格式 + +创建一次，即可在查询和加载数据时重复使用该格式： ```sql -CREATE FILE FORMAT my_custom_csv TYPE=CSV FIELD_DELIMITER='\t' -``` \ No newline at end of file +-- 1) 创建可复用的格式 +CREATE OR REPLACE FILE FORMAT my_custom_csv TYPE = CSV FIELD_DELIMITER = '\t'; + +-- 2) 查询 Stage 中的文件（stage 表函数参数使用 =>） +SELECT * FROM @mystage/data.csv (FILE_FORMAT => 'my_custom_csv') LIMIT 10; + +-- 3) 用 COPY INTO 导入文件（copy 选项使用 =） +COPY INTO my_table +FROM @mystage/data.csv +FILE_FORMAT = (FORMAT_NAME = 'my_custom_csv'); +``` + +为什么有 `=>` 与 `=` 的区别？Stage 表函数的参数使用键值写法 `=>`，而 `COPY INTO` 的选项采用常规的 `=` 赋值语法。 + +**快速流程：使用同一格式进行创建、查询和加载** + +```sql +-- 创建可复用的格式 +CREATE FILE FORMAT my_parquet TYPE = PARQUET; + +-- 使用该格式查询 Stage 中的文件（Stage 表函数语法使用 =>） +SELECT * FROM @sales_stage/2024/order.parquet (FILE_FORMAT => 'my_parquet') LIMIT 10; + +-- 使用 COPY INTO 加载 Stage 文件（LOAD 选项使用 =） +COPY INTO analytics.orders +FROM @sales_stage/2024/order.parquet +FILE_FORMAT = (FORMAT_NAME = 'my_parquet'); +``` diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/index.md index 5beb38cd6f..3166bc31a1 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/index.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/index.md @@ -31,7 +31,8 @@ This page provides a comprehensive overview of stage operations in Databend, org - [Working with Stages](/guides/load-data/stage/) - [Loading from Stage](/guides/load-data/load/stage) - [Querying & Transforming](/guides/load-data/transform/querying-stage) +- [File Format (DDL)](/sql/sql-commands/ddl/file-format/) :::note Stages in Databend are used as temporary storage locations for data files that you want to load into tables or unload from tables. -::: \ No newline at end of file +::: diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/13-file-format/01-ddl-create-file-format.md b/docs/en/sql-reference/10-sql-commands/00-ddl/13-file-format/01-ddl-create-file-format.md index 5f532103f8..7c13e0ac1d 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/13-file-format/01-ddl-create-file-format.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/13-file-format/01-ddl-create-file-format.md @@ -17,8 +17,36 @@ CREATE [ OR REPLACE ] FILE FORMAT [ IF NOT EXISTS ] FileFormatOpti For details about `FileFormatOptions`, see [Input & Output File Formats](../../../00-sql-reference/50-file-format-options.md). -## Examples +## Use the file format + +Create once, then reuse the format for both querying and loading: ```sql -CREATE FILE FORMAT my_custom_csv TYPE=CSV FIELD_DELIMITER='\t' -``` \ No newline at end of file +-- 1) Create a reusable format +CREATE OR REPLACE FILE FORMAT my_custom_csv TYPE = CSV FIELD_DELIMITER = '\t'; + +-- 2) Query staged files (stage table function syntax uses =>) +SELECT * FROM @mystage/data.csv (FILE_FORMAT => 'my_custom_csv') LIMIT 10; + +-- 3) Load staged files with COPY INTO (copy options use =) +COPY INTO my_table +FROM @mystage/data.csv +FILE_FORMAT = (FORMAT_NAME = 'my_custom_csv'); +``` + +Why the different operators? Stage table functions take key/value parameters written with `=>`, while `COPY INTO` options use standard assignments with `=`. + +**Quick workflow: create, query, and load with the same format** + +```sql +-- Create a reusable format +CREATE FILE FORMAT my_parquet TYPE = PARQUET; + +-- Query staged files with the format (stage table function syntax uses =>) +SELECT * FROM @sales_stage/2024/order.parquet (FILE_FORMAT => 'my_parquet') LIMIT 10; + +-- Load staged files with COPY INTO (copy options use =) +COPY INTO analytics.orders +FROM @sales_stage/2024/order.parquet +FILE_FORMAT = (FORMAT_NAME = 'my_parquet'); +```