ExecuteSQLRecord

ExecuteSQLRecord Processor

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

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

描述

执行提供的 SQL 选择查询。查询结果将转换为Record Writer指定的格式。使用流式传输，因此支持任意大的结果集。该处理器可以使用标准调度方法安排在计时器或 cron 表达式上运行，也可以由传入的 FlowFile 触发。如果它是由传入的 FlowFile 触发的，则在评估选择查询时该 FlowFile 的属性将可用，并且查询可以使用 ? 转义参数。在这种情况下，要使用的参数必须作为 FlowFile 属性存在，并具有命名约定 sql.args.N.type 和 sql.args.N.value，其中 N 是正整数。 sql.args.N.type 应该是一个指示 JDBC 类型的数字。 FlowFile 的内容预计为 UTF-8 格式。 FlowFile 属性“executesql.row.count”指示选择了多少行。

属性

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

名称	默认值	可选值	描述
Database Connection Pooling Service		控制器服务 API： `DBCPService` cn.org.acal.lynxus-lynxus-standard-services-api-nar-2.11.8	用于获取数据库连接的Controller Service
SQL Pre-Query			在主 SQL 查询执行之前执行的以分号分隔的查询列表。例如，在主查询之前设置会话属性。可以通过使用反斜杠转义 ('\;') 在语句本身中包含分号。如果没有错误，这些查询的结果/输出将被抑制。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
SQL Query			要执行的 SQL 查询。查询可以为空、常量值，或使用表达式语言基于属性构建。如果指定了此属性，无论传入 FlowFile 的内容如何，都将使用该属性。如果此属性为空，则传入 FlowFile 的内容应包含有效的 SQL 查询，由处理器发送到数据库执行。请注意，表达式语言不会对 FlowFile 内容进行求值。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
SQL Post-Query			在主 SQL 查询执行之后执行的以分号分隔的查询列表。例如，在主查询之后设置会话属性。可以通过使用反斜杠转义 ('\;') 在语句本身中包含分号。如果没有错误，这些查询的结果/输出将被抑制。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Max Wait Time	`0 seconds`		SQL select 查询允许运行的最大时间，零表示无限制。最大时间小于 1 秒时将等于零。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Record Writer		控制器服务 API： `RecordSetWriterFactory` cn.org.acal.lynxus-lynxus-standard-services-api-nar-2.11.8	指定用于将结果写入 FlowFile 的控制器服务。Record Writer 可以使用 Inherit Schema 来模拟推断的 Schema 行为，即不需要在 Writer 中定义显式 Schema，将使用与从列类型推断 Schema 相同的逻辑来提供。
Normalize Table/Column Names	`false`	true false	是否更改列名称中的字符。例如，冒号和句点将更改为下划线。
Use Avro Logical Types	`false`	true false	是否为 DECIMAL/NUMBER、DATE、TIME 和 TIMESTAMP 列使用 Avro 逻辑类型。如果禁用，则写为字符串。如果启用，则使用逻辑类型并写为其底层类型，具体来说，DECIMAL/NUMBER 写为逻辑 'decimal'：写为字节并带有附加的精度和小数位数元数据，DATE 写为逻辑 'date-millis'：写为自 Unix 纪元（1970-01-01）以来的天数（int），TIME 写为逻辑 'time-millis'：写为自 Unix 纪元以来的毫秒数（int），TIMESTAMP 写为逻辑 'timestamp-millis'：写为自 Unix 纪元以来的毫秒数（long）。如果写入的 Avro 记录的读取器也了解这些逻辑类型，则可以根据读取器实现以更丰富的上下文反序列化这些值。
Default Decimal Precision	`10`		当 DECIMAL/NUMBER 值作为 'decimal' Avro 逻辑类型写入时，需要特定的 'precision'（表示可用数字的位数）。通常，精度由列数据类型定义或数据库引擎默认值决定。但是，某些数据库引擎可能返回未定义的精度（0）。'默认小数精度' 用于写入这些未定义精度的数字。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Default Decimal Scale	`0`		当 DECIMAL/NUMBER 值作为 'decimal' Avro 逻辑类型写入时，需要特定的 'scale'（表示可用小数位数）。通常，小数位数由列数据类型定义或数据库引擎默认值决定。但是，当返回未定义的精度（0）时，某些数据库引擎的小数位数也可能不确定。'默认小数位数' 用于写入这些未定义的数字。如果值的小数位超过指定的小数位数，则值将被四舍五入，例如，小数位数为 0 时 1.53 变为 2，小数位数为 1 时 1.5 保持不变。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Max Rows Per FlowFile	`0`		单个 FlowFile 中将包含的最大结果行数。这允许您将非常大的结果集拆分为多个 FlowFile。如果指定的值为零，则所有行在单个 FlowFile 中返回。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Output Batch Size	`0`		在提交处理会话之前排队的输出 FlowFile 数量。设置为零时，将在所有结果集行处理完毕且输出 FlowFile 准备好传输到下游关系时提交会话。对于大型结果集，这可能导致在处理器执行结束时大量 FlowFile 突然传输。如果设置了此属性，则当指定数量的 FlowFile 准备好传输时，将提交会话，从而将 FlowFile 释放到下游关系。注意：设置此属性时，不会在 FlowFile 上设置 fragment.count 属性。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Fetch Size	`0`		每次从结果集中获取的结果行数。这是对数据库驱动的提示，可能不会被遵守和/或不完全准确。如果指定的值为零，则忽略该提示。支持表达式语言：是（使用 FlowFile 属性与环境/系统变量求值）
Set Auto Commit	`true`	true false	启用或禁用数据库连接的自动提交功能。默认值为 'true'。默认值适用于大多数 JDBC 驱动，且此功能在大多数情况下没有任何影响，因为此处理器用于读取数据。但是，对于某些 JDBC 驱动（如 PostgreSQL 驱动），需要禁用自动提交功能以限制每次获取的结果行数。启用自动提交时，PostgreSQL 驱动会一次性将整个结果集加载到内存中。这可能导致在执行获取大数据集的查询时消耗大量内存。有关 PostgreSQL 驱动此行为的更多详情，请参阅 https://jdbc.postgresql.org//documentation/head/query.html。

动态属性

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

名称	值	描述
sql.args.N.type	要提供的 SQL 类型参数	传入的 FlowFile 应为参数化 SQL 语句。每个参数的类型指定为表示参数 JDBC 类型的整数。接受的类型有：[LONGNVARCHAR: -16]、[BIT: -7]、[BOOLEAN: 16]、[TINYINT: -6]、[BIGINT: -5]、[LONGVARBINARY: -4]、[VARBINARY: -3]、[BINARY: -2]、[LONGVARCHAR: -1]、[CHAR: 1]、[NUMERIC: 2]、[DECIMAL: 3]、[INTEGER: 4]、[SMALLINT: 5]、[FLOAT: 6]、[REAL: 7]、[DOUBLE: 8]、[VARCHAR: 12]、[DATE: 91]、[TIME: 92]、[TIMESTAMP: 93]、[VARCHAR: 12]、[CLOB: 2005]、[NCLOB: 2011]
sql.args.N.value	要提供的参数	传入的 FlowFile 应为参数化 SQL 语句。参数的值指定为 sql.args.1.value、sql.args.2.value、sql.args.3.value 等。sql.args.1.value 参数的类型由 sql.args.1.type 属性指定。
sql.args.N.format	要提供的 SQL 格式参数	此属性始终是可选的，但默认选项可能并不总是适用于您的数据。传入的 FlowFile 应为参数化 SQL 语句。在某些情况下需要指定格式选项，目前这仅适用于二进制数据类型、日期、时间和时间戳。二进制数据类型（默认为 'ascii'）- ascii：属性值中的每个字符串字符代表单个字节，这是 Avro 处理器提供的格式。base64：字符串是可以解码为字节的 Base64 编码字符串。hex：字符串是十六进制编码的，所有字母大写且开头没有 '0x'。日期/时间/时间戳 - 日期、时间和时间戳格式都支持自定义格式或命名格式（'yyyy-MM-dd'、'ISO_OFFSET_DATE_TIME'），如 java.time.format.DateTimeFormatter 所指定。如果未指定，则 long 值输入预期为 unix 纪元（从 1970/1/1 起的毫秒数），或 Date 的 'yyyy-MM-dd' 格式字符串、Time 的 'HH:mm:ss.SSS' 格式（某些数据库引擎如 Derby 或 MySQL 不支持毫秒并将截断毫秒）、Timestamp 使用 'yyyy-MM-dd HH:mm:ss.SSS' 格式。

关系 (Relationships)

名称	描述	自动终止
`failure`	SQL 查询执行失败。传入的 FlowFile 将受到惩罚并路由到此关系	否
`success`	已成功从 SQL 查询结果集创建 FlowFile。	否

读取的 FlowFile 属性

名称	描述
`sql.args.N.type`	传入的 FlowFile 应为参数化 SQL 语句。每个参数的类型指定为表示参数 JDBC 类型的整数。接受的类型有：[LONGNVARCHAR: -16]、[BIT: -7]、[BOOLEAN: 16]、[TINYINT: -6]、[BIGINT: -5]、[LONGVARBINARY: -4]、[VARBINARY: -3]、[BINARY: -2]、[LONGVARCHAR: -1]、[CHAR: 1]、[NUMERIC: 2]、[DECIMAL: 3]、[INTEGER: 4]、[SMALLINT: 5]、[FLOAT: 6]、[REAL: 7]、[DOUBLE: 8]、[VARCHAR: 12]、[DATE: 91]、[TIME: 92]、[TIMESTAMP: 93]、[VARCHAR: 12]、[CLOB: 2005]、[NCLOB: 2011]
`sql.args.N.value`	传入的 FlowFile 应为参数化 SQL 语句。参数的值指定为 sql.args.1.value、sql.args.2.value、sql.args.3.value 等。sql.args.1.value 参数的类型由 sql.args.1.type 属性指定。
`sql.args.N.format`	此属性始终是可选的，但默认选项可能并不总是适用于您的数据。传入的 FlowFile 应为参数化 SQL 语句。在某些情况下需要指定格式选项，目前这仅适用于二进制数据类型、日期、时间和时间戳。二进制数据类型（默认为 'ascii'）- ascii：属性值中的每个字符串字符代表单个字节，这是 Avro 处理器提供的格式。base64：字符串是可以解码为字节的 Base64 编码字符串。hex：字符串是十六进制编码的，所有字母大写且开头没有 '0x'。日期/时间/时间戳 - 日期、时间和时间戳格式都支持自定义格式或命名格式（'yyyy-MM-dd'、'ISO_OFFSET_DATE_TIME'），如 java.time.format.DateTimeFormatter 所指定。如果未指定，则 long 值输入预期为 unix 纪元（从 1970/1/1 起的毫秒数），或 Date 的 'yyyy-MM-dd' 格式字符串、Time 的 'HH:mm:ss.SSS' 格式（某些数据库引擎如 Derby 或 MySQL 不支持毫秒并将截断毫秒）、Timestamp 使用 'yyyy-MM-dd HH:mm:ss.SSS' 格式。

写入的 FlowFile 属性

名称	描述
`executesql.row.count`	包含选择查询中返回的行数
`executesql.query.duration`	查询执行时间和获取时间的总持续时间（以毫秒为单位）
`executesql.query.executiontime`	查询执行时间的持续时间（以毫秒为单位）
`executesql.query.fetchtime`	结果集获取时间的持续时间（以毫秒为单位）
`executesql.resultset.index`	假设返回了多个结果集，此为结果集的从零开始的索引。
`executesql.error.message`	如果处理传入的 FlowFile 导致异常，FlowFile 路由到 failure，此属性设置为异常消息。
`fragment.identifier`	如果设置了'每个 FlowFile 的最大行数'，则来自同一查询结果集的所有 FlowFile 的 fragment.identifier 属性将具有相同的值。然后可以使用此值来关联结果。
`fragment.count`	这是单个结果集产生的 FlowFile 总数。可以与 fragment.identifier 属性结合使用，以了解有多少 FlowFile 属于同一传入结果集。
`fragment.index`	如果设置了'每个 FlowFile 的最大行数'，则此 FlowFile 在从同一结果集 FlowFile 派生的传出 FlowFile 列表中的位置。可以与 fragment.identifier 属性结合使用，以了解哪些 FlowFile 来自同一查询结果集以及 FlowFile 的产生顺序
`input.flowfile.uuid`	如果处理器有传入连接，传出的 FlowFile 将此属性设置为传入 FlowFile 的 UUID 值。如果没有传入连接，则不添加此属性。
`mime.type`	将 mime.type 属性设置为Record Writer指定的 MIME 类型。
`record.count`	Record Writer输出的记录数。

状态管理

该组件不存储状态。

受限 (Restricted)

该组件不受限。

输入要求

该组件允许有传入连接。