[confluence] MongoDB > BSON

5 views
Skip to first unread message

nor...@mongodb.onconfluence.com

unread,
Jan 16, 2013, 7:57:00 PM1/16/13
to mongodb...@googlegroups.com

nor...@mongodb.onconfluence.com

unread,
Jan 16, 2013, 7:57:00 PM1/16/13
to mongodb...@googlegroups.com

BSON

Page edited by Sam Kleinman


Changes (3)

{dochub:bson}
 
BSON is a bin­ary-en­coded seri­al­iz­a­tion of JSON-like doc­u­ments. BSON is designed to be lightweight, traversable, and efficient. BSON, like JSON, supports the embedding of objects and arrays within other objects and arrays. See [bsonspec.org|http://www.bsonspec.org/] for the spec and more information in general.
{redirect:http://docs.mongodb.org/meta-driver/latest/legacy/bson/}

h3. BSON and MongoDB

MongoDB uses [BSON|http://bsonspec.org] as the data storage and network transfer format for "documents". 

BSON at first seems BLOB-like, but there exists an important difference: the Mongo database understands BSON internals. This means that MongoDB can "[reach inside|DOCS:Dot Notation (Reaching into Objects)] " BSON objects, even nested ones. Among other things, this allows MongoDB to build indexes and match objects against query expressions on both top-level and nested BSON keys.

See also: the [BSON blog post|http://blog.mongodb.org/post/114440717/bson] and [BSON and Data Interchange|http://blog.mongodb.org/post/9333386434/bson-and-data-interchange]

h3. Language-Specific Examples

We often map from a language's "dictionary" type -- which may be its native objects -- to BSON.  The mapping is particularly natural in dynamically typed languages:


{code}JavaScript: {"foo" : "bar"}
Perl: {"foo" => "bar"}
PHP: array("foo" => "bar")
Python: {"foo" : "bar"}
Ruby: {"foo" => "bar"}
Java: DBObject obj = new BasicDBObject("foo", "bar");
{code}
h5. C

{code}bson b;
bson_buffer buf;
bson_buffer_init( &buf )
bson_append_string( &buf, "name", "Joe" );
bson_append_int( &buf, "age", 33 );
bson_from_buffer( &b, &buf );
bson_print( &b );
{code}See [http://github.com/mongodb/mongo-c-driver/blob/master/src/bson.h] for more information.

h5. C+\+

{code}BSONObj p = BSON( "name" << "Joe" << "age" << 33 );
cout << p.toString() << endl;
cout << p["age"].number() << endl;
{code}See the BSON section of the [C+\+ Tutorial|C++ Tutorial] for more information.

h5. Java

{code}BasicDBObject doc = new BasicDBObject();
doc.put("name", "MongoDB");
doc.put("type", "database");
doc.put("count", 1);
BasicDBObject info = new BasicDBObject();
info.put("x", 203);
info.put("y", 102);
doc.put("info", info);
coll.insert(doc);
{code}
h5. PHP

The PHP driver includes {{bson_encode}} and {{bson_decode}} functions. {{bson_encode}} takes any PHP type and serializes it, returning a string of bytes:

{code}$bson = bson_encode(null);
$bson = bson_encode(true);
$bson = bson_encode(4);
$bson = bson_encode("hello, world");
$bson = bson_encode(array("foo" => "bar"));
$bson = bson_encode(new MongoDate());
{code}Mongo-specific objects ({{MongoId}}, {{MongoDate}}, {{MongoRegex}}, {{MongoCode}}) will be encoded in their respective BSON formats. For other objects, it will create a BSON representation with the key/value pairs you would get by running {{for ($object as $key => $value)}}.

{{bson_decode}} takes a string representing a BSON object and parses it into an associative array.

h5. Python
{code}>>> from bson import BSON
>>> bson_string = BSON.encode({"hello": "world"})
>>> bson_string
'\x16\x00\x00\x00\x02hello\x00\x06\x00\x00\x00world\x00\x00'
>>> bson_string.decode()
{u'hello': u'world'}
{code}PyMongo also supports "ordered dictionaries" through the *bson.son* module. The *BSON* class can handle *SON* instances using the same methods you would use for regular dictionaries. Python2.7's collections.OrderedDict is also supported.

h5. Ruby

There are now two gems that handle BSON-encoding: bson and bson_ext. These gems can be used to work with BSON independently of the MongoDB Ruby driver.

{code}irb
>> require 'rubygems'
=> true
>> require 'bson'
=> true
>> doc = {:hello => "world"}
>> bson = BSON.serialize(doc).to_s
=> "\026\000\000\000\002hello\000\006\000\000\000world\000\000"
>> BSON.deserialize(bson.unpack("C*"))
=> {"hello" => "world"}
{code}
The BSON class also supports ordered hashes. Simply construct your documents using the OrderedHash class, also found in the MongoDB Ruby Driver.

h3. MongoDB Document Types

MongoDB uses BSON documents for three things:

# Data storage (user documents). These are the regular JSON-like objects that the database stores for us. These BSON documents are sent to the database via the INSERT operation. User documents have limitations on the "element name" space due to the usage of special characters in the JSON-like query language.
## A user document element name cannot begin with "$".
## A user document element name cannot have a "." in the name.
## The element name "_id" is reserved for use as a primary key id, but you can store anything that is unique in that field.
The database expects that drivers will prevent users from creating documents that violate these constraints.
\\
# Query "Selector" Documents : Query documents (or selectors) are BSON documents that are used in QUERY, DELETE and UPDATE operations. They are used by these operations to match against documents. Selector objects have no limitations on the "element name" space, as they must be able to supply special "marker" elements, like "$where" and the special "command" operations.
\\
# "Modifier" Documents : Documents that contain 'modifier actions' that modify user documents in the case of an update (see [Updating|Updating#ModifierOperations]).

Full Content

Redirection Notice
This page should redirect to http://docs.mongodb.org/meta-driver/latest/legacy/bson/.

Reply all
Reply to author
Forward
0 new messages