bag_unpack 插件bag_unpack plugin

bag_unpack 插件通过将每个属性包顶级槽视为列来解压缩 dynamic 类型的单个列。The bag_unpack plugin unpacks a single column of type dynamic, by treating each property bag top-level slot as a column.

T | evaluate bag_unpack(col1)

语法Syntax

T | evaluate bag_unpack( Column [, OutputColumnPrefix ] [, columnsConflict ] [, ignoredProperties ] )T | evaluate bag_unpack( Column [, OutputColumnPrefix ] [, columnsConflict ] [, ignoredProperties ] )

参数Arguments

  • T:要解压缩其列 Column 的表格输入。T: The tabular input whose column Column is to be unpacked.
  • Column:要解压缩的列 T。Column: The column of T to unpack. 必须是类型 dynamicMust be of type dynamic.
  • OutputColumnPrefix:添加到插件生成的所有列的常见前缀。OutputColumnPrefix: A common prefix to add to all columns produced by the plugin. 该参数可选。This argument is optional.
  • columnsConflict:有关列冲突解决的指导。columnsConflict: A direction for column conflict resolution. 该参数可选。This argument is optional. 如果提供了参数,该参数应为与以下值之一匹配的字符串文本:When argument is provided, it's expected to be a string literal matching one of the following values:
    • error - 查询生成错误(默认值)error - Query produces an error (default)
    • replace_source -源列被替换replace_source - Source column is replaced
    • keep_source - 源列被保留keep_source - Source column is kept
  • ignoredProperties:要忽略包属性的可选集。ignoredProperties: Optional set of bag properties to be ignored. 如果提供了参数,该参数应为具有一个或多个字符串文本的 dynamic 数组的常量。When argument is provided, it's expected to be a constant of dynamic array with one or more string literals.

返回Returns

bag_unpack 插件返回一个表,其中包含的记录与其表格输入 (T) 的数量相同。The bag_unpack plugin returns a table with as many records as its tabular input (T). 该表格的架构与表格输入的架构相同,但有以下修改:The schema of the table is the same as the schema of its tabular input with the following modifications:

  • 删除了指定的输入列 (Column)。The specified input column (Column) is removed.
  • 该架构扩展多个列,与 T 的顶层属性包值中非重复槽的数量相同。每个列的名称对应每个槽的名称,可选择将 OutputColumnPrefix 作为前缀。The schema is extended with as many columns as there are distinct slots in the top-level property bag values of T. The name of each column corresponds to the name of each slot, optionally prefixed by OutputColumnPrefix. 如果同一槽的所有值具有相同的类型,则其类型为槽的类型;如果类型中的值不同,则为 dynamicIts type is either the type of the slot, if all values of the same slot have the same type, or dynamic, if the values differ in type.

说明Notes

插件的输出架构依赖于数据值,这使得它和数据本身一样“不可预测”。The plugin's output schema depends on the data values, making it as "unpredictable" as the data itself. 使用不同的数据输入多次执行插件可能会产生不同的输出架构。Multiple executions of the plugin, using different data inputs, may produce different output schema.

插件的输入数据必须确保输出架构遵循表格架构的所有规则。The input data to the plugin must be such that the output schema follows all the rules for a tabular schema. 具体而言:In particular:

  • 如果不是要解压缩的列 (Column),则输出列名称不能与表格输入 T 中的现有列相同,因为这会产生两个具有相同名称的列 。An output column name can't be the same as an existing column in the tabular input T, unless it's the column to be unpacked (Column), since that will produce two columns with the same name.

  • 以 OutputColumnPrefix 为前缀时,所有槽名称必须是有效的实体名称,并遵循标识符命名规则All slot names, when prefixed by OutputColumnPrefix, must be valid entity names and follow the identifier naming rules.

示例Examples

展开包Expand a bag

datatable(d:dynamic)
[
    dynamic({"Name": "John", "Age":20}),
    dynamic({"Name": "Dave", "Age":40}),
    dynamic({"Name": "Jasmine", "Age":30}),
]
| evaluate bag_unpack(d)
名称Name AgeAge
JohnJohn 20 个20
DaveDave 4040
JasmineJasmine 3030

使用 OutputColumnPrefix 展开包Expand a bag with OutputColumnPrefix

展开包,并使用 OutputColumnPrefix 选项生成以前缀“Property_”开头的列名称。Expand a bag and use the OutputColumnPrefix option to produce column names that begin with the prefix 'Property_'.

datatable(d:dynamic)
[
    dynamic({"Name": "John", "Age":20}),
    dynamic({"Name": "Dave", "Age":40}),
    dynamic({"Name": "Jasmine", "Age":30}),
]
| evaluate bag_unpack(d, 'Property_')
Property_NameProperty_Name Property_AgeProperty_Age
JohnJohn 20 个20
DaveDave 4040
JasmineJasmine 3030

使用 columnsConflict 展开包Expand a bag with columnsConflict

展开包,并使用 columnsConflict 选项来解决现有的列和 bag_unpack() 运算符生成的列之间的冲突。Expand a bag and use the columnsConflict option to resolve conflicts between existing columns and columns produced by the bag_unpack() operator.

datatable(Name:string, d:dynamic)
[
    'Old_name', dynamic({"Name": "John", "Age":20}),
    'Old_name', dynamic({"Name": "Dave", "Age":40}),
    'Old_name', dynamic({"Name": "Jasmine", "Age":30}),
]
| evaluate bag_unpack(d, columnsConflict='replace_source') // Use new name
名称Name AgeAge
JohnJohn 20 个20
DaveDave 4040
JasmineJasmine 3030
datatable(Name:string, d:dynamic)
[
    'Old_name', dynamic({"Name": "John", "Age":20}),
    'Old_name', dynamic({"Name": "Dave", "Age":40}),
    'Old_name', dynamic({"Name": "Jasmine", "Age":30}),
]
| evaluate bag_unpack(d, columnsConflict='keep_source') // Keep old name
名称Name AgeAge
Old_nameOld_name 20 个20
Old_nameOld_name 4040
Old_nameOld_name 3030

使用 ignoredProperties 展开包Expand a bag with ignoredProperties

展开包,并使用 ignoredProperties 选项以忽略属性包中的某些属性。Expand a bag and use the ignoredProperties option to ignore certain properties in the property bag.

datatable(d:dynamic)
[
    dynamic({"Name": "John", "Age":20, "Address": "Address-1" }),
    dynamic({"Name": "Dave", "Age":40, "Address": "Address-2"}),
    dynamic({"Name": "Jasmine", "Age":30, "Address": "Address-3"}),
]
// Ignore 'Age' and 'Address' properties
| evaluate bag_unpack(d, ignoredProperties=dynamic(['Address', 'Age']))
名称Name
JohnJohn
DaveDave
JasmineJasmine