GenerateTableFetch Processor

类型全限定名：cn.org.acal.lynxus.processors.standard.GenerateTableFetch

所属 Bundle：cn.org.acal.lynxus:lynxus-standard-nar:2.11.8

描述

生成 SQL 查询语句，从表中分页获取数据行。分区大小属性与表的行数一起，决定分页的大小和数量以及生成的 FlowFile。此外，通过设置最大值列可以实现增量获取，这使处理器能够跟踪列的最大值，从而仅获取列值超过已观察最大值的行。此处理器仅应在主节点上运行。此处理器可以接受传入连接；处理器的行为取决于是否提供了传入连接： - 如果未指定传入连接，处理器将按照指定的调度计划生成 SQL 查询。支持表达式语言，但不可用 FlowFile 属性。不过属性将使用环境/系统属性进行计算。 - 如果指定了传入连接但没有 FlowFile 可供处理器任务使用，则不执行任何操作。 - 如果指定了传入连接且有 FlowFile 可供处理器任务使用，则 FlowFile 的属性可用于表达式语言，如表名等字段。但是，最大值列和返回列字段必须为空或引用每个指定表中可用的列。

属性

下表中，加粗的属性为必填项；其余为可选项。表格同时标注默认值、是否支持表达式语言，以及是否为敏感属性（值会被加密）。

名称	默认值	可选值	描述
Database Connection Pooling Service		控制器服务 API： `DBCPService` cn.org.acal.lynxus-lynxus-standard-services-api-nar-2.11.8	用于获取数据库连接的Controller Service。
数据库类型	`Generic`	Database Dialect Service — 需要为 SQL 语句配置 Database Dialect Service Generic — 生成 ANSI SQL Oracle — 生成符合 Oracle 规范的 SQL Oracle 12+ — 生成符合 Oracle 规范的 SQL（12 或更高版本） MS SQL 2012+ — 生成兼容 MS SQL 的 SQL（2012 或更高版本） MS SQL 2008 — 生成兼容 MS SQL 的 SQL（2008 版本） MySQL — 生成兼容 MySQL 的 SQL PostgreSQL — 生成兼容 PostgreSQL 的 SQL Phoenix — 生成符合 Phoenix 规范的 SQL	用于生成特定于服务或供应商的语句的数据库类型。通用类型支持大多数情况，但选择特定类型可以启用优化处理或额外功能。
Database Dialect Service		控制器服务 API： `DatabaseDialectService` cn.org.acal.lynxus-lynxus-standard-services-api-nar-2.11.8	数据库方言服务，用于生成特定于特定服务或供应商的语句。
Table Name			需要查询的数据库表名。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Columns to Return			逗号分隔的列名列表，用于查询中。如果您的数据库需要对名称进行特殊处理（例如引号），则每个名称应包含此类处理。如果未提供列名，将返回指定表中的所有列。注意：对于给定的表，使用一致的列名对于增量获取正常工作非常重要。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Maximum-value Columns			逗号分隔的列名列表。处理器将跟踪自处理器启动以来返回的每列的最大值。使用多列意味着列列表具有顺序关系，每列的值预期比前一列的值增长更慢。因此，使用多列意味着列的分层结构，通常用于分区表。此处理器可用于仅检索自上次检索以来添加/更新的行。请注意，某些 JDBC 类型（如 bit/boolean）不利于维护最大值，因此不应在此属性中列出这些类型的列，否则会在处理过程中导致错误。如果未提供列，将考虑表中的所有行，这可能会影响性能。注意：对于给定的表，使用一致的最大值列名对于增量获取正常工作非常重要。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Max Wait Time	`0 seconds`		正在运行的 SQL 查询允许的最大时间，零表示没有限制。最大时间小于 1 秒将等于零。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Partition Size	`10000`		每个生成的 SQL 语句要获取的结果行数。表中的总行数除以分区大小即为生成的 SQL 语句（即 FlowFile）数量。值为零表示生成单个 FlowFile，其 SQL 语句将获取表中的所有行。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Column for Value Partitioning			指定用于值分区的列名。默认行为是使用结果集上的行号进行分页，通过偏移量/限制策略从数据库获取数据。但在某些数据库中，在特定条件下使用列值本身来定义分页可能更高效。此属性仅应在默认查询性能不佳、没有最大值列或只有一个可强制转换为长整数的最大值列（即非日期或时间戳类型），且列值均匀分布不稀疏的情况下使用，以获得最佳性能。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Additional WHERE Clause			构建 SQL 查询时要在 WHERE 条件中添加的自定义子句。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Custom ORDER BY Column			指定用于在未提供最大值列且启用分区时对结果进行排序的列名。如果设置了最大值列或分区大小为 0，则忽略此属性。注意：如果既未设置最大值列也未设置自定义排序列，则根据数据库/驱动程序的不同，处理器可能会报告错误和/或生成的 SQL 可能导致缺失和/或重复的行。这是因为没有显式排序时，获取每个分区使用的是任意排序。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Output Empty FlowFile on Zero Results	`false`	true false	根据指定的属性，处理器的执行可能不会生成任何 SQL 语句。当此属性为 true 时，将生成一个空的 FlowFile（如果存在传入 FlowFile 则继承其父 FlowFile）并传输到 'success' 关系。当此属性为 false 时，不会生成任何输出 FlowFile。

动态属性

动态属性允许用户自定义属性的名称与值。

名称	值	描述
initial.maxvalue.<max_value_column>	指定列的初始最大值	指定最大值列的初始最大值。属性应以 `initial.maxvalue.<max_value_column>` 的格式添加。此值仅在首次访问表时使用（当指定了最大值列时）。对于传入连接，该值仅在 FlowFile 中指定的每个表首次使用时使用。

关系 (Relationships)

名称	描述	自动终止
`failure`	此关系仅在 SQL 查询执行（使用传入的 FlowFile）失败时使用。传入的 FlowFile 将被处罚并路由到此关系。如果未指定传入连接，则此关系未使用。	否
`success`	已成功从 SQL 查询结果集创建 FlowFile。	否

写入的 FlowFile 属性

名称	描述
`generatetablefetch.sql.error`	如果处理器有传入连接，且处理传入的 FlowFile 导致 SQL 异常，FlowFile 将被路由到 failure，此属性设置为异常消息。
`generatetablefetch.tableName`	需要查询的数据库表名。
`generatetablefetch.columnNames`	查询中使用的以逗号分隔的列名称列表。
`generatetablefetch.whereClause`	查询中使用Where子句来获取预期的行。
`generatetablefetch.maxColumnNames`	列名的逗号分隔列表，用于跟踪自处理器开始运行以来返回的数据。
`generatetablefetch.limit`	SQL 语句要获取的结果行数。
`generatetablefetch.offset`	用于检索相应分区的偏移量。
`fragment.identifier`	从同一查询结果集生成的所有 FlowFile 的 fragment.identifier 属性将具有相同的值。然后可以使用此值来关联结果。
`fragment.count`	这是单个结果集产生的 FlowFile 总数。可以与 fragment.identifier 属性结合使用，以了解有多少 FlowFile 属于同一传入结果集。
`fragment.index`	这是此 FlowFile 在从同一执行生成的传出 FlowFile 列表中的位置。可以与 fragment.identifier 属性结合使用，以了解哪些 FlowFile 来自同一执行以及 FlowFile 的产生顺序

状态管理

作用域	描述
CLUSTER	对指定表执行查询后，将保留指定列的最大值以供将来执行查询时使用。这允许处理器仅获取最大值大于保留值的记录。这可用于增量获取、获取新添加的行等。要清除最大值，请按照状态管理文档清除处理器的状态

受限 (Restricted)

该组件不受限。

输入要求

该组件允许有传入连接。

另请参阅

详细说明

GenerateTableFetch

GenerateTableFetch 利用自身的属性和指定的数据库连接，生成包含 SQL 语句的 FlowFile，这些 SQL 可以用来从表中按"页"（也称"分区"）获取数据。GenerateTableFetch 会向数据库执行查询以确定当前的行数和最大值；如果指定了 Maximum Value Columns，还会统计 Maximum Value Columns 的值大于 GenerateTableFetch 上次观测到的值的行数。这样就可以增量获取"新"行，而不必每次都生成获取整张表的 SQL。如果没有设置 Maximum Value Columns，该 Processor 每次都会生成获取整张表的 SQL。

为了生成分页/分区获取数据的 SQL，GenerateTableFetch 默认会生成按 Maximum Value Columns （如果存在）排序的 SQL，并利用结果集的行号来确定每一页。例如，如果 Maximum Value Column 是整型的 "id"，分区大小为 10，那么第一页的 SQL 可能是 "SELECT * FROM myTable LIMIT 10"，第二页可能是 "SELECT * FROM myTable OFFSET 10 LIMIT 10"，以此类推。

根据数据库类型、行数等不同，对数据排序可能是一个昂贵的操作。作为替代方案，可以使用 Column for Value Partitioning 属性指定一个列，用该列的值来确定分页。设置后， GenerateTableFetch 会确定该列的最小值和最大值，并以最小值作为初始偏移量。获取每一页的 SQL 基于这个初始偏移量和值的总差值（即最大值减最小值）除以页大小来计算。例如，如果用列 "id" 做值分区，该列的取值范围是 100 到 200，页大小为 10，那么获取第一页的 SQL 可能是 "SELECT * FROM myTable WHERE id >= 100 AND id < 110"，第二页可能是 "SELECT * FROM myTable WHERE id >= 110 AND id < 120"，以此类推。

为了获得最佳性能，Column for Value Partitioning 必须设置为类型可转换为长整型（即不是 date 或 timestamp）的列，并且该列的值应当分布均匀、不稀疏。作为上述示例的反例，考虑一个 "id" 列的取值为 100、2000 和 30000 的情况。如果 Partition Size 是 100，列值相对稀疏，那么"第二页"（见上述示例）的 SQL 将返回零行，直到查询中的值变为 "id >= 2000" 之前的每一页都是如此。另一个反例是取值分布不均匀的情况。考虑一个 "id" 列的取值为 100、200、201、202 ... 299，那么第一页的 SQL（见上述示例）将返回一行（id = 100），而第二页将返回 100 行（200 ... 299）。这会导致下游处理时间不稳定，因为各页包含的行数可能差异很大。基于这些原因，建议使用足够稠密（不稀疏）且分布相当均匀的列作为 Column for Value Partitioning。

GenerateTableFetch