`$convert`

在此页面上

定义

语法
行为
示例

定义

$convert 表达式转换二进制数据类型。它可用于转换 Kafka 标头中的二进制数据。

$convert

$convert 表达式采用以下原型形式：

{
  input: "$binDataField",
  to: <int, long, double>,
  byteOrder: "little"|"big"
}
{
  input: "$intLongOrDoubleField",
  to: "binData",
  byteOrder: "little"|"big"
}
{
  input: "$binDataField",
  to: "string",
  format: <base64, base64url, hex, uuid, utf8>
}
{
  input: "$stringField",
  to: "binData",
  format: <base64, base64url, hex, uuid, utf8>
}

语法

$convert 聚合操作符可在数据类型之间进行转换，但 $convert 表达式的 Atlas Stream Processing 版本中提供的二进制数据类型除外。

$convert 表达式采用包含以下字段的文档：

字段	值	必要性	说明
`input`	`binData`、 `int` 、 `long` 、 `double`和`string`	必需	可转换为 `int`、`long`、`double` 或 `string` 类型的二进制数据，或者可转换为二进制数据的 `int`、`long`、`double` 或 `string` 类型数据。
`to`	`binData`、 `int` 、 `long` 、 `double`和`string`	必需	指定 `input` 转换后的数据类型。您可以指定 `int`、`long`、`double`、`string` 或 `binData`。
`byteOrder`	小，大	必需	指定 `binData` 输入和输出的大端或小端字节排序。如果未指定，则默认值为小端字节排序。注意 `byteOrder` 选项指定如何解释 input 或 output `binData`，但不控制数字类型的内部字节顺序。MongoDB 建议您使用大端排序，这是 Kafka 生态系统、Java 和 Python 语言中数字到字节转换的默认排序。
`format`	base64, base64url, hex, uuid, utf8	必需	指定 `string` 输入和输出的顶级格式参数。注意默认，`$toString` 辅助方法不会将 `binData` 解释为 utf-8 数据。默认为 `base64` 。您必须使用 $convert表达式进行 utf-8 转换。

行为

如果 $convert.to 的值为 int，则 binData input 值必须是 1、2 或 4。如果 $convert.to 的值为 long，则 binData input 值必须是 1、2、4 或 8。如果 input 的长度超出预期，则会产生错误。您可以通过配置 $convert.onError 来控制此行为。

转换为 binData 时，int 将变为 4 字节 binData，long 将变为 8 字节 binData，double 将变为 8 字节 binData。从 binData 转换为 double 时，8 字节的输入被解释为 IEEE 754 双精度浮点值，而 4 字节的输入被解释为 IEEE 754 单精度浮点值。由于 MQL 仅支持双精度浮点值，因此它执行从单精度浮点值到双精度浮点值的无损转换。

将 binData 转换为数值类型：

$convert.to	`int`	`long`	`double`
允许的宽度（以字节为单位）	1, 2, 4	1, 2, 4, 8	4, 8
`binData` 被解释为	二进制补码有符号整数	二进制补码有符号整数	IEEE 754 单精度或双精度浮点数

将数字类型转换为 binData：

输入	`int`	`long`	`double`
输出宽度（以字节为单位）	4	8	8

示例

在以下示例中，我们使用二进制表示法描述 binData，例如：

BinData(0b00000000 00000010)

最左边的字节 (00000000) 对应于最低内存地址，或字节数组的第 0 个索引。同样，我们使用十六进制表示法，例如：

BinData(0x0100 000A)

最左边的字节 (01) 对应于最低内存地址，或字节数组的第 0 个索引。

以下文档是跨 BinData、int、long 和 double 表示法转换值的 $convert 表达式示例：

{
  $convert: {
    input: BinData(0b00000000 00000010),
    to: “int”,
    byteOrder: “big” }
}

结果：2

{
  $convert: {
    input: BinData(0b00000001 00000000),
    to: “int”,
    byteOrder: “big” }
}

结果：256

{
  $convert: {
    input: BinData(0b00000001 00000000),
    to: “int”,
    byteOrder: “little” }
}

结果：1

{
  $convert: {
    input: BinData(0x0001 0000),
    to: “int”,
    byteOrder: “big” }
}

结果：65536

{
  $convert: {
    input: BinData(0x0001 0000 0000 0000),
    to: “long”,
    byteOrder: “big” }
}

结果：281474976710656

{
  $convert: {
    input: BinData(0xFFFE7960),
    to: “int”,
    byteOrder: “big” }
}

结果：-100000

{
  $convert: {
    input: BinData(0x0001 0000 0000 0000),
    to: “int”,
    byteOrder: “big” }
}

结果：错误 — 当 to == “int” 时，binData 长度只能是 1 、 2 或 4 字节。

{
  $convert: {
    input: BinData(0xC04C CCCD),
    to: “double”,
    byteOrder: “big” }
}

Result: -3.2000000476837158203125

{
  $convert: {
    input: BinData(0x0000),
    to: “double”,
    byteOrder: “big” }
}

结果：错误— 当 to == “double” 时，binData 的长度只能为 4 或 8 字节。

{
  $convert: {
    input: true,
    to: “binData” }
}

Result: BinData(0x01) // subtype 0

{
  $convert: {
    input: false,
    to: “binData” }
}

Result: BinData(0x00) // subtype 0

{
  $convert: {
    input: NumberLong(42),
    to: “binData”,
    byteOrder: “big” }
}

Result: BinData(0x0000 0000 0000 002A) // subtype 0

{
  $convert: {
    input: NumberLong(42),
    to: “binData”,
    byteOrder: “little” }
}

Result: BinData(0x2A00 0000 0000 0000) // subtype 0

{
  $convert: {
    input: { $toInt: “$myNumericField” },
    to: “binData”,
    byteOrder: “little” }
}

假设 myNumericField 是 Int(42)、Long(42) 或 Double(42.0)...

Result: BinData(0x2A00 0000)

{
  $convert: {
    input: “$myIntOrLongField”,
    to: “binData”,
    byteOrder: “little” }
}

如果输入为 Int(42)：

Result: BinData(0x2A00 0000)

如果输入为 Long(42)：

BinData(0x2A00 0000 0000 0000)

后退

聚合表达式

来年

聚合管道

定义

语法

注意

注意

行为

示例