/ 
MongoDB-0.701.4
River stage two • 48 direct dependents • 56 total dependents
/ MongoDB::DBRef

NAME

MongoDB::DBRef - Native DBRef support

VERSION

version 0.701.4

SYNOPSIS

my $dbref = MongoDB::DBRef->new( db => 'my_db', ref => 'my_collection', id => 123 );
$coll->insert( { foo => 'bar', other_doc => $dbref } );

my $other_doc = $coll->find_one( { foo => 'bar' } )->{other_doc}->fetch;

DESCRIPTION

This module provides support for database references (DBRefs) in the Perl MongoDB driver. A DBRef is a special embedded document which points to another document in the database. DBRefs are not the same as foreign keys and do not provide any referential integrity or constraint checking. For example, a DBRef may point to a document that no longer exists (or never existed.)

NAME

MongoDB::DBRef - A MongoDB database reference

ATTRIBUTES

db

Required. The database in which the referenced document lives. Either a MongoDB::Database object or a string containing the database name. The object will be coerced to string form.

ref

Required. The collection in which the referenced document lives. Either a MongoDB::Collection object or a string containing the collection name. The object will be coerced to string form.

id

Required. The _id value of the referenced document. If the _id is an ObjectID, then you must use a MongoDB::OID object.

client

Optional. A MongoDB::MongoClient object to be used to fetch the referenced document from the database. You must supply this attribute if you want to use the fetch method.

When you retrieve a document from MongoDB, any DBRefs will automatically be inflated into MongoDB::DBRef objects with the client attribute automatically populated.

It is not necessary to specify a client if you are just making DBRefs to insert in the database as part of a larger document.

verify_db

Optional. Check that the referenced database exists before trying to fetch a document from it. The default is 1. Set to 0 to disable checking.

verify_coll

Optional. Check that the referenced collection exists before trying to fetch a document from it. The default is 1. Set to 0 to disable checking.

METHODS

fetch

Retrieve the referenced document from the database. If the document does not exist, you'll get back undef. You must populate the client attribute of the DBRef object in order to use this method. If there's no client, fetch will throw a fatal error.

If verify_db or <verify_coll> are on, fetch will throw a fatal error if the database or collection concerned does not exist.

AUTHORS

  • Florian Ragwitz <rafl@debian.org>

  • Kristina Chodorow <kristina@mongodb.org>

  • Mike Friedman <mike.friedman@10gen.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2013 by 10gen, Inc..

This is free software, licensed under:

The Apache License, Version 2.0, January 2004