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. Passproduction
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 |
---|---|
|
A dictionary that identifies a record zone in the database, described in Zone ID Dictionary. |
|
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. |
|
The query to apply, described in Query Dictionary. This key is required. |
|
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 |
|
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 |
|
A Boolean value determining whether all zones should be searched. This key is ignored if |
|
A Boolean value indicating whether number fields should be represented by strings. The default value is |
Response
An array of dictionaries describing the results of the operation. The dictionary contains the following keys:
Key |
Description |
---|---|
|
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. |
|
If included, indicates that there are more results matching this query. To fetch the other results, pass the value of the |
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.
Modifying Records (records/modify)
Copyright © 2018 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2016-06-13