支持的 MongoDB 数据类型和驱动程序

下表列出了与 MongoDB 兼容的 Firestore 支持的 MongoDB 数据类型、驱动程序和第三方工具。

数据类型

BSON 类型 支持
32 位整数 是
64 位整数 是
数组 是
二进制数据 是
布尔值 是
日期 是
DBPointer 否
Decimal128 是
双精度型 是
JavaScript 否
JavaScript（带范围） 否
MaxKey 是
MinKey 是
空 是
对象 是
ObjectId 是
正则表达式 是
字符串 是
符号 否
时间戳 是
未定义 否

文档 _id

文档中的顶级 _id 字段必须是以下类型之一：

  • ObjectId
  • 字符串
  • 64 位整数
  • 32 位整数
  • 双精度型
  • 二进制
  • 对象
  • 布尔值

_id 的总大小不得超过 1500 字节。

对象类型 ID 中的每个值也必须是受支持的 ID 类型或值数组，其中每个值都是受支持的 ID 类型。

不支持其他 BSON 类型。

语言和 MongoDB 驱动程序

与 MongoDB 兼容的 Firestore 支持以下驱动程序版本：

语言 驱动程序版本
Java 5.x
Node.js 6.x
5.x
Python 4.x
3.x (x ≥ 12)
Go 2.x
C# 3.x
Ruby 2.x (x ≥ 16)

OIDC 身份验证支持

对于所有受支持的驱动程序版本，Go、C# 和 Ruby 驱动程序支持从Google Cloud 进行 OpenID Connect (OIDC) 身份验证。

从以下驱动程序版本开始，Java、Node.js 和 Python 驱动程序支持从Google Cloud 进行 OIDC 身份验证：

  • Java：4.10
  • Node.js：6.7
  • Python：4.7

第三方工具

与 MongoDB 兼容的 Firestore 支持本部分中所述的第三方工具。

工具 说明 备注
mongoimport MongoDB 数据库工具 请参阅 批量加载数据
mongoexport MongoDB 数据库工具
mongodump MongoDB 数据库工具
mongorestore MongoDB 数据库工具 请参阅 批量加载数据
mongosh MongoDB Shell
Mongoose MongoDB 对象建模工具
MongoDB Compass 用于数据探索的 GUI 工具

BSON 和 Firestore 类型兼容性

本部分总结了 MongoDB BSON 类型与 Firestore 值之间的映射。由于 BSON 是二进制格式，而 Firestore API 使用协议缓冲区，因此某些类型会直接映射，而其他类型则需要特殊的映射表示。

映射概览

下表显示了 BSON 数据类型与 Firestore 协议缓冲区表示形式的对应关系。

直接映射

这些类型在两个系统中都有直接对等类型。

BSON 类型 BSON Firestore Proto 备注
双精度型 1.23 double_value: 1.23
字符串 "hello" string_value: "hello"
对象 
{
  "a": 1.23
}
 
map_value {
  fields {
    key: "a"
    value {
      double_value: 1.23
    }
  }
}
数组 
[
  1.23,
  "a"
]
 
array_value {
  values {
    double_value: 1.23
  }
  values {
    string_value: "a"
  }
}
二进制（子类型零） BinData(0, 'SGVsbG8=') bytes_value: "Hello"
布尔值 true boolean_value: true
Null null null_value: NULL_VALUE
64 位整数 Long('1234567890') integer_value: 1234567890
日期 ISODate('2026-05-22T04:00:00Z') 
timestamp_value {
  seconds: 1779470400
  nanos: 0
}
 Firestore 时间戳值以微秒精度存储，但在转换为 BSON 时，任何超出毫秒精度的部分都会丢失。

在 Firestore API 中表示为映射的 BSON 类型

这些 BSON 类型封装在 Firestore map_value 中，并带有表示类型的特殊键。

BSON 类型 BSON Firestore Proto 备注
32 位整数 123 
map_value {
  fields {
    key: "__int__"
    value {
      integer_value: 123
    }
  }
}
二进制（非零子类型） BinData(1, 'AQIDBA==') 
map_value {
  fields {
    key: "__binary__"
    value {
      bytes_value: "<subtype + data>"
    }
  }
}
 在数据前面添加的子类型字节。
ObjectId ObjectId('67eea9446dc71ec469e9496a') 
map_value {
  fields {
    key: "__oid__"
    value {
      string_value:
        "67eea9446dc71ec469e9496a"
    }
  }
}
 小写十六进制字符串。
时间戳（内部） Timestamp(123, 1) 
map_value {
  fields {
    key: "__request_timestamp__"
    value {
      map_value {
        fields {
          key: "seconds"
          value {
            integer_value: 123
          }
        }
        fields {
          key: "increment"
          value {
            integer_value: 1
          }
        }
      }
    }
  }
}
 MongoDB 内部时间戳。
正则表达式 RegExp('.*', 'im') 
map_value {
  fields {
    key: "__regex__"
    value {
      map_value {
        fields {
          key: "pattern"
          value {
            string_value: ".*"
          }
        }
        fields {
          key: "options"
          value {
            string_value: "im"
          }
        }
      }
    }
  }
}
Min Key MinKey() 
map_value {
  fields {
    key: "__min__"
    value {
      null_value: NULL_VALUE
    }
  }
}
Max Key MaxKey() 
map_value {
  fields {
    key: "__max__"
    value {
      null_value: NULL_VALUE
    }
  }
}
Decimal128 Decimal128('4E7') 
map_value {
  fields {
    key: "__decimal128__"
    value {
      string_value: "4E7"
    }
  }
}

BSON 中不原生支持的 Firestore 类型

这些 Firestore 类型在转换为 BSON 时会表示为具有特殊结构的映射。

Firestore 类型 BSON Firestore Proto
GeoPoint 
{
  "__fs_geopoint__": {
    "latitude": 37.42,
    "longitude": -122.08
  }
}
 
geo_point_value {
  latitude: 37.42
  longitude: -122.08
}
矢量 
{
  "__fs_vector__": [
    1.0,
    2.0
  ]
}
 
map_value {
  fields {
    key: "__type__"
    value {
      string_value: "__vector__"
    }
  }
  fields {
    key: "value"
    value {
      array_value {
        ...
      }
    }
  }
}
文档参考 
{
  "__fs_ref__": "projects/.../documents/col/doc"
}
 reference_value: "projects/.../documents/col/doc"

字段名称

存储在 Firestore 中时，MongoDB 中与 __.*__ 匹配的字段名称会通过合并 r: 进行转义。例如，BSON 字段 __foo__ 在 Firestore 中会变为 __r:foo__。

客户端 SDK 中的 BSON 数据类型

使用 Firestore 客户端 SDK 时，您可以使用专用 SDK 类来表示 BSON 数据类型，例如 128 位小数、正则表达式和 BSON 时间戳。

Node.js
const { RegexValue, Decimal128Value, BsonTimestamp } = require('@google-cloud/firestore');

// Setting fields with BSON data types
const res = await db.collection('foo').doc('bar').set({
  regex: new RegexValue('myRegexPattern', 'i'),
  decimal: new Decimal128Value('0.73e-7'),
  bsonTimestamp: new BsonTimestamp(1732754912, 500),
});
Java
import com.google.cloud.firestore.BsonTimestamp;
import com.google.cloud.firestore.Decimal128Value;
import com.google.cloud.firestore.RegexValue;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> data = new HashMap<>();
data.put("regex", new RegexValue("myRegexPattern", "i"));
data.put("decimal", new Decimal128Value("0.73e-7"));
data.put("bson_timestamp", new BsonTimestamp(1732754912, 500));

db.collection("foo").doc("bar").set(data);
Java
Android
import com.google.firebase.firestore.BsonTimestamp;
import com.google.firebase.firestore.Decimal128Value;
import com.google.firebase.firestore.RegexValue;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> data = new HashMap<>();
data.put("regex", new RegexValue("myRegexPattern", "i"));
data.put("decimal", new Decimal128Value("0.73e-7"));
data.put("bson_timestamp", new BsonTimestamp(1732754912, 500));

db.collection("foo").doc("bar").set(data);
Go
import (
    "context"

    "cloud.google.com/go/firestore"
)

func writeBsonTypes(ctx context.Context, client *firestore.Client) error {
    _, err := client.Collection("foo").Doc("bar").Set(ctx, map[string]interface{}{
        "regex":     firestore.RegexValue{Pattern: "myRegexPattern", Options: "i"},
        "decimal":   firestore.Decimal128Value{Value: "0.73e-7"},
        "bson_timestamp": firestore.BsonTimestamp{Seconds: 1732754912, Increment: 500},
    })
    return err
}

后续步骤