barrel_doc (barrel_docdb v1.0.0)

View Source

Document utilities for barrel_docdb

Provides functions for document manipulation and CBOR document content access.

The module supports two document representations: - Indexed binary: CBOR with structural index for O(1) path access - Erlang map: Standard map for manipulation

All map-like functions work with both representations transparently.

Summary

Types

att_info/0
cbor_doc/0
change/0
db_config/0
db_name/0
db_ref/0
doc/0
doc_info/0
doc_input/0
docid/0
endpoint/0
path/0
rep_options/0
rev_info/0
revid/0
revtree/0
seq/0
seq_string/0
view_name/0
view_result/0

Functions

decode_embedding(Binary)

Decode an embedding entity column back to a vector.

deleted(_)

Check if document is deleted

doc_without_meta(Doc)

Remove metadata fields from document. _-prefixed top-level fields are reserved metadata and are stripped before storage. <<"_embedding">> is extracted separately (see make_doc_record) and stored as a document entity column, never in the body, so it does not affect the revision hash.

encode_embedding(Vector)

Encode an embedding vector for entity-column storage. 32-bit little-endian floats, the same width the vector stores use.

ensure_indexed(Doc)

Alias for normalize/1

filter(Pred, Doc)

Filter key-value pairs using a predicate Returns indexed binary

find(Doc, Key)

Find a key (like maps:find/2) Returns {ok, Value} if found, error if not

fold(Fun, Acc, Doc)

Fold over top-level key-value pairs

from_cbor(CborBin)

Import from plain CBOR (adds index if missing)

from_json(JsonBin)

Import from JSON binary

from_map(Map)

Import from Erlang map (alias for new/1)

generate_docid()

Generate a unique document ID

get(Doc, Path)

Get value at path (lazy - uses index when available)

get(Doc, Path, Default)

Get value at path with default

id(_)

Get document ID

id_rev(_)

Get document ID and revision

is_indexed(_)

Check if binary has barrel index (starts with "CB" magic)

is_key(Doc, Key)

Check if key exists at top level (uses index, no decode)

keys(Doc)

Get all top-level keys (uses index when available)

make_doc_record(Doc0)

Create internal document record from user document. The document's version identity is issued by the writer (barrel_db_server); the record only carries the caller's expected current version (_rev token) for the CAS check.

map(Fun, Doc)

Map a function over all top-level values Returns indexed binary

merge(Doc1, Doc2)

Merge two documents (second overwrites first) Returns indexed binary

new()

Create empty indexed document

new(Map)

Create indexed document from Erlang map

normalize(Doc)

Normalize any input to indexed binary (for storage) Auto-detects: map | indexed binary | plain CBOR

remove(Doc, Key)

Remove a key from the document (returns indexed binary)

rev(_)

Get document revision

set(Doc, Path, Value)

Set value at path (returns indexed binary)

size(Doc)

Get number of top-level entries

take(Doc, Key)

Remove and return value at key Returns {Value, UpdatedDoc} or error if key not found

to_cbor(Doc)

Export to plain CBOR (without index) Use when sending to external clients

to_json(Doc)

Export to JSON binary

to_list(Doc)

Convert to list of {Key, Value} tuples (top-level only)

to_map(Doc)

Export to Erlang map (full decode) Handles both indexed CBOR and plain CBOR

update(Doc, Path, Fun)

Update value at path using a function (returns indexed binary) Fun is called with current value (or undefined if not present)

values(Doc)

Get all values (top-level only)

Types

att_info/0

-type att_info() ::
          #{name := binary(),
            content_type := binary(),
            length := non_neg_integer(),
            digest := binary(),
            chunked => boolean(),
            chunk_size => pos_integer(),
            chunk_count => pos_integer()}.

cbor_doc/0

-type cbor_doc() :: binary().

change/0

-type change() :: map().

db_config/0

-type db_config() :: #{path => string(), store => module(), atom() => term()}.

db_name/0

-type db_name() :: binary().

db_ref/0

-type db_ref() :: pid() | atom().

doc/0

-type doc() :: #{binary() => term()}.

doc_info/0

-type doc_info() :: #{id := docid(), rev := revid(), deleted := boolean(), revtree := revtree()}.

doc_input/0

-type doc_input() :: map() | cbor_doc().

docid/0

-type docid() :: binary().

endpoint/0

-type endpoint() :: db_name() | {node(), db_name()} | {module(), term()}.

path/0

-type path() :: [binary() | integer()].

rep_options/0

-type rep_options() ::
          #{continuous => boolean(),
            since => seq_string(),
            filter => fun((doc()) -> boolean()),
            atom() => term()}.

rev_info/0

-type rev_info() ::
          #{id := revid(),
            parent := revid() | undefined,
            deleted := boolean(),
            attachments => #{binary() => att_info()}}.

revid/0

-type revid() :: binary().

revtree/0

-type revtree() :: #{revid() => rev_info()}.

seq/0

-type seq() :: barrel_hlc:timestamp().

seq_string/0

-type seq_string() :: binary().

view_name/0

-type view_name() :: binary().

view_result/0

-type view_result() :: #{key := term(), value := term(), id := docid()}.

Functions

decode_embedding(Binary)

-spec decode_embedding(binary()) -> [float()].

Decode an embedding entity column back to a vector.

deleted(_)

-spec deleted(doc()) -> boolean().

Check if document is deleted

doc_without_meta(Doc)

-spec doc_without_meta(doc()) -> doc().

Remove metadata fields from document. _-prefixed top-level fields are reserved metadata and are stripped before storage. <<"_embedding">> is extracted separately (see make_doc_record) and stored as a document entity column, never in the body, so it does not affect the revision hash.

encode_embedding(Vector)

-spec encode_embedding([number()]) -> binary().

Encode an embedding vector for entity-column storage. 32-bit little-endian floats, the same width the vector stores use.

ensure_indexed(Doc)

-spec ensure_indexed(doc_input()) -> cbor_doc().

Alias for normalize/1

filter(Pred, Doc)

-spec filter(fun((binary(), term()) -> boolean()), doc_input()) -> cbor_doc().

Filter key-value pairs using a predicate Returns indexed binary

find(Doc, Key)

-spec find(doc_input(), binary()) -> {ok, term()} | error.

Find a key (like maps:find/2) Returns {ok, Value} if found, error if not

fold(Fun, Acc, Doc)

-spec fold(fun((binary(), term(), Acc) -> Acc), Acc, doc_input()) -> Acc.

Fold over top-level key-value pairs

from_cbor(CborBin)

-spec from_cbor(binary()) -> cbor_doc().

Import from plain CBOR (adds index if missing)

from_json(JsonBin)

-spec from_json(binary()) -> cbor_doc().

Import from JSON binary

from_map(Map)

-spec from_map(map()) -> cbor_doc().

Import from Erlang map (alias for new/1)

generate_docid()

-spec generate_docid() -> docid().

Generate a unique document ID

get(Doc, Path)

-spec get(doc_input(), path()) -> term() | undefined.

Get value at path (lazy - uses index when available)

get(Doc, Path, Default)

-spec get(doc_input(), path(), term()) -> term().

Get value at path with default

id(_)

-spec id(doc()) -> docid() | undefined.

Get document ID

id_rev(_)

-spec id_rev(doc()) -> {docid() | undefined, revid()}.

Get document ID and revision

is_indexed(_)

-spec is_indexed(binary() | map()) -> boolean().

Check if binary has barrel index (starts with "CB" magic)

is_key(Doc, Key)

-spec is_key(doc_input(), binary()) -> boolean().

Check if key exists at top level (uses index, no decode)

keys(Doc)

-spec keys(doc_input()) -> [binary()].

Get all top-level keys (uses index when available)

make_doc_record(Doc0)

-spec make_doc_record(doc()) -> map().

Create internal document record from user document. The document's version identity is issued by the writer (barrel_db_server); the record only carries the caller's expected current version (_rev token) for the CAS check.

map(Fun, Doc)

-spec map(fun((binary(), term()) -> term()), doc_input()) -> cbor_doc().

Map a function over all top-level values Returns indexed binary

merge(Doc1, Doc2)

-spec merge(doc_input(), doc_input()) -> cbor_doc().

Merge two documents (second overwrites first) Returns indexed binary

new()

-spec new() -> cbor_doc().

Create empty indexed document

new(Map)

-spec new(map()) -> cbor_doc().

Create indexed document from Erlang map

normalize(Doc)

-spec normalize(doc_input()) -> cbor_doc().

Normalize any input to indexed binary (for storage) Auto-detects: map | indexed binary | plain CBOR

remove(Doc, Key)

-spec remove(doc_input(), binary()) -> cbor_doc().

Remove a key from the document (returns indexed binary)

rev(_)

-spec rev(doc()) -> revid().

Get document revision

set(Doc, Path, Value)

-spec set(doc_input(), path(), term()) -> cbor_doc().

Set value at path (returns indexed binary)

size(Doc)

-spec size(doc_input()) -> non_neg_integer().

Get number of top-level entries

take(Doc, Key)

-spec take(doc_input(), binary()) -> {term(), cbor_doc()} | error.

Remove and return value at key Returns {Value, UpdatedDoc} or error if key not found

to_cbor(Doc)

-spec to_cbor(doc_input()) -> binary().

Export to plain CBOR (without index) Use when sending to external clients

to_json(Doc)

-spec to_json(doc_input()) -> binary().

Export to JSON binary

to_list(Doc)

-spec to_list(doc_input()) -> [{binary(), term()}].

Convert to list of {Key, Value} tuples (top-level only)

to_map(Doc)

-spec to_map(doc_input()) -> map().

Export to Erlang map (full decode) Handles both indexed CBOR and plain CBOR

update(Doc, Path, Fun)

-spec update(doc_input(), path(), fun((term()) -> term())) -> cbor_doc().

Update value at path using a function (returns indexed binary) Fun is called with current value (or undefined if not present)

values(Doc)

-spec values(doc_input()) -> [term()].

Get all values (top-level only)