Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Support undefined partition keys (PartitionKey.None) across item commands

Aperta
  • Qualcosa non va?
#251 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 2 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
15/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
csharp
Ambito
cli, database

Direzione di ricerca

Start with the shared partition-key conversion that the typed parser uses, and with how mkitem and create item currently infer keys from item content. Before changing anything, reproduce the missing-key case against the emulator and check how print and patch behave. The issue leaves the shell syntax for requesting None open, so agree on that with maintainers first. Done means the acceptance criteria hold, including the warning rules and the tests that use same-id items in the None, Null, and string partitions.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Summary

Cosmos DB supports items whose configured partition-key property is absent. The .NET SDK represents this value with PartitionKey.None, distinct from explicit JSON null, represented by PartitionKey.Null.

Cosmos DB Shell can create and enumerate missing-key items, but no command can explicitly address their logical partition. Consequently, such items cannot be point-read, patched, replaced, transactionally updated, or reliably deleted.

This gap also applies to missing components in hierarchical partition keys. The SDK exposes PartitionKeyBuilder.AddNoneType() for this case.

Current command behavior

Commands Current behavior
mkitem, create item Implicitly support create/upsert because the partition key is omitted from CreateItemAsync/UpsertItemAsync and extracted from the document.
import Implicitly supports insert/upsert for the same reason.
query Can discover missing-key items with NOT IS_DEFINED(c.<path>), but cannot use None as an explicit routing value.
ls, export Can enumerate missing-key items through scans/queries.
watch An unscoped feed can observe them; --partition-key cannot select None.
print Cannot point-read an item using PartitionKey.None. PR #248 adds typed scalar and hierarchical keys but no undefined-key representation.
patch Its shared typed parser has no syntax for PartitionKey.None.
batch Cannot open a transactional batch for the None logical partition.
sproc exec Cannot execute a stored procedure against the None logical partition.
rm --partition-key cannot express None; scan-based removal skips items when a configured key path is absent.
replace Rejects an item when any configured partition-key path is absent.

No shell command currently provides explicit PartitionKey.None support.

SDK and documentation evidence

The SDK documentation defines:

Microsoft's partitioning guidance recommends a stable, high-cardinality property with a value on every item. Supporting None is therefore primarily needed for legacy, transitional, and exceptional data, not as a recommended data model: partition-key guidance.

Proposed behavior

When a configured partition-key path is absent, treat it as the valid Cosmos DB value PartitionKey.None instead of rejecting or skipping the item.

Define an unambiguous shell representation for explicitly requesting None. It must remain distinct from:

  • explicit JSON null;
  • the strings "none" and "undefined";
  • an accidentally omitted required argument.
Warning behavior

Warning: Creating or modifying an item with an implicitly inferred PartitionKey.None must always produce a visible warning.

  • Reads using None are valid and must not warn.
  • Mutations using explicitly requested None must not warn.
  • Mutations using implicitly inferred None must always warn.
  • Bulk operations must emit one bounded summary warning with the affected item count.

Extend shared partition-key conversion to produce:

  • PartitionKey.None for a scalar undefined key;
  • PartitionKeyBuilder.AddNoneType() for undefined HPK components.

Commands that derive keys from item content, including mkitem, create item, import, replace, and scan-based rm, should infer None for absent paths. They must warn before or while performing mutations unless the caller explicitly acknowledged None.

Commands with explicit partition targeting, including print, patch, batch, sproc, rm, and partition-scoped watch, should accept the new explicit representation. Because these requests are intentional, they should not warn.

Acceptance criteria

  • Missing scalar and hierarchical key components are converted to the SDK's None representation instead of being rejected or skipped.
  • Reads using inferred or explicit None do not warn.
  • Every mutation using implicitly inferred None emits a warning.
  • Mutations using explicitly requested None do not warn.
  • Bulk mutations produce one bounded summary warning with an accurate item count.
  • Create fixtures with the same id in the None, Null, and string logical partitions and prove each command addresses only the intended item.
  • Cover scalar and hierarchical keys with one or more missing components.
  • Point-read, patch, replace, delete, batch, stored-procedure, and scoped-watch operations use the SDK's None representation.
  • Preserve literal strings resembling the chosen None sentinel.
  • Keep omitted required arguments distinct from an explicit None value.
  • Add shell parser, command, MCP schema/call, warning, and emulator integration coverage.
  • Document the syntax, warning behavior, distinction from null, and Microsoft's recommendation to use a present, stable, high-cardinality partition-key value.
  • Coordinate the print implementation with #248.
Lingua principale
C#
Stelle
4
Fork
7
Merge medio
2g 13m
PR unite (30g)
30

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Azure/CosmosDBShell

Tutte le issue di Azure/CosmosDBShell

Issue simili

Altre issue su C#

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.