Crate bson

Expand description

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.

§Installation

§Requirements

Rust 1.64+

§Importing

This crate is available on crates.io. To use it in your application, simply add it to your project’s Cargo.toml.

[dependencies]
bson = "2.15.0"

Note that if you are using bson through the mongodb crate, you do not need to specify it in your Cargo.toml, since the mongodb crate already re-exports it.

§Feature Flags

Feature	Description	Default
`chrono-0_4`	Enable support for v0.4 of the `chrono` crate in the public API.	no
`uuid-0_8`	Enable support for v0.8 of the `uuid` crate in the public API.	no
`uuid-1`	Enable support for v1.x of the `uuid` crate in the public API.	no
`time-0_3`	Enable support for v0.3 of the `time` crate in the public API.	no
`serde_with`	Enable `serde_with` 1.x integrations for `DateTime` and `Uuid`.	no
`serde_with-3`	Enable `serde_with` 3.x integrations for `DateTime` and `Uuid`.	no
`serde_path_to_error`	Enable support for error paths via integration with `serde_path_to_error`. This is an unstable feature and any breaking changes to `serde_path_to_error` may affect usage of it via this feature.	no

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

use bson::{bson, Bson};

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

use bson::{bson, Bson};

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

Documents can be created directly either from a byte reader containing BSON data or via the doc! macro:

use bson::{doc, Document};
use std::io::Read;

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:

use bson::doc;

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

use serde::{Deserialize, Serialize};
use bson::{bson, Bson};

#[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.

When serializing values that cannot be represented in BSON, or deserialzing from BSON that does not match the format expected by the type, the default error will only report the specific field that failed. To aid debugging, enabling the serde_path_to_error feature will augment errors with the full field path from root object to failing field. This feature does incur a small CPU and memory overhead during (de)serialization and should be enabled with care in performance-sensitive environments.

§Working with datetimes

The BSON format includes a datetime type, which is modeled in this crate by the DateTime struct, and the Serialize and Deserialize implementations for this struct produce and parse BSON datetimes when serializing to or deserializing from BSON. The popular crate chrono also provides a DateTime type, but its Serialize and Deserialize implementations operate on strings instead, so when using it with BSON, the BSON datetime type is not used. To work around this, the chrono-0_4 feature flag can be enabled. This flag exposes a number of convenient conversions between bson::DateTime and chrono::DateTime, including the serde_helpers::chrono_datetime_as_bson_datetime serde helper, which can be used to (de)serialize chrono::DateTimes to/from BSON datetimes, and the From<chrono::DateTime> implementation for Bson, which allows chrono::DateTime values to be used in the doc! and bson! macros.

e.g.

use serde::{Serialize, Deserialize};
use bson::doc;

#[derive(Serialize, Deserialize)]
struct Foo {
    // serializes as a BSON datetime.
    date_time: bson::DateTime,

    // serializes as an RFC 3339 / ISO-8601 string.
    chrono_datetime: chrono::DateTime<chrono::Utc>,

    // serializes as a BSON datetime.
    // this requires the "chrono-0_4" feature flag
    #[serde(with = "bson::serde_helpers::chrono_datetime_as_bson_datetime")]
    chrono_as_bson: chrono::DateTime<chrono::Utc>,
}

// this automatic conversion also requires the "chrono-0_4" feature flag
let query = doc! {
    "created_at": chrono::Utc::now(),
};

§Working with UUIDs

See the module level documentation for the uuid module.

§WASM support

This crate compiles to the wasm32-unknown-unknown target; when doing so, the js-sys crate is used for the current timestamp component of ObjectId generation.

§Minimum supported Rust version (MSRV)

The MSRV for this crate is currently 1.81. This will be rarely be increased, and if it ever is, it will only happen in a minor or major version release.

Re-exports§

pub use self::de::from_reader_utf8_lossy;
pub use self::de::from_slice_utf8_lossy;

Modules§

binary
datetime: Module containing functionality related to BSON DateTimes. For more information, see the documentation for the DateTime type.
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: Module containing functionality related to BSON ObjectIds. For more information, see the documentation for the ObjectId type.
raw: An API for interacting with raw BSON bytes.
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.
uuid: UUID support for BSON.

Macros§

bson: Construct a bson::BSON value from a literal.
doc: Construct a bson::Document value.
rawbson: Construct a crate::RawBson value from a literal.
rawdoc: Construct a crate::RawDocumentBuf value.

Structs§

Binary: Represents a BSON binary value.
DateTime: Struct representing a BSON datetime. Note: BSON datetimes have millisecond precision.
DbPointer: Represents a DBPointer. (Deprecated)
Decimal128: Struct representing a BSON Decimal128 type.
Deserializer: Serde Deserializer
DeserializerOptions: Options used to configure a Deserializer. These can also be passed into crate::from_bson_with_options and crate::from_document_with_options.
Document: A BSON document represented as an associative HashMap with insertion ordering.
JavaScriptCodeWithScope: Represents a BSON code with scope value.
RawArray: A slice of a BSON document containing a BSON array value (akin to std::str). This can be retrieved from a RawDocument via RawDocument::get.
RawArrayBuf: An owned BSON array value (akin to std::path::PathBuf), backed by a buffer of raw BSON bytes. This type can be used to construct owned array values, which can be used to append to RawDocumentBuf or as a field in a Deserialize struct.
RawBinaryRef: A BSON binary value referencing raw bytes stored elsewhere.
RawDbPointerRef: A BSON DB pointer value referencing raw bytes stored elesewhere.
RawDocument: A slice of a BSON document (akin to std::str). This can be created from a RawDocumentBuf or any type that contains valid BSON data, including static binary literals, Vec<u8>, or arrays.
RawDocumentBuf: An owned BSON document (akin to std::path::PathBuf), backed by a buffer of raw BSON bytes. This can be created from a Vec<u8> or a crate::Document.
RawJavaScriptCodeWithScope: A BSON “code with scope” value backed by owned raw BSON.
RawJavaScriptCodeWithScopeRef: A BSON “code with scope” value referencing raw bytes stored elsewhere.
RawRegexRef: A BSON regex referencing raw bytes stored elsewhere.
Regex: Represents a BSON regular expression value.
Serializer: Serde Serializer
SerializerOptions: Options used to configure a Serializer.
Timestamp: Represents a BSON timestamp value.
Uuid: A struct modeling a BSON UUID value (i.e. a Binary value with subtype 4).

Enums§

Bson: Possible BSON value types.
RawBson: A BSON value backed by owned raw BSON bytes.
RawBsonRef: A BSON value referencing raw bytes stored elsewhere.
UuidRepresentation: Enum of the possible representations to use when converting between Uuid and Binary. This enum is necessary because the different drivers used to have different ways of encoding UUIDs, with the BSON subtype: 0x03 (UUID old). If a UUID has been serialized with a particular representation, it MUST be deserialized with the same representation.

Functions§

from_bson: Deserialize a T from the provided Bson value.
from_bson_with_options: Deserialize a T from the provided Bson value, configuring the underlying deserializer with the provided options.
from_document: Deserialize a T from the provided Document.
from_document_with_options: Deserialize a T from the provided Document, configuring the underlying deserializer with the provided options.
from_reader: Deserialize an instance of type T from an I/O stream of BSON.
from_slice: Deserialize an instance of type T from a slice of BSON bytes.
to_bson: Encode a T Serializable into a Bson value.
to_bson_with_options: Encode a T into a Bson value, configuring the underlying serializer with the provided options.
to_document: Encode a T Serializable into a BSON Document.
to_document_with_options: Encode a T into a Document, configuring the underlying serializer with the provided options.
to_raw_document_buf: Serialize the given T as a RawDocumentBuf.
to_vec: Serialize the given T as a BSON byte vector.

Type Aliases§

Array: Alias for Vec<Bson>.

Crate bsonCopy item path