From 0689a9da350e5c22b49b6ae15c68f29a5127b6fc Mon Sep 17 00:00:00 2001 From: D3Hunter Date: Thu, 21 Mar 2024 19:56:15 +0800 Subject: [PATCH] importinto 8.0 change & DXF enhancement (#16672) --- sql-statements/sql-statement-import-into.md | 146 +++++++++++++------- tidb-distributed-execution-framework.md | 6 +- 2 files changed, 103 insertions(+), 49 deletions(-) diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index 676088bdf8d8..e895c2d72c78 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -5,43 +5,49 @@ summary: TiDB 数据库中 IMPORT INTO 的使用概况。 # IMPORT INTO -`IMPORT INTO` 语句使用 TiDB Lightning 的[物理导入模式](/tidb-lightning/tidb-lightning-physical-import-mode.md)，用于将 `CSV`、`SQL`、`PARQUET` 等格式的数据导入到 TiDB 的一张空表中。 +`IMPORT INTO` 语句使用 TiDB Lightning 的[物理导入模式](/tidb-lightning/tidb-lightning-physical-import-mode.md)导入数据，提供以下两种用法： -`IMPORT INTO` 支持导入存储在 Amazon S3、GCS 和 TiDB 本地的数据文件。 - -- 对于存储在 S3 或 GCS 的数据文件，`IMPORT INTO` 支持通过 [TiDB 分布式执行框架](/tidb-distributed-execution-framework.md)运行。 - - - 当此框架功能开启时（即 [tidb_enable_dist_task](/system-variables.md#tidb_enable_dist_task-从-v710-版本开始引入) 为 `ON`），`IMPORT INTO` 会将一个数据导入任务拆分成多个子任务并分配到各个 TiDB 节点上运行，以提高导入效率。 - - 当此框架功能关闭时，`IMPORT INTO` 仅支持在当前用户连接的 TiDB 节点上运行。 - -- 对于存储在 TiDB 本地的数据文件，`IMPORT INTO` 仅支持在当前用户连接的 TiDB 节点上运行，因此数据文件需要存放在当前用户连接的 TiDB 节点上。如果是通过 PROXY 或者 Load Balancer 访问 TiDB，则无法导入存储在 TiDB 本地的数据文件。 +- `IMPORT INTO ... FROM FILE` 用于将 `CSV`、`SQL`、`PARQUET` 等格式的数据文件导入到 TiDB 的一张空表中。 +- `IMPORT INTO ... FROM SELECT` 用于将 `SELECT` 语句的查询结果导入到 TiDB 的一张空表中，也支持导入使用 [`AS OF TIMESTAMP`](/as-of-timestamp.md) 查询的历史数据。 ## 使用限制 -- 目前该语句支持导入 10 TiB 以内的数据。 - 只支持导入数据到数据库中已有的空表。 - 不支持事务，也无法回滚。在显式事务 (`BEGIN`/`END`) 中执行会报错。 -- 在导入完成前会阻塞当前连接，如果需要异步执行，可以添加 `DETACHED` 选项。 - 不支持和 [Backup & Restore](/br/backup-and-restore-overview.md)、[`FLASHBACK CLUSTER`](/sql-statements/sql-statement-flashback-cluster.md)、[创建索引加速](/system-variables.md#tidb_ddl_enable_fast_reorg-从-v630-版本开始引入)、TiDB Lightning 导入、TiCDC 数据同步、[Point-in-time recovery (PITR)](/br/br-log-architecture.md) 等功能同时工作。 -- 每个集群上同时只能有一个 `IMPORT INTO` 任务在运行。`IMPORT INTO` 会 precheck 是否存在运行中的任务，但并非硬限制，如果多个客户端同时执行 `IMPORT INTO` 仍有可能启动多个任务，请避免该情况，否则可能导致数据不一致或者任务失败的问题。 - 导入数据的过程中，请勿在目标表上执行 DDL 和 DML 操作，也不要在目标数据库上执行 [`FLASHBACK DATABASE`](/sql-statements/sql-statement-flashback-database.md)，否则会导致导入失败或数据不一致。导入期间也不建议进行读操作，因为读取的数据可能不一致。请在导入完成后再进行读写操作。 - 导入期间会占用大量系统资源，建议 TiDB 节点使用 32 核以上的 CPU 和 64 GiB 以上内存以获得更好的性能。导入期间会将排序好的数据写入到 TiDB [临时目录](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入)下，建议优先考虑配置闪存等高性能存储介质。详情请参考[物理导入使用限制](/tidb-lightning/tidb-lightning-physical-import-mode.md#必要条件及限制)。 - TiDB [临时目录](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入)至少需要有 90 GiB 的可用空间。建议预留大于等于所需导入数据的存储空间，以保证最佳导入性能。 -- 一个导入任务只支持导入数据到一张目标表中。如需导入数据到多张目标表，需要在一张目标表导入完成后，再新建一个任务导入下一张目标表。 +- 一个导入任务只支持导入数据到一张目标表中。 - TiDB 集群升级期间不支持使用该语句。 -- 当使用[全局排序](/tidb-global-sort.md)导入数据时，单行数据的总长度不能超过 32 MiB。 -- 当使用全局排序导入数据时，如果 TiDB 集群在导入任务尚未完成时被删除了，Amazon S3 上可能会残留用于全局排序的临时数据。该场景需要手动删除这些数据，以免增加 S3 存储成本。 - 所需导入的数据不能存在主键或非空唯一索引冲突的记录，否则会导致任务失败。 -- 对于基于分布式执行框架调度的 `IMPORT INTO` 任务，如该任务已运行，不支持被调度到新的 TiDB 节点上执行。当前在执行导入任务的 TiDB 节点如果重启，该 TiDB 节点不会再执行该导入任务，而是被转移到其他 TiDB 节点继续执行。如果是导入 TiDB 节点本地的数据，任务异常后不会被 failover 到其他 TiDB 节点。 - 已知问题：在 TiDB 节点配置文件中的 PD 地址与当前集群 PD 拓扑不一致时（如曾经缩容过 PD，但没有对应更新 TiDB 配置文件或者更新该文件后未重启 TiDB 节点），执行 `IMPORT INTO` 会失败。 +### `IMPORT INTO ... FROM FILE` 使用限制 + +- 目前该语句支持导入 10 TiB 以内的数据。 +- 在导入完成前会阻塞当前连接，如果需要异步执行，可以添加 `DETACHED` 选项。 +- 每个集群上最多同时有 16 个 `IMPORT INTO` 任务（参考 [TiDB 分布式执行框架使用限制](/tidb-distributed-execution-framework.md#使用限制)）在运行，当集群没有足够资源或者达到任务数量上限时，新提交的导入任务会排队等待执行。 +- 当使用[全局排序](/tidb-global-sort.md)导入数据时，`THREAD` 选项值需要大于或等于 `16`。 +- 当使用[全局排序](/tidb-global-sort.md)导入数据时，单行数据的总长度不能超过 32 MiB。 +- 当使用全局排序导入数据时，如果 TiDB 集群在导入任务尚未完成时被删除了，Amazon S3 上可能会残留用于全局排序的临时数据。该场景需要手动删除这些数据，以免增加 S3 存储成本。 +- 未开启 [TiDB 分布式执行框架](/tidb-distributed-execution-framework.md)时创建的所有 `IMPORT INTO` 任务会直接在提交任务的节点上运行，后续即使开启了分布式执行框架，这些任务也不会被调度到其它 TiDB 节点上执行。开启分布式执行框架后，新创建的 `IMPORT INTO` 任务如果导入的是 S3 或 GCS 中的数据，则会自动调度或者 failover 到其它 TiDB 节点执行。 + +### `IMPORT INTO ... FROM SELECT` 使用限制 + +- `IMPORT INTO ... FROM SELECT` 仅能在当前用户连接的 TiDB 节点执行，在导入完成前会阻塞当前连接。 +- `IMPORT INTO ... FROM SELECT` 仅支持配置 `THREAD` 和 `DISABLE_PRECHECK` 这两个[导入选项](#withoptions)。 +- `IMPORT INTO ... FROM SELECT` 不支持使用 `SHOW IMPORT JOB(s)` 和 `CANCEL IMPORT JOB ` 等任务管理语句。 +- TiDB [临时目录](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入)需要有足够的空间来存储整个 `SELECT` 语句查询结果（暂不支持设置 `DISK_QUOTA` 选项）。 +- 不支持使用 [`tidb_snapshot`](/read-historical-data.md) 导入历史数据。 + ## 导入前准备 在使用 `IMPORT INTO` 开始导入数据前，请确保： - 要导入的目标表在 TiDB 中已经创建，并且是空表。 - 当前集群有足够的剩余空间能容纳要导入的数据。 -- 当前连接的 TiDB 节点的[临时目录](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入)至少有 90 GiB 的磁盘空间。如果开启了 [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-从-v710-版本开始引入)，需要确保集群中所有 TiDB 节点的临时目录都有足够的磁盘空间。 +- 当前连接的 TiDB 节点的[临时目录](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入)至少有 90 GiB 的磁盘空间。如果导入存储在 S3 或 GCS 的数据文件且开启了 [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-从-v710-版本开始引入)，需要确保集群中所有 TiDB 节点的临时目录都有足够的磁盘空间。 ## 需要的权限 @@ -52,10 +58,15 @@ summary: TiDB 数据库中 IMPORT INTO 的使用概况。 ```ebnf+diagram ImportIntoStmt ::= 'IMPORT' 'INTO' TableName ColumnNameOrUserVarList? SetClause? FROM fileLocation Format? WithOptions? + | + 'IMPORT' 'INTO' TableName ColumnNameList? FROM SelectStatement WithOptions? ColumnNameOrUserVarList ::= '(' ColumnNameOrUserVar (',' ColumnNameOrUserVar)* ')' +ColumnNameList ::= + '(' ColumnName (',' ColumnName)* ')' + SetClause ::= 'SET' SetItem (',' SetItem)* @@ -99,13 +110,14 @@ SET 表达式左侧只能引用 `ColumnNameOrUserVarList` 中没有的列名。 > > 如果目标集群开启了 [SEM](/system-variables.md#tidb_enable_enhanced_security)，则 fileLocation 不能指定为本地文件路径。 -使用 fileLocation 可以指定单个文件，也可使用通配符 `*` 来匹配需要导入的多个文件。注意通配符只能用在文件名部分，不会匹配目录，也不会递归处理子目录下相关的文件。下面以数据存储在 S3 为例： +使用 fileLocation 可以指定单个文件，也可使用通配符 `*` 和 `[]` 来匹配需要导入的多个文件。注意通配符只能用在文件名部分，不会匹配目录，也不会递归处理子目录下相关的文件。下面以数据存储在 S3 为例： - 导入单个文件：`s3:///path/to/data/foo.csv` - 导入指定路径下的所有文件：`s3:///path/to/data/*` - 导入指定路径下的所有以 `.csv` 结尾的文件：`s3:///path/to/data/*.csv` - 导入指定路径下所有以 `foo` 为前缀的文件：`s3:///path/to/data/foo*` - 导入指定路径下以 `foo` 为前缀、以 `.csv` 结尾的文件：`s3:///path/to/data/foo*.csv` +- 导入指定路径下的 `1.csv` 和 `2.csv`：`s3:///path/to/data/[12].csv` ### Format @@ -113,11 +125,11 @@ SET 表达式左侧只能引用 `ColumnNameOrUserVarList` 中没有的列名。 ### WithOptions -你可以通过 WithOptions 来指定导入选项，控制数据导入过程。例如，如需使导入任务在后台异步执行，你可以通过在 `IMPORT INTO` 语句中添加 `WITH DETACHED` 选项来开启导入任务的 `DETACHED` 模式。 +你可以通过 WithOptions 来指定导入选项，控制数据导入过程。例如，如需使导入数据文件的任务在后台异步执行，你可以通过在 `IMPORT INTO` 语句中添加 `WITH DETACHED` 选项来开启导入任务的 `DETACHED` 模式。 目前支持的选项包括： -| 选项名 | 支持的数据格式 | 描述 | +| 选项名 | 支持的数据源以及格式 | 描述 | |:---|:---|:---| | `CHARACTER_SET=''` | CSV | 指定数据文件的字符集，默认为 `utf8mb4`。目前支持的字符集包括 `binary`、`utf8`、`utf8mb4`、`gb18030`、`gbk`、`latin1` 和 `ascii`。 | | `FIELDS_TERMINATED_BY=''` | CSV | 指定字段分隔符，默认为 `,`。 | @@ -127,17 +139,29 @@ SET 表达式左侧只能引用 `ColumnNameOrUserVarList` 中没有的列名。 | `LINES_TERMINATED_BY=''` | CSV | 指定行分隔符，默认 `IMPORT INTO` 会自动识别分隔符为 `\n`、`\r` 或 `\r\n`，如果行分隔符为以上三种，无须显式指定该选项。 | | `SKIP_ROWS=` | CSV | 指定需要跳过的行数，默认为 `0`。可通过该参数跳过 CSV 中的 header，如果是通过通配符来指定所需导入的源文件，该参数会对 fileLocation 中通配符匹配的所有源文件生效。 | | `SPLIT_FILE` | CSV | 将单个 CSV 文件拆分为多个 256 MiB 左右的小文件块进行并行处理，以提高导入效率。该参数仅对**非**压缩的 CSV 文件生效，且该参数和 TiDB Lightning 的 [`strict-format`](/tidb-lightning/tidb-lightning-data-source.md#启用严格格式) 有相同的使用限制。 | -| `DISK_QUOTA=''` | 所有格式 | 指定数据排序期间可使用的磁盘空间阈值。默认值为 TiDB [临时目录](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入)所在磁盘空间的 80%。如果无法获取磁盘总大小，默认值为 50 GiB。当显式指定 DISK_QUOTA 时，该值同样不能超过 TiDB [临时目录](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入)所在磁盘空间的 80%。 | -| `DISABLE_TIKV_IMPORT_MODE` | 所有格式 | 指定是否禁止导入期间将 TiKV 切换到导入模式。默认不禁止。如果当前集群存在正在运行的读写业务，为避免导入过程对这部分业务造成影响，可开启该参数。 | -| `THREAD=` | 所有格式 | 指定导入的并发度。默认值为 TiDB 节点的 CPU 核数的 50%，最小值为 1。可以显示指定该参数来控制对资源的占用，但最大值不能超过 CPU 核数。如需导入数据到一个空集群，建议可以适当调大该值，以提升导入性能。如果目标集群已经用于生产环境，请根据业务要求按需调整该参数值。 | -| `MAX_WRITE_SPEED=''` | 所有格式 | 控制写入到单个 TiKV 的速度，默认无速度限制。例如设置为 `1MiB`，则限制写入速度为 1 MiB/s。| -| `CHECKSUM_TABLE=''` | 所有格式 | 配置是否在导入完成后对目标表是否执行 CHECKSUM 检查来验证导入的完整性。可选的配置项为 `"required"`（默认）、`"optional"` 和 `"off"`。`"required"` 表示在导入完成后执行 CHECKSUM 检查，如果 CHECKSUM 检查失败，则会报错退出。`"optional"` 表示在导入完成后执行 CHECKSUM 检查，如果报错，会输出一条警告日志并忽略报错。`"off"` 表示导入结束后不执行 CHECKSUM 检查。 | -| `DETACHED` | 所有格式 | 该参数用于控制 `IMPORT INTO` 是否异步执行。开启该参数后，执行 `IMPORT INTO` 会立即返回该导入任务的 `Job_ID` 等信息，且该任务会在后台异步执行。 | -| `CLOUD_STORAGE_URI` | 所有格式 | 指定编码后的 KV 数据[全局排序](/tidb-global-sort.md)的目标存储地址。未指定该参数时，`IMPORT INTO` 会根据系统变量 [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-从-v740-版本开始引入) 的值来确定是否使用全局排序，如果该系统变量指定了目标存储地址，就使用指定的地址进行全局排序。当指定该参数时，如果参数值不为空，`IMPORT INTO` 会使用该参数值作为目标存储地址；如果参数值为空，则表示强制使用本地排序。目前目标存储地址仅支持 Amazon S3，具体 Amazon S3 URI 格式配置，请参见 [Amazon S3 URI 格式](/external-storage-uri.md#amazon-s3-uri-格式)。注意当使用该功能时，所有 TiDB 节点都需要有目标 Amazon S3 bucket 的读写权限。 | +| `DISK_QUOTA=''` | 所有文件格式 | 指定数据排序期间可使用的磁盘空间阈值。默认值为 TiDB [临时目录](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入)所在磁盘空间的 80%。如果无法获取磁盘总大小，默认值为 50 GiB。当显式指定 `DISK_QUOTA` 时，该值同样不能超过 TiDB [临时目录](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入)所在磁盘空间的 80%。 | +| `DISABLE_TIKV_IMPORT_MODE` | 所有文件格式 | 指定是否禁止导入期间将 TiKV 切换到导入模式。默认不禁止。如果当前集群存在正在运行的读写业务，为避免导入过程对这部分业务造成影响，可开启该参数。 | +| `THREAD=` | 所有文件格式、`SELECT` 语句的查询结果 | 指定导入的并发度。对于 `IMPORT INTO ... FROM FILE`，`THREAD` 默认值为 TiDB 节点的 CPU 核数的 50%，最小值为 `1`，最大值为 CPU 核数；对于 `IMPORT INTO ... FROM SELECT`，`THREAD` 默认值为 `2`，最小值为 `1`，最大值为 TiDB 节点的 CPU 核数的 2 倍。如需导入数据到一个空集群，建议可以适当调大该值，以提升导入性能。如果目标集群已经用于生产环境，请根据业务要求按需调整该参数值。 | +| `MAX_WRITE_SPEED=''` | 所有文件格式 | 控制写入到单个 TiKV 的速度，默认无速度限制。例如设置为 `1MiB`，则限制写入速度为 1 MiB/s。| +| `CHECKSUM_TABLE=''` | 所有文件格式 | 配置是否在导入完成后对目标表是否执行 CHECKSUM 检查来验证导入的完整性。可选的配置项为 `"required"`（默认）、`"optional"` 和 `"off"`。`"required"` 表示在导入完成后执行 CHECKSUM 检查，如果 CHECKSUM 检查失败，则会报错退出。`"optional"` 表示在导入完成后执行 CHECKSUM 检查，如果报错，会输出一条警告日志并忽略报错。`"off"` 表示导入结束后不执行 CHECKSUM 检查。 | +| `DETACHED` | 所有文件格式 | 该参数用于控制 `IMPORT INTO` 是否异步执行。开启该参数后，执行 `IMPORT INTO` 会立即返回该导入任务的 `Job_ID` 等信息，且该任务会在后台异步执行。 | +| `CLOUD_STORAGE_URI` | 所有文件格式 | 指定编码后的 KV 数据[全局排序](/tidb-global-sort.md)的目标存储地址。未指定该参数时，`IMPORT INTO` 会根据系统变量 [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-从-v740-版本开始引入) 的值来确定是否使用全局排序，如果该系统变量指定了目标存储地址，就使用指定的地址进行全局排序。当指定该参数时，如果参数值不为空，`IMPORT INTO` 会使用该参数值作为目标存储地址；如果参数值为空，则表示强制使用本地排序。目前目标存储地址仅支持 Amazon S3，具体 Amazon S3 URI 格式配置，请参见 [Amazon S3 URI 格式](/external-storage-uri.md#amazon-s3-uri-格式)。注意当使用该功能时，所有 TiDB 节点都需要有目标 Amazon S3 bucket 的读写权限，至少包括 `s3:ListBucket`、`s3:GetObject`、`s3:DeleteObject`、`s3:PutObject`、`s3:AbortMultipartUpload`。 | +| `DISABLE_PRECHECK` | 所有文件格式、`SELECT` 语句的查询结果 | 设置该选项后会关闭非 critical 的前置检查项，如检查是否存在 CDC 或 PITR 等任务。 | + +## `IMPORT INTO ... FROM FILE` 使用说明 -## 压缩文件 +`IMPORT INTO ... FROM FILE` 支持导入存储在 Amazon S3、GCS 和 TiDB 本地的数据文件。 -`IMPORT INTO` 支持导入压缩的 `CSV` 和 `SQL` 文件，会自动根据数据文件后缀来确定该文件是否为压缩文件以及压缩格式： +- 对于存储在 S3 或 GCS 的数据文件，`IMPORT INTO ... FROM FILE` 支持通过 [TiDB 分布式执行框架](/tidb-distributed-execution-framework.md)运行。 + + - 当此框架功能开启时（即 [tidb_enable_dist_task](/system-variables.md#tidb_enable_dist_task-从-v710-版本开始引入) 为 `ON`），`IMPORT INTO` 会将一个数据导入任务拆分成多个子任务并分配到各个 TiDB 节点上运行，以提高导入效率。 + - 当此框架功能关闭时，`IMPORT INTO ... FROM FILE` 仅支持在当前用户连接的 TiDB 节点上运行。 + +- 对于存储在 TiDB 本地的数据文件，`IMPORT INTO ... FROM FILE` 仅支持在当前用户连接的 TiDB 节点上运行，因此数据文件需要存放在当前用户连接的 TiDB 节点上。如果是通过 PROXY 或者 Load Balancer 访问 TiDB，则无法导入存储在 TiDB 本地的数据文件。 + +### 压缩文件 + +`IMPORT INTO ... FROM FILE` 支持导入压缩的 `CSV` 和 `SQL` 文件，会自动根据数据文件后缀来确定该文件是否为压缩文件以及压缩格式： | 后缀名 | 压缩格式 | |:---|:---| @@ -150,13 +174,13 @@ SET 表达式左侧只能引用 `ColumnNameOrUserVarList` 中没有的列名。 > - Snappy 压缩文件必须遵循[官方 Snappy 格式](https://github.com/google/snappy)。不支持其他非官方压缩格式。 > - 由于无法对单个大压缩文件进行并发解压，因此压缩文件的大小会直接影响导入速度。建议解压后的文件大小不要超过 256 MiB。 -## 全局排序 +### 全局排序 > **警告：** > > 全局排序为实验特性，不建议在生产环境中使用。 -`IMPORT INTO` 会将源数据文件的导入拆分到多个子任务中，各个子任务独立进行编码排序并导入。如果各个子任务编码后的 KV (TiDB 将数据编码为 KV 的方式，参考 [TiDB 数据库的计算](/tidb-computing.md)) range 重叠过多，导入时 TiKV 需要不断地进行 compaction，会降低导入的性能和稳定性。 +`IMPORT INTO ... FROM FILE` 会将源数据文件的导入拆分到多个子任务中，各个子任务独立进行编码排序并导入。如果各个子任务编码后的 KV (TiDB 将数据编码为 KV 的方式，参考 [TiDB 数据库的计算](/tidb-computing.md)) range 重叠过多，导入时 TiKV 需要不断地进行 compaction，会降低导入的性能和稳定性。 在以下情况中，可能存在较多的 KV range 重叠： @@ -169,8 +193,8 @@ SET 表达式左侧只能引用 `ColumnNameOrUserVarList` 中没有的列名。 全局排序对内存资源的使用较高，在数据导入开始前，建议先设置 [`tidb_server_memory_limit_gc_trigger`](/system-variables.md#tidb_server_memory_limit_gc_trigger-从-v640-版本开始引入) 和 [`tidb_server_memory_limit`](/system-variables.md#tidb_server_memory_limit-从-v640-版本开始引入) 两个变量，避免频繁触发 golang GC 从而影响导入效率： ```sql -SET GLOBAL tidb_server_memory_limit_gc_trigger=0.99; -SET GLOBAL tidb_server_memory_limit='88%'; +SET GLOBAL tidb_server_memory_limit_gc_trigger=1; +SET GLOBAL tidb_server_memory_limit='75%'; ``` > **注意：** @@ -178,11 +202,11 @@ SET GLOBAL tidb_server_memory_limit='88%'; > - 如果源数据文件 KV range 重叠较少，开启全局排序后可能会降低导入性能，因为全局排序需要等所有子任务的数据本地排序后，再进行额外的全局排序操作，之后才进行导入。 > - 使用全局排序的导入任务完成后，存放在云存储里用于全局排序的文件会在后台线程中异步清理。 -## 输出内容 +### 输出内容 -当 `IMPORT INTO` 导入完成，或者开启了 `DETACHED` 模式时，`IMPORT INTO` 会返回当前任务的信息。以下为一些示例，字段的含义描述请参考 [`SHOW IMPORT JOB(s)`](/sql-statements/sql-statement-show-import-job.md)。 +当 `IMPORT INTO ... FROM FILE` 导入完成，或者开启了 `DETACHED` 模式时，TiDB 会返回当前任务的信息。以下为一些示例，字段的含义描述请参考 [`SHOW IMPORT JOB(s)`](/sql-statements/sql-statement-show-import-job.md)。 -当 `IMPORT INTO` 导入完成时输出： +当 `IMPORT INTO ... FROM FILE` 导入完成时输出： ```sql IMPORT INTO t FROM '/path/to/small.csv'; @@ -193,7 +217,7 @@ IMPORT INTO t FROM '/path/to/small.csv'; +--------+--------------------+--------------+----------+-------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+ ``` -开启了 `DETACHED` 模式时，执行 `IMPORT INTO` 语句会立即返回输出。从输出中，你可以看到该任务状态 `Status` 为 `pending`，表示等待执行。 +开启了 `DETACHED` 模式时，执行 `IMPORT INTO ... FROM FILE` 语句会立即返回输出。从输出中，你可以看到该任务状态 `Status` 为 `pending`，表示等待执行。 ```sql IMPORT INTO t FROM '/path/to/small.csv' WITH DETACHED; @@ -204,27 +228,27 @@ IMPORT INTO t FROM '/path/to/small.csv' WITH DETACHED; +--------+--------------------+--------------+----------+-------+---------+------------------+---------------+----------------+----------------------------+------------+----------+------------+ ``` -## 查看和控制导入任务 +### 查看和控制导入任务 对于开启了 `DETACHED` 模式的任务，可通过 [`SHOW IMPORT`](/sql-statements/sql-statement-show-import-job.md) 来查看当前任务的执行进度。 任务启动后，可通过 [`CANCEL IMPORT JOB `](/sql-statements/sql-statement-cancel-import-job.md) 来取消对应任务。 -## 使用示例 +### 使用示例 -### 导入带有 header 的 CSV 文件 +#### 导入带有 header 的 CSV 文件 ```sql IMPORT INTO t FROM '/path/to/file.csv' WITH skip_rows=1; ``` -### 以 `DETACHED` 模式异步导入 +#### 以 `DETACHED` 模式异步导入 ```sql IMPORT INTO t FROM '/path/to/file.csv' WITH DETACHED; ``` -### 忽略数据文件中的特定字段 +#### 忽略数据文件中的特定字段 假设数据文件为以下 CSV 文件： @@ -240,15 +264,21 @@ id,name,age IMPORT INTO t(id, name, @1) FROM '/path/to/file.csv' WITH skip_rows=1; ``` -### 使用通配符 `*` 导入多个数据文件 +#### 使用通配符导入多个数据文件 假设在 `/path/to/` 目录下有 `file-01.csv`、`file-02.csv` 和 `file-03.csv` 三个文件，如需通过 `IMPORT INTO` 将这三个文件导入到目标表 `t` 中，可使用如下 SQL 语句： ```sql -IMPORT INTO t FROM '/path/to/file-*.csv' +IMPORT INTO t FROM '/path/to/file-*.csv'; +``` + +如果只需要将 `file-01.csv` 和 `file-03.csv` 导入到目标表，可以使用如下 SQL 语句： + +```sql +IMPORT INTO t FROM '/path/to/file-0[13].csv'; ``` -### 从 S3 或 GCS 导入数据 +#### 从 S3 或 GCS 导入数据 - 从 S3 导入数据 @@ -264,7 +294,7 @@ IMPORT INTO t FROM '/path/to/file-*.csv' 关于 Amazon S3 或 GCS 的 URI 路径配置，详见[外部存储服务的 URI 格式](/external-storage-uri.md)。 -### 通过 SetClause 语句计算列值 +#### 通过 SetClause 语句计算列值 假设数据文件为以下 CSV 文件： @@ -280,13 +310,13 @@ id,name,val IMPORT INTO t(id, name, @1) SET val=@1*100 FROM '/path/to/file.csv' WITH skip_rows=1; ``` -### 导入 SQL 格式的数据文件 +#### 导入 SQL 格式的数据文件 ```sql IMPORT INTO t FROM '/path/to/file.sql' FORMAT 'sql'; ``` -### 限制写入 TiKV 的速度 +#### 限制写入 TiKV 的速度 限制写入单个 TiKV 的速度为 10 MiB/s： @@ -294,6 +324,26 @@ IMPORT INTO t FROM '/path/to/file.sql' FORMAT 'sql'; IMPORT INTO t FROM 's3://bucket/path/to/file.parquet?access-key=XXX&secret-access-key=XXX' FORMAT 'parquet' WITH MAX_WRITE_SPEED='10MiB'; ``` +## `IMPORT INTO ... FROM SELECT` 使用说明 + +`IMPORT INTO ... FROM SELECT` 支持将 `SELECT` 语句的查询结果导入到 TiDB 的一张空表中，也支持导入使用 [`AS OF TIMESTAMP`](/as-of-timestamp.md) 查询的历史数据。 + +### 导入 SELECT 语句的查询结果 + +导入 `UNION` 结果到目标表 `t`，指定导入的并发度为 `8`，并且关闭非 critical 的 precheck 项： + +``` +IMPORT INTO t FROM SELECT * FROM src UNION SELECT * FROM src2 WITH THREAD = 8, DISABLE_PRECHECK; +``` + +### 导入指定时间点的历史数据 + +导入指定时间点的历史数据到目标表 `t`： + +``` +IMPORT INTO t FROM SELECT * FROM src AS OF TIMESTAMP '2024-02-27 11:38:00'; +``` + ## MySQL 兼容性 该语句是对 MySQL 语法的扩展。 diff --git a/tidb-distributed-execution-framework.md b/tidb-distributed-execution-framework.md index 20d2fc52a850..304d4aaaf75d 100644 --- a/tidb-distributed-execution-framework.md +++ b/tidb-distributed-execution-framework.md @@ -36,7 +36,11 @@ TiDB 采用计算存储分离架构，具有出色的扩展性和弹性的扩缩 ## 使用限制 -- 分布式执行框架一次只能调度一个 `ADD INDEX` 任务进行分布式执行。如果在当前的 `ADD INDEX` 分布式任务还未执行完成时就提交了一个新的 `ADD INDEX` 任务，则新提交的 `ADD INDEX` 任务不会被该框架调度，而是直接通过事务的方式来执行。 +分布式执行框架最多同时调度 16 个任务（包括 `ADD INDEX` 和 `IMPORT INTO`）。 + +### `ADD INDEX` 的使用限制 + +- 集群内同时只能有一个 `ADD INDEX` 任务进行分布式执行。如果在当前的 `ADD INDEX` 分布式任务还未执行完成时就提交了一个新的 `ADD INDEX` 任务，则新提交的 `ADD INDEX` 任务不会被该框架调度，而是直接通过事务的方式来执行。 - 不支持通过分布式执行框架对数据类型为 `TIMESTAMP` 的列添加索引，否则会导致索引和数据不一致的问题。 ## 启用前提