QueryResult
QueryResult
QueryResult holds the response of one query request. Use it to read the entries that matched, the number of entries, and the content type when the query asked for it.
You receive a QueryResult in the completion block of two Query methods:
- find: on a query from [contentType query], which sends the Get all entries request.
- findTaxonomy: on a query from [taxonomy query], which sends the Get all entries with defined taxonomies request.
The result argument is nil whenever the completion block receives an error, so check error first.
content_type
content_type returns the content_type dictionary that the response carries alongside the entries.
Returns: NSDictionary or nil. The content_type dictionary of the response, or nil.
Validation
- There is no client-side validation. content_type reads the stored response and makes no request.
- It returns nil when the response has no content_type key, or when the value is not a dictionary.
Behavior
- Client-side only. The Swift signature is content_type() -> [AnyHashable : Any]?.
- The response carries content_type when the query called includeContentType before find:. includeContentType sends the include_content_type and include_global_field_schema parameters.
- The dictionary holds the content type definition, with its field definitions under the schema key. Its values have mixed types, so read them as id in Objective-C and cast them in Swift.
Example
Read the content type with the entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] query];
[query includeContentType];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSDictionary *contentType = [result content_type];
NSArray *fields = contentType[@"schema"];
NSLog(@"%@ has %lu fields", contentType[@"title"], (unsigned long)fields.count);
}];Read the content type with the entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.contentType(withName: "CONTENT_TYPE_UID").query()
query.includeContentType()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
let contentType = result?.content_type() ?? [:]
let fields = contentType["schema"] as? [[String: Any]] ?? []
print("\(contentType["title"] ?? "") has \(fields.count) fields")
}getResult
getResult reads the entries array of the response and returns one Entry object for each item.
Returns: NSArray or nil. The entries of the response as Entry objects, or nil.
Validation
- There is no client-side validation. getResult reads the stored response and makes no request.
- It returns nil when the response has no entries key, or when entries is not an array.
- It returns an empty array when entries is an empty array.
Behavior
- Client-side only. The Objective-C type is NSArray<Entry *> *. The Swift signature is getResult() -> [Entry]?.
- Each call builds new Entry objects from the stored response, so changes to an entry from one call do not show in the next call.
- Each entry holds the fields of its item. Read them with the Entry properties, such as title and uid, or with objectForKey:.
- Entries from a find: result belong to the content type of the query. They carry its headers if you fetch them again.
- The API returns its own default number of entries per request. Use limitObjects: and skipObjects: on the query to read further pages, as the Pagination section of the API reference describes.
Example
Read the entries of a query (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] query];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSArray<Entry *> *entries = [result getResult];
for (Entry *entry in entries) {
NSLog(@"%@ %@", entry.uid, entry.title);
}
}];Read the entries of a query (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.contentType(withName: "CONTENT_TYPE_UID").query()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
let entries = result?.getResult() ?? []
for entry in entries {
print(entry.uid, entry.title)
}
}Fetch an entry from a taxonomy result again (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack taxonomy] query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@"TERM_UID"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
Entry *found = [[result getResult] firstObject];
if (found == nil) { return; }
// Build the entry from its content type, because the taxonomy entry has none.
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:found.uid];
[entry fetch:^(ResponseType type, NSError *error) {
if (error) { return; }
NSLog(@"%@", entry.title);
}];
}];Fetch an entry from a taxonomy result again (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.taxonomy().query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: "TERM_UID")
query.findTaxonomy { (type, result, error) in
guard error == nil, let found = result?.getResult()?.first else { return }
// Build the entry from its content type, because the taxonomy entry has none.
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: found.uid)
entry.fetch { (type, error) in
guard error == nil else { return }
print(entry.title)
}
}initWithTaxonomy:objectDictionary:
initWithTaxonomy:objectDictionary: builds a QueryResult from a response body that you already hold, such as a stored taxonomy response or a fixture in a unit test.
| Name | Type | Description |
|---|---|---|
| taxonomy (required) | Taxonomy * | Taxonomy the entries of the result belong to. |
| dictionary (required) | NSDictionary * | Response body to read, with keys such as entries. |
Returns: QueryResult. A new result object that holds the given response dictionary.
Validation
- There is no client-side validation. initWithTaxonomy:objectDictionary: copies the keys of dictionary and makes no request.
- A nil dictionary gives an empty result: getResult returns nil and totalCount returns 0.
- Pass a taxonomy from [stack taxonomy]. With a nil taxonomy, getResult raises NSInvalidArgumentException when entries holds at least one dictionary, because it has no object to build the entries from.
Behavior
- Client-side only. In Swift, the initializer is QueryResult(taxonomy:objectDictionary:).
- The result behaves like one from findTaxonomy:. getResult builds entries that belong to the taxonomy, so the Known issue on getResult applies to them.
- The result keeps a copy of the top-level keys. Changes to dictionary after the call do not reach it.
Example
Build a result from a stored response (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
NSDictionary *response = @{
@"entries": @[@{@"uid": @"ENTRY_UID", @"title": @"Red running shoes"}],
@"count": @1
};
QueryResult *result = [[QueryResult alloc] initWithTaxonomy:[stack taxonomy] objectDictionary:response];
for (Entry *entry in [result getResult]) {
NSLog(@"%@ %@", entry.uid, entry.title);
}
NSLog(@"%ld in total", (long)[result totalCount]);Build a result from a stored response (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let response: [AnyHashable: Any] = [
"entries": [["uid": "ENTRY_UID", "title": "Red running shoes"]],
"count": 1
]
let result = QueryResult(taxonomy: stack.taxonomy(), objectDictionary: response)
for entry in result.getResult() ?? [] {
print(entry.uid, entry.title)
}
print("\(result.totalCount()) in total")schema
schema returns the array stored under the top-level schema key of the response.
Returns: NSArray or nil. The top-level schema array of the response, or nil.
Validation
- There is no client-side validation. schema reads the stored response and makes no request.
- It returns nil when the response has no top-level schema key, or when the value is not an array.
Behavior
- Client-side only. The Swift signature is schema() -> [Any]?.
- No Query method asks the API for a top-level schema key. includeContentType removes any include_schema parameter from the query and requests the content type instead.
- To read the field definitions of the content type, call includeContentType before find: and read the schema key of content_type.
Example
Read the field definitions that came with the entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] query];
[query includeContentType];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
// A top-level schema key, when present, comes first.
NSArray *fields = [result schema] ?: [result content_type][@"schema"];
NSLog(@"%lu fields", (unsigned long)fields.count);
}];Read the field definitions that came with the entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.contentType(withName: "CONTENT_TYPE_UID").query()
query.includeContentType()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
// A top-level schema key, when present, comes first.
let fields = result?.schema() ?? (result?.content_type()?["schema"] as? [Any]) ?? []
print("\(fields.count) fields")
}totalCount
totalCount returns the count value of the response, or the number of entries in the response when it has no count.
Returns: NSInteger. The count value of the response, or else the number of entries it holds.
Validation
- There is no client-side validation. totalCount reads the stored response and makes no request.
- It returns 0 when the response has neither a numeric count nor an entries array.
Behavior
- Client-side only. The Swift signature is totalCount() -> Int.
- totalCount checks two keys, in the order below:
- When the response carries a numeric count, it returns that value. The response carries count when the query called includeCount, as the Count section of the API reference describes.
- Otherwise it returns the number of items in entries.
- Without includeCount, the value is the size of this page of entries, not the total. The API caps each page, so call includeCount when you need the total to plan pagination.
Example
Read the total number of matching entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] query];
[query includeCount];
[query limitObjects:@10];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSInteger total = [result totalCount];
NSUInteger onThisPage = [result getResult].count;
NSLog(@"%lu of %ld entries", (unsigned long)onThisPage, (long)total);
}];Read the total number of matching entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.contentType(withName: "CONTENT_TYPE_UID").query()
query.includeCount()
query.limitObjects(10)
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
guard let result = result else { return }
let total = result.totalCount()
let onThisPage = result.getResult()?.count ?? 0
print("\(onThisPage) of \(total) entries")
}