Crate bson[−][src]
BSON, short for Binary JSON, is a binary-encoded serialization of JSON-like documents. Like JSON, BSON supports the embedding of documents and arrays within other documents and arrays. BSON also contains extensions that allow representation of data types that are not part of the JSON spec. For example, BSON has a datetime type and a binary data type.
// JSON equivalent
{"hello": "world"}
// BSON encoding
\x16\x00\x00\x00 // total document size
\x02 // 0x02 = type String
hello\x00 // field name
\x06\x00\x00\x00world\x00 // field value
\x00 // 0x00 = type EOO ('end of object')
BSON is the primary data representation for MongoDB, and this crate is used in the
mongodb
driver crate in its API and implementation.
For more information about BSON itself, see bsonspec.org.
BSON values
Many different types can be represented as a BSON value, including 32-bit and 64-bit signed
integers, 64 bit floating point numbers, strings, datetimes, embedded documents, and more. To
see a full list of possible BSON values, see the BSON specification. The various
possible BSON values are modeled in this crate by the Bson
enum.
Creating Bson
instances
Bson
values can be instantiated directly or via the
bson!
macro:
let string = Bson::String("hello world".to_string()); let int = Bson::Int32(5); let array = Bson::Array(vec![Bson::Int32(5), Bson::Boolean(false)]); let string: Bson = "hello world".into(); let int: Bson = 5i32.into(); let string = bson!("hello world"); let int = bson!(5); let array = bson!([5, false]);
bson!
has supports both array and object literals, and it automatically
converts any values specified to Bson
, provided they are Into<Bson>
.
Bson
value unwrapping
Bson
has a number of helper methods for accessing the underlying native Rust
types. These helpers can be useful in circumstances in which the specific type of a BSON value
is known ahead of time.
e.g.:
let value = Bson::Int32(5); let int = value.as_i32(); // Some(5) let bool = value.as_bool(); // None let value = bson!([true]); let array = value.as_array(); // Some(&Vec<Bson>)
BSON documents
BSON documents are ordered maps of UTF-8 encoded strings to BSON values. They are logically
similar to JSON objects in that they can contain subdocuments, arrays, and values of several
different types. This crate models BSON documents via the
Document
struct.
Creating Document
s
Document
s can be created directly either from a byte
reader containing BSON data or via the doc!
macro:
let mut bytes = hex::decode("0C0000001069000100000000").unwrap(); let doc = Document::from_reader(&mut bytes.as_slice()).unwrap(); // { "i": 1 } let doc = doc! { "hello": "world", "int": 5, "subdoc": { "cat": true }, };
doc!
works similarly to bson!
, except that it always
returns a Document
rather than a Bson
.
Document
member access
Document
has a number of methods on it to facilitate member
access:
let doc = doc! { "string": "string", "bool": true, "i32": 5, "doc": { "x": true }, }; // attempt get values as untyped Bson let none = doc.get("asdfadsf"); // None let value = doc.get("string"); // Some(&Bson::String("string")) // attempt to get values with explicit typing let string = doc.get_str("string"); // Ok("string") let subdoc = doc.get_document("doc"); // Some(Document({ "x": true })) let error = doc.get_i64("i32"); // Err(...)
Modeling BSON with strongly typed data structures
While it is possible to work with documents and BSON values directly, it will often introduce a
lot of boilerplate for verifying the necessary keys are present and their values are the correct
types. serde
provides a powerful way of mapping BSON data into Rust data structures largely
automatically, removing the need for all that boilerplate.
e.g.:
#[derive(Serialize, Deserialize)] struct Person { name: String, age: i32, phones: Vec<String>, } // Some BSON input data as a `Bson`. let bson_data: Bson = bson!({ "name": "John Doe", "age": 43, "phones": [ "+44 1234567", "+44 2345678" ] }); // Deserialize the Person struct from the BSON data, automatically // verifying that the necessary keys are present and that they are of // the correct types. let mut person: Person = bson::from_bson(bson_data).unwrap(); // Do things just like with any other Rust data structure. println!("Redacting {}'s record.", person.name); person.name = "REDACTED".to_string(); // Get a serialized version of the input data as a `Bson`. let redacted_bson = bson::to_bson(&person).unwrap();
Any types that implement Serialize
and Deserialize
can be used in this way. Doing so helps
separate the “business logic” that operates over the data from the (de)serialization logic that
translates the data to/from its serialized form. This can lead to more clear and concise code
that is also less error prone.
Re-exports
pub use self::bson::Document; |
pub use self::de::from_bson; |
pub use self::de::from_document; |
pub use self::decimal128::Decimal128; |
pub use self::ser::to_bson; |
pub use self::ser::to_document; |
Modules
compat | Backward compatibility |
de | Deserializer |
decimal128 | BSON Decimal128 data type representation |
document | A BSON document represented as an associative HashMap with insertion ordering. |
extjson | Deserialization and serialization of MongoDB Extended JSON v2 |
oid | ObjectId |
ser | Serializer |
serde_helpers | Collection of helper functions for serializing to and deserializing from BSON using Serde |
spec | Constants derived from the BSON Specification Version 1.1. |
Macros
bson | Construct a bson::BSON value from a literal. |
doc | Construct a bson::Document value. |
Structs
Binary | Represents a BSON binary value. |
DateTime |
|
DbPointer | Represents a DBPointer. (Deprecated) |
Deserializer | Serde Deserializer |
JavaScriptCodeWithScope | Represents a BSON code with scope value. |
Regex | Represents a BSON regular expression value. |
Serializer | Serde Serializer |
Timestamp | Represents a BSON timestamp value. |
Enums
Bson | Possible BSON value types. |
Type Definitions
Array | Alias for |