GSI template-based keys not written/updated during upsert/patch/update operations

[ryota8128]

Description

When using template-based GSI keys (both PK and SK), upsert, patch, and update operations do not write the GSI key attributes (gsiN1pk, gsiN1sk) to the DynamoDB item. Only create and put (which use PutItem internally) correctly write these attributes.

Reproduction

Entity definition

export const ArticleLikeEntity = new Entity(
  {
    model: {
      entity: 'articleLike',
      version: '1',
      service: 'media',
    },
    attributes: {
      articleId: {
        type: 'string',
        required: true,
      },
      likeCount: {
        type: 'number',
        required: true,
        default: 0,
      },
    },
    indexes: {
      byArticleId: {
        pk: {
          field: 'pk',
          composite: ['articleId'],
        },
        sk: {
          field: 'sk',
          composite: [],
        },
      },
      likeRanking: {
        index: 'gsiN1',
        pk: {
          field: 'gsiN1pk',
          composite: [],
          template: 'ARTICLE_LIKE',
        },
        sk: {
          field: 'gsiN1sk',
          composite: ['likeCount'],
          template: '${likeCount}',
        },
      },
    },
  },
  { client: dynamoClient, table: tableName }
);

Steps to reproduce

1. Using upsert (GSI keys NOT written):

await ArticleLikeEntity.upsert({ articleId: 'test-article' })
  .add({ likeCount: 1 })
  .go();

Result: Item is created with likeCount: 1, but gsiN1pk and gsiN1sk are missing from the record.

2. Using create (GSI keys ARE written):

await ArticleLikeEntity.create({
  articleId: 'test-article',
  likeCount: 1,
}).go();

Result: Item is created with likeCount: 1, gsiN1pk: "article_like", and gsiN1sk: 1. GSI keys are correctly populated.

3. Using patch after create (GSI SK not updated):

// After create with likeCount: 1
await ArticleLikeEntity.patch({ articleId: 'test-article' })
  .add({ likeCount: 1 })
  .go();

Result: likeCount is incremented to 2, but gsiN1sk remains 1 (not updated to 2).

Expected behavior

• upsert should write GSI template-based key attributes.
• patch/update should re-compute and update GSI template-based SK when the underlying attribute changes.

Actual behavior

• upsert does not include GSI template-based keys in the UpdateExpression.
• patch/update updates the underlying attribute but does not re-compute the GSI SK from the template.

Root cause analysis

Looking at the source code:

• create/put use PutItem, which includes updatedKeys (containing GSI attributes) directly in the Item — works correctly.
• upsert/patch/update use UpdateItem with UpdateExpression. The GSI key re-computation from templates appears to be missing from the expression builder for these operations.

This seems related to previously fixed issues (#343, #366, #412) but specifically affects the template-based key pattern with Number-typed SK.

Environment

• ElectroDB: v3.7.5
• AWS SDK: v3
• DynamoDB Local: latest
• Node.js: v24.1.0

Workaround

Use put (PutItem) instead of patch/upsert for mutations that affect GSI template-based keys:

const existing = await ArticleLikeEntity.get({ articleId }).go();
const newCount = (existing.data?.likeCount ?? 0) + 1;
await ArticleLikeEntity.put({ articleId, likeCount: newCount }).go();

[rflorence]

I'm seeing the same thing with patch not updating a string GSI SK.

export const result = new Entity({
  model: {
    entity: 'result',
    version: '1',
    service: 'service'
  },
  attributes: {
    id: { type: 'string', required: true, default: () => randomUUID() },
    externalId: { type: 'string' },
  },
  indexes: {
    byExternalId: {
      index: 'gsi3',
      pk: { field: 'GSI3PK', composite: ['externalId'], template: 'externalid#${externalId}' },
      sk: { field: 'GSI3SK', composite: ['id'], template: 'result#${id}' }
    }
  }
})

await result.patch({ id: result.id })
  .set({ externalId })
  .go()

That patch sets externalId and GSI3PK but not GSI3SK. Adding .composite({ id: result.id }) doesn't change the behavior.

Here's another workaround to add the SK to the parameters if put is not ideal:

const patchParams = result.patch({ id: result.id })
  .set({ externalId })
  .params()

patchParams.ExpressionAttributeNames['#GSI3SK'] = 'GSI3SK';
patchParams.ExpressionAttributeValues[':GSI3SK_u0'] = `result#${result.id}`;
patchParams.UpdateExpression += ', #GSI3SK = :GSI3SK_u0';

const docClient = DynamoDBDocumentClient.from(new DynamoDBClient({}))
await docClient.send(new UpdateCommand(patchParams))

[tywalch]

Hi @rflorence 👋

I read through your examples, thank you for being so detailed. Firstly, I put together a model that I believe will achieve what you're hoping to do. Here is a playground for that model, note that I added field: 'gsiN1sk', on line 43.

Keeping key values in sync with attributes can be really difficult, and paired with ElectroDB's stance to not do implicit get->set operations under the hood, sometimes those constraints have weird seams. The only operations that affect indexes are set and delete, because they don't need to "know" the stored value to replicate it. This is a challenge with string keys, but you're right to point out that ElectroDB should probably account for numeric keys differently here.

I'll look into this to see how heavy the lift would be to add this caveat.

[tywalch]

Also, hi @rflorence 👋

Can you provide a more complete Entity for your example? I think the way your table index is defined may be contributing to what you're seeing, but without it, I can't be sure. Here's a playground I started using your example, it just needs a primary table index definition added to the entity to work: playground

[rflorence]

Sorry, I wanted to remove the noise and removed too much. Here is an updated playground that doesn't include the GSI3SK I expected it to include.