Skip to main content

Crate arcadedb_protocol

Crate arcadedb_protocol 

Source
Expand description

A lightweight gRPC client for ArcadeDB.

Generated tonic stubs for com.arcadedb.grpc, a typed record-decode path (RecordDecode derive + runtime), a serde_json bridge for dynamic access, and nothing else.

§What’s here

  • client::ArcadeDbClient — wraps the data + admin gRPC services (connect with retry, auth headers, execute/query/create_database/ bulk_insert, …). Clone (shares one tonic Channel).
  • error::ArcadeDbError — the typed error for every fallible client call: match on the failure category (transport, server-rejected command, decode, invalid input) and inspect the gRPC code/metadata.
  • JSON bridge (grpc_record_to_json): GrpcRecord → serde_json::Value for callers that need dynamic access. The typed decode path is RecordDecode (see below) — there is no serde Deserializer anymore.
  • record — the typed-decode runtime: record::FromGrpcValue, record::RecordDecodeError, and the property-access helpers used by the generated code.
  • RecordDecode (re-exported derive) — #[derive(RecordDecode)] turns a model struct into TryFrom<&GrpcRecord>+FromGrpcValuewith per-field type coercion, honoring#[serde(rename/default/flatten)]for drop-in adoption. Custom types plug in via the#[record(with = “…”)]attribute or by implementingFromGrpcValue` directly.
  • RecordEncode (re-exported derive) — the write-side mirror: derives record::ToGrpcRecord so bulk writers call dto.to_grpc_record(class) instead of hand-assembling GrpcValue/GrpcRecord protos.
  • Value builders (Params, IntoGrpcValue) for fixture/test code.

§Optional features

  • ahash — aHash maps as first-class wire maps: ahash::AHashMap<String, V> binds as the wire Map (encode) and decodes back into an AHashMap (decode), so a DTO field or a params! value can be an aHash map with no std↔aHash conversion.
  • cache — transient KV facade over the Redis plugin (client.cache()).
  • decimal — exact rust_decimal::Decimal mapping for DECIMAL columns.
  • fxhash — rustc’s FxHash maps as first-class wire maps (rustc_hash::FxHashMap<String, V>), same as the ahash feature.
  • rayon — parallel decode of large batches.
  • serde — serde impls for wire-identity types (Link ↔ rid string).

§What’s NOT here

Identity types and query/repository layers. ArcadeDB’s native RID (#bucket:pos) is the only identifier this crate deals with; apps choose their own logical identity scheme (e.g. table:key or an external id) and build their repo + query functions on top of ArcadeDbClient.

use arcadedb_protocol::ArcadeDbClient;
let client = ArcadeDbClient::connect("127.0.0.1:50051", "root", "password", "mydb").await?;
let res = client.query("mydb", "SELECT FROM item LIMIT 10").await?;
println!("{} rows in {} ms", res.len(), res.execution_time_ms);

Re-exports§

pub use batch::Batch;
pub use batch::ScriptBuffer;
pub use client::consume_stream;
pub use client::ArcadeDbClient;
pub use client::DatabaseClient;
pub use client::QueryResult;
pub use client::QueryResultBatch;
pub use client::StreamSummary;
pub use client::Transaction;
pub use client::TxCommands;
pub use options::ClientOptions;
pub use stream::StreamOptions;
pub use error::ArcadeDbError;
pub use error::Result;
pub use proto::com::arcadedb::grpc::GrpcRecord;
pub use proto::com::arcadedb::grpc::GrpcEmbedded;
pub use proto::com::arcadedb::grpc::GrpcList;
pub use proto::com::arcadedb::grpc::GrpcMap;
pub use proto::com::arcadedb::grpc::GrpcValue;
pub use proto::com::arcadedb::grpc::grpc_value::Kind;
pub use record::changed_param_map;
pub use record::from_map_via_value;
pub use record::props_diff;
pub use record::DecodeFromMap;
pub use record::FromGrpcValue;
pub use record::RecordDecodeError;
pub use record::ToGrpcRecord;
pub use proto::com::arcadedb::grpc::arcade_db_admin_service_client::ArcadeDbAdminServiceClient;
pub use proto::com::arcadedb::grpc::arcade_db_service_client::ArcadeDbServiceClient;
pub use proto::com::arcadedb::grpc::ExecuteCommandResponse;
pub use proto::com::arcadedb::grpc::InsertSummary;

Modules§

admin
Admin operations — the ArcadeDbClient::admin facade.
batch
Multi-statement units — the ArcadeDbClient::batch facade.
error
The client-facing error type: every fallible ArcadeDbClient / DatabaseClient call returns Result<T, ArcadeDbError> instead of an opaque error. Matching on the failure category distinguishes transport vs. server-rejected vs. decode vs. client-side validation errors, and the gRPC tonic::Code stays inspectable.
options
Connection configuration: the ClientOptions builder.
proto
record
Typed record decoding — the runtime behind crate::RecordDecode.
scan
Full-type/bucket iteration — the ArcadeDbClient::scan facade.
stream
Streaming query options — the ArcadeDbClient::stream_query_with_options builder.
testutil
Throwaway test databases for suites running against a live server.

Macros§

embedded
Assemble an embedded record value — the nestable, value-form sibling of rec: same key: value entry grammar as params!, each field dispatching its own IntoGrpcValue, producing the wire’s embedded (Kind::EmbeddedValue) shape. Values nest and compose: vec![embedded!(..), ..] is a list of embedded values, and a built value rides anywhere a value does (rec fields, params!, SetClause) through the GrpcValue pass-through.
impl_decode_from_map_via_value
Implement DecodeFromMap for a manual FromGrpcValue type through the clone-based from_map_via_value path — for manual types used as #[serde(flatten)] targets. Prefer deriving RecordDecode on flatten targets (zero-copy).
params
Assemble bound parameters with map semantics — the literal form for the client’s *_with_values methods.
sql
sql! — write the statement as a literal, get a syntax check for free.

Structs§

ArcadeDbClient
A lightweight gRPC client for ArcadeDB.
DatabaseClient
An ArcadeDbClient bound to one database: every delegated method drops the database: &str parameter. The connect-time name is the single source of truth, which removes the per-call-site repetition and the wrong-db mistake class.
FilterClause
Accumulates AND-joined WHERE fragments and their bound values.
Params
Bound-parameter map for the client’s *_with_values / execute_with_values methods. Construct it from an array literal (the common case) or wrap an existing map / a RecordEncode DTO’s ToGrpcRecord::to_param_map output.
QueryResult
The result of a SQL query, bundling the returned records with server-side execution timing.
SetClause
Accumulates col = :col SET fragments and their bound values for INSERT INTO … SET … / UPDATE … SET … statements whose shape is only known at runtime (optional fields, conditional writes).
StreamSummary
Accounting for a consumed StreamQuery stream.
Timestamp
The protobuf well-known Timestamp — the wire shape for date/datetime values (Kind::TimestampValue), re-exported for RecordEncode DTOs. A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one.
Transaction
A drop-safe explicit transaction: the guard returned by ArcadeDbClient::transaction. Commands run through the guard; finishing is explicit (commit/rollback both consume self), and a guard dropped unfinished rolls back in a background task — the server’s idle-reaper is the last line of defense.
TxCommands
Commands issued inside ArcadeDbClient::run_transaction’s current attempt — the Transaction guard’s operations without the lifecycle (begin/commit/rollback are the runner’s job).

Traits§

IntoGrpcValue
The encode-side mirror of crate::record::FromGrpcValue: Rust values convert to their natural wire kind, so params! can accept computed expressions and let trait resolution pick the constructor.

Functions§

consume_stream
Consume a StreamQuery batch stream through on_batch, one batch at a time. This is the testable core of ArcadeDbClient::stream_query: generic over any stream of proto batches, so tests drive it with fakes instead of a live server.
grpc_record_to_json
Convert a record’s properties into a JSON object.
grpc_value_to_json
Convert a single typed value. None kind -> null.
json_to_grpc_value
Convert a serde_json value onto the matching wire kind — the inverse of grpc_value_to_json, enabling dynamic (schemaless) ENCODE paths: serde_json::Value DTO fields, API-request payloads bound as :params.
rec
Build a record of type_name from (field, value) pairs — values go through IntoGrpcValue, same coverage as params! (no constructor ceremony at call sites; already-converted GrpcValues pass through). rid is left empty (the server assigns it on insert).

Derive Macros§

RecordDecode
#[derive(RecordDecode)].
RecordEncode
#[derive(RecordEncode)] — the encode-side mirror of RecordDecode: generates ToGrpcRecord (see the module docs for the attribute reference).