PHPackages                             satori-db/satori-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. satori-db/satori-client

ActiveLibrary[Database & ORM](/categories/database)

satori-db/satori-client
=======================

PHP client for Satori database

00PHP

Since Feb 24Pushed 2mo agoCompare

[ Source](https://github.com/satori-db/satori-client)[ Packagist](https://packagist.org/packages/satori-db/satori-client)[ RSS](/packages/satori-db-satori-client/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

📚 Satori PHP SDK
================

[](#-satori-php-sdk)

A PHP client library for interacting with the Satori database via WebSockets. This SDK provides comprehensive support for CRUD operations, graph operations, AI-powered features, encryption, and mindspace operations.

---

📋 Table of Contents
-------------------

[](#-table-of-contents)

- [✨ Features](#-features)
- [🚀 Installation](#-installation)
- [🏁 Quick Start](#-quick-start)
- [🔧 Configuration](#-configuration)
- [📦 Basic Operations](#-basic-operations)
    - [SET - Create Data](#set---create-data)
    - [GET - Read Data](#get---read-data)
    - [PUT - Update Data](#put---update-data)
    - [DELETE - Delete Data](#delete---delete-data)
- [🔢 Array Operations](#-array-operations)
    - [PUSH - Add to Array](#push---add-to-array)
    - [POP - Remove Last Element](#pop---remove-last-element)
    - [SPLICE - Remove First Element](#splice---remove-first-element)
    - [REMOVE - Remove Specific Value](#remove---remove-specific-value)
- [🔐 Encryption Operations](#-encryption-operations)
    - [ENCRYPT - Encrypt Data](#encrypt---encrypt-data)
    - [DECRYPT - Decrypt Data](#decrypt---decrypt-data)
- [🕸️ Graph Operations](#-graph-operations)
    - [SET\_VERTEX - Add Relationship](#set_vertex---add-relationship)
    - [GET\_VERTEX - Get Relationships](#get_vertex---get-relationships)
    - [DELETE\_VERTEX - Remove Relationship](#delete_vertex---remove-relationship)
    - [DFS - Depth-First Search](#dfs---depth-first-search)
    - [GRAPH\_BFS - Breadth-First Search](#graph_bfs---breadth-first-search)
    - [GRAPH\_DFS - Graph DFS](#graph_dfs---graph-dfs)
    - [GRAPH\_SHORTEST\_PATH - Shortest Path](#graph_shortest_path---shortest-path)
    - [GRAPH\_CONNECTED\_COMPONENTS - Connected Components](#graph_connected_components---connected-components)
    - [GRAPH\_SCC - Strongly Connected Components](#graph_scc---strongly-connected-components)
    - [GRAPH\_DEGREE\_CENTRALITY - Degree Centrality](#graph_degree_centrality---degree-centrality)
    - [GRAPH\_CLOSENESS\_CENTRALITY - Closeness Centrality](#graph_closeness_centrality---closeness-centrality)
    - [GRAPH\_CENTROID - Find Centroid](#graph_centroid---find-centroid)
- [🤖 AI Operations](#-ai-operations)
    - [ASK - Ask Questions](#ask---ask-questions)
    - [ANN / GET\_SIMILAR - Similarity Search](#ann--get_similar---similarity-search)
- [📊 Analytics Operations](#-analytics-operations)
    - [GET\_OPERATIONS - Operation History](#get_operations---operation-history)
    - [GET\_ACCESS\_FREQUENCY - Access Count](#get_access_frequency---access-count)
- [🧠 Mindspace Operations](#-mindspace-operations)
    - [SET\_MINDSPACE - Create Mindspace](#set_mindspace---create-mindspace)
    - [DELETE\_MINDSPACE - Delete Mindspace](#delete_mindspace---delete-mindspace)
    - [CHAT\_MINDSPACE - Chat with Mindspace](#chat_mindspace---chat-with-mindspace)
    - [LECTURE\_MINDSPACE - Import Corpus](#lecture_mindspace---import-corpus)
- [🔔 Real-time Notifications](#-real-time-notifications)
- [🐘 Schema Class](#-schema-class)
- [📝 Response Format](#-response-format)
- [💡 Complete Example](#-complete-example)

---

✨ Features
----------

[](#-features)

- **CRUD Operations** - Create, read, update, and delete objects
- **Advanced Queries** - Field-based filtering with `field_array`
- **Graph Operations** - Full graph traversal and analysis
- **AI-Powered Features** - Natural language queries and semantic search
- **Encryption** - AES encryption for sensitive data
- **Mindspaces** - AI-powered conversational contexts
- **Real-time Notifications** - Subscribe to object changes

---

🚀 Installation
--------------

[](#-installation)

Install the required dependencies using Composer:

```
composer require textalk/websocket
```

Include the autoloader and Satori class in your PHP project:

```
require_once 'vendor/autoload.php';
require_once 'src/Satori.php';
use Satori\Satori;
```

---

🏁 Quick Start
-------------

[](#-quick-start)

```
require_once 'vendor/autoload.php';
require_once 'src/Satori.php';
use Satori\Satori;

// Connect to Satori server
$client = new Satori('ws://localhost:8000', 'username', 'password');
$client->connect();

// Create an object
$client->set([
    'key' => 'user:john',
    'data' => [
        'name' => 'John Doe',
        'email' => 'john@example.com',
        'age' => 30
    ],
    'type' => 'user'
]);

// Retrieve the object
$user = $client->get(['key' => 'user:john']);
```

---

🔧 Configuration
---------------

[](#-configuration)

### Constructor Parameters

[](#constructor-parameters)

ParameterTypeRequiredDescription`host`stringYesWebSocket connection URL (e.g., `ws://localhost:8000`)`username`stringNoAuthentication username`password`stringNoAuthentication password---

📦 Basic Operations
------------------

[](#-basic-operations)

### SET - Create Data

[](#set---create-data)

Creates a new object in the database. If no key is provided, a UUID is automatically generated.

```
$client->set([
    'key' => 'user:john',
    'data' => [
        'name' => 'John Doe',
        'email' => 'john@example.com',
        'age' => 30
    ],
    'type' => 'user',
    'expires' => false,
    'expiration_time' => null
]);
```

**Parameters:**

ParameterTypeRequiredDescription`key`stringNoObject key (auto-generated if omitted)`data`arrayNoObject data content (default: `{}`)`type`stringNoObject class/type (default: `"normal"`)`expires`booleanNoWhether object expires (default: `false`)`expiration_time`integerNoExpiration timestamp in milliseconds**Response:**

```
{
    "type": "SUCCESS",
    "message": "OK",
    "id": "request-id",
    "key": "user:john"
}
```

---

### GET - Read Data

[](#get---read-data)

Retrieves one or more objects from the database. Use `"*"` for key to return all objects.

```
// Get single object
$user = $client->get(['key' => 'user:john']);

// Get all objects
$allObjects = $client->get(['key' => '*']);

// Query with filters
$results = $client->get([
    'field_array' => [
        ['field' => 'age', 'value' => 30]
    ],
    'one' => true,
    'max' => 10
]);
```

**Parameters:**

ParameterTypeRequiredDescription`key`stringNo\*Object key to retrieve. Use `"*"` for all objects`field_array`arrayNo\*Query conditions for field-based search`one`booleanNoReturn only first match (default: `false`)`max`integerNoMaximum results to return`encryption_key`stringNoKey to decrypt encrypted objects\*Either `key` or `field_array` must be provided, but not both.

---

### PUT - Update Data

[](#put---update-data)

Updates one or more fields of an existing object.

```
$client->put([
    'key' => 'user:john',
    'replace_field' => 'age',
    'replace_value' => 31
]);

// Batch update with field_array
$client->put([
    'field_array' => [
        ['field' => 'type', 'value' => 'premium']
    ],
    'replace_field' => 'status',
    'replace_value' => 'active'
]);
```

**Parameters:**

ParameterTypeRequiredDescription`key`stringNo\*Object key to update`field_array`arrayNo\*Query to select objects for batch update`replace_field`stringYesField name to update`replace_value`anyYesNew value for the field`encryption_key`stringNoKey for encrypted objects\*Either `key` or `field_array` must be provided.

---

### DELETE - Delete Data

[](#delete---delete-data)

Removes one or more objects from the database.

```
$client->delete(['key' => 'user:john']);

// Delete multiple with field_array
$client->delete([
    'field_array' => [
        ['field' => 'status', 'value' => 'inactive']
    ]
]);
```

**Parameters:**

ParameterTypeRequiredDescription`key`stringNo\*Object key to delete`field_array`arrayNo\*Query to select objects for deletion\*Either `key` or `field_array` must be provided.

---

🔢 Array Operations
------------------

[](#-array-operations)

### PUSH - Add to Array

[](#push---add-to-array)

Adds a value to the end of an array field.

```
$client->push([
    'key' => 'user:john',
    'array' => 'tags',
    'value' => 'premium'
]);
```

**Parameters:**

ParameterTypeRequiredDescription`key`stringNo\*Object key`field_array`arrayNo\*Query for batch operation`array`stringYesName of the array field`value`anyYesValue to append`encryption_key`stringNoKey for encrypted objects---

### POP - Remove Last Element

[](#pop---remove-last-element)

Removes and returns the last element from an array field.

```
$client->pop([
    'key' => 'user:john',
    'array' => 'notifications'
]);
```

---

### SPLICE - Remove First Element

[](#splice---remove-first-element)

Removes the first element from an array field.

```
$client->splice([
    'key' => 'user:john',
    'array' => 'notifications'
]);
```

---

### REMOVE - Remove Specific Value

[](#remove---remove-specific-value)

Removes a specific value from an array field by finding and removing the first matching element.

```
$client->remove([
    'key' => 'user:john',
    'array' => 'tags',
    'value' => 'premium'
]);
```

---

🔐 Encryption Operations
-----------------------

[](#-encryption-operations)

### ENCRYPT - Encrypt Data

[](#encrypt---encrypt-data)

Encrypts the data field of an object using AES encryption.

```
$client->encrypt([
    'key' => 'user:john',
    'encryption_key' => 'secret-key-123'
]);
```

**Parameters:**

ParameterTypeRequiredDescription`key`stringYesObject key to encrypt`encryption_key`stringYesEncryption key (used for decryption)---

### DECRYPT - Decrypt Data

[](#decrypt---decrypt-data)

Decrypts an encrypted object's data using the provided encryption key.

```
$client->decrypt([
    'key' => 'user:john',
    'encryption_key' => 'secret-key-123'
]);
```

**Parameters:**

ParameterTypeRequiredDescription`key`stringYesObject key to decrypt`encryption_key`stringYesEncryption key (must match encryption)---

🕸️ Graph Operations
-------------------

[](#️-graph-operations)

### SET\_VERTEX - Add Relationship

[](#set_vertex---add-relationship)

Adds vertices (connections) to an object for graph relationships.

```
// Simple vertex
$client->setVertex([
    'key' => 'user:john',
    'vertex' => 'user:jane'
]);

// Vertex with relation
$client->setVertex([
    'key' => 'user:john',
    'vertex' => [
        'vertex' => 'user:jane',
        'relation' => 'friend',
        'weight' => 1.0
    ]
]);

// Multiple vertices
$client->setVertex([
    'key' => 'user:john',
    'vertex' => ['user:jane', 'user:alice']
]);
```

**Parameters:**

ParameterTypeRequiredDescription`key`stringYesObject key to add vertices to`vertex`string|array|objectYesVertex/vertices to add`encryption_key`stringNoKey for encrypted objects---

### GET\_VERTEX - Get Relationships

[](#get_vertex---get-relationships)

Returns all vertices (connections) defined for an object.

```
$vertices = $client->getVertex([
    'key' => 'user:john'
]);
```

**Response:**

```
{
    "type": "SUCCESS",
    "message": "OK",
    "id": "request-id",
    "data": [
        {"vertex": "user:jane", "relation": "friend", "weight": 1.0},
        {"vertex": "post:123", "relation": "author", "weight": 1.0}
    ]
}
```

---

### DELETE\_VERTEX - Remove Relationship

[](#delete_vertex---remove-relationship)

Removes a specific vertex/connection from an object.

```
$client->deleteVertex([
    'key' => 'user:john',
    'vertex' => 'user:jane'
]);
```

---

### DFS - Depth-First Search

[](#dfs---depth-first-search)

Performs a distributed depth-first search traversal starting from a given node.

```
$results = $client->dfs([
    'node' => 'user:john',
    'relation' => 'friend'
]);
```

**Parameters:**

ParameterTypeRequiredDescription`node`stringYesStarting node key`relation`stringNoFilter by relation type---

### GRAPH\_BFS - Breadth-First Search

[](#graph_bfs---breadth-first-search)

Returns all nodes reachable from a starting node using breadth-first search.

```
$nodes = $client->graph_bfs([
    'node' => 'user:john'
]);
```

**Parameters:**

ParameterTypeRequiredDescription`node`stringNoStarting node (default: empty returns all)---

### GRAPH\_DFS - Graph DFS

[](#graph_dfs---graph-dfs)

Returns all nodes reachable from a starting node using depth-first search.

```
$nodes = $client->graph_dfs([
    'node' => 'user:john'
]);
```

---

### GRAPH\_SHORTEST\_PATH - Shortest Path

[](#graph_shortest_path---shortest-path)

Finds the shortest path between a start node and end node using Dijkstra's algorithm.

```
$path = $client->graph_shortest_path([
    'node' => 'user:john',
    'target' => 'post:123'
]);
```

**Response:**

```
{
    "type": "SUCCESS",
    "message": "OK",
    "id": "request-id",
    "data": ["user:john", "user:alice", "post:123"]
}
```

---

### GRAPH\_CONNECTED\_COMPONENTS - Connected Components

[](#graph_connected_components---connected-components)

Identifies all connected components in the graph (groups of nodes where each node is reachable from any other node in the group).

```
$components = $client->graph_connected_components([]);
```

**Response:**

```
{
    "type": "SUCCESS",
    "message": "OK",
    "id": "request-id",
    "data": [
        ["node1", "node2", "node3"],
        ["node4", "node5"],
        ["node6"]
    ]
}
```

---

### GRAPH\_SCC - Strongly Connected Components

[](#graph_scc---strongly-connected-components)

Identifies strongly connected components using Tarjan's algorithm.

```
$scc = $client->graph_scc([]);
```

---

### GRAPH\_DEGREE\_CENTRALITY - Degree Centrality

[](#graph_degree_centrality---degree-centrality)

Calculates the degree centrality (number of connections) for each node in the graph.

```
$centrality = $client->graph_degree_centrality([]);
```

**Response:**

```
{
    "type": "SUCCESS",
    "message": "OK",
    "id": "request-id",
    "data": {
        "node1": 5,
        "node2": 3,
        "node3": 8
    }
}
```

---

### GRAPH\_CLOSENESS\_CENTRALITY - Closeness Centrality

[](#graph_closeness_centrality---closeness-centrality)

Calculates closeness centrality for each node, which measures how close a node is to all other nodes in the graph.

```
$centrality = $client->graph_closeness_centrality([]);
```

**Response:**

```
{
    "type": "SUCCESS",
    "message": "OK",
    "id": "request-id",
    "data": {
        "node1": 0.45,
        "node2": 0.32,
        "node3": 0.58
    }
}
```

---

### GRAPH\_CENTROID - Find Centroid

[](#graph_centroid---find-centroid)

Finds the node with the highest closeness centrality (the most central node in the graph).

```
$centroid = $client->graph_centroid([]);
```

**Response:**

```
{
    "type": "SUCCESS",
    "message": "OK",
    "id": "request-id",
    "data": "node-with-highest-centrality"
}
```

---

🤖 AI Operations
---------------

[](#-ai-operations)

> **Note:** Some AI operations require a valid license. `ANN` requires a license, while `GET_SIMILAR` is always available.

### ASK - Ask Questions

[](#ask---ask-questions)

Uses AI to answer complex questions about the database. The system automatically gathers relevant context using GET, DFS, GET\_VERTEX, and ANN operations.

```
$response = $client->ask([
    'question' => 'Which user has the most posts?',
    'session' => 'global',
    'backend' => 'ollama'
]);
```

**Parameters:**

ParameterTypeRequiredDescription`question`stringYesThe question to ask`session`stringNoMindspace session to use (default: `"global"`)`backend`stringNoLLM backend (`"ollama"` or `"openai"`)**Response:**

```
{
    "type": "SUCCESS",
    "message": "SUCCESS",
    "id": "request-id",
    "data": {
        "response": "AI-generated answer...",
        "context": [...],
        "session": "session-id"
    }
}
```

---

### ANN / GET\_SIMILAR - Similarity Search

[](#ann--get_similar---similarity-search)

Performs approximate nearest neighbor search to find semantically similar objects using vector embeddings.

```
// Using existing object's embedding
$results = $client->ann([
    'key' => 'user:john',
    'k' => 10
]);

// Using GET_SIMILAR (always available, no license required)
$results = $client->get_similar([
    'key' => 'user:john',
    'k' => 10
]);

// Using a vector directly
$results = $client->ann([
    'vector' => [0.1, 0.2, 0.3, 0.4, ...],
    'k' => 10,
    'ef' => 25
]);
```

**Parameters:**

ParameterTypeRequiredDescription`vector`arrayNo\*Query vector as array of floats`key`stringNo\*Use embedding from existing object`k`integerNoNumber of neighbors to return (default: 5)`ef`integerNoSearch width parameter (default: 25)`use`stringNoFor key-based: `"data"` or `"embedding"`\*Either `vector` or `key` must be provided.

---

📊 Analytics Operations
----------------------

[](#-analytics-operations)

### GET\_OPERATIONS - Operation History

[](#get_operations---operation-history)

Returns a log of recent database operations.

```
$operations = $client->get_operations([]);
```

**Response:**

```
{
    "type": "SUCCESS",
    "message": "OK",
    "id": "request-id",
    "data": "[{\"operation\":{...},\"response\":{...},\"timestamp\":1234567890},...]"
}
```

---

### GET\_ACCESS\_FREQUENCY - Access Count

[](#get_access_frequency---access-count)

Returns the number of times an object has been queried or accessed.

```
$count = $client->get_access_frequency([
    'key' => 'user:john'
]);
```

**Response:**

```
{
    "type": "SUCCESS",
    "message": "OK",
    "id": "request-id",
    "data": 42
}
```

---

🧠 Mindspace Operations
----------------------

[](#-mindspace-operations)

Mindspaces provide AI-powered conversational contexts for semantic operations.

### SET\_MINDSPACE - Create Mindspace

[](#set_mindspace---create-mindspace)

Creates a new mindspace (cognitive context) for AI-powered conversations.

```
$result = $client->set_mindspace([
    'mindspace_id' => 'conversation-1'
]);
```

**Parameters:**

ParameterTypeRequiredDescription`mindspace_id`stringNoCustom mindspace ID (auto-generated if omitted)---

### DELETE\_MINDSPACE - Delete Mindspace

[](#delete_mindspace---delete-mindspace)

Removes a mindspace and all its associated context.

```
$client->delete_mindspace([
    'mindspace_id' => 'conversation-1'
]);
```

**Parameters:**

ParameterTypeRequiredDescription`mindspace_id`stringYesMindspace ID to delete---

### CHAT\_MINDSPACE - Chat with Mindspace

[](#chat_mindspace---chat-with-mindspace)

Sends a message to a mindspace and receives an AI-generated response. The mindspace maintains conversation context.

```
$response = $client->chat_mindspace([
    'mindspace_id' => 'conversation-1',
    'message' => 'What do you know about users?'
]);
```

**Parameters:**

ParameterTypeRequiredDescription`mindspace_id`stringYesMindspace ID to chat with`message`stringYesUser message**Response:**

```
{
    "type": "SUCCESS",
    "message": "OK",
    "id": "request-id",
    "response": {
        "response": "AI response text...",
        "context": [...]
    }
}
```

---

### LECTURE\_MINDSPACE - Import Corpus

[](#lecture_mindspace---import-corpus)

Imports text corpus into a mindspace for semantic search and context retrieval.

```
$client->lecture_mindspace([
    'mindspace_id' => 'conversation-1',
    'corpus' => 'User John Doe is a software engineer who specializes in Rust and distributed systems...'
]);
```

**Parameters:**

ParameterTypeRequiredDescription`mindspace_id`stringYesMindspace ID to import into`corpus`stringYesText content to import---

🔔 Real-time Notifications
-------------------------

[](#-real-time-notifications)

Subscribe to real-time updates when an object changes.

```
$client->notify('user:123', function($data) {
    echo "User updated!\n";
    print_r($data);
});
```

---

🐘 Schema Class
--------------

[](#-schema-class)

The `Schema` class provides an object-oriented way to model your data.

```
use Satori\Satori;
use Satori\Schema;

$satori = new Satori('ws://localhost:8000', 'username', 'password');
$satori->connect();

// Create a schema-based object
$user = new Schema($satori, "user", ["name" => "Anna"], "my_key");
$user->set();

// Available methods:
// CRUD: set(), delete(), encrypt(), decrypt()
// Graph: setVertex(), getVertex(), deleteVertex(), dfs()
// References: setRef(), getRefs(), deleteRefs()
// Arrays: push(), pop(), splice(), remove()
```

---

📝 Response Format
-----------------

[](#-response-format)

All successful responses follow this general structure:

```
{
    "type": "SUCCESS",
    "message": "OK",
    "id": "request-id",
    "key": "optional-key",
    "data": { ... }
}
```

Error responses:

```
{
    "type": "ERROR",
    "message": "Error description",
    "id": "request-id"
}
```

---

💡 Complete Example
------------------

[](#-complete-example)

```