Pure Elixir document struct with type-tagged fields for zvec collections.
Fields are stored as %{"field_name" => {type_atom, value}} to preserve
type information through NIF marshaling boundaries.
Example
alias Zvex.Document
alias Zvex.Vector
doc =
Document.new()
|> Document.put_pk("doc-1")
|> Document.put("title", "Hello world")
|> Document.put("embedding", Vector.from_list([1.0, 2.0, 3.0], :fp32))
Document.to_map(doc)
#=> %{"title" => "Hello world", "embedding" => <<...>>}Summary
Functions
Returns a new empty document, discarding all fields and the primary key.
Deserializes a binary produced by serialize/1 back into a document.
Like deserialize/1 but raises on error.
Returns a human-readable string describing the document's fields and types.
Like detail_string/1 but raises on error.
Returns true if the document has no fields and no primary key set.
Returns true if the field exists and its value is nil.
Returns the list of field names present in the document.
Builds a document from a plain map using the schema for type resolution.
Reconstructs a document from the internal NIF map format.
Returns true if the document contains a field named field.
Returns the estimated memory usage of the document in bytes.
Like memory_usage/1 but raises on error.
Merges two documents. Fields from doc2 overwrite those in doc1.
The primary key is taken from doc2 if set, otherwise from doc1.
Creates an empty document with no fields and no primary key.
Sets a field value on the document.
Sets a field with an explicit type atom, bypassing automatic type inference.
Sets a field to null (type :null, value nil).
Sets the primary key for this document. Must be a string.
Removes a field from the document by name. No-op if the field does not exist.
Serializes the document to a compact binary representation via the native layer.
Like serialize/1 but raises on error.
Converts the document to a plain map, stripping type information from field values.
Converts the document to the internal map format expected by the NIF layer.
Converts one or more documents to a list of NIF-ready maps.
Validates the document against a schema.
Types
@type t() :: %Zvex.Document{ fields: %{required(String.t()) => {atom(), term()}}, pk: String.t() | nil }
A typed document for insertion into a zvec collection.
:fields— map of"field_name" => {type_atom, value}tuples preserving type information through NIF boundaries.:pk— the primary key value (a string), ornilif not yet set.
Functions
Returns a new empty document, discarding all fields and the primary key.
@spec deserialize(binary()) :: {:ok, t()} | {:error, Zvex.Error.t()}
Deserializes a binary produced by serialize/1 back into a document.
Like deserialize/1 but raises on error.
@spec detail_string(t()) :: {:ok, String.t()} | {:error, Zvex.Error.t()}
Returns a human-readable string describing the document's fields and types.
Like detail_string/1 but raises on error.
Returns true if the document has no fields and no primary key set.
Returns true if the field exists and its value is nil.
Returns the list of field names present in the document.
@spec from_map(map(), Zvex.Collection.Schema.t()) :: t()
Builds a document from a plain map using the schema for type resolution.
Keys in map that don't match a schema field are silently ignored.
The primary key field is used to set both the :pk and the field entry.
Vector values can be given as plain lists — they are automatically packed
into the schema's vector type.
Reconstructs a document from the internal NIF map format.
Returns true if the document contains a field named field.
@spec memory_usage(t()) :: {:ok, non_neg_integer()} | {:error, Zvex.Error.t()}
Returns the estimated memory usage of the document in bytes.
@spec memory_usage!(t()) :: non_neg_integer()
Like memory_usage/1 but raises on error.
Merges two documents. Fields from doc2 overwrite those in doc1.
The primary key is taken from doc2 if set, otherwise from doc1.
@spec new() :: t()
Creates an empty document with no fields and no primary key.
Sets a field value on the document.
The type is inferred automatically from the value:
Zvex.Vector— uses the vector's typeboolean—:boolbinary/string—:stringinteger—:int64float—:double
Use the 4-arity put/4 to specify an explicit type atom.
Sets a field with an explicit type atom, bypassing automatic type inference.
Sets a field to null (type :null, value nil).
Sets the primary key for this document. Must be a string.
Removes a field from the document by name. No-op if the field does not exist.
@spec serialize(t()) :: {:ok, binary()} | {:error, Zvex.Error.t()}
Serializes the document to a compact binary representation via the native layer.
Like serialize/1 but raises on error.
Converts the document to a plain map, stripping type information from field values.
Converts the document to the internal map format expected by the NIF layer.
Converts one or more documents to a list of NIF-ready maps.
@spec validate(t(), Zvex.Collection.Schema.t()) :: :ok | {:error, Zvex.Error.t()}
Validates the document against a schema.
Checks that the primary key is set (if required), all non-nullable fields are present, field types match, and vector dimensions are correct.