Description
Feature Request: Native Support for Begins_With on Index Keys in ElectroDB
Summary
We are requesting native support in ElectroDB for begins_with query semantics on index keys, particularly for use cases where the key represents a hierarchical or scoped string. This would enable clean and intuitive querying of entities with flexible scope strings like org, org:1234-1234, or org:1234-1234:team, without requiring manual construction of begins_with queries.
Background
We use ElectroDB to model a Role entity with a scope field representing organizational hierarchy. Our use case requires fetching all roles within a given scope, which is a custom string like:
orgorg:1234-1234org:1234-1234:team
Currently, to support prefix-based querying on these values, we create a custom index using the following pattern:
indexes: {
scope: {
index: 'gsi1',
pk: {
field: 'gsi1pk',
composite: [],
},
sk: {
field: 'gsi1sk',
composite: ['scope', '_'],
template: 'scope_${scope}${_}',
},
},
}We use a dummy _ attribute of type string with a default value of an empty string '', solely to enable begins_with functionality on the scope attribute when using queries.
attributes: {
_: {
type: 'string',
readOnly: true,
default: '',
},With this setup, we are able to do:
Role.query.scope({ scope: 'org:1234-1234' });and get all records with scopes beginning with org:1234-1234. However, this requires all records to have the _ field defined just to maintain a valid sort key template and support begins_with.
We want to eliminate the need to include the _ attribute on every record, and instead support this pattern natively.
Proposed Feature
Introduce an option in ElectroDB to allow query.<index>({ field }) calls to automatically translate into a begins_with query on the index's sort key when configured accordingly.
Example Configuration
indexes: {
scope: {
index: 'gsi1',
pk: {
field: 'gsi1pk',
composite: [],
},
sk: {
field: 'gsi1sk',
composite: ['scope'],
template: 'scope_${scope}',
query: 'begins_with' // <--- proposed option
},
},
}Or a new API feature:
Role.query.scope({ scope: 'org:1234-1234' }, { match: 'begins_with' });Benefits
- Clean, expressive, and intuitive querying API.
- Eliminates the need for placeholder attributes like
_. - Reduces boilerplate and improves developer experience.
- Encourages idiomatic usage of scoped and hierarchical keys in DynamoDB.
Workarounds Today
To achieve this behavior today, we:
- Define a
_attribute of typestring, defaulting to''. - Include
_in the composite sort key template. - Use
.query.scope({ scope })to achievebegins_withsemantics.
While functional, this is a workaround. We do not use manual .where().begins() calls like:
Role.query.scope({}).where(({ gsi1sk }, { begins }) => begins('scope_org:1234-1234'));Conclusion
Adding built-in support for begins_with queries on index sort keys would significantly enhance the flexibility of ElectroDB in hierarchical data scenarios, reduce complexity in application code, and allow index key modeling that better aligns with real-world use cases like scoping, tenancy, and category hierarchies.