# 📚 Satori Rust SDK
A comprehensive Rust client library for interacting with the Satori database via WebSockets. Satori is a powerful in-memory database with support for CRUD operations, advanced queries, graph relationships, encryption, AI-powered semantic search, and mindspace conversations.
---
## ✨ Features
- **Ultra-fast CRUD operations** ⚡
- **Advanced queries** using `field_array` for conditional operations 🔍
- **Real-time notifications** 📢
- **Graph-like relations** (vertices and edges) 🕸️
- **Data encryption and decryption** using AES 🔐
- **Approximate Nearest Neighbor (ANN) search** for semantic similarity 🎯
- **Mindspace conversations** for AI-powered context-aware chat 💬
---
## 🚀 Installation
Add the following to your `Cargo.toml`:
```toml
[dependencies]
satori-client = "0.1.8"
tokio = { version = "1.36", features = ["full"] }
serde_json = "1.0"
```
---
## 🏁 Quick Start
```rust
use satori_client::Satori;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let client = Satori::connect(
"username".to_string(),
"password".to_string(),
"ws://localhost:8000".to_string()
).await?;
// Create an object
client.set(serde_json::json!({
"key": "user:john",
"data": { "name": "John Doe", "email": "john@example.com", "age": 30 },
"type": "user"
})).await?;
Ok(())
}
```
---
## 📋 Command Reference
All operations are invoked via WebSocket with a JSON request format. The client provides convenient methods for each operation.
### Base Request Structure
```json
{
"command": "OPERATION_NAME",
"id": "unique-request-id",
"username": "optional-username",
"password": "optional-password",
"key": "object-key",
"data": { ... }
}
```
---
## 🗃️ CRUD Operations
### SET - Create Data
Creates a new object in the database. If no key is provided, a UUID is automatically generated.
```rust
client.set(serde_json::json!({
"key": "user:john",
"data": { "name": "John Doe", "email": "john@example.com" },
"type": "user",
"expires": false,
"expiration_time": -1
})).await?;
```
**Parameters:**
| `key` | string | No | Object key. If omitted, a UUID is generated |
| `data` | JSON | No | Object data content (default: `{}`) |
| `type` | string | No | Object class/type (default: `"normal"`) |
| `expires` | boolean | No | Whether object expires (default: `false`) |
| `expiration_time` | integer | No | Expiration timestamp in milliseconds |
---
### GET - Read Data
Retrieves one or more objects from the database. If key is `"*"`, returns all objects in memory.
```rust
// Get single object
let user = client.get(serde_json::json!({ "key": "user:john" })).await?;
// Get all objects
let all = client.get(serde_json::json!({ "key": "*" })).await?;
// Query by field
let results = client.get(serde_json::json!({
"field_array": [
{ "field": "age", "value": 30 }
],
"one": true,
"max": 10
})).await?;
```
**Parameters:**
| `key` | string | No* | Object key to retrieve. Use `"*"` for all objects |
| `field_array` | array | No* | Query conditions for field-based search |
| `one` | boolean | No | Return only first match (default: `false`) |
| `max` | integer | No | Maximum results to return |
| `encryption_key` | string | No | Key to decrypt encrypted objects |
*Either `key` or `field_array` must be provided, but not both.
---
### PUT - Update Data
Updates one or more fields of an existing object.
```rust
client.put(serde_json::json!({
"key": "user:john",
"replace_field": "age",
"replace_value": 31
})).await?;
// Batch update using field_array
client.put(serde_json::json!({
"field_array": [{ "field": "type", "value": "user" }],
"replace_field": "status",
"replace_value": "active"
})).await?;
```
**Parameters:**
| `key` | string | No* | Object key to update |
| `field_array` | array | No* | Query to select objects for batch update |
| `replace_field` | string | Yes | Field name to update |
| `replace_value` | any | Yes | New value for the field |
| `encryption_key` | string | No | Key for encrypted objects |
*Either `key` or `field_array` must be provided.
---
### DELETE - Remove Data
Removes one or more objects from the database.
```rust
client.delete(serde_json::json!({ "key": "user:john" })).await?;
// Delete multiple objects matching a query
client.delete(serde_json::json!({
"field_array": [{ "field": "status", "value": "inactive" }]
})).await?;
```
**Parameters:**
| `key` | string | No* | Object key to delete |
| `field_array` | array | No* | Query to select objects for deletion |
*Either `key` or `field_array` must be provided.
---
## 📦 Array Manipulation
### PUSH - Add to Array
Appends a value to an array field within an object.
```rust
client.push(serde_json::json!({
"key": "user:john",
"array": "tags",
"value": "premium"
})).await?;
```
### POP - Remove Last from Array
Removes and returns the last element from an array field.
```rust
client.pop(serde_json::json!({
"key": "user:john",
"array": "notifications"
})).await?;
```
### SPLICE - Remove First from Array
Removes the first element from an array field.
```rust
client.splice(serde_json::json!({
"key": "user:john",
"array": "notifications"
})).await?;
```
### REMOVE - Remove Specific Value
Removes a specific value from an array field by finding and removing the first matching element.
```rust
client.remove(serde_json::json!({
"key": "user:john",
"array": "tags",
"value": "premium"
})).await?;
```
**Common Parameters:**
| `key` | string | No* | Object key |
| `field_array` | array | No* | Query for batch operation |
| `array` | string | Yes | Name of the array field |
| `value` | any | Yes* | Value to add/remove |
| `encryption_key` | string | No | Key for encrypted objects |
*Required for PUSH and REMOVE; not required for POP and SPLICE.
---
## 🔐 Encryption
### ENCRYPT
Encrypts the data field of an object using AES encryption.
```rust
client.encrypt(serde_json::json!({
"key": "user:john",
"encryption_key": "secret-key-123"
})).await?;
```
### DECRYPT
Decrypts an encrypted object's data using the provided encryption key.
```rust
client.decrypt(serde_json::json!({
"key": "user:john",
"encryption_key": "secret-key-123"
})).await?;
```
---
## 🕸️ Graph Operations
### SET_VERTEX
Adds vertices (connections) to an object for graph relationships.
```rust
// Simple vertex
client.set_vertex(serde_json::json!({
"key": "user:john",
"vertex": "user:jane"
})).await?;
// Vertex with relation
client.set_vertex(serde_json::json!({
"key": "user:john",
"vertex": { "vertex": "user:jane", "relation": "friend", "weight": 1.0 }
})).await?;
// Multiple vertices
client.set_vertex(serde_json::json!({
"key": "user:john",
"vertex": ["user:jane", "user:alice"]
})).await?;
```
### GET_VERTEX
Retrieves all vertices from an object.
```rust
let vertices = client.get_vertex(serde_json::json!({
"key": "user:john"
})).await?;
```
### DELETE_VERTEX
Removes a specific vertex from an object.
```rust
client.delete_vertex(serde_json::json!({
"key": "user:john",
"vertex": "user:jane"
})).await?;
```
### DFS - Depth-First Search
Traverses the graph starting from a given node using depth-first search.
```rust
let results = client.dfs(serde_json::json!({
"node": "user:john",
"relation": "friend"
})).await?;
```
### GRAPH_BFS - Breadth-First Search
Returns all nodes reachable from a starting node using breadth-first search.
```rust
let results = client.graph_bfs(serde_json::json!({
"node": "user:john"
})).await?;
```
### GRAPH_DFS - Graph Depth-First Search
Returns all nodes reachable from a starting node using depth-first search.
```rust
let results = client.graph_dfs(serde_json::json!({
"node": "user:john"
})).await?;
```
### GRAPH_SHORTEST_PATH
Finds the shortest path between a start node and end node using Dijkstra's algorithm.
```rust
let path = client.graph_shortest_path(serde_json::json!({
"node": "user:john",
"target": "post:123"
})).await?;
```
### GRAPH_CONNECTED_COMPONENTS
Identifies all connected components in the graph (groups of nodes where each node is reachable from any other node in the group).
```rust
let components = client.graph_connected_components(serde_json::json!({
"id": "req-001"
})).await?;
```
### GRAPH_SCC - Strongly Connected Components
Identifies strongly connected components using Tarjan's algorithm.
```rust
let scc = client.graph_scc(serde_json::json!({
"id": "req-001"
})).await?;
```
### GRAPH_DEGREE_CENTRALITY
Calculates the degree centrality (number of connections) for each node in the graph.
```rust
let centrality = client.graph_degree_centrality(serde_json::json!({
"id": "req-001"
})).await?;
```
### GRAPH_CLOSENESS_CENTRALITY
Calculates closeness centrality for each node, which measures how close a node is to all other nodes.
```rust
let centrality = client.graph_closeness_centrality(serde_json::json!({
"id": "req-001"
})).await?;
```
### GRAPH_CENTROID
Finds the node with the highest closeness centrality (the most central node in the graph).
```rust
let centroid = client.graph_centroid(serde_json::json!({
"id": "req-001"
})).await?;
```
---
## 🤖 AI Operations
### ANN / GET_SIMILAR
Performs approximate nearest neighbor search to find semantically similar objects using vector embeddings.
```rust
// Search by vector
let similar = client.ann(serde_json::json!({
"vector": [0.1, 0.2, 0.3, ...],
"k": 10,
"ef": 25
})).await?;
// Search by existing object's embedding
let similar = client.get_similar(serde_json::json!({
"key": "user:john",
"use": "embedding",
"k": 10
})).await?;
```
**Parameters:**
| `vector` | array | No* | Query vector as array of floats |
| `key` | string | No* | Use embedding from existing object |
| `k` | integer | No | Number of neighbors to return (default: 5) |
| `ef` | integer | No | Search width parameter (default: 25) |
| `use` | string | No | For key-based search: `"data"` or `"embedding"` |
*Either `vector` or `key` must be provided.
---
### ASK
Uses AI to answer complex questions about the database. The system automatically gathers relevant context.
```rust
let response = client.ask(serde_json::json!({
"question": "Which user has the most posts?",
"session": "global",
"backend": "ollama"
})).await?;
```
**Note:** This operation requires a valid license.
---
## 💬 Mindspace Operations
Mindspaces provide cognitive contexts for AI-powered conversations and semantic operations.
### SET_MINDSPACE / CREATE_MINDSPACE
Creates a new mindspace.
```rust
let mindspace_id = client.set_mindspace(serde_json::json!({
"mindspace_id": "conversation-1"
})).await?;
// Or use alias
let mindspace_id = client.create_mindspace(serde_json::json!({
"mindspace_id": "conversation-1"
})).await?;
```
### DELETE_MINDSPACE
Removes a mindspace and all its associated context.
```rust
client.delete_mindspace(serde_json::json!({
"mindspace_id": "conversation-1"
})).await?;
```
### CHAT_MINDSPACE
Sends a message to a mindspace and receives an AI-generated response. The mindspace maintains conversation context.
```rust
let response = client.chat_mindspace(serde_json::json!({
"mindspace_id": "conversation-1",
"message": "What do you know about users?"
})).await?;
```
### LECTURE_MINDSPACE
Imports text corpus into a mindspace for semantic search and context retrieval.
```rust
client.lecture_mindspace(serde_json::json!({
"mindspace_id": "conversation-1",
"corpus": "User John Doe is a software engineer who specializes in Rust and distributed systems..."
})).await?;
```
---
## 📊 Analytics Operations
### GET_OPERATIONS
Returns a log of recent database operations.
```rust
let operations = client.get_operations().await?;
```
### GET_ACCESS_FREQUENCY
Returns the query count (access frequency) for a specific object.
```rust
let frequency = client.get_access_frequency(serde_json::json!({
"key": "user:john"
})).await?;
```
---
## 🔔 Real-time Notifications
Receive automatic updates when an object changes:
```rust
client.set_notify("user:john", |data| {
println!("User updated! {:?}", data);
}).await?;
```
---
## 📝 Response Format
All successful responses follow this general structure:
```json
{
"type": "SUCCESS",
"message": "OK",
"id": "request-id",
"key": "optional-key",
"data": { ... }
}
```
Error responses:
```json
{
"type": "ERROR",
"message": "Error description",
"id": "request-id"
}
```
---
## 🧠 Key Concepts
| **key** | Unique identifier of the object |
| **type** | Object type (e.g., 'user', 'post') |
| **data** | The actual content stored in the object |
| **field_array** | Advanced filters for conditional operations |
| **vertices** | Graph-like relationships between objects |
| **encryption_key** | Key used for AES encryption/decryption |
| **mindspace** | Cognitive context for AI conversations |
---
## 🤝 Contributing
Questions or suggestions? Feel free to open an issue or contribute!
---
Made with ❤️ from the Satori team