CloudKit Web Services Reference: Fetching Records Using a Query (records/query)

You can fetch records using a query.

Path

POST [path]/database/[version]/[container]/[environment]/[database]/records/query

Parameters

path

The URL to the CloudKit web service, which is https://api.apple-cloudkit.com.

version

The protocol version—currently, 1.

container

A unique identifier for the app’s container. The container ID should begin with iCloud..

environment

The version of the app’s container. Pass development to use the environment that is not accessible by apps available on the store. Pass production to use the environment that is accessible by development apps and apps available on the store.

database

The database to store the data within the container. The possible values are:

public: The database that is accessible to all users of the app.
private: The database that contains private data that is visible only to the current user.
shared: The database that contains records shared with the current user.

Request

The POST request is a JSON dictionary containing the following keys:


Key	Description
`zoneID`	A dictionary that identifies a record zone in the database, described in Zone ID Dictionary.
`resultsLimit`	The maximum number of records to fetch. The default is the maximum number of records in a response that is allowed, described in Data Size Limits.
`query`	The query to apply, described in Query Dictionary. This key is required.
`continuationMarker`	The location of the last batch of results. Use this key when the results of a previous fetch exceeds the maximum. See Response. The default value is `null`.
`desiredKeys`	An array of strings containing record field names that limits the amount of data returned in this operation. Only the fields specified in the array are returned. The default is `null`, which fetches all record fields.
`zoneWide`	A Boolean value determining whether all zones should be searched. This key is ignored if `zoneID` is non-`null`. To search all zones, set to `true`. To search the default zone only, set to `false`.
`numbersAsStrings`	A Boolean value indicating whether number fields should be represented by strings. The default value is `false`.

Response

An array of dictionaries describing the results of the operation. The dictionary contains the following keys:


Key	Description
`records`	An array containing a result dictionary for each record requested. If successful, the result dictionary contains the keys described in Record Dictionary. If unsuccessful, the result dictionary contains the keys described in Record Fetch Error Dictionary.
`continuationMarker`	If included, indicates that there are more results matching this query. To fetch the other results, pass the value of the `continuationMarker` key as the value of the `continuationMarker` key in another query.

Discussion

A request to fetch records performs a query on indexed fields for a particular record type. At least one field in the record needs to be indexed to perform an empty query that fetches all records. Because indexes are updated asynchronously, they are not guaranteed to be current. If more than the maximum results are found, use continuationMarker in the response to fetch more records in batches.

Queries can be configured against system fields as well as developer-defined fields. The system fields are special fields on which an index can be defined. These fields have a special mapping such that the `___` prefix does not need to be used.


fieldName	systemFieldName
___recordId	recordName
___share	share
___parent	parent
___createdBy	createdUserRecordName
___createTime	createdTimestamp
___modTime	modifiedTimestamp
___modifiedBy	modifiedUserRecordName

The filter dictionary can take a key systemFieldName instead of fieldName. This can take one of the mapped values to query for these system field names.

The sort descriptor dictionary can take a key systemFieldName instead of fieldName where the mapped values can be used.

A sample query request:

        "{
  "zoneID": {
    "zoneName": "myCustomZone",
  },
  "query": {
    "recordType": "myRecordType",
    "filterBy": [
      {
        "systemFieldName": "createdUserRecordName",
        "comparator": "EQUALS",
        "fieldValue": {
          "value": {
            "recordName": "recordA",
          },
          "type": "REFERENCE"
        }
      }
    ],
    "sortBy": [
      {
        "systemFieldName": "createdTimestamp",
        "ascending": false
      }
    ]
  }
}"

      

Related Framework API

This request is similar to using the CKQueryOperation class in the CloudKit framework.