Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

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

Ouverte
  • Quelque chose ne va pas ?
#251 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 2 jours

@mkrueger y travaille déjà.

Depuis le 14/10/2026.

  • #252 par @mkrueger — ouverte

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
15/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
Active
Stack technique
csharp
Domaine
cli, database

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.
Langage dominant
C#
Étoiles
4
Forks
7
Merge moyen
2 j 40 min
PR mergées (30 j)
30

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de Azure/CosmosDBShell

Toutes les issues de Azure/CosmosDBShell

Issues similaires

Plus d'issues C#

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.