MongoDB::BSON(3) Tools for serializing and deserializing data in BSON form


version v1.2.3


my $codec = MongoDB::BSON->new;
my $bson = $codec->encode_one( $document );
my $doc = $codec->decode_one( $bson );


This class implements a BSON encoder/decoder (``codec''). It consumes documents and emits BSON strings and vice versa.



A document with keys $ref and $id is a special MongoDB convention representing a DBRef <>.

This attribute specifies a function reference that will be called with a hash reference argument representing a DBRef.

The hash reference will have keys $ref and $id and may have $db and other keys. The callback must return a scalar value representing the dbref (e.g. a document, an object, etc.)

The default "dbref_callback" returns the DBRef hash reference without modification.

Note: in MongoDB::MongoClient, when no MongoDB::BSON object is provided as the "bson_codec" attribute, <MongoDB:MongoClient> creates a custom MongoDB::BSON object that inflates DBRefs into MongoDB::DBRef objects using a custom "dbref_callback":

    dbref_callback => sub { return MongoDB::DBRef->new(shift) },

Object-database mappers may wish to implement alternative "dbref_callback" attributes to provide whatever semantics they require.


Sets the type of object which is returned for BSON DateTime fields. The default is DateTime. Other acceptable values are Time::Moment, DateTime::Tiny and "undef". The latter will give you the raw epoch value (possibly as a floating point value) rather than an object.


This attribute specifies a function reference that will be called with three positional arguments:
  • an error string argument describing the error condition
  • a reference to the problematic document or byte-string
  • the method in which the error occurred (e.g. "encode_one" or "decode_one")

Note: for decoding errors, the byte-string is passed as a reference to avoid copying possibly large strings.

If not provided, errors messages will be thrown with "Carp::croak".


A string containing ASCII characters that must not appear in keys. The default is the empty string, meaning there are no invalid characters.


This attribute defines the maximum document size. The default is 0, which disables any maximum.

If set to a positive number, it applies to both encoding and decoding (the latter is necessary for prevention of resource consumption attacks).


This is a single character to use for special operators. If a key starts with "op_char", the "op_char" character will be replaced with ``$''.

The default is ``$''.


If set to true, scalar values that look like a numeric value will be encoded as a BSON numeric type. When false, if the scalar value was ever used as a string, it will be encoded as a BSON UTF-8 string.

The default is false.



    $byte_string = $codec->encode_one( $doc );
    $byte_string = $codec->encode_one( $doc, \%options );

Takes a ``document'', typically a hash reference, an array reference, or a Tie::IxHash object and returns a byte string with the BSON representation of the document.

An optional hash reference of options may be provided. Valid options include:

  • first_key – if "first_key" is defined, it and "first_value" will be encoded first in the output BSON; any matching key found in the document will be ignored.
  • first_value - value to assign to "first_key"; will encode as Null if omitted
  • error_callback – overrides codec default
  • invalid_chars – overrides codec default
  • max_length – overrides codec default
  • op_char – overrides codec default
  • prefer_numeric – overrides codec default


    $doc = $codec->decode_one( $byte_string );
    $doc = $codec->decode_one( $byte_string, \%options );

Takes a byte string with a BSON-encoded document and returns a hash reference representin the decoded document.

An optional hash reference of options may be provided. Valid options include:

  • dbref_callback – overrides codec default
  • dt_type – overrides codec default
  • error_callback – overrides codec default
  • max_length – overrides codec default


    $codec->clone( dt_type => 'Time::Moment' );

Constructs a copy of the original codec, but allows changing attributes in the copy.



This software is Copyright (c) 2016 by MongoDB, Inc..

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004