Crate tricoredb

Expand description

Blocking Rust client for TriCoreDB: SQL, documents, cache, vectors, graphs and LLM context over one connection.

It speaks TriCoreDB’s own tricore protocol directly over TCP, optionally inside TLS. There is no async runtime: calls block, and a Pool is what serves concurrent work.

use tricoredb::{params, Client, Options};

let mut db = Client::connect(&Options::new("127.0.0.1", 8427).user("admin").secret("pw"))?;

db.execute("CREATE TABLE IF NOT EXISTS users (id INT PRIMARY KEY, name TEXT)")?;
db.execute_params("INSERT INTO users VALUES (?, ?)", &params![1, "O'Hara"])?;

let rows = db.query_params("SELECT name FROM users WHERE id = ?", &params![1])?;
assert_eq!(rows.get(0, "name"), Some("O'Hara"));

db.cache_set("sessions", "u1", b"token")?;
let token = db.cache_get("sessions", "u1")?; // None on a miss

§One connection, one request at a time

The protocol is a single request/response stream, so every call takes &mut self. Sharing a Client between threads does not compile, which is the frame interleaving this design rules out rather than documents. Use a Pool when you need several requests at once.

§Values are bound by the server

Client::execute_params and Client::query_params send the values beside the statement; the server substitutes them at positions its grammar has already fixed, so a value can never be read as SQL. When a server does not offer that capability, those calls fail before sending anything instead of quietly building the statement text here — see ErrorKind::FeatureNotGranted.

§Errors

Every fallible call returns Error. Branch on Error::kind and Error::code, never on the message text. A write refused by a follower in a cluster has Error::is_redirect true and, when the cluster knows one, Error::leader_hint. By default the client follows it itself: see Options::follow_leader.

§Features

tls (default): TLS and mutual TLS through TlsOptions, built on rustls. Turn it off for a build with no cryptography dependencies.

Macros§

params: Build a Vec<Param> from heterogeneous values.

Structs§

AccumulatorOp: One reduction inside a group stage.
AggregateStage: One stage of an aggregation pipeline.
BulkWriteResult: What Client::document_bulk_write applied.
CacheCommand: One cache operation inside Client::cache_pipeline, Client::cache_transaction or a script.
CacheEntry: One key and its value, as Client::cache_mset and Client::cache_warm take them.
CacheEvictionStats: The evictor in CacheStats.
CacheKeyInfo: One live key in a namespace.
CacheLock: The answer to Client::cache_lock_acquire.
CacheLockRenewal: The answer to Client::cache_lock_renew.
CacheMemoryStats: The memory budget in CacheStats.
CachePair: One (field, value) entry of a hash or a stream.
CacheStats: What one node’s cache is doing. Node-wide, not per database.
CentralityOptions: What Client::graph_centrality should compute over.
ChannelMessage: One message read by Client::cache_poll.
Client: One session with a TriCoreDB server.
CollectionOptions: Rules a collection applies to every document written into it.
CommunityOptions: What Client::graph_communities should consider.
CompareAndSwap: The answer to Client::cache_compare_and_swap.
ComponentOptions: What Client::graph_connected_components should consider.
DocumentCommit: What Client::document_commit_transaction landed.
DocumentFilter: A query predicate.
DocumentIndex: One secondary index on a collection.
DocumentPlan: How a find ran, as Client::document_explain reports it.
DocumentSchema: A document shape: required paths, per-path rules, and whether top-level fields the schema does not name are allowed.
DocumentStats: What Client::document_analyze measured.
DocumentUpdate: Field changes applied to one document: set overwrites the value at a dot path, inc adds a number to it. Every set happens before every inc.
Embedding: What Client::vector_embed produced.
Error: Any failure from the transport, the protocol or the server.
ExpireAtOutcome: What Client::cache_expire_at did.
ExplainOptions: What Client::document_explain should run. The default explains an unbounded, unsorted find.
FieldRule: What one field may hold. Every rule given must pass.
Frame: One decoded frame.
FreshRead: The answer to Client::cache_get_fresh.
FusedHit: One hit of a fused ranking.
FusedSearchResult: The answer to Client::vector_search_multi.
GraphCentrality: The answer to Client::graph_centrality.
GraphCommunities: The communities of a graph, largest first.
GraphComponents: The connected components of a graph, largest first.
GraphConsistency: The answer to Client::graph_check_consistency.
GraphConstraint: One constraint.
GraphCounts: How many nodes and edges a batch write or a copy handled.
GraphCycle: One cycle, as the evidence Client::graph_detect_cycle returns.
GraphCycleCheck: The answer to Client::graph_detect_cycle.
GraphEdge: One stored edge, directed from one node to another.
GraphEdgeInput: One edge of Client::graph_add_many.
GraphEdgePage: One page of a graph’s edges.
GraphEdgeTypeSchema: One edge type in a GraphSchema.
GraphFindings: One class of finding in a GraphConsistency.
GraphFoundNodes: The answer to Client::graph_find_nodes.
GraphGroup: One group of nodes: a connected component, or a community.
GraphIndex: One node index.
GraphLabelSchema: One node label, or the unlabelled nodes, in a GraphSchema.
GraphMirrorCheck: How the resident mirror compares with storage.
GraphNeighbor: One edge incident to a node, and the node at its other end.
GraphNode: One stored node.
GraphNodeInput: One node of Client::graph_add_many.
GraphNodePage: One page of a graph’s nodes.
GraphNodeTriangles: One node’s triangles.
GraphPageRank: The answer to Client::graph_page_rank.
GraphPath: The outcome of a path search.
GraphPathEntry: One path of a GraphPaths.
GraphPaths: Several paths between two nodes.
GraphPropertySchema: One property key seen on a label or an edge type.
GraphRemoved: What Client::graph_remove_many deleted.
GraphRows: The result of a Cypher query.
GraphSchema: What a graph’s data looks like.
GraphSchemaObjects: A graph’s indexes and constraints.
GraphScore: One node and the score an algorithm gave it.
GraphStats: Counts describing a graph.
GraphSubgraph: The part of a graph around some seed nodes.
GraphTraversal: The outcome of a bounded breadth-first walk.
GraphTriangles: The answer to Client::graph_triangle_count.
GraphVisit: One node reached by a traversal.
GraphWriteSummary: What a Cypher write changed.
GroupAccumulator: An accumulator and the field it writes into the grouped document.
GroupKey: How AggregateStage::group derives a group key.
IndexRebuild: What Client::document_rebuild_index rebuilt.
KPathOptions: What Client::graph_k_shortest_paths should search.
LlmOptions: What to include in an export, and what to hide.
LlmSource: One read-only source contributing to a context bundle.
NamedVector: One named vector declared on a collection.
NamespaceLimit: A namespace’s limit and what it holds now.
NeighborOptions: What Client::graph_neighbors should include. The default follows outgoing edges of every label, up to the server’s cap.
NodeUpdate: What Client::graph_update_node should change. The default changes nothing.
Options: What to connect to, and how.
PageRankOptions: What Client::graph_page_rank should compute.
PathOptions: What Client::graph_shortest_path should search.
PolledMessages: One page of messages from Client::cache_poll.
Pool: A bounded, thread-safe pool of connections.
PurgeCounts: What Client::document_purge_expired removed.
RecallOptions: What Client::vector_measure_recall should sample. Every None leaves the server’s default.
ReplaceOptions: How Client::document_replace behaves. The default refuses a missing document, returns no document and checks no version.
ReplaceResult: What Client::document_replace did.
Response: A decoded RESPONSE frame.
Rows: A SQL result set: the column names, and each row’s values as the server rendered them.
ScoreBound: One end of a score range.
ScoredMember: One member of a sorted set and its score.
SimilarityOptions: What Client::graph_node_similarity should compare.
SortKey: One sort key. After a group stage the addressable fields are _id and the accumulator outputs, not the original document’s fields.
SparseVector: A sparse vector: parallel lists of term indices and their weights.
Statement: One statement of a transaction script, with the values bound to its placeholders.
StreamEntry: One entry of a stream.
TextUpsert: One text of Client::vector_upsert_text.
TlsOptions: How the TLS session is set up.
TransactionResult: What the server did with a transaction.
TraverseOptions: What Client::graph_traverse should walk. The default walks outgoing edges of every label to the server’s default depth and node limit.
TrimCounts: What Client::cache_ltrim left behind.
UpdateCounts: What Client::document_update_many changed.
VectorAlias: One alias and the collection it names.
VectorCollectionInfo: A collection’s metadata and its live vector count.
VectorCollectionSummary: One entry of Client::vector_list_collections.
VectorConfig: A collection’s configuration after Client::vector_set_collection_config.
VectorConfigChange: What Client::vector_set_collection_config should change. A None leaves that setting as it is.
VectorHit: One search result.
VectorIndexRebuild: What Client::vector_rebuild_index did.
VectorIndexStats: The shape of a collection’s search index.
VectorItem: One stored vector and its metadata.
VectorPage: One page of Client::vector_list_vectors.
VectorPartition: One partition of a collection.
VectorPartitions: The partitions of a collection, as Client::vector_list_partitions reports them.
VectorRecall: The recall Client::vector_measure_recall measured.
VectorSearchOptions: What a batch or example search should apply beyond its query vectors.
VectorSearchResult: A search’s hits, and which path answered it.
VectorUpsert: One vector of Client::vector_upsert_many.
WarmCounts: What Client::cache_warm did.
WeightedPathOptions: What Client::graph_weighted_shortest_path should search.
ZAddCounts: What Client::cache_zadd changed.

Enums§

AnnIndex: Which approximate index a search uses.
BitOpKind: The bitwise operation Client::cache_bit_op applies across its sources.
BulkOp: One operation of Client::document_bulk_write.
CacheExpiry: What an operation does with a key’s deadline.
CacheReply: What one operation of a pipeline, transaction or script answered.
CentralityMeasure: The measure Client::graph_centrality computes.
ComponentKind: How Client::graph_connected_components groups nodes.
ConstraintKind: The rule a constraint enforces.
ConstraintTarget: What a constraint applies to.
ErrorKind: What category of failure an Error is.
FieldType: A JSON type a FieldRule can demand. Integer is a number with no fractional part.
FilterStrategy: How a filtered search combines the filter with the index.
FreshState: Which of its four answers Client::cache_get_fresh gave.
FusionMethod: How Client::vector_search_multi merges its queries’ rankings.
GraphDirection: Which edges of a node an operation follows.
ListEnd: Which end of a list an element leaves or joins.
OutputFormat: How the server should render an export.
Param: One SQL parameter.
ReturnDocument: Whether a by-id write hands back the document it touched, and which version of it.
ScoreMetric: The measure a search scores by, when it should differ from the collection’s own metric.
SetCondition: When Client::cache_set_if is allowed to write.
SimilarityMetric: How Client::graph_node_similarity compares neighbour sets.
Tag: A frame tag as it appears on the wire.
VectorExample: One example for Client::vector_search_by_examples: a stored vector named by id, or a vector given outright.
VectorMetric: How a collection measures closeness. Fixed when the collection is created.
VectorQuantization: How the search index stores vectors in memory.

Constants§

ALL_FEATURES: Every capability this build understands, and what Options announces unless Options::features narrows it.
DEFAULT_DATABASE: The database a request names when none was chosen.
DEFAULT_PORT: The port tricore-server listens on unless it was configured otherwise.
FEATURE_CORRELATION_ID: The client understands a request-scoped correlation id that the server joins to its access log, audit trail and cancel registry.
FEATURE_SERVER_PARAMS: The server binds ? placeholders to a typed array sent beside the statement, instead of the client rendering values into the SQL text.
FEATURE_SESSION_TXN: BEGIN, the statements, and COMMIT/ROLLBACK as separate requests on one connection, with a real rollback boundary between them.
FRAME_VERSION: The frame header format version this client writes and the highest it reads.
MAX_CONTROL_PAYLOAD: Payload ceiling for every other (control) frame (64 KiB).
MAX_DATA_PAYLOAD: Payload ceiling for REQUEST and RESPONSE frames (16 MiB).
NOT_LEADER: The error code a Raft follower attaches when it cannot serve a request.
OUTCOME_UNKNOWN: The code of a request a follower handed to the leader and lost the answer to, or one the leader could not confirm in time. It may or may not have been applied, so this client never sends it again.
VERSION: This crate’s own version, so an application can report the client it uses.

Type Aliases§

Document: One JSON document as the server stores it. Every stored document carries an _id, whether the caller chose it or the server did.
Result: Result alias used throughout the crate.

Crate tricoredb

Crate tricoredb Copy item path

§One connection, one request at a time

§Values are bound by the server

§Errors

§Features

Macros§

Structs§

Enums§

Constants§

Type Aliases§

Crate tricoredb