entity.ensureBatch · Umwelt docs

Reference/Commands/entity.ensureBatch

entity.ensureBatchcommandsince 0.1

Registers entities by your own ids: creates the missing ones and updates the others, in one transaction.

Command lineTypeScript.NET

Request

umwelt call story.umw entity.ensureBatch '{
  "projectId": "ball",
  "entities": [
    {
      "externalRef": { "system": "game", "id": "npc-12" },
      "id": "guard",
      "typeId": "person",
      "name": "The guard"
    }
  ]
}'

Request

const result = await client.entityEnsureBatch({
  projectId: 'ball',
  entities: [
    {
      externalRef: { system: 'game', id: 'npc-12' },
      id: 'guard',
      typeId: 'person',
      name: 'The guard',
    },
  ],
});

Request

var result = engine.EntityEnsureBatch(new EnsureEntitiesInput
{
    ProjectId = "ball",
    Entities = new()
    {
        new EnsureEntityInput
        {
            ExternalRef = new ExternalRef { System = "game", Id = "npc-12" },
            Id = "guard",
            TypeId = "person",
            Name = "The guard",
        },
    },
});

Response

[
  {
    "created": true,
    "entity": {
      "id": "guard",
      "projectId": "ball",
      "name": "The guard",
      "aliases": [],
      "typeId": "person",
      "archived": false,
      "createdAt": { "tick": 0 },
      "externalRef": { "id": "npc-12", "system": "game" },
      "fields": {}
    }
  }
]

Payload

Field	Type	Description
`projectId`required	string	The project to write to.
`entities`required	EnsureEntityInput[]	The entities, each keyed by its `externalRef`, with a `typeId`, a `name` and optionally an `id`, aliases, fields and `createdAt`.

Result

A list of EnsureEntityResult, each with:

Field	Type	Description
`created`always	boolean	True when the entity was created, false when it existed.
`entity`always	Entity	The entity as stored now.

Rules

Ensuring twice changes nothing. An existing entity has its name, aliases and fields updated, and keeps its id and type.

Choose the ids yourself, or keep the map. Give id (for example your game’s own id) or keep the map this returns: other operations take engine ids.

Errors

VALIDATION_FAILEDThe payload is malformed, the same reference appears twice, or an existing entity is given another typeId.

CONFLICTAn existing entity is given another id.

NOT_FOUNDThe project or an entity type does not exist.

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Rules

Errors

See also