nbson is an OTP library to encode/decode BSON documents from/to Erlang terms.
%%% e.g., rebar.config
{deps, [
{nbson, {git, "git@github.com:nomasystems/nbson.git", {branch, "main"}}}
]}.nbson exposes utilities via its API that allows you to:
| Function | Description |
|---|---|
nbson:encode/1 |
Serialize an Erlang term to BSON |
nbson:decode/2 |
Deserialize a BSON to an Erlang term |
nbson represents BSONs as Erlang proplists with tuple values only.
Produced proplists' keys are binaries and value types depend on the associated BSON type.
The following table represents the association between Erlang types and BSON types on serialization.
| Erlang Data Type | BSON Types |
|---|---|
float() |
Double (1) |
binary() |
String (2) |
[ tuple() | _ ] |
Object (3) |
list() |
Array (4) |
{data, binary, binary()} |
Binary data (5) |
{vector, int8, [integer()]} |
Binary Vector INT8 (5, subtype 9) |
{vector, float32, [float()]} |
Binary Vector FLOAT32 (5, subtype 9) |
{vector, packed_bit, binary()} |
Binary Vector PACKED_BIT (5, subtype 9) |
{vector, packed_bit, binary(), 0..7} |
Binary Vector PACKED_BIT with padding (5, subtype 9) |
undefined |
Undefined (6) |
{object_id, <<_:96>>} |
ObjectId (7) |
false | true |
Boolean (8) |
{integer(), integer(), integer()} |
Date (9) |
null |
Null (10) |
{regex, charlist(), charlist()} |
Regular Expression (11) |
{pointer, binary(), <<_:96>>} |
DBPointer (12) |
{javascript, [{}], binary()} |
JavaScript (13) |
Atom :: atom() when Atom =/= min_key, Atom =/= max_key |
Symbol (14) |
{javascript, [ tuple() | _ ], binary()} |
JavaScript code with scope (15) |
I32 :: integer() when -16#80000000 =< I32, I32 =< 16#7fffffff |
32-bit integer (16) |
{timestamp, binary(), binary()} |
Timestamp (17) |
I64 :: integer() when -16#8000000000000000 =< I64, I64 =< 16#7fffffffffffffff |
64-bit integer (18) |
{long, I64 :: integer()} when -16#8000000000000000 =< I64, I64 =< 16#7fffffffffffffff |
64-bit integer (18) |
max_key |
Max key (127) |
min_key |
Min key (-1) |
On deserialization, we prevent the dynamic generation of atoms by converting BSON Symbol, Max Key and Min Key values to Erlang binaries.
nbson supports BSON Binary Subtype 9 for efficient storage of dense numeric vectors, useful for AI/ML applications and semantic search.
| Vector Type | Erlang Representation | Value Range |
|---|---|---|
| INT8 | {vector, int8, [integer()]} |
-128 to 127 |
| FLOAT32 | {vector, float32, [float()]} |
IEEE 754 single-precision (supports infinity, neg_infinity) |
| PACKED_BIT | {vector, packed_bit, binary()} |
Raw bytes (0-255) representing packed bits |
| PACKED_BIT | {vector, packed_bit, binary(), Padding} |
With padding (0-7 bits to ignore in final byte) |
%% INT8 vector
{ok, Bin} = nbson:encode(#{<<"embedding">> => {vector, int8, [127, -128, 0, 42]}}).
{ok, #{<<"embedding">> := {vector, int8, [127, -128, 0, 42]}}} = nbson:decode(Bin).
%% FLOAT32 vector with special values
{ok, Bin} = nbson:encode(#{<<"v">> => {vector, float32, [1.5, infinity, neg_infinity]}}).
%% PACKED_BIT vector with padding (13 bits = 2 bytes with 3 bits padding)
{ok, Bin} = nbson:encode(#{<<"bits">> => {vector, packed_bit, <<255, 248>>, 3}}).The BSON decoder implementation in nbson_decoder.erl uses CPS. In this particular case, CPS leads to the use of the sub binary delayed optimization and improved efficiency in the deserialization process.
The nbson_bench repository hosts benchmarks to measure the decoding and encoding times of different BSONs compared to other equivalent tools.
Check out the nbson_SUITE.erl file under tests to see some examples of BSONs and their Erlang representation.
Any doubt or suggestion? Please check out our issue tracker.