shadeDB

The machine-native, semi-structured database built for autonomous agents, real-time pipelines, and sub-millisecond ingestion.

Premium Server • Contact / Support

Key Pillars

• Machine-Native — Designed for AI agents and automated services, removing human-centric query overhead.
• Millisecond Execution — Direct command-dispatch architecture built for extreme performance.
• Structured Native Language (SNL) — An ultra-fast, command-based execution layer that drastically reduces parsing time.
• Deterministic Execution — Predictable latency, sync execution models, and zero unexpected overhead.
• Minimal & Composable — Zero bloat, low allocation footprints, and dead-simple multi-platform setup.

Quick Links & Navigation

• Why shadeDB?
• What is shadedb-api?
• Installation
• Connecting to a Partition Cluster
• 30-Second Quickstart
• Basic Usage
• Structured Native Language (SNL)
  • Fetch Operations
  • Where & Filtering
  • Pagination & Sorting
  • Data Lifecycle & Mutexes
• CLI Reference
• Architecture & Error Handling
• Vision

Why shadeDB?

Traditional databases were built for human queries, complex ORMs, and verbose text parsing.

shadeDB flips the script. Autonomous AI agents, high-frequency execution engines, and real-time event streams don't need pretty syntax — they need pure velocity, low memory footprints, and deterministic responses.

shadeDB uses Structured Native Language (SNL) to bypass heavy parsing cycles, yielding near-instant operations across cloud, edge, and embedded runtime environments.

What is shadedb-api?

shadedb-api is the official synchronous subcommunicator layer interfacing your Python environment directly with remote shadeDB instances.

┌────────────────────────┐      Direct Command Pipeline       ┌────────────────────────┐
│  Application / Agent   │ ─────────────────────────────────> │   shadedb-api Client   │
└────────────────────────┘                                    └────────────────────────┘
                                                                          │
                                                                   Sync Network Shift
                                                                          │
                                                                          ▼
                                                              ┌────────────────────────┐
                                                              │ Remote shadeDB Engine  │
                                                              └────────────────────────┘

Installation

pip install shadedb-api

Connecting to a Partition Cluster

Before using shadedb-api, obtain the following credentials from your shadeDB dashboard:

• Partition Endpoint – The unique endpoint assigned to your partition.
• Connection Token – Authenticates your client.
• Cluster Token – Grants access to the target partition cluster.

Keep both tokens secret. Never expose them in public repositories or client-side applications.

Temporary Connection

To connect without saving the configuration:

shadedb-api CONNECTION_ENDPOINT CONNECTION_TOKEN CLUSTER_TOKEN

Example:

shadedb-api http://host.com/connect/sdb7f585246acf1480b9caac05f811c3 
8da846a452f13d1d4cf4ddfac656a115 
8c2ff6b8c408f68

The connection is valid only for the current session. You'll need to provide the credentials again the next time you connect.

Persistent Initialization

To save the connection details for future sessions:

shadedb-api-init CONNECTION_ENDPOINT CONNECTION_TOKEN CLUSTER_TOKEN

Example:

shadedb-api-init http://host.com/connect/sdb7f585246acf1480b9caac05f811c3 
8da846a452f13d1d4cf4ddfac656a115 
8c2ff6b8c408f68

This stores the endpoint and authentication tokens locally.

Reconnecting

After initialization, simply run:

shadedb-api

The client automatically loads the previously saved connection details and opens an interactive session.

30-Second Quickstart

from shadedb_api.frame.sync import syncFrame

# Initialize the synchronized DB engine
db = syncFrame(
    endpoint="https://your_database_endpoint",
    connection_token="YOUR_CONNECTION_TOKEN",
    inspection=False,
    query_timeout=0.5
)

Basic Usage

Insert Record

result = db.snlComplexQuery(
    command="Insert",
    context={"username": "shade", "age": 12}
)
print(result)

Full Overwrite

result = db.snlComplexQuery(
    command="Overwrite;id::int(1)",
    context={"username": "zeus", "age": 56, "email": "zeus@mail.com"}
)
print(result)

Direct String Query

result = db.snlQuery("Fetch;id::int(1)")
print(result)

Structured Native Language (SNL)

SNL is shadeDB’s core execution dialect. It reduces syntax parsing to simple instruction.

Fetch

Retrieve records instantly via indexed fields:

Fetch;username::sherifdeen

Verify field values directly on fetch:

Fetch;username::sherifdeen;verify(field='value')

Select or exclude specific fields:

Fetch;username::sherifdeen;get(username,role)
Fetch;username::sherifdeen;exclude(password,auth_token)

Atomic update on target key:

Fetch;username::sherifdeen;update(age='int(21)');
Fetch;username::sherifdeen;strict(age='int(21)');

Where (Filtering)

Filter non-unique fields with precision:

Where;gender::male;get(username,role)
Where;gender::male;exclude(password,auth_token)

Pagination & Ordering

Fine-tune record sets without heavy query wrappers:

• start X, limit Y — Offset and page limits
• order(ascend) — Sort ascending
• order(descend) — Sort descending
• order(random) — Shuffle returned records

Where;status::active;start 1, limit 50;order(descend);

Insert / Update / Lifecycle

# Insert record (JSON payload required)
Insert;jsonString({ "username":"admin", "id":56 });

# Atomic Field Update
Fetch;username::sherifdeen;update(age='int(43)');

# Full Record Overwrite
Overwrite;username::sherifdeen;jsonString({ "username":"shade", "role":"admin" });

Lifecycle Controls

Freeze;id::int(17);     # Soft delete (Reversible)
Unfreeze;id::int(17);   # Restore soft-deleted record
Delete;id::int(17);     # Hard delete (Storage reclaimed on compaction)

Interactive CLI

shadeDB provides a fully functional shell for interactive session management, telemetry, and quick debugging.

# Initialize persistent configuration
shadedb-api-init [https://your-endpoint.com](https://your-endpoint.com) (connection_token) (cluster_token)

# Launch interactive CLI session
shadedb-api

Session Example

Active


[sdb4e74facf8711447b9e33e6dc83a07] >> fetch;id::int(2)
{'id': 2, 'username': 'sherifdeen'}
[sdb4e74facf8711447b9e33e6dc83a07] >> insert;{"username":"john","age":26,"account_type":"user","disabled":false}
{'account_type': 'user', 'age': 26, 'disabled': False, 'id': 3, 'username': 'john'}
[sdb4e74facf8711447b9e33e6dc83a07] >> fetch;username::john;exclude(account_type);
{'age': 26, 'disabled': False, 'id': 3, 'username': 'john'}
[sdb4e74facf8711447b9e33e6dc83a07] >>*;
[{'id': 1, 'username': 'shade'}, {'id': 2, 'username': 'sherifdeen'}]
[sdb4e74facf8711447b9e33e6dc83a07] >> exit
Exiting shadedb-api Console.

Error Handling

Catch predictable exceptions safely with built-in error modules:

from shadedb_api.frame.excepts import (
    ShadeDBError,
    URLEndpointMissingError, 
    SNLMissingError, 
    SNLContextMissingError,
    ConnectionTokenMissingError,
    ClusterTokenMissingError
)

try:
    db.snlQuery("fetch;id::int(23)")
except TokenMissingError as e:
    print(f"[shadeDB Security Alert]: Authentication failed -> {e}")
except SNLMissingError as e:
    print(f"[shadeDB Command Error]: Invalid SNL query string -> {e}")

Vision

The future of software isn't human-facing dashboards or verbose SQL query builders. The future is machine agents operating, reasoning, and transacting data at lightspeed.

shadeDB provides the raw execution layer necessary to power that transition.

Maintained by Harkerbyte.