SIGN IN SIGN UP

INTPYTHON-948 Fix multikey index collision on namespace array (#375)

INTPYTHON-948

## Summary

Replace the unique index on the namespace array + key with one on a
denormalized namespace_str field (e.g. \`"users/alice/preferences"\`) +
key. Indexing an array creates a multikey index whose entries are
individual elements, so two documents sharing any namespace component
and the same key would collide with a duplicate-key error.

On init, legacy documents are backfilled with \`namespace_str\` in
batches, then the new \`(namespace_str, key)\` unique index is created,
and finally the old \`(namespace, key)\` index is dropped — ensuring
uniqueness is always enforced. All read and write operations (\`get\`,
\`delete\`, \`batch\`) now filter on \`namespace_str\` + \`key\` to use
the new index. Namespace parts are validated to not contain the
separator to prevent join collisions.

## Changes in this PR

- Replaces multikey index on \`namespace\` array with a unique index on
\`namespace_str\` + \`key\`
- Backfills \`namespace_str\` on legacy documents in batches of 1000
before building the unique index
- Drops the old \`(namespace, key)\` index only after the new unique
index exists (no window without uniqueness enforcement)
- Migrates all query filters in \`get()\`, \`delete()\`, and \`batch()\`
to use \`namespace_str\` + \`key\`
- Stores \`namespace\` array via \`\$setOnInsert\` on upsert so \`Item\`
deserialization continues to work
- Raises \`ValueError\` if any namespace part contains the separator to
prevent join collisions

## Test Plan

Integration tests cover the duplicate-key regression (INTPYTHON-948).

## Checklist

### Checklist for Author

- [x] Did you update the changelog (if necessary)?
- [x] Is the intention of the code captured in relevant tests?
- [ ] If there are new TODOs, has a related JIRA ticket been created?
- [ ] Has a MongoDB Employee run [the patch build of this
PR](https://github.com/mongodb-labs/ai-ml-pipeline-testing?tab=readme-ov-file#running-a-patch-build-of-a-given-pr)?

### Checklist for Reviewer

- [x] Does the title of the PR reference a JIRA Ticket?
- [x] Do you fully understand the implementation? (Would you be
comfortable explaining how this code works to someone else?)
- [ ] Is all relevant documentation (README or docstring) updated?

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
J
Jeffrey 'Alex' Clark committed
f9068887a1d3157566114b27ef88209b6d12d5ca
Parent: 0373a5a
Committed by GitHub <noreply@github.com> on 5/5/2026, 5:43:27 PM