功能边界#

本文将介绍 OpenMLDB SQL 的功能边界。

Note

如果对 SQL 语句有疑问，请参考 OpenMLDB SQL，或直接利用搜索功能搜索。

系统配置——TaskManager#

通过配置 TaskManager 可以决定离线存储地址 offline.data.prefix、离线 job 计算所需 Spark 模式 spark.master 等。

offline.data.prefix：可配置为文件路径或 HDFS 路径。生产环境建议配置 HDFS 路径，测试环境（特指 onebox 型，例如在 Docker 容器内启动，或所有组件都在一台机器上）可以配置本地文件路径。这是因为，TaskManager提交local的Spark Job，这个Job可以访问到本地文件路径。但这样的话，将无法支持多 TaskManager 分布式部署（TaskManager 之间不会传输数据）。

  • 如果想在多台主机上部署 TaskManager，请使用 HDFS 等多机可同时访问到的存储介质。

  • 如果想测试多 TaskManager 工作协同，可以在一台主机上部署多个 TaskManager，此时可以使用文件路径作为离线存储。

spark.master=local[*]：Spark 默认配置为 local[*] 模式（自动绑定 CPU 核数，如果发现离线任务比较慢，建议使用 yarn 模式，改变配置后重启 TaskManager 生效。更多配置可参考 master-urls。

配置更新#

TaskManager除了spark.default.conf，其他所有配置都需要重启生效。TaskManager是无状态的，只要不是正在访问中，重启不会有副作用。如果你只需要临时改变离线命令相关的配置，可以不用在TaskManager的配置中更新，可以使用临时spark配置的方式，只对单个离线任务进行配置调整。

spark.default.conf#

更多可选配置，可以写在 spark.default.conf 参数中，格式为 k1=v1;k2=v2。例如：

spark.default.conf=spark.port.maxRetries=32;foo=bar

spark.port.maxRetries：默认为 16，参考 Spark 配置。每个离线 job 都会绑定 Spark UI，对应一个 port。每次 port 都是从默认初始端口开始尝试绑定，retry 即绑定下一个端口 port+1，如果同时运行的 job 大于 spark.port.maxRetries，retry 次数也就大于 spark.port.maxRetries，job 就会启动失败。如果你需要更大的 job 并发，请配置更大的 spark.port.maxRetries，重启 TaskManager 生效。

临时Spark配置#

见客户端Spark配置文件，CLI支持临时更改Spark配置，不需要重启TaskManager。但此配置方式不可以改变spark.master等配置，只能改变spark.default.conf中的配置项。

DDL 边界——DEPLOY 语句#

通过 DEPLOY <deploy_name> <sql> 可以部署上线 SQL 方案，这个操作也会自动解析 SQL 帮助创建索引（可以通过 DESC <table_name> 查看索引详情），详情可参考 DEPLOY STATEMENT。

部署上线操作成功后，可能会创建索引，索引还会后台进行数据复制。所以，如果要保证DEPLOYMENT可以开始使用，需要查看后台复制Nameserver OP的情况，或DEPLOY时添加SYNC配置，详情见语法文档。

长窗口 SQL#

长窗口 SQL，即 DEPLOY 语句带有 OPTIONS(long_windows=...) 配置项，语法详情见长窗口。长窗口 SQL 的部署条件比较严格，必须保证 SQL 中使用的表没有在线数据。否则，即使部署和之前一致的 SQL，也会操作失败。

普通 SQL#

  • 如果部署之前已存在相关的索引，那么这一次部署操作不会创建索引。无论表中有无在线数据，DEPLOY 操作将成功。

    • 如果索引需要更新ttl，仅更新ttl value是可以成功的，但ttl更新生效需要2个gc interval，并且更新ttl前被淘汰的数据不会找回。如果ttl需要更新type，在<0.8.1的版本中将会失败，>=0.8.1的版本可以成功。

  • 如果部署时需要创建新的索引，而此时表中已有在线数据，版本<0.8.1将 DEPLOY 失败，>=0.8.1将在后台进行数据复制到新索引，需要等待一定时间。

对于旧版本解决方案有两种：

  • 严格保持先 DEPLOY 再导入在线数据，不要在表中有在线数据后做 DEPLOY。

  • CRATE INDEX 语句可以在创建新索引时，自动导入已存在的在线数据（已有索引里的数据）。如果一定需要在表已有在线数据的情况下 DEPLOY，可以先手动 CREATE INDEX 创建需要的索引（新索引就有数据了），再 DEPLOY（这时的 DEPLOY 不会创建新索引，计算时直接使用手动创建的那些索引）。

Note

如果你只能使用旧版本，如何知道应该创建哪些索引？

目前没有太直接的方法。推荐通过OpenMLDB SQL Emulator genddl获得建表语句，其中有创建的索引配置。 Java SDK 也支持，可以通过 SqlClusterExecutor.genDDL 获取需要创建的所有索引（静态方法，无需连接集群），但需要额外编码。而且 genDDL 是获得建表语句，所以需要手动转换为 CREATE INDEX。

DML 边界#

离线信息#

表的离线信息中存在两种path，一个是offline_path，一个是symbolic_paths。offline_path是离线数据的实际存储路径，symbolic_paths是离线数据的软链接路径。两种path都可以通过LOAD DATA来修改，symbolic_paths还可以通过ALTER语句修改。

offline_path和symbolic_paths的区别在于，offline_path是OpenMLDB集群所拥有的路径，如果实施硬拷贝，数据将写入此路径，而symbolic_paths是OpenMLDB集群外的路径，软拷贝将会在这个信息中增添一个路径。离线查询时，两个路径的数据都会被加载。两个路径使用同样的格式和读选项，不支持不同配置的路径。

因此，如果目前离线中存在offline_path，那么LOAD DATA只能修改symbolic_paths，如果目前离线中存在symbolic_paths，那么LOAD DATA可以修改offline_path和symbolic_paths。

errorifexists当表存在离线信息时就会报错。存在软链接时硬拷贝，或存在硬拷贝时软拷贝，都会报错。

LOAD DATA#

LOAD DATA 无论导入到在线或离线，都是离线 job。源数据的格式规则，离线在线没有区别。

推荐使用 HDFS 文件作为源数据，无论 TaskManager 是 local/yarn 模式，还是 TaskManager 在别的主机上运行，都可以导入。

如果源数据为本地文件，是否可以顺利导入需要考虑 TaskManager 模式和运行主机：

  • TaskManager 是 local 模式，只有将源数据放在 TaskManager 进程的主机上才能顺利导入。

  • TaskManager 是 yarn (client and cluster) 模式时，由于不知道运行容器是哪台主机，不可使用文件路径作为源数据地址。

ONLINE LOAD DATA#

在线导入还需要考虑并发问题，在线导入本质上是Spark中每个partition task启动一个Java SDK，每个SDK会创建一个与zk之间的session，如果并发过高，同时活跃的task过多，zk的session数量就会很大，可能超过其限制maxClientCnxns，具体问题现象见issue 3219。简单来说，请注意你的导入任务并发数和单个导入任务的并发数，如果你同时会进行多个导入任务，建议降低单个导入任务的并发数。

单个任务最大的并发数限制为spark.executor.instances * spark.executor.cores，请调整这两个配置。当spark.master=local时，调整driver的，而不是executor的。

DQL 边界#

根据执行模式的不同，支持的查询模式（即 SELECT 语句）也有所不同：

执行模式

查询语句

离线模式

批查询

在线模式

批查询（又称在线预览模式，仅支持部分 SQL）和请求查询（又称在线请求模式）

在线预览模式#

OpenMLDB CLI 中在线模式下执行 SQL，均为在线预览模式。在线预览模式支持有限，详情可参考 SELECT STATEMENT。

在线预览模式主要目的为预览查询结果。如果希望能运行复杂 SQL，请使用离线模式。如果希望查询完整的在线数据，建议使用数据导出工具查看（比如 SELECT INTO 命令 ）。如果在线表数据量过大，还可能触发数据截断，SELECT * FROM table 命令很可能会导致部分结果不被返回。

在线数据通常是分布式存储的，SELECT * FROM table 从各个 Tablet Server 中获取结果，但并不会做全局排序，且 Server 顺序有一定的随机性。所以每次执行 SELECT * FROM table 的结果不能保证数据顺序一致。

离线模式与在线请求模式#

在特征工程开发上线全流程中，主要使用离线模式和在线请求模式。

  • 离线模式的批查询：离线特征生成

  • 在线请求模式的请求查询：实时特征计算

两种模式虽然不同，但使用的是相同的 SQL 语句，且计算结果一致。但由于离线和在线使用两套执行引擎，功能尚未完全对齐，因此离线可执行的 SQL 不一定可以部署上线（在线请求模式可执行的 SQL 是离线可执行 SQL 的子集）。在实际开发中，需要在完成离线 SQL 开发后 DEPLOY，来测试 SQL 是否可上线。

离线命令同步模式#

所有离线命令都可以通过set @@sync_job=true;来设置同步模式，同步模式下，命令执行完毕后才会返回，否则会立即返回离线Job的Job info，需要通过SHOW JOB <id>来查询Job的执行状态。而同步模式下的返回值会根据命令的不同而不同：

  • DML，例如LOAD DATA等，以及DQL SELECT INTO，返回的是Job Info的ResultSet。它们和异步模式的结果没有区别，只是返回时间的区别，Job Info的ResultSet也可解析。

  • DQL的普通SELECT，在异步模式中返回Job Info，同步模式中则是返回查询结果，但目前支持不完善，详细解释见离线同步模式-select。其结果为csv格式，但不保证数据完整性，不建议将其作为可靠的查询结果使用。

    • CLI是交互模式，所以将结果直接打印。

    • SDK中，返回的是一行一列的ResultSet，将整个查询结果作为一个字符串返回。所以，不建议SDK使用同步模式查询，并处理其结果。

同步模式涉及超时问题，详情见调整配置。