aws / aws/aws-record-ruby

Feature request: support DynamoDB multi-attribute GSI key schemas

Open
#155 1 comment 0 reactions 0 assignees View on GitHub
feature-request
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.