Delete

GraphQL allows to query and mutate data. Mutations are operations like create, update and delete. This chapter describes how data can be deleted.

Delete options

The delete operation supports two modes via the options parameter:

Option	Description
ARCHIVE	Soft delete - entity is marked as archived and excluded from query results (default)
ERASE	Hard delete - entity is permanently removed from the database

By default, entities are archived (ARCHIVE). Archived entities are not returned in normal queries but remain in the database.

Simple delete mutation

To delete entities, use the runtimeEntities endpoint with the delete operation. You need to provide an array of RtEntityId objects, which contain both the rtId and the ckTypeId.

mutation {
  runtime {
    runtimeEntities {
      delete(
        options: ARCHIVE
        entities: [
          {
            rtId: "662532d5241639b42933057e"
            ckTypeId: "Industry.Energy/EnergyMeter"
          }
        ]
      )
    }
  }
}

The result will be a boolean indicating success:

{
  "data": {
    "runtime": {
      "runtimeEntities": {
        "delete": true
      }
    }
  }
}

Permanent delete (ERASE)

To permanently remove entities from the database, use options: ERASE:

mutation {
  runtime {
    runtimeEntities {
      delete(
        options: ERASE
        entities: [
          {
            rtId: "662532d5241639b42933057e"
            ckTypeId: "Industry.Energy/EnergyMeter"
          }
        ]
      )
    }
  }
}

caution

Using ERASE permanently removes the entity from the database. This operation cannot be undone.

Delete with variables

For programmatic use, it is recommended to use GraphQL variables:

mutation deleteEntities($rtEntityIds: [RtEntityId]!, $options: DeleteOptions) {
  runtime {
    runtimeEntities {
      delete(options: $options, entities: $rtEntityIds)
    }
  }
}

Variables:

{
  "options": "ARCHIVE",
  "rtEntityIds": [
    {
      "rtId": "662532d5241639b42933057e",
      "ckTypeId": "Industry.Energy/EnergyMeter"
    }
  ]
}

Batch delete

Multiple entities can be deleted in a single mutation. The entities can be of different types:

mutation deleteEntities($rtEntityIds: [RtEntityId]!) {
  runtime {
    runtimeEntities {
      delete(entities: $rtEntityIds)
    }
  }
}

Variables:

{
  "rtEntityIds": [
    {
      "rtId": "662532d5241639b42933057e",
      "ckTypeId": "Industry.Energy/EnergyMeter"
    },
    {
      "rtId": "65dc6d24cc529cdc46c84fcc",
      "ckTypeId": "Industry.Energy/EnergyMeter"
    },
    {
      "rtId": "667acc3be06025c7329fc57c",
      "ckTypeId": "Basic/EquipmentGroup"
    }
  ]
}

RtEntityId structure

The RtEntityId input type requires two fields:

Field	Type	Description
rtId	OctoObjectId	The runtime identifier of the entity
ckTypeId	String	The construction kit type identifier (e.g., Industry.Energy/EnergyMeter)

Both fields are required to uniquely identify and delete an entity.

Cascade behavior

When deleting entities, be aware of the cascade behavior:

• Associations: Deleting an entity will remove all associations where this entity is involved
• Child entities: Depending on the association configuration, child entities might be deleted automatically (cascade delete) or the delete might fail if children exist

info

With ARCHIVE (default), entities can potentially be restored. With ERASE, deletion is permanent and cannot be undone. Always ensure you have proper backups before performing ERASE operations on production data.