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



Annotate this POD


View/Report Bugs
Module Version: v1.6.0   Source   Latest Release: BSON-v1.6.5


BSON::OID - BSON type wrapper for Object IDs


version v1.6.0


    use BSON::Types ':all';

    my $oid  = bson_oid();
    my $oid  = bson_oid->from_epoch(1467543496, 0); # for queries only

    my $bytes = $oid->oid;
    my $hex   = $oid->hex;


This module provides a wrapper around a BSON Object ID.



A 12-byte (packed) Object ID (OID) string. If not provided, a new OID will be generated.



    my $oid = BSON::OID->new;

    my $oid = BSON::OID->new( oid => $twelve_bytes );

This is the preferred way to generate an OID. Without arguments, a unique OID will be generated. With a 12-byte string, an object can be created around an existing OID byte-string.


    # generate a new OID

    my $oid = BSON::OID->from_epoch( $epoch, 0); # other bytes zeroed
    my $oid = BSON::OID->from_epoch( $epoch, $eight_more_bytes );

    # reset an existing OID

    $oid->from_epoch( $new_epoch, 0 );
    $oid->from_epoch( $new_epoch, $eight_more_bytes );

Warning! You should not rely on this method for a source of unique IDs. Use this method for query boundaries, only.

An OID is a twelve-byte string. Typically, the first four bytes represent integer seconds since the Unix epoch in big-endian format. The remaining bytes ensure uniqueness.

With this method, the first argument to this method is an epoch time (in integer seconds). The second argument is the remaining eight-bytes to append to the string.

When called as a class method, it returns a new BSON::OID object. When called as an object method, it mutates the existing internal OID value.

As a special case, if the second argument is defined and zero ("0"), then the remaining bytes will be zeroed.

    my $oid = BSON::OID->from_epoch(1467545180, 0);

This is particularly useful when looking for documents by their insertion date: you can simply look for OIDs which are greater or lower than the one generated with this method.

For backwards compatibility with Mango, if called without a second argument, the method generates the remainder of the fields "like usual". This is equivalent to calling BSON::OID->new and replacing the first four bytes with the packed epoch value.

    # UNSAFE: don't do this unless you have to

    my $oid = BSON::OID->from_epoch(1467545180);

If you insist on creating a unique OID with from_epoch, set the remaining eight bytes in a way that guarantees thread-safe uniqueness, such as from a reliable source of randomness (see Crypt::URandom).

  use Crypt::Random 'urandom';
  my $oid = BSON::OID->from_epoch(1467545180, urandom(8));


Returns the oid attributes as 24-byte hexadecimal value


Returns a number corresponding to the portion of the oid value that represents seconds since the epoch.


Returns a string for this OID, with the OID given as 24 hex digits.

If the BSON_EXTJSON option is true, it will instead be compatible with MongoDB's extended JSON format, which represents it as a document as follows:

    {"$oid" : "012345678901234567890123"}


The string operator is overloaded so any string operations will actually use the 24-character hex value of the OID. Fallback overloading is enabled.

Both numeric comparison (<=>) and string comparison (cmp) are overloaded to do string comparison of the 24-character hex value of the OID. If used with a non-BSON::OID object, be sure to provide a 24-character hex string or the results are undefined.


This module is thread safe.



This software is Copyright (c) 2018 by Stefan G. and MongoDB, Inc.

This is free software, licensed under:

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