记录头属性

记录头属性是记录头部中的属性,您可以根据需要在管道逻辑中使用它们。

某些阶段为特定目的创建记录头属性。例如,启用CDC的源端在sdc.operation.type记录头属性中包括CRUD操作类型。这使启用CRUD的目标端能够确定在处理记录时要使用的操作类型。同样,Hive Metadata处理器会生成记录头属性,某些目标端可以将其用作Hive漂移同步解决方案的一部分。

其他阶段在记录头属性中包含了与处理有关的信息以供一般使用。例如,如果您要基于该信息处理事件,则事件生成阶段会将事件类型包括在记录头属性中。多个源端为每条记录包含了如来源文件名、位置或分区等的信息。

您可以使用某些处理器来创建或更新记录头属性。例如,您可以使用Expression Evaluator来创建基于记录的写操作属性。

在记录头中包含属性不一定需要在管道中使用它们。例如,您可以在非CDC管道中使用启用CDC的Salesforce源端,而忽略自动生成的CDC记录头属性。

当将数据写入目标系统时,仅当使用Google Pub/Sub Publisher目标或将另一个目标使用SDC Record数据格式时,记录头属性才会与记录一起保留。若要在使用其他数据格式时保留信息,请使用Expression Evaluator将信息从记录头属性复制到记录字段。

使用头属性

您可以使用Expression Evaluator或任何脚本处理器来创建或更新记录头属性。例如,MongoDB目标端要求在记录头属性中指定CRUD操作。如果提供数据的源端不会自动生成该信息,则可以使用Expression Evaluator或脚本处理器来设置属性值。

记录头属性是字符串值。您可以在任何表达式中使用record:attribute函数,以在计算中包括属性值。

要点:记录头属性没有字段路径。在表达式中使用属性时,请仅使用属性名称,并用引号将其括起来,因为属性是字符串,如下所示:

 ${record:attribute('<attribute name>')}

例如,以下Expression Evaluator将Directory源端创建的文件和偏移记录头属性添加到记录中:

内部属性

随着记录在各个阶段之间移动,Data Collector会生成并更新一些只读内部记录头属性。可以查看这些属性以解决调试问题,但只能由Data Collector进行更新。

record:attribute函数不允许访问内部记录头属性。下表描述了内部记录头属性和可用于访问管道中该数据的函数:

内部记录头属性 描述 相关函数
stageCreator 创建记录的阶段的ID。 record:creator()
sourceId 记录的来源。可以根据来源类型包含不同的信息。 record:id()
stagePath 按阶段名称按顺序处理记录的阶段列表。 record:path()
trackingId 记录已通过管道的路线,从sourceId开始,然后列出处理记录的阶段。 不适用
previousTrackingId 记录进入当前阶段之前的记录的跟踪ID。 不适用
errorStage 产生错误的阶段。

仅在错误记录中。

record:errorStage()

errorStageLabel 阶段的用户定义名称。

仅在错误记录中。

record:errorStageLabel()
errorCode 错误代码。

仅在错误记录中。

record:errorCode()
errorJobId 启动管道的作业的ID。

仅在由Control Hub作业启动的管道的错误记录中。

不适用
errorMessage 错误消息。

仅在错误记录中。

record:errorMessage()

errorTimestamp 错误发生的时间。

仅在错误记录中。

record:errorTime()

errorStackTrace 与错误关联的堆栈跟踪。

仅在错误记录中。

不适用

生成头属性的阶段

下表列出了生成记录头属性以便启用特殊处理的阶段:

阶段 描述
启用CDC的源端 在sdc.operation.type标头属性中包含CRUD操作类型,并且在记录头属性中可以包含其他CRUD和CDC信息。有关更多信息,请参见启用CDC的源端。
处理Avro数据的源端和Data Parser处理器 在avroSchema记录头属性中包括Avro模式。
处理XML数据的源端 启用字段XPaths时,可以在xmlns记录头属性中包含名称空间。
产生事件的阶段 生成事件记录的记录头属性。有关事件记录头属性的详细信息,请参见阶段文档中的“事件记录”。
Amazon S3的源端 可以配置为在记录头属性中包括系统定义的和用户定义的对象元数据。
Amazon SQS Consumer源端 可以配置为在记录头属性中包括SQS消息属性。
Azure Data Lake Storage Gen1源端 在记录头属性中包含有关记录的原始文件的信息
Azure Data Lake Storage Gen2源端 在记录头属性中包含有关记录的原始文件的信息
Directory源端 在记录头属性中包含有关记录的原始文件的信息
File Tail源端 在记录头属性中包含有关记录的原始文件的信息

可以配置为对文件集使用标签属性。

Google Pub/Sub Subscriber源端 如果可用,则在记录头属性中包括用户定义的消息属性
Groovy Scrpiting源端 可以配置为创建记录头属性。
Hadoop FS源端 在记录头属性中包含有关文件和偏移量的信息。
Hadoop FS Standalone源端 在记录头属性中包含有关记录的原始文件的信息
HTTP Client源端 在记录头属性中包括响应头字段。
HTTP Server源端 在记录头属性中包含有关请求的URL和请求头字段的信息。
JavaScript Scripting源端 可以配置为创建记录头属性。
JDBC Multitable Consumer源端 在JDBC记录头属性中包括表和数据类型信息。
JDBC Query Consumer源端 可以配置为在JDBC记录头属性中包括表和数据类型信息 。
Jython Scripting源端 可以配置为创建记录头属性。
Kafka Consumer源端 在记录头属性中包含有关记录来源的信息。
Kafka Multitopic Consumer源端 在记录头属性中包含有关记录来源的信息。
MapR FS源端 在记录头属性中包含有关文件和偏移量的信息。
MapR FS Standalone源端 在记录头属性中包含有关记录的原始文件的信息
MapR Multitopic Streams Consumer源端 在记录头属性中包含有关记录来源的信息。
MapR Streams Consumer源端 在记录头属性中包含有关记录来源的信息。
MQTT Subscriber源端 在记录头属性中包含有关记录来源的信息。
Pulsar Consumer源端 在记录头属性的消息的属性字段中包含信息 。
RabbitMQ Consumer源端 在记录头属性中包含RabbitMQ属性。
REST Service源端 在记录头属性中包括有关URL和请求头字段的信息 。
Salesforce源端 在Salesforce头属性中包括有关记录来源的Salesforce信息。
SFTP / FTP / FTPS Client源端 在记录头属性中包含有关记录的原始文件的信息
Teradata Consumer源端 在JDBC记录头属性中包括表和数据类型信息。
Couchbase Lookup处理器 在记录头属性中包含有关查找文档状态的信息。
Expression Evaluator处理器 可以配置为创建或更新记录头属性。
Groovy Evaluator处理器

可以配置为创建或更新记录头属性。

Hive Metadata处理器 为数据记录生成记录头属性。这些属性可作为基于Hive的漂移同步解决方案的一部分用于基于记录的写入。

可以配置为将自定义头属性添加到元数据记录。

HTTP Client处理器 在记录头属性中包括响应头字段。
JavaScript Evaluator处理器 可以配置为创建或更新记录头属性。
Jython Evaluator处理器 可以配置为创建或更新记录头属性。
Schema Generator处理器 生成模式并将其写入用户定义的记录头属性。

基于记录的写操作的记录头属性

目标端可以使用记录头属性中的信息来写入数据。写入Avro数据的目标端可以在记录头中使用Avro模式。Hadoop FS和MapR FS目标端可以使用记录头属性来确定要写入的目录以及何时滚动文件,这是针对Hive的漂移同步解决方案的一部分。有关更多信息,请参见Hive漂移同步解决方案。

要使用记录头属性,请将目标端配置为使用头属性,并确保记录包含头属性。

Hive Metadata处理器自动为Hadoop FS和MapR FS生成记录头属性,以用作Hive漂移同步解决方案的一部分。对于所有其他目标,可以使用Expression Evaluator或脚本处理器来添加记录头属性。

您可以在目标中使用以下记录头属性:

所有Azure Data Lake Storage目标端以及Hadoop FS,Local FS和MapR FS目标端中的targetDirectory属性
targetDirectory记录头属性定义记录写入的目录。如果目录不存在,则目标端将创建目录。targetDirectory头属性替换目标端中的Directory Template属性。
使用targetDirectory提供目录时,为目标端配置的时间基准仅用于确定记录是否延迟。不使用时间基准来确定要创建的输出目录或将记录写入目录。
要使用targetDirectory标头属性,请在“Output”选项卡中选择“Directory in Header”
写入Avro数据的目标端中的avroSchema属性
avroSchema头属性定义记录的Avro模式。使用此头属性时,无法定义要在目标端中使用的Avro模式。
要使用avroSchema头属性,请在“Data Format选项卡上,选择Avro数据格式,然后为“Avro Schema Location属性选择“In Record Header
所有Azure Data Lake Storage目标端以及Hadoop FS,Local FS和MapR FS目标端中的roll属性
如果记录头中包含roll属性,则会触发该文件的滚动。
您可以定义滚动头属性的名称。当您使用Hive Metadata处理器生成滚动头属性时,请使用默认的“roll”属性名称。使用Expression Evaluator时,请使用在处理器中定义的roll属性的名称。
要使用卷标头属性,请在“Output选项卡上,选择“Use Roll Attribute并定义该属性的名称。

生成基于记录的写操作的属性

您可以使用Hive Metadata处理器,Expression Evaluator或脚本处理器为基于记录的写入生成记录头属性。Hive Metadata处理器自动为Hadoop FS和MapR FS生成记录头属性,以用作Hive漂移同步解决方案的一部分。对于所有其他目标端,可以使用Expression Evaluator或脚本处理器来添加记录头属性。

要使用Expression Evaluator或脚本处理器,必须生成目标端期望的记录头属性。使用以下准则来生成记录头属性:

生成目标目录
使用Expression Evaluator或脚本处理器生成目标目录时,请注意以下详细信息:
  • 目标端希望该目录位于名为“targetDirectory”的头属性中。
  • 目标端使用的目录与targetDirectory头属性中所写的完全相同。与目录模板不同,targetDirectory属性中指定的目录不应包含任何需要评估的组件,例如运行时参数,变量或运行时属性。

  • 当您定义计算结果为目录的表达式时,可以使用任何有效组件,包括计算记录中数据的表达式。

例如,您要基于运行管道的Data Collector以及发生交易的区域和商店ID将记录写入不同的目录。您可以设置一个名为DIR的运行时资源,该资源定义目录的基础,并为每个运行管道的Data Collector定义DIR 。然后,可以在Expression Evaluator中使用以下表达式来定义targetDirectory属性:

${runtime:conf('DIR')/transactions/${record.value('/region')}/${record.value('/storeID')}
生成Avro模式
使用Expression Evaluator或脚本处理器生成Avro模式时,请注意以下详细信息:

  • 目标端期望在名为“avroSchema”的头属性中使用Avro模式。
  • 使用标准的Avro模式格式,例如:
    {"type":"record","name":"table_name","namespace":"database_name",
    "fields":[{"name":"int_val","type":["null","int"],"default":null},
    {"name":"str_val","type":["null","string"],"default":null}]}
  • 数据库名称和表名称必须包含在Avro模式中。
提示:您可以使用Avro模式生成器来帮助生成Avro模式。
产生roll属性
使用Expression Evaluator或脚本处理器生成roll属性时,请注意以下详细信息:

  • 使用任何名称作为属性,并在目标端中指定属性名称。
  • 配置一个定义何时滚动文件的表达式。

要在Expression Evaluator中定义这些记录头属性,请执行以下步骤:

  1. 在“Expression Evaluator” 的“Expressions选项卡上,指定“Header Attribute名称。

    要生成目标目录,请使用targetDirectory

    要生成Avro模式,请使用avroSchema

    您可以为滚动指示器头属性使用任何名称。

  2. 对于“Header Attribute Expression,定义一个表达式,该表达式求值您希望目标使用的信息。

有关使用脚本处理器生成记录头属性的信息,请参阅脚本处理器文档。

在数据预览中查看属性

您可以使用数据预览来查看与管道中任何给定点上的记录关联的记录头属性。若要查看记录头属性,请启用“Show Record/Field Header”预览属性。

例如,下图显示了由Directory源在数据预览中生成的记录。

“Record Header”列表在管道的此点显示记录中的只读内部属性集。 “values”下的头属性是由Directory源端创建的属性。