docs(gresiq): document the document gateway + SDK upsert/query methods
Rewrites the GresIQ page to reflect the shipped JSONB document gateway and the new smbcloud-gresiq-sdk upsert_document/get_collection methods. Hold: merge to development only AFTER the SDK release publishes 0.4.7, since deploy-docs.yml auto-deploys on push to development and installs the latest published CLI. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
keypair34 committed
Jun 28, 2026 at 21:53 UTC
cab08c91da6de1f0a3229c959fbef5fffd44837a
1 file changed
+72
-11
website/content/gresiq.mdx
+72
-11
@@ -1,22 +1,83 @@
1
# GresIQ
2
3
-GresIQ is the database service — a managed, PostgreSQL-oriented database for your
4
-app.
3
+GresIQ is the managed data layer for your app — a document store built on
4
+PostgreSQL. You store and query JSON documents through a small REST gateway,
5
+authenticated with an API key and secret, so there is no database to run
6
+yourself.
7
8
## What you can do
9
8
-- Run a managed PostgreSQL-oriented database
9
-- Configure the service and get connection details
10
-- Reach your data through smbCloud Platform access patterns
10
+- Store JSON documents in named collections
11
+- Upsert by a natural key, or append documents that get a generated id
12
+- Query a collection with a containment filter, ordering, and a limit
13
+- Run simple counts and group-by aggregates over a collection
14
15
## How it fits together
16
14
-GresIQ is the data layer for your app. You set up the service, grab its
15
-connection details, and connect your app the way you would to any PostgreSQL
16
-database.
17
+Each GresIQ app gets an API key and secret — the data-plane credential — and
18
+reaches its data through the document gateway. There is no raw database
19
+connection to manage. Documents are grouped into **collections**, and each
20
+document is addressed by a **key** within its collection. The platform never
21
+interprets a document's shape; what the fields mean lives in your app.
22
+
23
+## The document gateway
24
+
25
+Every request authenticates with the `X-Gresiq-Api-Key` and
26
+`X-Gresiq-Api-Secret` headers and targets a collection:
27
+
28
+- `POST /gresiq/v1/collections/<collection>` — store a document. Send
29
+ `{ "key": "<id>", "doc": { ... } }` to upsert on that key, or omit `key` to
30
+ append a document with a generated id.
31
+- `GET /gresiq/v1/collections/<collection>` — list documents, optionally with a
32
+ `filter` (JSON containment), an `order` (`created_at` or `updated_at`), and a
33
+ `limit`.
34
+- `GET /gresiq/v1/collections/<collection>/<key>` — fetch one document.
35
+- `PATCH /gresiq/v1/collections/<collection>/<key>` — shallow-merge into a document.
36
+- `DELETE /gresiq/v1/collections/<collection>/<key>` — remove one document.
37
+- `POST /gresiq/v1/collections/<collection>/aggregate` — count, or group by a
38
+ single top-level field.
39
+
40
+## From Rust
41
+
42
+The `smbcloud-gresiq-sdk` crate wraps the gateway. Build a client from your
43
+environment and credentials, then upsert and query documents — the base URL is
44
+resolved from the environment, so you never hardcode a host:
45
+
46
+```rust
47
+use smbcloud_gresiq_sdk::{DocumentQuery, Environment, GresiqClient, GresiqCredentials};
48
+use serde_json::json;
49
+
50
+let client = GresiqClient::from_credentials(
51
+ Environment::Production,
52
+ GresiqCredentials { api_key: "your-key", api_secret: "your-secret" },
53
+);
54
+
55
+// Upsert a document keyed by "device-1".
56
+client
57
+ .upsert_document(
58
+ "devices",
59
+ Some("device-1"),
60
+ &json!({ "label": "Edge 1", "status": "online" }),
61
+ )
62
+ .await?;
63
+
64
+// Query the collection — only the documents matching the filter come back.
65
+let online = client
66
+ .get_collection::<serde_json::Value>(
67
+ "devices",
68
+ &DocumentQuery {
69
+ filter: Some(json!({ "status": "online" })),
70
+ ..Default::default()
71
+ },
72
+ )
73
+ .await?;
74
+```
75
+
76
+Each returned `GresiqDocument` carries the stored `doc` plus its `key` and
77
+timestamps.
78
79
## Getting started
80
20
-1. Create a GresIQ database.
21
-2. Open its connection details.
22
-3. Connect your app and start querying.
81
+1. Create a GresIQ app and copy its API key and secret.
82
+2. Pick a collection name and POST your first document.
83
+3. Read it back with a GET, or reach it from the SDK in your app.