docs: Update docs to reflect new support for composite keys in DynamoDB

Author: Tom McCarthy

docs/utilities/idempotency.md

@@ -321,16 +321,18 @@ This persistence layer is built-in, and you can either use an existing DynamoDB
     )
     ```
 
-These are knobs you can use when using DynamoDB as a persistence layer:
+When using DynamoDB as a persistence layer, you can alter the attribute names by passing these parameters when initializing the persistence layer:
 
 Parameter | Required | Default | Description
 ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------
 **table_name** | :heavy_check_mark: | | Table name to store state
-**key_attr** |  | `id` | Primary key of the table. Hashed representation of the payload
+**key_attr** |  | `id` | Partition key of the table. Hashed representation of the payload (unless **sort_key_attr** is specified)
 **expiry_attr** |  | `expiration` | Unix timestamp of when record expires
 **status_attr** |  | `status` | Stores status of the lambda execution during and after invocation
 **data_attr** |  | `data`  | Stores results of successfully executed Lambda handlers
 **validation_key_attr** |  | `validation` | Hashed representation of the parts of the event used for validation
+**sort_key_attr** | | | Sort key of the table (if table is configured with a sort key).
+**static_pk_value** | | `idempotency#{LAMBDA_FUNCTION_NAME}` | Static value to use as the partition key. Only used when **sort_key_attr** is set.
 
 ## Advanced
 
@@ -590,6 +592,36 @@ The **`boto_config`** and **`boto3_session`** parameters enable you to pass in a
        ...
     ```
 
+### Using a DynamoDB table with a composite primary key
+
+If you wish to use this utility with a DynamoDB table that is configured with a composite primary key (uses both partition key and sort key), you
+should set the `sort_key_attr` parameter when initializing your persistence layer. When this parameter is set, the partition key value for all idempotency entries
+will be the same, with the idempotency key being saved as the sort key instead of the partition key. You can optionally set a static value for the partition
+key using the `static_pk_value` parameter. If not specified, it will default to `idempotency#{LAMBDA_FUNCTION_NAME}`.
+
+=== "MyLambdaFunction"
+
+    ```python hl_lines="5"
+    from aws_lambda_powertools.utilities.idempotency import DynamoDBPersistenceLayer, idempotent
+
+    persistence_layer = DynamoDBPersistenceLayer(
+        table_name="IdempotencyTable",
+        sort_key_attr='sort_key')
+
+
+    @idempotent(persistence_store=persistence_layer)
+    def handler(event, context):
+        return {"message": "success": "id": event['body']['id]}
+    ```
+
+The example function above would cause data to be stored in DynamoDB like this:
+
+| id                           | sort_key                         | expiration | status      | data                                |
+|------------------------------|----------------------------------|------------|-------------|-------------------------------------|
+| idempotency#MyLambdaFunction | 1e956ef7da78d0cb890be999aecc0c9e | 1636549553 | COMPLETED   | {"id": 12391, "message": "success"} |
+| idempotency#MyLambdaFunction | 2b2cdb5f86361e97b4383087c1ffdf27 | 1636549571 | COMPLETED   | {"id": 527212, "message": "success"}|
+| idempotency#MyLambdaFunction | f091d2527ad1c78f05d54cc3f363be80 | 1636549585 | IN_PROGRESS |                                     |
+
 ### Bring your own persistent store
 
 This utility provides an abstract base class (ABC), so that you can implement your choice of persistent storage layer.