Clarify data-loss risk when adding .secondaryIndexes() to an existing model

[brightversion1]

Environment information

* Amplify Gen 2 data models
* Amplify CLI
* DynamoDB via CloudFormation

Describe the bug

When adding a .secondaryIndexes((index) => [ index("someField") ]) modifier to an existing model in AWS Amplify Gen 2, I observed that all existing records in the corresponding DynamoDB table were dropped. This behavior is not currently clearly explained in the “Customize secondary indexes” documentation. ([docs.amplify.aws][1])

Reproduction steps

Steps to reproduce

1. Create a model without any secondary index (e.g., MyModel).
2. Seed data into the model.
3. Update the model definition to include .secondaryIndexes((index) => [ index("myField") ]).
4. Run npx ampx sandbox (or equivalent).
5. Observe that the DynamoDB table is recreated and existing data is lost.

---

Expected behavior

Documentation should clearly state that adding, modifying, or removing a secondary index on a model will recreate the backend DynamoDB table, resulting in data loss unless handled via migration/export/import.

It should also provide:

• A migration strategy or warning for users with existing production data.

---

Actual behavior

• The doc shows how to add secondary indexes, but does not call out that doing so for a live model may delete existing data.
• Users may incorrectly assume that adding an index is a safe incremental change.

---

Suggested documentation improvements

• Add a section titled “Impact of modifying secondary indexes on existing data”.
• Explain that changing indexes causes the CloudFormation stack to rebuild the underlying DynamoDB table.
• Provide best practices (e.g., export data, apply schema change in a new table/environment, re-import data).
• Possibly provide example CLI/script for export/reimport.

---

[kaizencc]

hi @brightversion1, i'm sorry that you are seeing this behavior. adding secondary indexes should not cause dynamodb table recreation because that is a supported operation (see here). Is it possible that your change was accompanied by an additional diff that caused replacement?

[fossamagna]

I suspect this behavior occurs only in the sandbox environment.
The following code is the relevant section causing this behavior.

amplify-backend/packages/backend-data/src/factory.ts

Lines 340 to 346 in b6ef34d

	/**;
	* Enable the table replacement upon GSI update
	* This is allowed in sandbox mode ONLY
	*/
	if (isSandboxDeployment) {
	Aspects.of(amplifyApi).add(new ReplaceTableUponGsiUpdateOverrideAspect());
	}

It would be good if the documentation explicitly stated that DynamoDB tables are replaced only in the sandbox environment when changing the GSI.