Arcadic.Param (Arcadic v0.7.0)

Constructors for ArcadeDB's typed-JSON param value-wrappers — an efficient way to send a byte array or an INT8-quantized vector as a bound parameter instead of a verbose JSON number array.

A param VALUE that is a single-key JSON object {"$int8" => …} or {"$bytes" => …} is decoded server-side to a Java byte[] before the query runs (ArcadeDB's HTTP command handler). The statement still references the parameter by the normal per-language placeholder (:name for SQL, $name for Cypher):

# SQL: insert an int8 vector into a BINARY property
Arcadic.command(conn, "INSERT INTO Doc SET embedding = :e", %{"e" => Arcadic.Param.int8([0, 64, 127, -1, -128])}, language: "sql")

Caveats (documented, not enforced)

HTTP transport only. The decode lives in ArcadeDB's HTTP handler; the marker is inert over Bolt (Bolt sends the map through unchanged).
Requires ArcadeDB ≥ 26.5.1 (the marker decode shipped in 26.5.1).
Ambient single-key collision. ArcadeDB decodes ANY single-key {"$int8" => …} / {"$bytes" => …} in params — so a legitimate caller value that happens to be exactly a single-key map with that key is reinterpreted as a byte[]. Arcadic.Param does not cause this (it exposes the same server behavior arcadic's plain param passthrough already exposes); add a second key to a map you want left untouched.

Summary

Functions

bytes(bin)

Base64-encode a binary as the $bytes marker %{"$bytes" => base64}. Raises value-free on a non-binary.

int8(list)

Wrap a list of signed-byte integers (each in -128..127) as the $int8 marker %{"$int8" => list}. Raises ArgumentError (value-free) on a non-list or an out-of-range / non-integer element — client-side so the offending value never reaches the server 400 (which echoes it).

Functions

bytes(bin)

@spec bytes(binary()) :: %{required(String.t()) => String.t()}

Base64-encode a binary as the $bytes marker %{"$bytes" => base64}. Raises value-free on a non-binary.

int8(list)

@spec int8([integer()]) :: %{required(String.t()) => [integer()]}