shadedb-api 0.1.6

The official, high-performance Python client for ShadeDB cloud instances. ShadeDB provides a streamlined, developer-first approach to cloud data management. This library is designed to be the permanent interface for ShadeDB, ensuring a seamless transition from development to full-scale production. Currently in mvp stage

The fastest way to interact with shadeDB — a machine-native, semi-structured database built for real-time systems, autonomous agents, and sub-millisecond ingestion.

shadedb mvp 1 shadedb mvp 2 (active)

🧠 Agent-native
📡 Ultra-low latency
🧩 Minimal & composable
⚙️ Sync execution model
🐧 Structured Native Language (SNL)

---

Table of contents

• Why shadeDB?
• What is shadedb-api?
• Installation
• 30‑Second Quickstart
• Basic Usage
  • Insert
  • Update (Full Overwrite)
  • Query (SNL)
• Structured Native Language (SNL)
  • Fetch
  • Where (Filtering)
  • Pagination & Ordering
  • Insert / Update / Lifecycle
  • Unique Fields
• Architecture
• Module Overview
• CLI
• Configuration
• Error Handling
• Performance Philosophy
• Use Cases
• Requirements
• Contributing
• License
• Vision

---

Why shadeDB?

Traditional databases were built for humans.
shadeDB is built for machines.

Modern systems — AI agents, real-time pipelines, autonomous services — require:

• deterministic execution
• minimal parsing overhead
• high-frequency ingestion
• predictable latency

shadeDB introduces a command-based execution model optimized for speed, not syntax.

---

What is shadedb-api?

shadedb-api is a synchronous subcommunicator between your application and a remote shadeDB instance.

It is designed to:

• relay commands efficiently
• minimize transport overhead
• preserve execution determinism
• integrate cleanly into production systems

---

Installation

pip install shadedb-api

---

30‑Second Quickstart

from shadedb_api.frame.sync import syncFrame

db = syncFrame(
    endpoint="https://your-endpoint",
    token="your-db-token",
    inspection=True,
    query_timeout=60
)

---

Usage

Insert

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

Update (Full Overwrite)

result = db.snlComplexQuery(
    command="update :: id :: int(1)",
    context={"username": "zeus", "age": 56, "email": "[e-mail]"}
)
print(result)

Query (SNL)

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

---

Structured Native Language (SNL)

SNL is a delimiter-based command language designed for:

• ⚡ Fast parsing
• 🔐 Safer execution
• 🧠 Machine-native interaction

Below are common SNL patterns and examples.

Fetch

Direct record retrieval via indexed fields.

Fetch :: username :: sherifdeen

Record comparison/verification

Fetch :: username :: sherifdeen :: verify :: field :: value

Selective fields

Fetch :: username :: sherifdeen :: get :: username,role

Atomic update

Fetch :: username :: sherifdeen :: update :: age :: int(21)

Where (Filtering)

Query non-unique fields.

Where :: gender :: male :: get :: username,role

Pagination & Ordering

Modifiers:

• page(x,y) — slice results from index X to Y
• ascend — sort ascending
• descend — sort descending

Example:

Where :: status :: active :: page(1,50) :: descend

Insert / Update / Lifecycle

Insert — requires a valid JSON string. No overwrites by default.

Insert :: jsonString({ "username":"admin", "id":56 })

Atomic field update:

Fetch :: username :: sherifdeen :: update :: age :: int(43)

Full record overwrite:

Update :: username :: sherifdeen :: jsonString({ "username":"shade", "role":"admin" })

Data lifecycle commands:

• Fold (soft delete, reversible)

Fold :: id :: int(17)

• Unfold (restore)

Unfold :: id :: int(17)

• Delete (permanent, storage reclaimed during compaction)

Delete :: id :: int(17)

⚠️Note : Fold and unfold are unavailable in mvp version.

Unique Fields

Default unique keys:

[id, username, email, phone]

---

Architecture

[ Application ]
       │
       ▼
[ shadedb-api (Sync Layer) ]
       │
       ▼
[ Network Transport ]
       │
       ▼
[ Remote shadeDB Instance ]

---

Module Overview

• shadedb_api.frame.sync
  • Core execution engine: synchronous query dispatch, transport coordination, response handling
• shadedb_api.frame.excepts
  • Custom exception system: structured errors, predictable failure modes, debugging clarity

---

CLI

# initialize with endpoint and token - saved as default config
shadedb-api-init https://endpoint YOUR_TOKEN

# Re-initialize with endpoint and token - not saved
shadedb-api https://endpoint YOUR_TOKEN

# start an interactive client / CLI with saved config
shadedb-api  

# run snl queries from api cli
[API] $/ fetch :: id :: int(12)

# navigate to console for robust options
[API] $/ console

# navigated to console 
CONSOLE $/ 

# change database name 
CONSOLE $/ name ::mydb
{'database name': 'mydb', 'message': 'database name changed', 'success': True}

# retrieve your database information
mydb $/ info
{'Default pagination': [1, 15], 'Name': 'mydb', 'Total size': '0.000000 / 2.0MB', 'Unique keys': ['id'], 'Use cache': True}

# check your database storage size
mydb $/ stat :: volume
0.000000 / 2.0MB

# check your database unique fields
mydb $/ stat :: unique
[server ~ console]: {'unique keys': ['id']}

# modify your database unique fields
mydb $/ stat ::unique ::username,email,phone number
{'message': "Unique keys updated : ['username', 'email', 'phone number', 'id']", 'success': True}

# modify default page size during filter queries
mydb $/ stat :: page :: 1,30
[server ~ console]: {'message': 'Paged resized'}

# insert to your database from console (snl) 
mydb $/ snl :: insert :: {"username":"shade","email":"[e-mail]"}
Database latency: 0.0037282

{'email': '[e-mail]', 'id': 1, 'username': 'shade'}

# fetch from your database from console (snl
mydb $/ snl :: fetch :: id :: int(1)
Database latency: 0.0008728

{'email': '[e-mail]', 'id': 1, 'username': 'shade'}

# update to your database from console (snl)
mydb $/ snl :: update :: id :: int(1) :: {"username":"sherifdeen","email":"[e-mail]"}
Database latency: 0.0017347

{'email': '[e-mail]', 'id': 1, 'username': 'sherifdeen'}
# deactivate your database cache system
mydb $/ stat :: cache :: deactivate
{'message': 'cache deactivated', 'success': True}

# activate your database cache system
mydb $/ stat :: cache :: activate
{'message': 'cache activated', 'success': True}

# delete your remote database instance
mydb $/ stat :: terminate
{'message': 'Deleted'}

# close session from console
mydb $/ exit 2

---

Configuration

Example programmatic configuration:

db = syncFrame(
    endpoint="https://your-endpoint",
    token="your-token",
    inspection=True,
    query_timeout=60
)

---

Error Handling

Use the provided exception types to catch and inspect errors:

from shadedb_api.frame.excepts import URLEndpointMissingError, TokenMissingError, SNLMissingError, SNLContextMissingError


try:
    db.snlQuery("fetch :: id :: int(23)")
except TokenMissingError as e:
    print(f"shadeDB error: {e}")

---

Performance Philosophy

Execution speed scales with simplicity. shadeDB removes unnecessary abstraction layers:

• fewer allocations
• faster parsing
• deterministic execution
• increased uptime availability

Result: predictable, ultra-low latency at scale.

---

Use Cases

• Autonomous AI agents
• Real-time ingestion pipelines
• High-frequency event systems
• Edge data layers
• Experimental database architectures

---

Requirements

• Python 3.10+
• A running shadeDB instance ( remote )

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/your-feature)
3. Make changes, add tests
4. Open a pull request and describe your changes

Please follow the repository's code style and include tests where applicable.

---

Vision

shadeDB represents a shift from human-centric data systems.
The future isn’t dashboards. The future is agents thinking and executing at lightning speed.

---