Ultrahost/ docs

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.

SDKRESTDescription
documents.createCollection(name, config?)POST /documents/collectionsCreate a document collection
documents.getCollection(name)GET /documents/collections/{name}Get collection configuration
documents.listCollections()GET /documents/collectionsList 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}/indexesCreate an index
documents.listIndexes(name)GET /documents/collections/{name}/indexesList indexes
documents.deleteIndex(name, indexId)DELETE /documents/collections/{name}/indexes/{indexId}Remove an index
ts
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

SDKRESTDescription
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}/queryQuery 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}/countCount matching documents
documents.batch(collection, operations)POST /documents/{collection}/batchExecute several operations
ts
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.