MySQL HeatWave 用户指南  / 第 2 章热浪  / 2.2 加载数据  /  2.2.3 使用自动并行加载加载数据

2.2.3 使用自动并行加载加载数据

Auto Parallel Load 通过自动化所涉及的许多步骤来促进将数据加载到 HeatWave 的过程,包括:

  • 排除无法加载的架构、表和列。

  • 定义RAPID为要加载的表的辅助引擎。

  • 验证是否有足够的内存可用于数据。

  • 基于机器学习模型优化负载并行性。

  • 将数据加载到 HeatWave 中。

Auto Parallel Load 可以从任何 MySQL 客户端或连接器运行,它是作为一个名为 的存储过程实现的 heatwave_load,它驻留在 MySQL sys模式中。CALL运行 Auto Parallel Load 涉及为存储过程发出一条 语句,该语句将模式和选项作为参数;例如,此语句加载tpch 模式:

CALL sys.heatwave_load(JSON_ARRAY("tpch"),NULL);

自动并行加载在本节的以下主题下进行描述:

自动并联加载要求

  • 用户必须具有以下 MySQL 权限:

  • 要在 Auto Parallel Load"normal" 模式下运行,HeatWave Cluster 必须处于活动状态。

自动并行加载语法

CALL sys.heatwave_load (db_list,[options]);

db_list: {
     JSON_ARRAY({""|"schema_name"[,"schema_name"] ...)
}

options: {
     JSON_OBJECT("key","value"[,"key","value"] ...)
          "key","value": {
          ["mode",{"normal"|"dryrun"}]
          ["output",{"normal"|"compact"|"silent"|"help"}]
          ["sql_mode","sql_mode"]
          ["policy",{"disable_unsupported_columns"|"not_disable_unsupported_columns"}]
          ["exclude_list",JSON_ARRAY("db_object"[,"db_object"] ...)]
          ["set_load_parallelism",{TRUE|FALSE}]
          ["auto_enc",JSON_OBJECT("mode",{"off"|"check"}]
}

db_list指定要加载的模式。该列表指定为 JSON_ARRAY. 允许指定空数组以查看自动并行加载命令行帮助(请参阅自动并行加载命令行帮助)。否则,需要一个或多个有效的模式名称。

optionsJSON被指定为对象格式的键值对。如果未指定选项,则使用默认设置。如果未指定任何选项,NULL则可以指定代替选项的参数。

有关语法示例,请参阅 自动并行加载示例

自动并行加载选项包括:

  • mode:定义自动并行加载操作模式。允许的值为:

    • normal:默认。生成并执行加载脚本。

    • dryrun:仅生成加载脚本。dryrun如果 HeatWave Cluster 未激活, Auto Parallel Load 模式会自动执行 。

  • output:定义自动并行加载如何产生输出。允许的值为:

    • normal:默认。生成发送到 表stdout和 发送到heatwave_load_report表的汇总输出。(请参阅 自动并行加载报告表。)

    • silent:仅将输出发送到 heatwave_load_report表。(请参阅 自动并行加载报告表。)"silent"如果不需要人类可读的输出,则输出类型很有用;例如,当脚本使用输出时。有关使用 "silent"输出类型的自动并行加载调用的存储过程的示例,请参阅 自动并行加载示例

    • compact:产生紧凑的输出。

    • help:显示自动并行加载命令行帮助。请参阅 自动并行加载命令行帮助

  • sql_mode:定义加载表时使用的 SQL 模式。自动并行加载不支持 MySQL 全局或会话 sql_mode变量。要使用非 oci-default SQL 模式配置运行自动并行加载,请使用自动并行加载sql_mode选项指定配置作为字符串值。如果未指定 SQL 模式,则使用默认的 OCI SQL 模式配置。

    有关 SQL 模式的信息,请参阅 服务器 SQL 模式

  • policy:定义用于处理包含具有不受支持的数据类型的列的表的策略。允许的值为:

    • disable_unsupported_columns:默认。禁用具有不受支持的数据类型的列,并将该表包含在加载脚本中。明确预定义为的列将NOT SECONDARY被忽略(它们既未禁用也未启用)。

      Auto Parallel Load 不会生成语句来禁用明确定义为 NOT SECONDARY.

    • not_disable_unsupported_columns:如果表包含具有不受支持的数据类型的列,则从加载脚本中排除该表。

      具有不受支持的数据类型且明确定义为列的NOT SECONDARY列不会导致表被排除。有关将列定义为 的信息NOT SECONDARY,请参阅 排除表列

  • exclude_list:定义要从加载脚本中排除的数据库对象(模式、表和列)的列表。名称必须是不带反引号的完全限定,如以下示例所示:

    CALL sys.heatwave_load(JSON_ARRAY("tpch","airportdb"), 
    JSON_OBJECT("exclude_list",JSON_ARRAY("tpch.orders","airportdb.employee.salary")));

    Auto Parallel Load 自动排除无法卸载的数据库对象(根据默认policy设置)。这些对象不需要在排除列表中明确指定。系统架构、非InnoDB 表、已经加载到 HeatWave 中的表以及明确定义为的列将NOT SECONDARY被自动排除。

  • set_load_parallelism:默认启用。innodb_parallel_read_threads 通过在加载每个表之前优化变量设置, 基于机器学习模型优化加载并行性 。

  • auto_enc:检查是否有足够的内存用于字符串列编码。设置包括:

    • mode:定义 auto_enc操作模式。允许的值为:

      • off:禁用该 auto_enc选项。不执行内存检查。

      • check:默认。检查 MySQL 节点上是否有足够的内存用于字典编码列,以及是否有足够的根堆内存用于可变长度列编码开销。字典编码的列需要 MySQL 节点上的内存用于字典。对于每个加载的表,必须从根堆中分配 4MB 内存(默认堆段大小)用于可变长度列编码开销。从 MySQL 8.0.30 开始,默认的堆段大小从每个表的 4MB 减少到默认的 64KB。如果内存不够, "dryrun"模式并打印有关内存不足的警告。如果未明确指定选项并将其设置为 ,则 该 auto_enc选项运行 模式。有关详细信息,请参阅 字符串列编码的内存估计checkoff

运行自动并行加载

加载单个模式的自动并行加载调用 ("tpch")编写如下:

CALL sys.heatwave_load(JSON_ARRAY("tpch"),NULL);

指定NULL代替选项意味着自动并行加载使用默认选项设置运行。

您可以先在模式下运行自动并行加载 "dryrun"以检查错误和警告并检查生成的加载脚本。"dryrun"在指定单个模式的模式下调用 Auto Parallel Load("tpch") 的写法如下:

CALL sys.heatwave_load(JSON_ARRAY("tpch"), JSON_OBJECT("mode","dryrun"));

"dryrun"模式下,Auto Parallel Load 仅将加载脚本发送到 heatwave_load_report表。它不会将数据加载到 HeatWave 中。

如果自动并行加载失败并出现错误,请通过查询 heatwave_load_report表来检查错误:

SELECT log FROM sys.heatwave_load_report WHERE type="error";

当 Auto Parallel Load 完成运行时,使用以下查询检查警告:

SELECT log FROM sys.heatwave_load_report WHERE type="warn";

发出以下查询以检查生成的加载脚本:

SELECT log->>"$.sql" AS "Load Script" FROM sys.heatwave_load_report 
WHERE type = "sql" ORDER BY id;

CALL一旦您对 Auto Parallel Load语句和生成的加载脚本 感到满意 ,请重新发出 modeCALL语句 "normal"以将数据加载到 HeatWave 中。例如:

CALL sys.heatwave_load(JSON_ARRAY("tpch"), JSON_OBJECT("mode","normal"));
笔记

您可以在表中检索 DDL 语句或使用以下语句生成可以轻松复制和粘贴的 DDL 语句列表:

SET SESSION group_concat_max_len = 1000000;
SELECT GROUP_CONCAT(log->>"$.sql" SEPARATOR ' ') FROM sys.heatwave_load_report
  WHERE type = "sql" ORDER BY id;

加载数据所需的时间取决于数据大小。Auto Parallel Load 提供完成加载操作所需时间的估计。

表按顺序加载,按模式和表名排序。加载时错误会在遇到时报告。如果在加载表时遇到错误,操作不会终止。Auto Parallel Load 继续运行,移动到下一个表。

当 Auto Parallel Load 完成运行时,它会检查表是否已加载并显示包含已加载表数和加载失败表数的摘要。

字符串列编码的内存估计

auto_enc选项 check默认以模式运行,以确保有足够的内存用于字符串列编码。

如果要确保在尝试加载操作之前有足够的内存用于字符串列编码, 以下示例使用模式中的auto_enc 选项。check内存不足会导致加载失败。

CALL sys.heatwave_load(JSON_ARRAY("tpch"), 
  JSON_OBJECT("mode","dryrun","auto_enc",JSON_OBJECT("mode","check")));
笔记

无论是否在 Auto Parallel Load 调用语句中明确指定, 该auto_enc选项都会以 模式运行。check

在 Auto Parallel Load 输出中查找容量估算数据。结果表明是否有足够的内存来加载所有表。

自动并行加载报告表

运行 Auto Parallel Load 时,包括 Auto Parallel Load 执行日志和生成的加载脚本在内的输出将发送到架构 中的heatwave_load_report表。sys

heatwave_load_report表是一个临时表。它包含上次执行自动并行加载的数据。数据仅可用于当前会话,并在会话终止或服务器关闭时丢失。

自动并行加载报表查询示例

运行Auto Parallel Load后可以查询该heatwave_load_report表,如下例:

  • 查看错误信息以防自动并行加载意外停止:

    SELECT log FROM sys.heatwave_load_report WHERE type="error";
  • 查看警告以找出无法加载表的原因:

    SELECT log FROM sys.heatwave_load_report WHERE type="warn";
  • "normal"查看生成的加载脚本以查看自动并行加载模式下 将执行的命令 :

    SELECT log->>"$.sql" AS "Load Script" FROM sys.heatwave_load_report 
    WHERE type = "sql" ORDER BY id;
  • 查看生成的加载命令数:

    SELECT Count(*) AS "Total Load Commands Generated" FROM sys.heatwave_load_report 
    WHERE type = "sql" ORDER BY id;
  • 查看特定表的加载脚本数据:

    SELECT log->>"$.sql" FROM sys.heatwave_load_report  
    WHERE type="sql" AND log->>"$.schema_name" = "db0" AND log->>"$.table_name" = "tbl" 
    ORDER BY id;
  • 将自动并行加载生成的 DDL 语句连接到一个可以复制和粘贴以执行的字符串中。该 group_concat_max_len 变量以字节为单位设置 GROUP_CONCAT()函数的结果长度,以容纳可能很长的字符串。(默认 group_concat_max_len 设置为 1024 字节。)

    SET SESSION group_concat_max_len = 1000000;
    SELECT GROUP_CONCAT(log->>"$.sql" SEPARATOR ' ') FROM sys.heatwave_load_report 
      WHERE type = "sql" ORDER BY id;

自动并行加载命令行帮助

要查看 Auto Parallel Load 命令行帮助,请发出以下语句:

CALL sys.heatwave_load(JSON_ARRAY(""),JSON_OBJECT("output","help"));

命令行帮助提供了 Auto Parallel Load 实用程序的使用文档。

自动并行加载示例

  • 加载多个模式。没有指定选项,这意味着使用默认选项。

    CALL sys.heatwave_load(JSON_ARRAY("tpch","airportdb","employees","sakila"),NULL);
  • 使用该策略加载多个模式 not_disable_unsupported_columns ,这会导致包含不受支持的列的表被排除在加载操作之外。不受支持的列是那些具有不受支持的数据类型的列。

    CALL sys.heatwave_load(JSON_ARRAY("tpch","airportdb","employees","sakila"), 
    JSON_OBJECT("policy","not_disable_unsupported_columns"));
  • 加载多个模式,不包括指定的表和特定列:

    CALL sys.heatwave_load(JSON_ARRAY("tpch","airportdb"), 
    JSON_OBJECT("exclude_list",JSON_ARRAY("tpch.orders","airportdb.employee.salary")));
  • 从名为的模式加载以“ hw前缀 开头的表schema_customer_1

    SET @exc_list = (SELECT JSON_OBJECT('exclude_list',
                     JSON_ARRAYAGG(CONCAT(table_schema,'.',table_name))) 
                     FROM information_schema.tables 
                     WHERE table_schema = 'schema_customer_1' 
                     AND table_name NOT LIKE 'hw%');
    CALL sys.heatwave_load(JSON_ARRAY('schema_customer_1'), @exc_list);
  • 使用以“ hw前缀 开头的表加载所有模式 。

    SET @db_list = (SELECT json_arrayagg(schema_name) FROM information_schema.schemata);
    SET @exc_list = (SELECT JSON_OBJECT('exclude_list',
                     JSON_ARRAYAGG(CONCAT(table_schema,'.',table_name))) 
                     FROM information_schema.tables 
                     WHERE table_schema NOT IN
                     ('mysql','information_schema', 'performance_schema','sys') 
                     AND table_name NOT LIKE 'hw%');
    CALL sys.heatwave_load(@db_list, @exc_list);

    您可以检查db_listexc_list使用SELECT JSON_PRETTY(@db_list);SELECT JSON_PRETTY(@exc_list);

  • 从存储过程调用自动并行加载:

    DROP PROCEDURE IF EXISTS auto_load_wrapper;
    DELIMITER //
    CREATE PROCEDURE auto_load_wrapper()
    BEGIN
      -- AUTOMATED INPUT
      SET @db_list = (SELECT JSON_ARRAYAGG(schema_name) FROM information_schema.schemata);
      SET @exc_list = (SELECT JSON_ARRAYAGG(CONCAT(table_schema,'.',table_name)) 
      FROM information_schema.tables WHERE table_schema = "db0");
    
      CALL sys.heatwave_load(@db_list, JSON_OBJECT("output","silent","exclude_list", 
      CAST(@exc_list AS JSON)));
    
      -- CUSTOM OUTPUT
      SELECT log as 'Unsupported objects' FROM sys.heatwave_load_report WHERE type="warn" 
      AND stage="VERIFICATION" and log like "%Unsupported%";
      SELECT Count(*) AS "Total Load commands Generated" 
      FROM sys.heatwave_load_report WHERE type = "sql" ORDER BY id;
    
    END //
    DELIMITER ;
    
    CALL auto_load_wrapper();