Delete array items

Choose a mutation

Requirement	Mutation
Delete selected items by domain or service identity	deleteArrayItems
Delete one item by service-generated ID	deleteArrayItem
Clear an entire array	deleteArray

Delete selected items with deleteArrayItems

deleteArrayItems accepts itemIds, ids, or both. At least one selector list must be non-empty.

Example: Delete by itemId

mutation DeleteFavorites($input: DeleteArrayItemsInput!) {
  deleteArrayItems(input: $input) {
    acknowledged
    deletedCount
  }
}

{
  "input": {
    "scope": "USER",
    "key": "content:favorites",
    "itemIds": ["movie:100", "movie:200"]
  }
}

{
  "data": {
    "deleteArrayItems": {
      "acknowledged": true,
      "deletedCount": 2
    }
  }
}

Example: Combine itemId and service-generated ID selectors

{
  "input": {
    "scope": "USER",
    "key": "content:favorites",
    "itemIds": ["movie:100"],
    "ids": ["66b100000000000000000001"]
  }
}

The selector lists form a union. A document matching both is deleted once. Repeated selectors do not cause repeated deletion.

Unknown selectors and duplicate matches

• Unknown selectors are successful no-ops.
• Every qualifying legacy duplicate matching an itemId is deleted.
• deletedCount is the number of documents deleted, so it can exceed the number of unique itemId selectors.
• The raw combined selector count must not exceed 100 before deduplication.

Delete one item with deleteArrayItem

deleteArrayItem is supported and is not deprecated. It deletes one item using a service-generated ID.

Example: Delete by service-generated ID

mutation DeleteFavorite($input: DeleteArrayItemInput!) {
  deleteArrayItem(input: $input) {
    acknowledged
    deletedCount
  }
}

{
  "input": {
    "scope": "USER",
    "key": "content:favorites",
    "id": "66b100000000000000000001"
  }
}

An unknown ID is a successful no-op with deletedCount: 0.

Delete an entire array with deleteArray

deleteArray removes every item for the authenticated scope and key.

Example: Clear the favorites array

mutation ClearFavorites($input: DeleteArrayInput!) {
  deleteArray(input: $input) {
    acknowledged
    deletedCount
  }
}

{
  "input": {
    "scope": "USER",
    "key": "content:favorites"
  }
}

{
  "data": {
    "deleteArray": {
      "acknowledged": true,
      "deletedCount": 2
    }
  }
}

Use deleteArray instead of an empty replaceArrayItems request. Empty replacement arrays are invalid.

Understanding deletion responses

• acknowledged indicates that the mutation was accepted.
• deletedCount reports the actual number of stored item documents deleted.
• Inspect GraphQL errors[].extensions for failures; do not parse error message text.

Atomicity and concurrent writes

Array deletions are transactional. A CONCURRENT_WRITE_CONFLICT leaves stored data unchanged.

See Errors and limits.