++ed by:

25 PAUSE users
29 non-PAUSE users.

MongoDB Inc
and 53 contributors


MongoDB::BSON - Tools for serializing and deserializing data in BSON form


version v1.0.1


    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 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.


  • David Golden <david@mongodb.com>

  • Mike Friedman <friedo@friedo.com>

  • Kristina Chodorow <k.chodorow@gmail.com>

  • Florian Ragwitz <rafl@debian.org>


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

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004