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 函数仅导入该子集。

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

数据类型: 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 使您能够更改导入结构体中的值的类型并选择要导入的字段。

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

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"]

更新 KafkaStream 对象的 ImportOptions 属性。

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