View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
MongoDB Inc > MongoDB > MongoDB::BSON



Annotate this POD


View/Report Bugs
Module Version: v1.8.2   Source  


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


version v1.8.2


    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:

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:


    $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:


    $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) 2018 by MongoDB, Inc.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004
syntax highlighting: