Feature request: support DynamoDB multi-attribute GSI key schemas

[thomaswitt]

Describe the feature

DynamoDB now supports multi-attribute key schemas for GSIs (up to 4 partition key attributes + 4 sort key attributes).

aws-record currently models GSIs as:

• one hash_key
• optional one range_key

Because of this, there is no way to define newer GSI key schemas using Aws::Record DSL or TableConfig migrations.

Use Case

In real single-table designs, we currently pack multiple dimensions into synthetic strings (for example STATUS#timestamp#suffix) only because the DSL is limited to one hash + one range key.

With native multi-attribute GSIs, users can:

• avoid manual key concatenation/parsing
• preserve native attribute types
• express more access patterns with cleaner models
• reduce app-side key-munging logic

Proposed Solution

Add first-class support for multi-attribute GSI keys while keeping backward compatibility.

Potential API shape:

global_secondary_index :tournament_region,
  hash_keys: %i[tournament_id region],
  range_keys: %i[round bracket match_id],
  projection: { projection_type: 'ALL' }

Backward-compatible behavior:

• hash_key: -> treated as hash_keys: [hash_key]
• range_key: -> treated as range_keys: [range_key]

Areas that would need updates:

• index validation (secondary_indexes.rb)
• key schema generation (_si_key_schema)
• attribute definition collection in table config/migration paths

Other Information

Context links:

• AWS announcement: https://aws.amazon.com/about-aws/whats-new/2025/11/amazon-dynamodb-multi-attribute-composite-keys-global-secondary-indexes/
• DynamoDB docs (GSI.MultiAttributeKeys): https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html#GSI.MultiAttributeKeys
• Pattern guide with API examples: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.DesignPattern.MultiAttributeKeys.html

Observed current limit in aws-record main branch:

• global_secondary_index expects hash_key/range_key
• _si_key_schema emits only one HASH + optional one RANGE

Current workaround is using low-level Aws::DynamoDB::Client APIs directly for table/index creation, but then model/table declarations are split between two abstractions.

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

aws-sdk-ruby-record version used

2.14.0

Environment details (OS name and version, etc.)

Ruby 3.4.8, aws-sdk-dynamodb 1.161.0

[jterapin]

Thanks for the feature request! We already have this in our backlog and will update this issue when we have more details to share.