Supported MongoDB data types and drivers

The following tables list supported MongoDB data types, drivers, and third-party tools for Cloud Firestore.

Data types

BSON Type Supported
32-bit Integer Yes
64-bit Integer Yes
Array Yes
Binary Data Yes
Boolean Yes
Date Yes
DBPointer No
Decimal128 Yes
Double Yes
JavaScript No
JavaScript (with scope) No
MaxKey Yes
MinKey Yes
Null Yes
Object Yes
ObjectId Yes
Regular Expression Yes
String Yes
Symbol No
Timestamp Yes
Undefined No

Document _id

The top-level _id field in a document must be one of the following types:

  • ObjectId
  • String
  • 64-bit Integer
  • 32-bit Integer
  • Double
  • Binary
  • Object
  • Boolean

The total size of the _id must not exceed 1500 bytes.

Each values within an Object-typed ID must also be of a supported ID type or an Array of values, each of which is of a supported ID type.

Other BSON types are not supported.

Languages and MongoDB drivers

Cloud Firestore supports the following driver versions:

Language Driver versions
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 authentication support

The Go, C#, and Ruby drivers support OpenID Connect (OIDC) authentication from Google Cloud for all supported driver versions.

The Java, Node.js, and Python drivers support OIDC authentication from Google Cloud starting with the following driver versions:

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

Third-party tools

Cloud Firestore supports third-party tools described in this section.

Tool Description Notes
mongoimport MongoDB Database Tools See Bulk data loading
mongoexport MongoDB Database Tools
mongodump MongoDB Database Tools
mongorestore MongoDB Database Tools See Bulk data loading
mongosh MongoDB Shell
Mongoose MongoDB object modeling tool
MongoDB Compass GUI tool for data exploration

BSON and Cloud Firestore type compatibility

This section summarizes the mapping between MongoDB BSON types and Cloud Firestore values. Since BSON is a binary format and the Cloud Firestore API uses Protocol Buffers, some types map directly, while others require special map representations.

Mapping overview

The following tables show how BSON data types correspond to Cloud Firestore protocol buffer representations.

Direct mappings

These types have a direct equivalent in both systems.

BSON Type BSON Cloud Firestore Proto Notes
Double 1.23 double_value: 1.23
String "hello" string_value: "hello"
Object 
{
  "a": 1.23
}
 
map_value {
  fields {
    key: "a"
    value {
      double_value: 1.23
    }
  }
}
Array 
[
  1.23,
  "a"
]
 
array_value {
  values {
    double_value: 1.23
  }
  values {
    string_value: "a"
  }
}
Binary (Subtype Zero) BinData(0, 'SGVsbG8=') bytes_value: "Hello"
Boolean true boolean_value: true
Null null null_value: NULL_VALUE
64-bit Integer Long('1234567890') integer_value: 1234567890
Date ISODate('2026-05-22T04:00:00Z') 
timestamp_value {
  seconds: 1779470400
  nanos: 0
}
 Cloud Firestore timestamp values are stored at microsecond precision, but anything beyond millisecond precision is lost when converting to BSON.

BSON types represented as maps in Cloud Firestore API

These BSON types are wrapped in the Cloud Firestore map_value with special keys to denote the type.

BSON Type BSON Cloud Firestore Proto Notes
32-bit Integer 123 
map_value {
  fields {
    key: "__int__"
    value {
      integer_value: 123
    }
  }
}
Binary (Non-Zero Subtype) BinData(1, 'AQIDBA==') 
map_value {
  fields {
    key: "__binary__"
    value {
      bytes_value: "<subtype + data>"
    }
  }
}
 Subtype byte prepended to data.
ObjectId ObjectId('67eea9446dc71ec469e9496a') 
map_value {
  fields {
    key: "__oid__"
    value {
      string_value:
        "67eea9446dc71ec469e9496a"
    }
  }
}
 Lowercase hex string.
Timestamp (Internal) 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 internal timestamp.
Regular Expression 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"
    }
  }
}

Cloud Firestore types not natively in BSON

These Cloud Firestore types are represented as specially structured maps when converted to BSON.

Cloud Firestore Type BSON Cloud Firestore Proto
GeoPoint 
{
  "__fs_geopoint__": {
    "latitude": 37.42,
    "longitude": -122.08
  }
}
 
geo_point_value {
  latitude: 37.42
  longitude: -122.08
}
Vector 
{
  "__fs_vector__": [
    1.0,
    2.0
  ]
}
 
map_value {
  fields {
    key: "__type__"
    value {
      string_value: "__vector__"
    }
  }
  fields {
    key: "value"
    value {
      array_value {
        ...
      }
    }
  }
}
Document Ref 
{
  "__fs_ref__": "projects/.../documents/col/doc"
}
 reference_value: "projects/.../documents/col/doc"

Field names

Field names from MongoDB that match __.*__ are escaped by incorporating r: when stored in Cloud Firestore. For example, a BSON field __foo__ becomes __r:foo__ in Cloud Firestore.

BSON data types in client SDKs

When using Cloud Firestore client SDKs, you can use specialized SDK classes to represent BSON data types like 128-bit decimals, regular expressions, and BSON timestamps.

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

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
}

What's next