Data / flexible records
P0 · Foundation
Document Database
Store and retrieve structured information without rigid tables or predefined columns.
A developer creates a collection, optionally defines validation and indexes, and then stores JSON documents.
Paths in the tables are relative to https://api.ultrahost.com/v1/projects/{projectId}. Pagination, idempotency, and errors are described in Conventions.
Create
Create the collection before writing documents. A production documents.create() does not create a missing collection. See Architecture.
| SDK | REST | Description |
|---|---|---|
documents.createCollection(name, config?) | POST /documents/collections | Create a document collection |
documents.getCollection(name) | GET /documents/collections/{name} | Get collection configuration |
documents.listCollections() | GET /documents/collections | List collections |
documents.updateCollection(name, config) | PATCH /documents/collections/{name} | Update collection settings |
documents.deleteCollection(name) | DELETE /documents/collections/{name} | Delete a collection |
documents.createIndex(name, index) | POST /documents/collections/{name}/indexes | Create an index |
documents.listIndexes(name) | GET /documents/collections/{name}/indexes | List indexes |
documents.deleteIndex(name, indexId) | DELETE /documents/collections/{name}/indexes/{indexId} | Remove an index |
await ultrahost.documents.createCollection("projects");Configure
Use collection configuration for validation and for the indexes you actually query. Filters stay in Ultrahost's portable query format. They are not DynamoDB expressions, SQL, or another database's language.
An individual document does not support enable() or disable(). Those lifecycle verbs belong to configurable resources, not to each record.
Use
| SDK | REST | Description |
|---|---|---|
documents.create(collection, data) | POST /documents/{collection} | Create a document |
documents.get(collection, id) | GET /documents/{collection}/{id} | Retrieve by ID |
documents.list(collection, options?) | GET /documents/{collection} | List documents |
documents.query(collection, query) | POST /documents/{collection}/query | Query with filters and sorting |
documents.update(collection, id, data) | PATCH /documents/{collection}/{id} | Partially update a document |
documents.replace(collection, id, data) | PUT /documents/{collection}/{id} | Replace an entire document |
documents.upsert(collection, id, data) | PUT /documents/{collection}/{id} | Create or replace |
documents.delete(collection, id) | DELETE /documents/{collection}/{id} | Delete a document |
documents.count(collection, filter?) | POST /documents/{collection}/count | Count matching documents |
documents.batch(collection, operations) | POST /documents/{collection}/batch | Execute several operations |
const project = await ultrahost.documents.create("projects", {
name: "My Startup",
status: "active",
ownerId: user.id
});
const results = await ultrahost.documents.query("projects", {
filter: { status: "active" },
sort: [{ field: "createdAt", direction: "desc" }],
limit: 20
});In React, useDocuments("projects", query) and useDocument("projects", id) wrap the read path with loading and error state. See React.
replace and upsert share PUT. The SDK method names the caller's intent. The request body tells the two apart.