Feature request: support DynamoDB multi-attribute GSI key schemas
- Dominant language
- Ruby
- Stars
- 318
- Forks
- 43
- Avg merge
- 19h
- Merged PRs (30d)
- 1
Description
### Describe the feature
DynamoDB [now supports](https://aws.amazon.com/blogs/database/multi-key-support-for-global-secondary-index-in-amazon-dynamodb/) **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:
```ruby
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
Contributor guide
Assessment
This issue has not been assessed yet.