What is the $condition input parameter for in a GraphQL mutation generated by AWS Amplify CLI?

Question

I have generated a simple GraphQL API on AWS AppSync (using CLI) from this model:

type WalletProperty @model {
    id: ID!
    title: String!
}

This generated a CreateWalletProperty, UpdateWalletProperty and DeleteWalletProperty mutations all similar to this:

  mutation CreateWalletProperty(
    $input: CreateWalletPropertyInput!
    $condition: ModelWalletPropertyConditionInput    <<<<<<<<<<<<  what is this for?
  ) {
    createWalletProperty(input: $input, condition: $condition) {
      id
      title
      createdAt
      updatedAt
    }
  }

and the schema for the condition being:

input ModelWalletPropertyConditionInput {
  title: ModelStringInput
  and: [ModelWalletPropertyConditionInput]
  or: [ModelWalletPropertyConditionInput]
  not: ModelWalletPropertyConditionInput
}

Given that I always have to supply the mandatory $input, what is the $condition parameter for?

Answer 1

In my case above the GraphQL is backed by a DynamoDB table;

Behind the scenes, the GraphQL operations translate to PutItem, UpdateItem, and DeleteItem DynamoDB operations.

For these data manipulation operations, DynamoDB API allows you to specify a condition expression to determine which items should be modified. If the condition expression evaluates to true, the operation succeeds; otherwise, the operation fails.

You can read more about use cases for each of these conditions on the AWS Condition Expressions DynamoDB dev guide

At GraphQL mutation level, only if the record meets the condition, will the mutation go ahead. Otherwise the mutation is not allowed and a ConditionalCheckFailedException is returned:

"errors": [
    {
      "path": [
        "deleteWalletProperty"
      ],
      "data": null,
      "errorType": "DynamoDB:ConditionalCheckFailedException",
      "errorInfo": null,
      "locations": [
        {
          "line": 12,
          "column": 3,
          "sourceName": null
        }
      ],
      "message": "The conditional request failed (Service: DynamoDb, Status Code: 400, Request ID: E3PR9OM6M5J1QBHKNT8E4SM1DJVV4KQNSO5AEMVJF66Q9ASUAAJG, Extended Request ID: null)"
    }
  ]