Skip to content

Feature: Add custom CloudKit zone support for queries #146

Closed

Description

@leogdion

Description

The queryRecords() method currently hard-codes the zone name to _defaultZone, which prevents querying custom CloudKit zones.

Current Behavior

// Sources/MistKit/Service/CloudKitService+Operations.swift:105
zoneID: .init(zoneName: "_defaultZone"),

Proposed Solution

Add optional zoneName parameter with default value:

public func queryRecords(
  recordType: String,
  filters: [QueryFilter]? = nil,
  sortBy: [QuerySort]? = nil,
  limit: Int = 100,
  zoneName: String = "_defaultZone"
) async throws(CloudKitError) -> [RecordInfo] {
  // Use provided zoneName instead of hard-coded value
}

Use Cases

  • Querying custom zones for advanced CloudKit usage
  • Working with shared zones
  • Multi-zone applications

References

  • Identified in PR Adding Celestra to Demos #134 review by Claude Code (CloudKitService+Operations.swift:105)
  • CloudKit Web Services supports custom zones

Priority

Medium - Required for advanced CloudKit features

Activity

  1. added a commit that references this issue on Nov 13, 2025
    b88acd3
  2. leogdion commented on Feb 5, 2026

    @leogdion
    MemberAuthor

    This has been implemented. Custom CloudKit zone support is available:

    • Sources/MistKit/Service/ZoneID.swift - Zone identifier type
    • Zone support integrated throughout the service layer
    • CloudKitService.listZones() - List available zones
    • Query and modify operations support zone specification

    Custom zones can be used for organizing records and enabling features like atomic commits and change tracking.

    Closing as completed.

  3. leogdion commented on May 27, 2026

    @leogdion
    MemberAuthor

    Reopening — the "completed" close doesn't match the shipped code as of v1.0.0-beta.2.

    The closing comment claimed "Query and modify operations support zone specification" and cited Sources/MistKit/Service/ZoneID.swift, but:

    • That path doesn't exist; the type lives at Sources/MistKit/Models/Zones/ZoneID.swift.
    • queryRecords still hardcodes the zone — CloudKitService+Operations.swift builds the request body with zoneID: .init(zoneName: "_defaultZone") and exposes no zoneName/zoneID parameter on any overload.
    • The Query domain type (Sources/MistKit/Models/Queries/Query.swift) carries no zone field.
    • modifyRecords (CloudKitService+WriteOperations.swift) likewise takes no zone argument.

    ZoneID is only consumed by the zones/* operations (listZones, lookupZones, fetchZoneChanges) — record query/modify are still locked to _defaultZone. The original ask (an optional zoneName/zone parameter on queryRecords, defaulting to _defaultZone) is still outstanding.


    Generated by Claude Code

  4. leogdion commented on Aug 20, 2026

    @leogdion
    MemberAuthor

    Two review points for #426

    1. Wire-level behavior change (not just source-level). Requests previously always sent "zoneID": {"zoneName": "_defaultZone"}. With the new zoneID: ZoneID? = nil parameter, passing nothing now omits the zoneID key entirely and lets CloudKit resolve the default zone server-side.

    CloudKit should resolve to the same zone either way, and there's a test pinning the omission — but this is a real change to what goes over the wire, not a pure refactor. If any deployment depends on that key being present, it changes. Worth a conscious sign-off rather than being buried under "source-compatible".

    2. RecordManaging was left zone-unaware. The reasoning: it's a deprecated, database-agnostic abstraction that already hard-codes its auth preference, so threading a zone through it seemed like extending something on its way out. If you'd rather it gained zone support too, say so — it's a small follow-up, but doing it after release would be another source-breaking change to a protocol.

    Design note

    The issue proposed zoneName: String = "_defaultZone"; #426 threads a ZoneID instead. That sketch predates the ZoneID type, and ownerName is what makes shared zones addressable — one of this issue's own stated use cases, since a shared zone lives in the owner's database and a bare zone name cannot express that. It also matches existing precedent in modifyRecords(_:atomic:zoneID:…).

    The = nil default was a deliberate call against the no-silent-policy-defaults rule: that rule targets credential/attribution policy, where a silent default mis-attributes data. Zone selection carries no such semantics, and nil doesn't substitute a client-side default — it omits the key. database: remains non-defaulted.

    Note

    Possibly relevant to this issue's shared-zone support: ZoneID's owner key is ownerRecordName in Apple's archived reference but ownerName in both MistKit's domain type and its wire schema (surfaced in #386). If the wire name is wrong, owner-qualified addressing — the shared-zone path this issue asks for — would not actually work. I have not verified which is correct, so the shared-zone case here is untested against a live service.

    🤖 Generated with Claude Code

  5. leogdion commented on Aug 28, 2026

    @leogdion
    MemberAuthor

    Resolved on v1.0.0-beta.4 via #426 (commit d70e6ef). queryRecords now takes an optional ZoneID (rather than a bare zoneName) so shared zones — which need ownerName — are addressable too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions