entity.at · Umwelt docs

Reference/Queries/entity.at

entity.atquerysince 0.1

An entity as canon names it at a position: its name, title and aliases over time.

Command lineTypeScript.NET

Request

umwelt call story.umw entity.at '{
  "projectId": "ball",
  "entityId": "bob",
  "at": { "tick": 1 }
}'

Request

const result = await client.entityAt({ projectId: 'ball', entityId: 'bob', at: { tick: 1 } });

Request

var result = engine.EntityAt(new EntityAtPayload
{
    ProjectId = "ball",
    EntityId = "bob",
    At = new At { Tick = 1 },
});

Response

{
  "recordIds": ["bob-mask"],
  "name": "Bob",
  "aliases": ["the masked guest"],
  "entity": {
    "id": "bob",
    "projectId": "ball",
    "name": "Bob",
    "aliases": ["the masked guest"],
    "typeId": "person",
    "archived": false,
    "createdAt": { "tick": 0 },
    "fields": {}
  }
}

Payload

Field	Type	Description
`projectId`required	string	The project to read.
`entityId`required	string	The entity, by its engine id.
`at`	Atdefault {}	Where to read: `tick`, an optional `axis`, and `asOfVersion`. Defaults to the latest.
`timelineId`	stringdefault "main"	The timeline to read.

Result

Field	Type	Description
`entity`always	Entity	The entity as stored.
`name`always	string	Its name at the position: the latest active `umwelt:name` Fact, or the entity’s own name.
`title`	string	Its title at the position, from `umwelt:title`.
`aliases`always	string[]	Its aliases at the position, from `umwelt:alias`.
`recordIds`always	string[]	The Facts the name, title and aliases come from.

Rules

The latest Fact wins. A negated latest umwelt:title Fact clears the title.

This is canon. It says what the entity is called, not what anyone knows. Ask entity.asKnownBy for a holder.

Errors

VALIDATION_FAILEDThe payload is malformed.

NOT_FOUNDThe project, entity 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