Expand description
Rocia DB SDK client for gRPC upstream services.
The client speaks to a RociaDB server over gRPC and covers four service
areas: documents, graph nodes and edges, file transfer, and tenants.
Every call goes through a single RociaDbClient, built by
RociaDbBuilder, which owns the connection and the auth token refresh.
§Quick example
use rociadb_sdk::RociaDbBuilder;
use serde_json::json;
let client = RociaDbBuilder::new()
.host("http://127.0.0.1:50051")
.auth_client_credentials(
"https://example.com/token",
"client-id",
"client-secret",
)
.build()
.await?;
client
.create_document(
"tenant-1",
"products",
"sku-123",
json!({"sku": "sku-123"}),
Some("product".to_string()),
Some("products".to_string()),
)
.await?;§Building
The build script compiles the .proto files bundled with this crate, so
protoc must be available on any machine that compiles it, including
CI: either on PATH, or at the location given by the PROTOC environment
variable. Nothing else is needed from the system — the Google well-known
types the API uses ship inside the crate.
§Example project
example-rust-project
wires this SDK into a runnable program, end to end.
§Where things live
Document, graph, file and tenant calls are all inherent methods on
RociaDbClient, so the module list is short:
auth— token acquisition and refresh, and the interceptors that attach credentials to outgoing calls. Useful when you drive authentication yourself rather than through the builder.file— the option types for uploads (FileUploadOptions,FileStreamUploadOptions) and the chunking rules the wire contract imposes.graph— the page and node types returned by neighbor traversal (NeighborPage,NeighborNode).
§Stability
The public API follows semantic versioning from 1.0.0 onward, with one
documented exception: the internal pb module holds code generated from
the .proto files by prost and tonic, and is not covered by that promise.
A routine prost or
tonic upgrade can reshape those generated types without this SDK’s own API
changing. Five of them — CollectionInfo, StatResponse,
Neighbor, UploadRequest and DownloadResponse — appear in public
signatures and are re-exported at the crate root for that reason; depend on
the re-exports: the pb module itself is private.
Re-exports§
pub use file::FileStreamUploadOptions;pub use file::FileUploadOptions;pub use graph::NeighborNode;pub use graph::NeighborPage;
Modules§
- auth
- Auth helpers for bearer tokens and API keys.
- file
- File upload/download helpers.
- graph
- Graph node and edge operations: single-item reads and writes, batch upserts with bounded concurrency, and paginated neighbor traversal.
Structs§
- Collection
Info - Generated protobuf types that appear directly in a public method signature,
re-exported here so callers can name them without depending on the crate’s
private
pbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. Generated protobuf types that appear directly in a public method signature, re-exported here so callers can name them without depending on the crate’s privatepbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. Generated protobuf types that appear directly in a public method signature, re-exported here so callers can name them without depending on the crate’s privatepbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. - Document
Page - One page of document results, together with the total number of
documents matching the request (before pagination).
itemsandnext_cursorfollow the same contract asPage<T>. - Document
Query Filter - Filter definition for
QueryDoc. - Document
Query Sort - Sort definition for
QueryDoc. - Download
Response - Generated protobuf types that appear directly in a public method signature,
re-exported here so callers can name them without depending on the crate’s
private
pbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. Generated protobuf types that appear directly in a public method signature, re-exported here so callers can name them without depending on the crate’s privatepbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. Generated protobuf types that appear directly in a public method signature, re-exported here so callers can name them without depending on the crate’s privatepbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. - Edge
Input - One edge to upsert, used by
RociaDbClient::add_edges. - Neighbor
- Generated protobuf types that appear directly in a public method signature,
re-exported here so callers can name them without depending on the crate’s
private
pbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. Generated protobuf types that appear directly in a public method signature, re-exported here so callers can name them without depending on the crate’s privatepbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. Generated protobuf types that appear directly in a public method signature, re-exported here so callers can name them without depending on the crate’s privatepbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. - Node
Input - One node to upsert, used by
RociaDbClient::put_nodes. - Page
- One page of listed items with the cursor for the next page.
- Rocia
DbBuilder - Builder for RociaDbClient.
- Rocia
DbClient - gRPC client for document, graph, file, and tenant services.
- Stat
Response - Generated protobuf types that appear directly in a public method signature,
re-exported here so callers can name them without depending on the crate’s
private
pbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. Generated protobuf types that appear directly in a public method signature, re-exported here so callers can name them without depending on the crate’s privatepbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. Generated protobuf types that appear directly in a public method signature, re-exported here so callers can name them without depending on the crate’s privatepbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. - Streaming
- Re-exported so callers do not need
tonicas a direct dependency just to name the return type ofRociaDbClient::download_file_stream. The same stability caveat applies: a major tonic upgrade can reshape this type without the SDK’s own API changing. Streaming requests and responses. - Upload
Request - Generated protobuf types that appear directly in a public method signature,
re-exported here so callers can name them without depending on the crate’s
private
pbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. Generated protobuf types that appear directly in a public method signature, re-exported here so callers can name them without depending on the crate’s privatepbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing. Generated protobuf types that appear directly in a public method signature, re-exported here so callers can name them without depending on the crate’s privatepbmodule. The stability caveat in the crate documentation applies to them: a prost or tonic upgrade can reshape these types without the SDK’s own API changing.
Enums§
- Document
Query Operator - Supported document query operators exposed by the SDK.
- Document
Query Sort Direction - Supported document sort directions exposed by the SDK.
- Rocia
DbError - Error returned by the SDK.
Type Aliases§
- Result
- Result alias used throughout the public API.