holdings · Umwelt docs

Reference/Queries/holdings

holdingsquerysince 0.1

What a holder holds at a position, one page at a time, with how each Holding was acquired.

Command lineTypeScript.NET

Request

umwelt call story.umw holdings '{
  "projectId": "ball",
  "holder": "ana",
  "at": { "tick": 5 },
  "page": { "limit": 2 }
}'

Request

const result = await client.holdings({
  projectId: 'ball',
  holder: 'ana',
  at: { tick: 5 },
  page: { limit: 2 },
});

Request

var result = engine.Holdings(new HoldingsPayload
{
    ProjectId = "ball",
    Holder = "ana",
    At = new At { Tick = 5 },
    Page = new Page { Limit = 2 },
});

Response

{
  "items": [
    {
      "acquisition": { "kind": "witnessed", "eventId": "scene-1" },
      "record": {
        "kind": "holding",
        "id": "ana-saw",
        "projectId": "ball",
        "timelineId": "main",
        "eventId": "scene-1",
        "holder": "ana",
        "claim": {
          "subject": "bob",
          "predicate": "stole",
          "object": { "kind": "entity", "id": "necklace" },
          "polarity": true,
          "qualifiers": {}
        },
        "attitude": "knows",
        "confidence": 1.0,
        "accessibility": "available",
        "acquisition": { "kind": "witnessed", "eventId": "scene-1" },
        "position": { "tick": 1 },
        "provenance": { "origin": { "kind": "human" } },
        "recordedAt": 2
      }
    },
    {
      "acquisition": {
        "kind": "told-by",
        "intent": "unknown",
        "sourceHolderId": "bob",
        "sourceRecordId": "bob-hid"
      },
      "record": {
        "kind": "holding",
        "id": "ana-heard",
        "projectId": "ball",
        "timelineId": "main",
        "eventId": "01a1cbd8-63e7-79a2-b499-79f2f92d2d0f",
        "holder": "ana",
        "claim": {
          "subject": "necklace",
          "predicate": "hidden-in",
          "object": { "kind": "entity", "id": "garden" },
          "polarity": true,
          "qualifiers": {}
        },
        "attitude": "believes",
        "confidence": 1.0,
        "accessibility": "available",
        "acquisition": {
          "kind": "told-by",
          "intent": "unknown",
          "sourceHolderId": "bob",
          "sourceRecordId": "bob-hid"
        },
        "position": { "tick": 5 },
        "provenance": { "origin": { "kind": "system", "name": "umwelt:transmit" } },
        "recordedAt": 6
      }
    }
  ],
  "withheldCount": 0
}

Payload

Field	Type	Description
`projectId`required	string	The project to read.
`holder`required	string	The agent or group asked about.
`at`	Atdefault {}	Where to read: `tick`, an optional `axis`, and `asOfVersion`. Defaults to the latest.
`filter`	HoldingFilterdefault {"attitude":[],"includeWithheld":false}	Narrows the list: `predicate`, `about` (an entity in the subject or the object), `attitude` (any of the ones listed), `minConfidence`, and `includeWithheld` to include suppressed and inaccessible Holdings.
`page`	Pagedefault {"limit":100}	How many items to return (`limit`, 1 to 1000) and where to continue (`cursor`, the `nextCursor` of the previous page).
`timelineId`	stringdefault "main"	The timeline to read.

Result

Field	Type	Description
`items`always	HoldingItem[]	The Holdings, each with its `acquisition` and, when one applies, its transition `status`.
`nextCursor`	string	More Holdings follow; pass it as `page.cursor`.
`withheldCount`always	integer	How many suppressed or inaccessible Holdings match but were left out.

Rules

Only the holder’s own records. A Fact, another holder’s Holding or a group the holder belongs to never appears here.

Withheld knowledge is counted, not shown. Suppressed and inaccessible Holdings stay out unless filter.includeWithheld asks for them; withheldCount says how many there are.

Pages are stable. The order is (tick, recordedVersion, recordId), so a cursor stays valid when later writes arrive.

Errors

VALIDATION_FAILEDThe payload is malformed, or the page limit is outside 1 to 1000.

NOT_FOUNDThe project, holder or timeline does not exist, or the draft read was purged.

INVALID_STATEThe timeline read is a draft that was promoted. details.promotedInto names the timeline to read instead.

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Rules

Errors

See also