支援的 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
小茹 2.x (x ≥ 16)

支援 OIDC 驗證

Go、C# 和 Ruby 驅動程式支援從Google Cloud 進行 OpenID Connect (OIDC) 驗證，適用於所有支援的驅動程式版本。

Java、Node.js 和 Python 驅動程式支援 OIDC 驗證，Google Cloud 從下列驅動程式版本開始：

  • 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 附註
Double 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 類型

轉換為 BSON 時，這些 Firestore 類型會以特殊結構的對應表示。

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"

欄位名稱

如果 MongoDB 的欄位名稱與 __.*__ 相符，系統會在儲存至 Firestore 時加入 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
}

後續步驟