지원되는 MongoDB 데이터 유형 및 드라이버

다음 테이블에는 MongoDB 호환성을 갖춘 Firestore에서 지원되는 MongoDB 데이터 유형, 드라이버, 서드 파티 도구가 나와 있습니다.

데이터 유형

BSON 유형 지원됨
32비트 정수 예
64비트 정수 예
배열 예
바이너리 데이터 예
불리언 예
날짜 예
DBPointer 아니요
Decimal128 예
실수 예
JavaScript 아니요
JavaScript(범위 포함) 아니요
MaxKey 예
MinKey 예
Null 예
객체 예
ObjectId 예
정규 표현식 예
문자열 예
기호 아니요
타임스탬프 예
정의되지 않음 아니요

문서 _id

문서의 최상위 _id 필드는 다음 유형 중 하나여야 합니다.

  • ObjectId
  • 문자열
  • 64비트 정수
  • 32비트 정수
  • Double
  • 바이너리
  • 객체
  • 불리언

_id의 총 크기는 1,500바이트를 초과할 수 없습니다.

객체 유형 ID 내의 각 값도 지원되는 ID 유형이거나 각각 지원되는 ID 유형인 값의 배열이어야 합니다.

다른 BSON 유형은 지원되지 않습니다.

언어 및 MongoDB 드라이버

MongoDB 호환성을 갖춘 Firestore는 다음 드라이버 버전을 지원합니다.

언어 드라이버 버전
자바 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 참고
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"
  }
}
바이너리 (하위 유형 0) BinData(0, 'SGVsbG8=') bytes_value: "Hello"
Boolean 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
    }
  }
}
바이너리 (0이 아닌 하위 유형) 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"
    }
  }
}
 소문자 16진수 문자열입니다.
타임스탬프 (내부) 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"
          }
        }
      }
    }
  }
}
최소 키 MinKey() 
map_value {
  fields {
    key: "__min__"
    value {
      null_value: NULL_VALUE
    }
  }
}
고속 충전 키 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
}
Vector 
{
  "__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 클래스를 사용하여 128비트 십진수, 정규 표현식, BSON 타임스탬프와 같은 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),
});
자바
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);
자바
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
}

다음 단계