# shadeDB for LLMs

shadeDB is a database service with its own query language, SNL (Structured Native
Language). An app talks to a cluster through one endpoint using three values: the
connection endpoint, a cluster token and a connection token. Use this page to build
on shadeDB without reading the full docs. Full reference: /doc

## Connect

POST CONNECTION_ENDPOINT        (looks like https://HOST/connect/INSTANCE_ID)
Content-Type: application/json
{"token": "CLUSTER_TOKEN", "cntoken": "CONNECTION_TOKEN", "SNL": "QUERY"}

- Failures also return HTTP 200. Always check the JSON "status" field: "failed"
  means the query did not run, and "message" says why.
- Missing fields return "Missing cluster token", "Missing connection token" or
  "Missing query".
- HTTPS works on every plan. TCP and UDP are for paid plans.
- Keep both tokens on the server. Never put them in browser code or public repos.
- The free plan rate limits requests with a cooldown. Back off and retry.

## SNL in one minute

A query is an execution mode, then a record selection, then optional clauses.
Fields and values are typed on both sides, like str<username>::str<shade>.

Modes: FETCH; WHERE; EXIST; INSERT; UPDATE; OVERWRITE; DELETE; FREEZE; UNFREEZE
(see /doc for STRICT variants and exact INSERT/UPDATE/OVERWRITE bodies).

Check a record exists (returns True or False):
EXIST;
str<username>::str<shade>;

Fetch fields, newest first, one page of 25:
FETCH;
str<username>::str<john>;
GET(username, bio);
ORDER(DESCEND);
START ? 0, LIMIT ? 25;

Escape these characters with a backslash in any value you did not write yourself:
\ ; , < > = +
On the free plan, WHERE and wildcard results are capped at a span of 20: paginate.

## A client you can paste (Python, standard library only)

import json
import urllib.request


class ShadeClient:
    """Minimal shadeDB client. Keep your tokens on the server."""

    def __init__(self, endpoint, cluster_token, connection_token, timeout=10):
        self.endpoint = endpoint
        self.cluster_token = cluster_token
        self.connection_token = connection_token
        self.timeout = timeout

    def query(self, snl):
        body = json.dumps({
            "token": self.cluster_token,
            "cntoken": self.connection_token,
            "SNL": snl,
        }).encode()
        req = urllib.request.Request(
            self.endpoint,
            data=body,
            headers={"Content-Type": "application/json"},
            method="POST",
        )
        with urllib.request.urlopen(req, timeout=self.timeout) as res:
            data = json.loads(res.read())
        if isinstance(data, dict) and data.get("status") == "failed":
            raise RuntimeError(data.get("message", "query failed"))
        return data


db = ShadeClient("https://HOST/connect/INSTANCE_ID", "YOUR_CLUSTER_TOKEN", "YOUR_CONNECTION_TOKEN")
print(db.query("EXIST;\nstr<username>::str<shade>;"))

## Rules for agents

- Do not invent SNL syntax. If a mode or clause is not shown here, read /doc.
- Build query strings in one helper that escapes values. Never concatenate raw user input.
- Treat every response as untrusted JSON and check "status" before using it.
- One cluster token per service, so access can be rotated without touching the others.