ImportOptions

事件流的导入选项

自 R2022b 起

全页展开

此对象需要 Streaming Data Framework for MATLAB^® Production Server™。

说明

ImportOptions 对象指定 MATLAB 如何从事件流导入表格数据。该对象包含控制数据导入过程的属性，包括处理错误和缺失数据。

创建对象

您可以使用 detectImportOptions 函数或 eventStreamImportOptions 函数创建 ImportOptions 对象。首选方法是使用 detectImportOptions。

使用 detectImportOptions 根据 stream 指定的事件流的内容检测并填充导入属性。
```
opts = detectImportOptions(stream)
```
使用 eventStreamImportOptions 通过将导入选项指定为名称-值参量来创建导入属性。
```
opts = eventStreamImportOptions(Name1=Value1,...,NameN=ValueN)
```

属性

全部展开

`SelectedVariableNames` — 要导入的变量子集
字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

要导入的变量子集，指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

SelectedVariableNames 必须是 VariableNames 属性中包含的名称的子集。默认情况下，SelectedVariableNames 包含来自 VariableNames 属性的所有变量名称，这意味着所有变量都被导入。

使用 SelectedVariableNames 属性仅导入感兴趣的变量。使用 SelectedVariableNames 属性指定变量的子集，并使用 readtimetable 函数仅导入该子集。

示例: 当您使用 opts.SelectedVariableNames = "x" 将事件流数据导入时间表时，x 仅从事件流导入变量 readtimetable。

数据类型: char | string

`VariableNames` — 变量名称
字符向量元胞数组 | 字符串数组

变量名称，指定为字符向量元胞数组或字符串数组。VariableNames 属性包含将变量从事件流导入时间表时使用的名称。

这些变量名必须存在于流中。如果修改的变量名不在流中，则导入操作失败。

示例: io.VariableNames 返回事件流中的当前变量名称。

示例: io.VariableNames(3) = {'Mass'} 将第三个变量的名称更改为 Mass。

数据类型: cell | string

`VariableTypes` — 变量的数据类型
字符向量元胞数组 | 字符串数组

变量的数据类型，指定为包含一组有效数据类型名称的字符向量元胞数组或字符串数组。VariableTypes 属性指定将变量从事件流导入时间表时要使用的数据类型。

导入操作尝试将流中的值转换为这些类型。仅当原始类型之间的转换已知且无歧义时，此操作才会成功，例如：

整数到字符串的转换
目标类型的构造函数可以接受流中该类型的变量的转换

要更新 VariableTypes 属性，请使用 setvartype 函数。

示例: io.VariableTypes 返回流变量导入 MATLAB 时间表后的数据类型，即对应时间表列的类型。

示例: io = setvartype(io,"vMotor","int32") 将 vMotor 变量的数据类型更改为 int32。

数据类型: cell | string

`KeyVariable` — 键变量名称
`key` (默认) | 字符串标量 | 字符向量

事件流中键变量的名称，指定为字符串标量或字符向量。默认值为 key。

数据类型: string | char

对象函数

setvartype 设置用于将变量导入和导出到流的数据类型

示例

全部折叠

从事件流数据创建导入选项

假设您有一个在网络地址 kafka.host.com:9092 上运行的 Kafka^® 服务器，该服务器有一个主题 Triangles，其 JSON 编码事件值为 '{"triangle":{"x":"3","y":"4","z":"5"}}'。每个事件值包含一个变量 "triangle"，它是一个边长为 "x"、"y"、"z" 的结构体。边长是整数，但被编码为字符串。readtimetable 为此变量创建一个 triangle 表列，并将列值设置为此结构体：

triangle = 

  struct with fields:

    x: "3"
    y: "4"
    z: "5"

ImportOptions 使您能够更改导入结构体中的值的类型并选择要导入的字段。

创建一个连接到 KafkaStream 主题的 Triangles 对象。

ks = kafkaStream("kafka.host.com",9092,"Triangles");

从 Kafka 流对象创建一个 ImportOptions 对象。每条边的长度的数据类型为 string。

opts = detectImportOptions(ks)

opts = 

  ImportOptions with properties:

            VariableNames: ["triangle/x"    "triangle/y"    "triangle/z"]
            VariableTypes: ["string"    "string"    "string"]
              KeyVariable: "key"
    SelectedVariableNames: ["triangle/x"    "triangle/y"    "triangle/z"]

要对导入的数据执行数学运算，请将变量的数据类型更新为 double。由于边长变量嵌套在 "triangle" 中，因此使用正斜杠 ("/") 指定这些变量的路径。

opts = setvartype(opts, ["triangle/x", "triangle/y", "triangle/z"], "double")

opts = 

  ImportOptions with properties:

            VariableNames: ["triangle/x"    "triangle/y"    "triangle/z"]
            VariableTypes: ["double"    "double"    "double"]
              KeyVariable: "key"
    SelectedVariableNames: ["triangle/x"    "triangle/y"    "triangle/z"]

更新 ImportOptions 对象的 KafkaStream 属性。

ks.ImportOptions = opts

ks = 

  KafkaStream with properties:

                  Topic: "Triangles"
                  Group: "85c42e39-695d-467a-86f0-f0095792e7de"
                  Order: EventTime
                   Host: "kafka.host.com"
                   Port: 9092
      ConnectionTimeout: 30
         RequestTimeout: 61
          ImportOptions: "Import to MATLAB types"
          ExportOptions: "Source: function eventSchema"
          PublishSchema: "true"
             WindowSize: 50
            KeyVariable: "key"
            KeyEncoding: "utf16"
                KeyType: "text"
           KeyByteOrder: "BigEndian"
           BodyEncoding: "utf8"
             BodyFormat: "JSON"
              ReadLimit: "Size"
    TimestampResolution: "Milliseconds"

导入三角形时，readtimetable 将边长转换为 double 值。

tt = readtimetable(ks);
tt(1,:).triangle

ans = 

  struct with fields:

    x: 3
    y: 4
    z: 5

通过指定导入变量名称和类型创建导入选项

通过指定导入期间要使用的变量名称及其数据类型，创建将数据从事件流导入 MATLAB 的模式。

names = ["x","symbol"];
types = ["double","string"];

使用此数据导入模式构造一个 ImportOptions 对象。

opts = eventStreamImportOptions(VariableNames=names,VariableTypes=types)

opts = 

  ImportOptions with properties:

            VariableNames: ["x"    "symbol"]
            VariableTypes: ["double"    "string"]
              KeyVariable: [0×0 string]
    SelectedVariableNames: ["x"    "symbol"]

创建 KafkaStream 对象时应用导入选项。

ks = kafkaStream("kafka.host.com",9092,"Your_Kafka_Topic",ImportOptions=opts);

导入数据。"Your_Kafka_Topic" 主题必须包含恰好两个变量的事件，即 x 和 symbol。此外，这些变量的类型必须分别可以转换为双精度型和字符串型。否则，readtimetable 会抛出错误。

tt = readtimetable(ks);

版本历史记录

在 R2022b 中推出

另请参阅

detectImportOptions | setvartype | readtimetable