Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#251 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 2 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
15/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
csharp
Área
cli, database

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
C#
Estrellas
4
Forks
7
Merge medio
2 d 13 min
PR fusionados (30 d)
30

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Azure/CosmosDBShell

Todos los issues de Azure/CosmosDBShell

Issues similares

Más issues de C#

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.