Version 1 of 1 · · razie · in person · Current version

name
d3-f-data
description
Data and objects — reading and writing a class's objects through the object API (one, list, query, batch), sample objects, private objects, inventories, objects from rules, quotas. Get skills only from /api/v2/skills/d3.
feature
data
concepts
[object, inventory]
tags
#skill #feature #d3skill #wip

d3-f-data

Intro

Objects: the instances of a project's classes.

Objects are the instances of a project's classes, Class:key, unique per class and project. They are read and written only through the object API (or the same operations from rules), checked against their class on every write, and stored in the class's inventory. Classes are d3-f-domain; showing data on a page is d3-f-pages › table_show. Spec: Spec › data.

Essentials

  • R-data-1 Objects go only through the object API or its rule operations; NEVER write them any other way.
  • R-data-2 A PUT replaces the whole object: read it, change it, put it back.
  • R-data-3 Many objects: one batch, never a loop of single writes.
  • R-data-4 A rejected write changed nothing: fix each field named in problems and resend.
  • R-data-5 Show data with a table on a page, not code (d3-f-pages › table_show).
  • R-data-6 Give your person the HTML twins (the same paths without /api/v2), never API links.

Concepts

object

One instance of a class with a @key: Class:key, unique per class and project. Also called: record, row, entry, data. Fields: the class's fields (d3-f-domain › field); computed fields come back on read, never stored.

object_read

  • Summary: list, query or one, by class.
  • When: before any change; to answer about data.
  • Needs: the class (and key for one).
  • Call: GET /api/v2/dom/val/Company → {total, class, data} Also: ?query=stage%20is%20%22Producer%22 · GET /api/v2/dom/val/Company:FLR → one.
  • Rules: R-data-6. Rate limits are per token: read once.
  • Errors: E_NOT_FOUND (404) → no object with that key, or a private class that isn't yours.
  • Gotchas: —

object_query

  • Summary: a query is an expression over fields.
  • When: filtering a list, a table or a rule's dom.find.
  • Needs: field names.
  • Call: ?query= with e.g. stage is "Producer" and marketCap > 100000000; a reference list: "prop-frost" in (properties ?? []).
  • Rules: —
  • Errors: E_WAIT → a web fetch in a query: fetch in a rule.
  • Gotchas: —

object_create

  • Summary: create a new key; an existing key is refused.
  • When: a new object.
  • Needs: every required field; a key not yet used.
  • Call: POST /api/v2/dom/val/Company {…}.
  • Rules: R-data-4. Every write is checked against its class.
  • Errors: E_EXISTS (409) → PUT to replace, or pick another key · E_VALIDATION (422) → fix problems · E_QUOTA (403) → plan limit: tell your person.
  • Gotchas: —

object_put

  • Summary: replace the whole object — read, change, put back.
  • When: changing an existing object.
  • Needs: the current object (object_read).
  • Call: PUT /api/v2/dom/val/Company:FLR {…whole object}.
  • Rules: R-data-2, R-data-4. Updating an existing object still works over quota.
  • Errors: E_VALIDATION (422).
  • Gotchas: —

object_delete

  • Summary: delete by key.
  • When: an object is no longer wanted.
  • Needs: the key.
  • Call: DELETE /api/v2/dom/val/Company:FLR.
  • Rules: —
  • Errors: E_NOT_FOUND (404).
  • Gotchas: —

object_batch

  • Summary: many writes, across classes, in one call.
  • When: more than a handful of writes; seeding; imports.
  • Needs: the writes; under 200 writes and 2 MB.
  • Call: POST /api/v2/dom/batch {mode, writes: [{op: "put"|"create"|"delete", cls, key, data}]} → {ok, written, results: [{i, cls, key, result: created|replaced|deleted|failed, problems?}]}.
  • Rules: R-data-3. mode: "all" (default) writes nothing if one is bad; "each" writes the good ones and lists the bad. One rate-limit write per 50 objects.
  • Errors: E_VALIDATION (422, all mode) → bad writes listed, nothing written · E_RATE → you wrote one by one: batch.
  • Gotchas: —

object_declare

  • Summary: sample objects as $object lines in a Story: or Spec: topic.
  • When: seeding a model so your person sees it working; test data.
  • Needs: the class.
  • Call: $object Company:FRST (ticker = "FRST", name = "Frost Inc", stage = "developer").
  • Rules: Story runs use a scratch copy of the objects, so they never change data — use them to test rules against data.
  • Errors: —
  • Gotchas: —

object_fromRule

  • Summary: rules write objects with the same checks as the API.
  • When: logic that creates or changes data (d3-f-engine).
  • Needs: —
  • Call: dom.upsert, dom.find, dom.list, dom.remove.
  • Rules: Every real write (not a story's scratch run) raises its entity event (diesel.entity.on.created…). A flow over quota gets E_QUOTA too.
  • Errors: E_VALIDATION · E_QUOTA.
  • Gotchas: —

object_private

  • Summary: @view=owner objects are seen only by their creator and mods up.
  • When: per-person data.
  • Needs: the class annotated @view=owner (d3-f-domain › class).
  • Call: the ordinary object routes.
  • Rules: —
  • Errors: E_NOT_FOUND (404) → it's private and not yours.
  • Gotchas: —

inventory

Where a class's objects live (@inventory): mongo (the default, a database) or col (the project's own file, a small opt-out). Also called: store, storage, collection.

inventory_choose

  • Summary: mongo by default; col only as a small opt-out.
  • When: declaring a class whose objects should live in the project's file.
  • Needs: —
  • Call: @inventory("col") on the $class line.
  • Rules: Any other name is refused. The API is the same for both. A class moved to another inventory takes its objects with it. Topics, drafts, history, trash and accounts are kept by d2 itself, not by any class's choice.
  • Errors: —
  • Gotchas: —

Rules

  • R-data-7 Per project, from its owner's plan (Settings:Quotas): objects (300 on Free), total size, and an object at most 250 KB as JSON; one more is E_QUOTA; updating an existing object still works. The Architect's writes and projects have no limit.
  • R-data-8 Demo projects reset every deploy from their seed: never rely on data you wrote there, and never re-create it by hand.

Errors

  • E_VALIDATION (422) with problems — fix each named field (type, required, unknown); nothing was written. see #object_create
  • E_EXISTS (409) — create with a key already there → PUT to replace, or another key. see #object_create
  • E_NOT_FOUND (404) — no object with that key, or a private class not yours. see #object_read
  • E_QUOTA (403) — the plan's object count or size; updates still work → tell your person. see #object_create
  • E_RATE — too many writes a minute → /dom/batch. see #object_batch
  • E_WAIT — a web fetch in a query → fetch in a rule. see #object_query