delete() — Entity Service

General Description

The delete operation removes entities from the database based on specified criteria.

Detailed Description

This operation allows you to delete one or more entities that match specific criteria. It can delete a single entity by ID or multiple entities that match certain conditions. The operation is permanent and cannot be undone, so it should be used with caution.

Input Parameters

Parameter	Type	Required	Description
request	object	Yes	The delete request object specifying what to delete.
confirm	boolean	No	Must be true to execute. Without it the operation returns a confirmation challenge instead of deleting.
confirmationToken	string	No	The token returned by the challenge. Required when confirm is true.
token	string	No	Authentication token for your request. If not provided, the system will use the default API key from environment variables.
tenantCode	string	No	Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables.

Request Object Structure

Property	Type	Required	Description
entDefName	string	Yes*	Name of the entity definition. Required if entDefId is not provided.
entDefId	string	Yes*	ID of the entity definition. Required if entDefName is not provided.
entityDef	object	No	Optional entity definition object with id and/or name properties.
entityId	string	Yes	ID of the entity to delete.

Two-step confirmation

delete is registered as a destructive tool. It is disabled by default and gated behind a confirmation handshake:

1. Call it with the request only. The response carries requiresConfirmation: true and a confirmationToken derived from the request payload and tenant.
2. Repeat the identical call with confirm: true and that confirmationToken.

The token is bound to the exact payload. Changing any field between the two calls invalidates it, and each token is consumed on use.

Cascade Delete

Cascade behavior is configured on the child entity's reference property with cascadeReference: true. The reference points from the dependent child to its parent. Deleting the parent then automatically deletes every child that refers to it through that property.

Cascade delete is recursive. If a deleted child is itself the parent of another cascade reference, those dependent records are deleted too. For example:

Order <- OrderItem.order (cascadeReference: true)
OrderItem <- OrderItemVariant.orderItem (cascadeReference: true)

A single delete request for an Order deletes its matching OrderItem records and their matching OrderItemVariant records. Callers do not issue separate delete requests for those descendants.

Single-entity deletes also execute configured workflow and serverless delete triggers. To preserve cascades and triggers while deleting multiple root records, batch multiple single-entity delete requests instead of using deleteQuery.

Only relationships whose child reference has cascadeReference: true participate. Unmarked references are not implicitly deleted and may cause the root delete to fail when referential integrity requires the related records to remain.

Response

Confirmation Challenge

{
    "success": false,
    "requiresConfirmation": true,
    "operation": "delete",
    "confirmationToken": "delete-1a2b3c4d",
    "message": "Confirmation required. Repeat delete with confirm=true and confirmationToken=delete-1a2b3c4d."
}

Success Response

{
    "success": true,
    "data": {
        "affectedRowCount": 1,
        "deleteCount": 1,
        "status": 200,
        "message": "string"
    }
}

data is the raw backend response. affectedRowCount is the authoritative count of removed rows.

Error Response

{
    "success": false,
    "message": "Error message describing what went wrong"
}

Condition	message
confirm: true sent without a token	confirmationToken is required when confirm=true.
Token does not match the payload, or was already used	Invalid or stale confirmation token. Call the tool once without confirm to get a new token.
Neither entDefName, entDefId, nor entityDef supplied	Entity definition is required
entityId missing	Entity id is required
Token missing, expired, or issued for another tenant	Authentication error text from the backend
Caller lacks delete permission on the definition or tenant	Authorization error text from the backend
A referential integrity constraint blocks the delete	Constraint error text from the backend
Network or transport failure	The underlying transport error message

The operation does not throw across the tool boundary; every failure is returned in this shape.

Example Usage

Delete a Single Entity by ID

const result = await delete({
  request: {
    entDefName: "Customer",
    entityId: "customer-id-to-delete"
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log(`Deleted ${result.data.affectedRowCount} customer(s)`);
} else {
  console.error("Error:", result.message);
}

Complete the two-step confirmation from the CLI

# 1. Ask for the token
gsb call delete --raw --input '{
  "request": { "entDefName": "Customer", "entityId": "customer-id" }
}'

# 2. Repeat the identical payload with the returned token
gsb call delete --yes --raw --input '{
  "request": { "entDefName": "Customer", "entityId": "customer-id" },
  "confirm": true,
  "confirmationToken": "delete-1a2b3c4d"
}'

Delete Using Entity Definition ID

const result = await delete({
  request: {
    entDefId: "customer-def-id",
    entityId: "customer-id-to-delete"
  },
  confirm: true,
  confirmationToken: "delete-1a2b3c4d",
  token: "your-auth-token"
});

if (result.success) {
  console.log("Customer deleted successfully");
} else {
  console.error("Error:", result.message);
}

Delete with Entity Definition Object

const result = await delete({
  request: {
    entityDef: {
      name: "Order"
    },
    entityId: "order-id-to-delete"
  },
  token: "your-auth-token"
});

Additional Information

• The delete operation is permanent and cannot be undone. Use it with caution.
• When deleting by ID, exactly one entity will be deleted if it exists.
• The count of removed rows is data.affectedRowCount.
• Access permissions are enforced based on the provided token.
• For filter-driven bulk removal that does not require cascades or delete triggers, use deleteQuery.
• Cascade rules apply automatically and recursively as described above.
• For soft delete (marking entities as deleted without physically removing them), use a status field and save instead.
• Model-generated deletes require explicit user confirmation before the second call is made.