Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#251 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 2 ngày

@mkrueger đang làm issue này rồi.

Từ ngày 14/10/2026.

  • #252 của @mkrueger — đang mở

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
15/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
csharp
Lĩnh vực
cli, database

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
C#
Star
4
Fork
7
Merge trung bình
2 ngày 40 phút
Pull request đã merge (30 ngày)
30

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của Azure/CosmosDBShell

Tất cả issue của Azure/CosmosDBShell

Issue tương tự

Thêm issue về C#

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.