Skip to content

Latest commit

 

History

History
83 lines (75 loc) · 4.35 KB

types.md

File metadata and controls

83 lines (75 loc) · 4.35 KB
id title sidebar_label
types
Type Mappings
Type Mappings

Scala / Java to BSON Type Mappings

ZIO Bson provides BsonEncoder and BsonDecoder typeclass instances for a wide range of Scala and Java types. The encoder determines the primary BSON type a value is written as. The decoder accepts the primary type and, where it makes sense, additional fallback BSON types.

Scala / Java Type Encoder → BSON Decoder fallbacks
Boolean BOOLEAN —
Byte INT32 INT64 (range check), DOUBLE (lossless), DECIMAL128 (lossless), STRING
Short INT32 INT64 (range check), DOUBLE (lossless), DECIMAL128 (lossless), STRING
Int INT32 INT64 (range check), DOUBLE (lossless), DECIMAL128 (lossless), STRING
Long INT64 INT32, DOUBLE (lossless), DECIMAL128 (lossless), STRING
Float DOUBLE INT32, INT64, DECIMAL128 (lossless), STRING
Double DOUBLE INT32, INT64, DECIMAL128 (lossless), STRING
java.math.BigDecimal DECIMAL128 INT32, INT64, DOUBLE, STRING
BigDecimal DECIMAL128 INT32, INT64, DOUBLE, STRING
java.math.BigInteger STRING INT32, INT64, DOUBLE (lossless), DECIMAL128 (lossless)
BigInt STRING INT32, INT64, DOUBLE (lossless), DECIMAL128 (lossless)
String STRING SYMBOL
Char STRING SYMBOL
scala.Symbol STRING SYMBOL
UUID STRING —
java.util.Currency STRING —
DayOfWeek STRING —
Month STRING —
MonthDay STRING —
Year INT32 INT64 (range check), DOUBLE (lossless), DECIMAL128 (lossless), STRING
YearMonth STRING —
ZoneId STRING —
ZoneOffset STRING —
Duration STRING —
Period STRING —
Instant DATE_TIME —
LocalDate DATE_TIME —
LocalDateTime DATE_TIME —
LocalTime DATE_TIME —
OffsetDateTime DOCUMENT —
OffsetTime DOCUMENT —
ZonedDateTime DOCUMENT —
org.bson.types.ObjectId OBJECT_ID —
Option[A] same as A / NULL —
Array[Byte] BINARY —
Iterable[Byte] subtype BINARY —
NonEmptyChunk[Byte] BINARY —
Array[A] (non-byte) ARRAY —
Iterable[A] subtype (non-byte) ARRAY —
NonEmptyChunk[A] (non-byte) ARRAY —
Map[K, V] DOCUMENT —
T <: BsonValue any (pass-through) —

Special Cases

  • Byte and Short are decoded via the Int decoder followed by a range check using validateIntRange. All BSON numeric types and STRING are accepted, but the decoded value must fit within the type's range, otherwise a decoder error is returned.
  • BigInt and java.math.BigInteger encode to STRING but decode from all numeric BSON types. Conversion from DOUBLE and DECIMAL128 requires the value to be a lossless integer (no fractional part).
  • String decoder also accepts SYMBOL for backward compatibility with legacy BSON documents.
  • Char decoder requires the string to be exactly one character long.
  • OffsetDateTime and OffsetTime encode as a DOCUMENT with two fields: date_time (DATE_TIME) and offset (STRING).
  • ZonedDateTime encodes as a DOCUMENT with two fields: date_time (DATE_TIME) and zone_id (STRING).
  • Option[A] encodes None as NULL and Some(a) using the encoder for A. The decoder returns None for NULL and Some(a) for any value accepted by the decoder for A.

BSON Types Without Scala Mappings

The following BSON types have no dedicated Scala or Java codec in this library. They are accessible only via the T <: BsonValue pass-through encoder/decoder using the underlying MongoDB Java driver:

BSON Type Notes
SYMBOL Deprecated BSON type; accepted by the String decoder for backward compatibility, but no encoder exists
UNDEFINED Deprecated BSON type
REGULAR_EXPRESSION —
DB_POINTER Deprecated BSON type
JAVASCRIPT —
JAVASCRIPT_WITH_SCOPE —
TIMESTAMP MongoDB internal replication timestamp
MIN_KEY —
MAX_KEY —
END_OF_DOCUMENT Internal sentinel used by the reader loop; never a value