# 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.
shadeDB