Query
Query
Query builds a request for published entries and sends it. Use this class to
- match entries by field value, reference, tag or taxonomy term
- choose the locale, fields and references that the response carries
- sort the entries and read them one page at a time
- send the request with find:, findOne: or findTaxonomy:
Every other method stores a setting on the query and returns void. Call the setters one after another on the same object, then call a send method.
| Name | Type | Description |
|---|---|---|
| cachePolicy | [CachePolicy](../CachePolicy/class_reference.md) | Read and write. Whether the send methods read the network or the cache. Known issue: CACHE_ONLY, CACHE_ELSE_NETWORK and CACHE_THEN_NETWORK never read the cache. They request the network and store the response. Use NETWORK_ELSE_CACHE for an offline fallback. |
addHeadersWithDictionary:
addHeadersWithDictionary: adds several HTTP headers to every request this query sends.
| Name | Type | Description |
|---|---|---|
| headers (required) | NSDictionary<NSString *, NSString *> * | Header names mapped to their values. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation. Passing nil from Objective-C adds nothing and raises nothing.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Behavior
- Client-side only. addHeadersWithDictionary: stores each pair on the query and makes no request.
- A name the query already holds takes the new value. Names not in the dictionary keep their value.
- A query header replaces a header with the same name on the stack, content type or taxonomy.
- The SDK writes X-User-Agent, User-Agent and a Config branch after the query headers, as the setHeader:forKey: method describes.
- In Swift, the method is addHeaders(with:).
Example
Add a variant header and a branch header (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query addHeadersWithDictionary:@{@"x-cs-variant-uid": @"VARIANT_UID", @"branch": @"BRANCH_UID"}];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Add a variant header and a branch header (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.addHeaders(with: ["x-cs-variant-uid": "VARIANT_UID", "branch": "BRANCH_UID"])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}addParamKey:andValue:
addParamKey:andValue: adds one request parameter with a string value.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | Name of the parameter. |
| value (required) | NSString * | Value of the parameter. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation. A nil key from Objective-C adds nothing and raises nothing.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. addParamKey:andValue: writes the pair and makes no request.
- It replaces a value that another method wrote under the same name.
- It takes a string only. For a number, array or dictionary, use the addQueryWithKey:andValue: method.
Example
Resolve taxonomy terms in the response (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query addParamKey:@"include_taxonomy_terms" andValue:@"true"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Resolve taxonomy terms in the response (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.addParamKey("include_taxonomy_terms", andValue: "true")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Resolve taxonomy terms on a taxonomy query (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.color" equalTo:@"red"];
[query addParamKey:@"include_taxonomy_terms" andValue:@"true"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Resolve taxonomy terms on a taxonomy query (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
query.whereKey("taxonomies.color", equalTo: "red")
query.addParamKey("include_taxonomy_terms", andValue: "true")
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}addQueryParams:
addQueryParams: replaces every parameter of the query with the pairs of a dictionary.
| Name | Type | Description |
|---|---|---|
| queryDict (required) | NSDictionary<NSString *, id> * | Parameter names mapped to their values. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. addQueryParams: makes no request.
- It discards every setting made before it, including conditions, limit and locale, and keeps only the pairs in the dictionary. Call it first, then chain other methods.
- The SDK sends a string or number as text, an array as one <key>[] pair per item, and a dictionary as <key>[<subkey>] pairs. Under the query key, pass a dictionary, which the SDK sends as JSON.
- In Swift, the method is addParams(_:).
Known issue The SDK copies only the top level of the dictionary, so a dictionary you pass under query stays immutable. A later whereKey: method, orWithSubqueries: or andWithSubqueries: on this query, or passing this query as a subquery to one of those two methods, raises NSInvalidArgumentException and crashes the app. Put every condition in the one dictionary. In Objective-C, passing an NSMutableDictionary also avoids the crash.
Example
Set several parameters, then add a limit (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query addQueryParams:@{@"locale": @"fr-fr", @"include_fallback": @"true"}];
[query limitObjects:@(10)];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Set several parameters, then add a limit (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.addParams(["locale": "fr-fr", "include_fallback": "true"])
query.limitObjects(10)
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}addQueryWithKey:andValue:
addQueryWithKey:andValue: adds one request parameter that the SDK has no method for.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | Name of the parameter. |
| value (required) | id | Value of the parameter. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- A string under the query key raises NSInvalidArgumentException from the send call, because the SDK converts that value to JSON as a dictionary.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. addQueryWithKey:andValue: writes the pair and makes no request.
- The SDK sends a string or number as text, an array as one <key>[] pair per item, and a dictionary as <key>[<subkey>] pairs. Under the query key, pass a dictionary, which the SDK sends as JSON.
- It replaces a value that another method wrote under the same name, for example limit from limitObjects:.
- Remove the parameter with the removeQueryWithKey: method.
- In Swift, the method is add(withKey:andValue:).
Known issue Under the query key, the SDK stores the dictionary you pass without copying it into a mutable one. A later whereKey: method, orWithSubqueries: or andWithSubqueries: on this query, or passing this query as a subquery to one of those two methods, raises NSInvalidArgumentException and crashes the app. Put every condition in the one dictionary. In Objective-C, passing an NSMutableDictionary also avoids the crash.
Example
Resolve taxonomy terms in the response (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query addQueryWithKey:@"include_taxonomy_terms" andValue:@"true"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Resolve taxonomy terms in the response (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.add(withKey: "include_taxonomy_terms", andValue: "true")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Return nested embedded items (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query addQueryWithKey:@"include_embedded_items" andValue:@[@"RECURSIVE"]];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Return nested embedded items (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.add(withKey: "include_embedded_items", andValue: ["RECURSIVE"])
query.find { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}andWithSubqueries:
andWithSubqueries: matches entries that satisfy every one of several subqueries.
| Name | Type | Description |
|---|---|---|
| queries (required) | NSArray<Query *> * | Subqueries whose conditions to join with $and. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
- A subquery whose conditions came from the query: method raises NSInvalidArgumentException. See the Known issue on that page.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. andWithSubqueries: writes the conditions of each subquery as an array under $and in this query's query object and makes no request. See AND Operator.
- Use it to apply two conditions to one field, such as a price range. A second whereKey: call on the same field replaces the first condition, so a range needs one subquery per bound.
- Conditions already on this query stay beside the joined array in the same query object. A second call replaces the array from the first.
- Build each subquery with at least one condition method. A subquery with no condition adds all of its parameters, such as its limit, to the array as one object.
- The SDK reads only the conditions of each subquery. Settings such as limit or locale on a subquery that has a condition have no effect, so set them on this query.
- On a taxonomy query, build the subqueries from the same taxonomy and send with the findTaxonomy: method. See AND Operator (Taxonomy).
- In Swift, the method is and(withSubqueries:).
Example
Match entries in a price range (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
Query *minPrice = [contentType query];
[minPrice whereKey:@"price_in_usd" greaterThanOrEqualTo:@(100)];
Query *maxPrice = [contentType query];
[maxPrice whereKey:@"price_in_usd" lessThanOrEqualTo:@(600)];
[query andWithSubqueries:@[minPrice, maxPrice]];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries in a price range (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
let minPrice = contentType.query()
minPrice.whereKey("price_in_usd", greaterThanOrEqualTo: 100)
let maxPrice = contentType.query()
maxPrice.whereKey("price_in_usd", lessThanOrEqualTo: 600)
query.and(withSubqueries: [minPrice, maxPrice])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Match taxonomy entries that carry both terms (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
Query *colorQuery = [taxonomy query];
[colorQuery whereKey:@"taxonomies.color" equalTo:@"red"];
Query *sizeQuery = [taxonomy query];
[sizeQuery whereKey:@"taxonomies.size" equalTo:@"small"];
[query andWithSubqueries:@[colorQuery, sizeQuery]];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match taxonomy entries that carry both terms (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
let colorQuery = taxonomy.query()
colorQuery.whereKey("taxonomies.color", equalTo: "red")
let sizeQuery = taxonomy.query()
sizeQuery.whereKey("taxonomies.size", equalTo: "small")
query.and(withSubqueries: [colorQuery, sizeQuery])
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}cancelRequests
cancelRequests cancels the requests that this query started and that have not finished.
Returns: void. Nothing.
Validation
- There is no client-side validation. On a query that sent nothing, or whose requests have finished, cancelRequests does nothing.
Behavior
- cancelRequests cancels every request that find:, findOne: and findTaxonomy: started on this query. It does not affect other queries.
- The completion block of a cancelled request still runs, with an NSError in the NSURLErrorDomain domain and the code NSURLErrorCancelled.
- With the NETWORK_ELSE_CACHE cache policy, the SDK answers a cancelled request from the cache instead, as it does for any network failure. See CachePolicy.
Example
Cancel a request in progress (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if ([error.domain isEqualToString:NSURLErrorDomain] && error.code == NSURLErrorCancelled) {
NSLog(@"Request cancelled");
return;
}
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%lu entries", (unsigned long)[result getResult].count);
}];
[query cancelRequests];Cancel a request in progress (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.find { (type, result, error) in
if let error = error as NSError?, error.domain == NSURLErrorDomain, error.code == NSURLErrorCancelled {
print("Request cancelled")
return
}
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("\(result?.getResult()?.count ?? 0) entries")
}
query.cancelRequests()exceptFields:
exceptFields: leaves the fields you list out of each entry in the response.
| Name | Type | Description |
|---|---|---|
| fieldUIDs (required) | NSArray<NSString *> * | UIDs of the fields to leave out. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. exceptFields: writes the list to except[BASE][] and makes no request. See Exclude Operator.
- A second call replaces the first list. Field lists for reference fields from the includeReferenceFieldWithKey:excludingFields: method stay.
- To name a field inside a group or modular block, pass its path, for example group_UID.field_UID.
Example
Leave the description out of each entry (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query exceptFields:@[@"description"]];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Leave the description out of each entry (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.exceptFields(["description"])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}find:
find: sends the query and passes one page of matching entries to the completion block.
| Name | Type | Description |
|---|---|---|
| completionBlock (required) | void (^)(ResponseType, QueryResult *, NSError *) | Receives the response type, result and error. |
Returns: void. Nothing. The completion block receives the result.
Validation
- There is no client-side validation.
- When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.
- find: raises NSInvalidArgumentException and crashes the app when the query came from Taxonomy query, because it reads the environment from an object that query does not hold. Use the findTaxonomy: method for that query.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Each call sends one GET /content_types/{content_type_uid}/entries request with every setting on the query and the environment of the stack. See Get all entries.
- On success, result is a QueryResult and error is nil. getResult returns the entries as Entry objects. On failure, result is nil.
- find: returns one page. Without the limitObjects: method, the API returns the first 100 entries. Use skipObjects: and includeCount to read later pages. See Pagination.
- The query keeps its settings, so a second find: on the same query sends the same request again.
- The cachePolicy property of the query decides whether the result comes from the network or the cache, and type reports which. See CachePolicy.
- To stop a request in progress, call the cancelRequests method.
- In Swift, try await query.find() returns the response type and result, and throws the error.
Example
List the entries of a content type (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];List the entries of a content type (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Filter, sort and limit the entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"price_in_usd" lessThan:@(600)];
[query orderByAscending:@"price_in_usd"];
[query limitObjects:@(10)];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Filter, sort and limit the entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("price_in_usd", lessThan: 600)
query.order(byAscending: "price_in_usd")
query.limitObjects(10)
query.find { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}findOne:
findOne: sends the query and passes the first matching entry to the completion block.
| Name | Type | Description |
|---|---|---|
| completionBlock (required) | void (^)(ResponseType, Entry *, NSError *) | Receives the response type, entry and error. |
Returns: void. Nothing. The completion block receives the result.
Validation
- There is no client-side validation.
- When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.
- When no entry matches, the completion block receives nil for both entry and error. Check entry before you use it.
- findOne: raises NSInvalidArgumentException and crashes the app when the query came from Taxonomy query, because it reads the environment from an object that query does not hold. Use the findTaxonomy: method for that query.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Each call sends the same GET /content_types/{content_type_uid}/entries request as the find: method, with a limit of 1. See Get all entries.
- On success, entry is the first Entry in the response.
- After it builds the request, findOne: removes the limit setting from the query, including a value from limitObjects:. A later find: on the same query returns the API default page size unless you set the limit again.
- Chain orderByAscending: or orderByDescending: to choose which entry comes first.
- The cachePolicy property of the query decides whether the result comes from the network or the cache, and type reports which. See CachePolicy.
- To stop a request in progress, call the cancelRequests method.
- In Swift, try await query.findOne() returns the response type and entry, and throws the error.
Example
Read the newest entry (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query orderByDescending:@"created_at"];
[query findOne:^(ResponseType type, Entry *entry, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
if (entry == nil) {
NSLog(@"No entry matches");
return;
}
NSLog(@"%@", entry.title);
}];Read the newest entry (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.order(byDescending: "created_at")
query.findOne { (type, entry, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
guard let entry = entry else {
print("No entry matches")
return
}
print(entry.title)
}findTaxonomy:
findTaxonomy: sends a taxonomy query and passes the matching entries, from any content type, to the completion block.
| Name | Type | Description |
|---|---|---|
| completionBlock (required) | void (^)(ResponseType, QueryResult *, NSError *) | Receives the response type, result and error. |
Returns: void. Nothing. The completion block receives the result.
Validation
- There is no client-side validation.
- When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.
- findTaxonomy: raises NSInvalidArgumentException and crashes the app when the query came from ContentType query, because it reads the environment from an object that query does not hold. Use the find: method for that query.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Each call sends one GET /taxonomies/entries request with the conditions of the query, its other settings, and the environment of the stack. See Get all entries with defined taxonomies.
- Create the query with query on the Taxonomy class: [[stack taxonomy] query].
- On success, result is a QueryResult and error is nil. getResult returns the entries as Entry objects. On failure, result is nil.
- Build the conditions with taxonomies.<taxonomy_uid> as the key. The table below maps each taxonomy operator to the method that writes it:
| Operator | Method | API reference |
|---|---|---|
| Equals a term | whereKey:equalTo: | Get all entries with defined taxonomies |
| $in | whereKey:containedIn: | IN Operator |
| $or | orWithSubqueries: | OR Operator (Taxonomy) |
| $and | andWithSubqueries: | AND Operator (Taxonomy) |
| $exists | whereKeyExists: | Exists Operator |
| $eq_below, $below, $eq_above, $above | whereKey:equalTo: with a dictionary value | Equal and Below Operator |
- The request also takes locale, include_fallback and include_taxonomy_terms. Set them with the locale:, includeFallback and addParamKey:andValue: methods.
- The query keeps its settings, so a second findTaxonomy: on the same query sends the same request again.
- The cachePolicy property of the query decides whether the result comes from the network or the cache, and type reports which. See CachePolicy.
- To stop a request in progress, call the cancelRequests method.
- In Swift, try await query.findTaxonomy() returns the response type and result, and throws the error.
Example
List the entries tagged with a term (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.color" equalTo:@"red"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];List the entries tagged with a term (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
query.whereKey("taxonomies.color", equalTo: "red")
query.findTaxonomy { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}List entries for a term and the terms below it (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.color" equalTo:@{@"$eq_below": @"blue", @"levels": @(2)}];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];List entries for a term and the terms below it (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
query.whereKey("taxonomies.color", equalTo: ["$eq_below": "blue", "levels": 2])
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}includeBranch
includeBranch asks the API to state the branch that the content comes from.
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeBranch writes include_branch=true and makes no request.
- The API adds the _branch top-level key, which holds the UID of the branch. See Get all entries.
- To read from a branch other than the default, set the branch property of Config.
Example
Request the branch with the entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query includeBranch];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Request the branch with the entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.includeBranch()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}includeContentType
includeContentType asks the API to return the content type of the entries along with them.
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeContentType writes include_content_type=true and include_global_field_schema=true and makes no request.
- It also removes an include_schema parameter that the query holds.
- Read the content type from content_type on the QueryResult that the send call returns.
- The Get all entries request does not list include_content_type. The content type requests document include_global_field_schema, which adds the schema of each Global field.
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"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType 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 *contentTypeInfo = [result content_type];
NSLog(@"%@", contentTypeInfo[@"title"]);
}];Read the content type with the entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.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 contentTypeInfo = result?.content_type()
print(contentTypeInfo?["title"] ?? "")
}includeCount
includeCount adds the total number of matching entries to the response.
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeCount writes include_count=true and makes no request. See Count.
- Read the total with totalCount on the QueryResult that the send call returns. The total counts every matching entry, not only the page.
- Compare the total with the page size to decide whether to request the next page with the skipObjects: method.
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"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query includeCount];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"Total: %ld, in this page: %lu", (long)[result totalCount], (unsigned long)[result getResult].count);
}];Read the total number of matching entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.includeCount()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("Total: \(result?.totalCount() ?? 0), in this page: \(result?.getResult()?.count ?? 0)")
}includeEmbeddedItems
includeEmbeddedItems asks the API to return the entries and assets embedded in rich text fields.
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeEmbeddedItems writes include_embedded_items[]=BASE and makes no request.
- The API returns the embedded items under the _embedded_items key. See Get information on embedded RTE objects.
- BASE returns the first level of embedded items. includeEmbeddedItems has no option for RECURSIVE. Use the addQueryWithKey:andValue: method with include_embedded_items and @[@"RECURSIVE"] for nested items.
Example
Request the embedded items with the entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query includeEmbeddedItems];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Request the embedded items with the entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.includeEmbeddedItems()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}includeFallback
includeFallback asks the API for content from the fallback locale when the requested locale has no published version of an entry.
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeFallback writes include_fallback=true and makes no request.
- Chain it with the locale: method. When an entry has no published content in that locale, the API returns the content published in the fallback locale. See Get all entries.
- On a taxonomy query, the API also resolves taxonomy terms through the fallback locales. See Get all entries with defined taxonomies.
Example
Read French entries with fallback content (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query locale:@"fr-fr"];
[query includeFallback];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Read French entries with fallback content (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.locale("fr-fr")
query.includeFallback()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}includeMetadata
includeMetadata asks the API to return the metadata of each entry.
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeMetadata writes include_metadata=true and makes no request.
- The API returns the metadata under the _metadata key, with one key per extension UID. See Get all entries.
- Read it with objectForKey: on each Entry.
Example
Read the metadata of each entry (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query includeMetadata];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@: %@", entry.title, [entry objectForKey:@"_metadata"]);
}
}];Read the metadata of each entry (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.includeMetadata()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title, entry.object(forKey: "_metadata") ?? "")
}
}includeOwner
includeOwner asks the API to return the owner details of each entry.
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeOwner writes include_owner=true and makes no request.
- The Get all entries request does not list include_owner among its parameters.
Example
Request the owner of each entry (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query includeOwner];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Request the owner of each entry (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.includeOwner()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}includeReferenceContentTypeUid
includeReferenceContentTypeUid asks the API to return the content type UID of each referenced entry.
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeReferenceContentTypeUid writes include_reference_content_type_uid=true and makes no request.
- Chain it with an includeReferenceFieldWithKey: method so the response carries the referenced entries.
- The Get all entries request does not list include_reference_content_type_uid among its parameters.
Example
Request the content type UID of referenced entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query includeReferenceFieldWithKey:@[@"brand"]];
[query includeReferenceContentTypeUid];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Request the content type UID of referenced entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.includeReferenceField(withKey: ["brand"])
query.includeReferenceContentTypeUid()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}includeReferenceFieldWithKey:
includeReferenceFieldWithKey: returns the content of referenced entries instead of their UIDs.
| Name | Type | Description |
|---|---|---|
| key (required) | NSArray<NSString *> * | UIDs of the reference fields to resolve. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeReferenceFieldWithKey: adds each UID to the include[] parameter and makes no request. See Include Reference.
- Each call adds to the list. The SDK does not remove duplicates.
- To resolve a reference field inside a group or modular block, pass its path, for example group_UID.reference_field_UID.
- In Swift, the method is includeReferenceField(withKey:).
Example
Return the brand and category entries in full (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query includeReferenceFieldWithKey:@[@"brand", @"categories"]];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Return the brand and category entries in full (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.includeReferenceField(withKey: ["brand", "categories"])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}includeReferenceFieldWithKey:excludingFields:
includeReferenceFieldWithKey:excludingFields: returns the referenced entries of one field without the fields you list.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the reference field to resolve. |
| fieldUIDs (required) | NSArray<NSString *> * | Fields to leave out of each referenced entry. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. The method adds key to include[], writes the list to except[<key>][], and makes no request. See Exclude Operator.
- A second call for the same reference field replaces its field list and adds the field to include[] again.
- The list for the entry itself comes from the exceptFields: method and stays separate.
- In Swift, the method is includeReferenceField(withKey:excludingFields:).
Example
Leave the description out of each brand (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query includeReferenceFieldWithKey:@"brand" excludingFields:@[@"description"]];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Leave the description out of each brand (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.includeReferenceField(withKey: "brand", excludingFields: ["description"])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}includeReferenceFieldWithKey:onlyFields:
includeReferenceFieldWithKey:onlyFields: returns the referenced entries of one field with only the fields you list.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the reference field to resolve. |
| fieldUIDs (required) | NSArray<NSString *> * | Fields to return for each referenced entry. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. The method adds key to include[], writes the list to only[<key>][], and makes no request. See Only Operator.
- A second call for the same reference field replaces its field list and adds the field to include[] again.
- The list for the entry itself comes from the onlyFields: method and stays separate.
- In Swift, the method is includeReferenceField(withKey:onlyFields:).
Example
Return only the title of each brand (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query includeReferenceFieldWithKey:@"brand" onlyFields:@[@"title"]];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Return only the title of each brand (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.includeReferenceField(withKey: "brand", onlyFields: ["title"])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}language:
language: sets the locale of the entries to read, from a Language enum value.
| Name | Type | Description |
|---|---|---|
| language (required) | Language | Enum value that names the locale to read. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- In Objective-C, an integer outside the Language range raises NSRangeException, because language: reads the locale code from a fixed list by position.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. language: writes the locale parameter and makes no request.
- The SDK converts the enum value to its locale code. For example, ENGLISH_UNITED_STATES sends en-us.
- language: and the locale: method write the same parameter, so the later call wins.
Example
Read entries in English (United States) (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query language:ENGLISH_UNITED_STATES];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Read entries in English (United States) (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.language(.ENGLISH_UNITED_STATES)
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}limitObjects:
limitObjects: sets the maximum number of entries the response returns.
| Name | Type | Description |
|---|---|---|
| number (required) | NSNumber * | Maximum number of entries to return. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation. The SDK sends the number as given.
- The API accepts positive integers only. For 0 or a non-numeric value, it returns the default number of entries rather than every entry. See Limit.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. limitObjects: writes the limit parameter and makes no request.
- Without limitObjects:, the API returns the first 100 entries. See Pagination.
- A second call replaces the first value.
- The findOne: method sends a limit of 1 and then removes the limit setting from the query, including a value from limitObjects:. Set it again before a later find: call.
Example
Read at most five entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query limitObjects:@(5)];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Read at most five entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.limitObjects(5)
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}locale:
locale: sets the locale of the entries to read.
| Name | Type | Description |
|---|---|---|
| locale (required) | NSString * | Locale code, for example en-us. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. locale: writes the locale parameter and makes no request.
- The API returns only the entries published in that locale. Chain the includeFallback method to read fallback locale content for entries that have no published version in it. See Get all entries.
- locale: works on a taxonomy query too. The Get all entries with defined taxonomies request takes locale.
- locale: and the deprecated language: method write the same parameter, so the later call wins.
Example
Read entries in French (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query locale:@"fr-fr"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Read entries in French (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.locale("fr-fr")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Read taxonomy entries in French (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.color" equalTo:@"red"];
[query locale:@"fr-fr"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Read taxonomy entries in French (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
query.whereKey("taxonomies.color", equalTo: "red")
query.locale("fr-fr")
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}objectsCount
objectsCount asks the API for the number of matching entries instead of the entries.
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. objectsCount writes count=true and makes no request.
- With count=true, the API returns only the count of matching entries, with no entry data. See Count.
- To read the entries and their total together, use the includeCount method and read totalCount on the QueryResult.
Example
Request only the number of matching entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"price_in_usd" lessThan:@(600)];
[query objectsCount];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
// The response holds the count of matching entries, not the entries.
NSLog(@"Count request succeeded");
}];Request only the number of matching entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("price_in_usd", lessThan: 600)
query.objectsCount()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
// The response holds the count of matching entries, not the entries.
print("Count request succeeded")
}onlyFields:
onlyFields: limits each entry in the response to the fields you list.
| Name | Type | Description |
|---|---|---|
| fieldUIDs (required) | NSArray<NSString *> * | UIDs of the fields to return. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. onlyFields: writes the list to only[BASE][] and makes no request. See Only Operator.
- A second call replaces the first list. Field lists for reference fields from the includeReferenceFieldWithKey:onlyFields: method stay.
- To name a field inside a group or modular block, pass its path, for example group_UID.field_UID.
Example
Return only the title and price (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query onlyFields:@[@"title", @"price_in_usd"]];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Return only the title and price (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.onlyFields(["title", "price_in_usd"])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}orWithSubqueries:
orWithSubqueries: matches entries that satisfy at least one of several subqueries.
| Name | Type | Description |
|---|---|---|
| queries (required) | NSArray<Query *> * | Subqueries whose conditions to join with $or. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
- A subquery whose conditions came from the query: method raises NSInvalidArgumentException. See the Known issue on that page.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. orWithSubqueries: writes the conditions of each subquery as an array under $or in this query's query object and makes no request. See OR Operator.
- Conditions already on this query stay beside the joined array in the same query object. A second call replaces the array from the first.
- Build each subquery with at least one condition method. A subquery with no condition adds all of its parameters, such as its limit, to the array as one object.
- The SDK reads only the conditions of each subquery. Settings such as limit or locale on a subquery that has a condition have no effect, so set them on this query.
- On a taxonomy query, build the subqueries from the same taxonomy and send with the findTaxonomy: method. See OR Operator (Taxonomy).
- In Swift, the method is or(withSubqueries:).
Example
Match entries by title or by price (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
Query *titleQuery = [contentType query];
[titleQuery whereKey:@"title" equalTo:@"Welcome"];
Query *priceQuery = [contentType query];
[priceQuery whereKey:@"price_in_usd" lessThan:@(100)];
[query orWithSubqueries:@[titleQuery, priceQuery]];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries by title or by price (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
let titleQuery = contentType.query()
titleQuery.whereKey("title", equalTo: "Welcome")
let priceQuery = contentType.query()
priceQuery.whereKey("price_in_usd", lessThan: 100)
query.or(withSubqueries: [titleQuery, priceQuery])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Match taxonomy entries by either of two terms (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
Query *colorQuery = [taxonomy query];
[colorQuery whereKey:@"taxonomies.color" equalTo:@"black"];
Query *sizeQuery = [taxonomy query];
[sizeQuery whereKey:@"taxonomies.size" equalTo:@"small"];
[query orWithSubqueries:@[colorQuery, sizeQuery]];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match taxonomy entries by either of two terms (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
let colorQuery = taxonomy.query()
colorQuery.whereKey("taxonomies.color", equalTo: "black")
let sizeQuery = taxonomy.query()
sizeQuery.whereKey("taxonomies.size", equalTo: "small")
query.or(withSubqueries: [colorQuery, sizeQuery])
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}orderByAscending:
orderByAscending: sorts the entries by the value of one field in ascending order.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to sort by. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. orderByAscending: writes the asc parameter and makes no request. See Order by asc.
- A second call replaces the field from the first.
- The orderByDescending: method writes a different parameter, so calling both sends both. Call only one of the two on a query.
- To sort by a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- In Swift, the method is order(byAscending:).
Example
Sort entries by price (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query orderByAscending:@"price_in_usd"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Sort entries by price (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.order(byAscending: "price_in_usd")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}orderByDescending:
orderByDescending: sorts the entries by the value of one field in descending order.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to sort by. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. orderByDescending: writes the desc parameter and makes no request. See Order by desc.
- A second call replaces the field from the first.
- The orderByAscending: method writes a different parameter, so calling both sends both. Call only one of the two on a query.
- To sort by a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- In Swift, the method is order(byDescending:).
Example
Sort entries by price (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query orderByDescending:@"price_in_usd"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Sort entries by price (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.order(byDescending: "price_in_usd")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}query:
query: sets the whole condition object of the query from a dictionary.
| Name | Type | Description |
|---|---|---|
| queryString (required) | NSDictionary * | Conditions in the JSON shape of query. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation. The SDK converts the dictionary to JSON when a send method runs.
- A value that JSON cannot represent, such as an NSDate, raises NSInvalidArgumentException from the send call. Pass dates as strings, for example @"2024-01-01".
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. query: writes the dictionary under the query key and makes no request. The send call serializes it to JSON in the query parameter.
- It replaces every condition that whereKey: methods, orWithSubqueries: and andWithSubqueries: wrote before it.
- Use it for an operator that has no method, or for a taxonomy query that also filters by content type with _content_type_uid. See Get all entries with defined taxonomies.
- In Swift, the parameter type is [AnyHashable : Any].
Known issue The SDK stores the dictionary you pass without copying it into a mutable one. A later whereKey: method, orWithSubqueries: or andWithSubqueries: on this query, or passing this query as a subquery to one of those two methods, raises NSInvalidArgumentException and crashes the app. Put every condition in the one dictionary. In Objective-C, passing an NSMutableDictionary also avoids the crash.
Example
Match entries with a condition dictionary (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query query:@{@"title": @"Welcome", @"price_in_usd": @{@"$lt": @(600)}}];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries with a condition dictionary (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.query(["title": "Welcome", "price_in_usd": ["$lt": 600]])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Match taxonomy entries of one content type (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
[query query:@{@"taxonomies.color": @"red", @"_content_type_uid": @"CONTENT_TYPE_UID"}];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match taxonomy entries of one content type (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
query.query(["taxonomies.color": "red", "_content_type_uid": "CONTENT_TYPE_UID"])
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}removeHeaderForKey:
removeHeaderForKey: removes a header that this query holds.
| Name | Type | Description |
|---|---|---|
| headerKey (required) | NSString * | Name of the header to remove. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation. A name the query does not hold, or nil from Objective-C, changes nothing and raises nothing.
Behavior
- Client-side only. removeHeaderForKey: deletes the header from the query and makes no request.
- It removes only headers that setHeader:forKey: or addHeadersWithDictionary: added to this query. A header of the same name on the content type, taxonomy or stack stays, and the SDK still sends it.
- In Swift, the method is removeHeader(forKey:).
Example
Remove a header before the request (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query setHeader:@"VARIANT_UID" forKey:@"x-cs-variant-uid"];
[query removeHeaderForKey:@"x-cs-variant-uid"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Remove a header before the request (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.setHeader("VARIANT_UID", forKey: "x-cs-variant-uid")
query.removeHeader(forKey: "x-cs-variant-uid")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}removeQueryWithKey:
removeQueryWithKey: removes one request parameter from the query.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | Name of the parameter to remove. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation. A name the query does not hold changes nothing.
Behavior
- Client-side only. removeQueryWithKey: deletes the parameter and makes no request.
- It removes a parameter that any method wrote, by its request name. For example, limit undoes limitObjects:, locale undoes locale:, and query removes every condition.
- Removing environment has no lasting effect, because each send call writes it again from the stack.
- In Swift, the method is remove(withKey:).
Example
Remove a limit before the request (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query limitObjects:@(5)];
[query removeQueryWithKey:@"limit"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Remove a limit before the request (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.limitObjects(5)
query.remove(withKey: "limit")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}search:
search: sends a free-text search string with the query.
| Name | Type | Description |
|---|---|---|
| searchString (required) | NSString * | Text to search the entries for. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. search: writes the string to the typeahead parameter and makes no request.
- A second call replaces the first string.
- The Get all entries request does not list typeahead among its parameters. To match a field against a pattern, use the whereKey:matchesRegex: method.
Example
Search entries for a word (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query search:@"headphones"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Search entries for a word (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.search("headphones")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}setHeader:forKey:
setHeader:forKey: adds one HTTP header to every request this query sends.
| Name | Type | Description |
|---|---|---|
| headerValue (required) | NSString * | Value of the header. |
| headerKey (required) | NSString * | Name of the header. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation. The SDK sends the header name and value as given.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Behavior
- Client-side only. setHeader:forKey: stores the header on the query and makes no request. The find:, findOne: and findTaxonomy: methods send it.
- A second call with the same name replaces the value.
- A query header replaces a header with the same name on the stack or on the content type or taxonomy that created the query.
- The SDK writes X-User-Agent and User-Agent after the query headers, and branch when Config has a branch. A query header with one of those names has no effect.
- Query has no variant method. To read entry variants, set the x-cs-variant-uid header. See Get multiple variants of an entry and, for a taxonomy query, Get entries by taxonomy with variants.
Example
Read entry variants through a header (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query setHeader:@"VARIANT_UID" forKey:@"x-cs-variant-uid"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Read entry variants through a header (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.setHeader("VARIANT_UID", forKey: "x-cs-variant-uid")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Read taxonomy entries with a variant applied (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.color" equalTo:@"red"];
[query setHeader:@"VARIANT_UID" forKey:@"x-cs-variant-uid"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Read taxonomy entries with a variant applied (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
query.whereKey("taxonomies.color", equalTo: "red")
query.setHeader("VARIANT_UID", forKey: "x-cs-variant-uid")
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}skipObjects:
skipObjects: skips a number of matching entries before the page of results starts.
| Name | Type | Description |
|---|---|---|
| number (required) | NSNumber * | Number of entries to skip. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. skipObjects: writes the skip parameter and makes no request. See Skip.
- Chain it with the limitObjects: and includeCount methods to read the results one page at a time. Each send call returns one page. See Pagination.
- A second call replaces the first value.
Example
Read the second page of ten entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query skipObjects:@(10)];
[query limitObjects:@(10)];
[query includeCount];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"Total: %ld", (long)[result totalCount]);
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Read the second page of ten entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.skipObjects(10)
query.limitObjects(10)
query.includeCount()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("Total: \(result?.totalCount() ?? 0)")
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}tags:
tags: sends a list of tags to match entries by.
| Name | Type | Description |
|---|---|---|
| tagsArray (required) | NSArray<NSString *> * | Tags to match the entries against. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- tags: raises an NSException named Error if an item is not an NSString, because the SDK joins the items into one string. The Swift type [String] prevents this.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. tags: joins the tags with commas into the tags parameter, for example tags=phone,laptop, and makes no request.
- A second call replaces the first list.
- The Get all entries request does not list tags among its parameters.
Example
Match entries tagged phone or laptop (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query tags:@[@"phone", @"laptop"]];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries tagged phone or laptop (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.tags(["phone", "laptop"])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:containedIn:
whereKey:containedIn: matches entries whose field equals any of the values you list.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
| array (required) | NSArray * | Values the field may equal. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation. An empty array, or nil from Objective-C, sends an empty list.
- A value that JSON cannot represent, such as an NSDate, raises NSInvalidArgumentException from the send call. Pass dates as strings, for example @"2024-01-01".
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKey:containedIn: writes {"<key>": {"$in": [<values>]}} into the query object and makes no request. See Array Equals Operator.
- A second whereKey:containedIn: call on the same field adds its values to the same list.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- On a taxonomy query, pass taxonomies.<taxonomy_uid> as the key and send with the findTaxonomy: method. See IN Operator.
- In Swift, the method is whereKey(_:containedIn:).
Known issue When the field already holds a condition from another whereKey: method, whereKey:containedIn: raises NSInvalidArgumentException if that condition is a plain value, such as one from whereKey:equalTo:, and otherwise sends the array nested inside itself, so the filter does not match as written. Put each condition on the field in its own subquery and join them with the andWithSubqueries: method.
Example
Match entries in either of two colors (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"color" containedIn:@[@"Gold", @"Black"]];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries in either of two colors (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("color", containedIn: ["Gold", "Black"])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Match taxonomy entries by either of two terms (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.color" containedIn:@[@"red", @"yellow"]];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match taxonomy entries by either of two terms (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
query.whereKey("taxonomies.color", containedIn: ["red", "yellow"])
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:equalTo:
whereKey:equalTo: matches entries whose field equals a value.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
| object (required) | id | Value the field must equal. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- A value that JSON cannot represent, such as an NSDate, raises NSInvalidArgumentException from the send call. Pass dates as strings, for example @"2024-01-01".
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKey:equalTo: writes {"<key>": <object>} into the query object and makes no request. See Equals Operator.
- A second whereKey: call on the same field replaces the condition from the first. To apply two conditions to one field, such as a range, use the andWithSubqueries: method with one subquery per condition.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- On a taxonomy query, pass taxonomies.<taxonomy_uid> as the key and send with the findTaxonomy: method. See Get all entries with defined taxonomies.
- A dictionary as the value passes an operator that has no method. For example, @{@"$eq_below": @"blue", @"levels": @2} on a taxonomy key matches the term and the terms below it. Without levels, the API goes down 10 levels. See Equal and Below Operator.
- In Swift, the method is whereKey(_:equalTo:).
Example
Match entries by title (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"title" equalTo:@"Welcome"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries by title (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("title", equalTo: "Welcome")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Match taxonomy entries by term (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.color" equalTo:@"red"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match taxonomy entries by term (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
query.whereKey("taxonomies.color", equalTo: "red")
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Match taxonomy entries by a term and the terms below it (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.color" equalTo:@{@"$eq_below": @"blue", @"levels": @(2)}];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match taxonomy entries by a term and the terms below it (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
query.whereKey("taxonomies.color", equalTo: ["$eq_below": "blue", "levels": 2])
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:greaterThan:
whereKey:greaterThan: matches entries whose field is greater than a value.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
| object (required) | id | Value the field must be greater than. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- A value that JSON cannot represent, such as an NSDate, raises NSInvalidArgumentException from the send call. Pass dates as strings, for example @"2024-01-01".
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKey:greaterThan: writes {"<key>": {"$gt": <object>}} into the query object and makes no request. See Greater Than.
- A second whereKey: call on the same field replaces the condition from the first. To apply two conditions to one field, such as a range, use the andWithSubqueries: method with one subquery per condition.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- In Swift, the method is whereKey(_:greaterThan:).
Example
Match entries updated after a date (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"updated_at" greaterThan:@"2024-01-01"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries updated after a date (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("updated_at", greaterThan: "2024-01-01")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:greaterThanOrEqualTo:
whereKey:greaterThanOrEqualTo: matches entries whose field is greater than or equal to a value.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
| object (required) | id | Lowest value the field may hold. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- A value that JSON cannot represent, such as an NSDate, raises NSInvalidArgumentException from the send call. Pass dates as strings, for example @"2024-01-01".
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKey:greaterThanOrEqualTo: writes {"<key>": {"$gte": <object>}} into the query object and makes no request. See Greater Than Or Equal To.
- A second whereKey: call on the same field replaces the condition from the first. To apply two conditions to one field, such as a range, use the andWithSubqueries: method with one subquery per condition.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- In Swift, the method is whereKey(_:greaterThanOrEqualTo:).
Example
Match entries from a price upward (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"price_in_usd" greaterThanOrEqualTo:@(100)];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries from a price upward (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("price_in_usd", greaterThanOrEqualTo: 100)
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:in:
whereKey:in: matches entries whose reference field points to entries that satisfy a subquery.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the reference field. |
| query (required) | Query * | Query whose conditions select the referenced entries. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- When the subquery has no condition, whereKey:in: records nothing and raises nothing, so the request goes out without this filter. The same applies to nil from Objective-C.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKey:in: writes {"<key>": {"$in_query": <subquery conditions>}} into the query object and makes no request. See Reference Search Equals.
- The SDK reads only the conditions of the subquery. Create it from the referenced content type for clarity, and set no other options on it.
- A second whereKey: call on the same reference field replaces this condition.
- This filter applies to entries of a content type. Use it on a query from ContentType query.
- In Swift, the method is whereKey(_:in:).
Example
Match products whose brand is Apple Inc. (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
Query *brandQuery = [[stack contentTypeWithName:@"brand"] query];
[brandQuery whereKey:@"title" equalTo:@"Apple Inc."];
[query whereKey:@"brand" in:brandQuery];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match products whose brand is Apple Inc. (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
let brandQuery = stack.contentType(withName: "brand").query()
brandQuery.whereKey("title", equalTo: "Apple Inc.")
query.whereKey("brand", in: brandQuery)
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:lessThan:
whereKey:lessThan: matches entries whose field is less than a value.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
| object (required) | id | Value the field must be less than. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- A value that JSON cannot represent, such as an NSDate, raises NSInvalidArgumentException from the send call. Pass dates as strings, for example @"2024-01-01".
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKey:lessThan: writes {"<key>": {"$lt": <object>}} into the query object and makes no request. See Less Than.
- A second whereKey: call on the same field replaces the condition from the first. To apply two conditions to one field, such as a range, use the andWithSubqueries: method with one subquery per condition.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- In Swift, the method is whereKey(_:lessThan:).
Example
Match entries under a price (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"price_in_usd" lessThan:@(600)];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries under a price (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("price_in_usd", lessThan: 600)
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:lessThanOrEqualTo:
whereKey:lessThanOrEqualTo: matches entries whose field is less than or equal to a value.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
| object (required) | id | Highest value the field may hold. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- A value that JSON cannot represent, such as an NSDate, raises NSInvalidArgumentException from the send call. Pass dates as strings, for example @"2024-01-01".
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKey:lessThanOrEqualTo: writes {"<key>": {"$lte": <object>}} into the query object and makes no request. See Less Than Or Equal To.
- A second whereKey: call on the same field replaces the condition from the first. To apply two conditions to one field, such as a range, use the andWithSubqueries: method with one subquery per condition.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- In Swift, the method is whereKey(_:lessThanOrEqualTo:).
Example
Match entries up to a price (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"price_in_usd" lessThanOrEqualTo:@(600)];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries up to a price (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("price_in_usd", lessThanOrEqualTo: 600)
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:matchesRegex:
whereKey:matchesRegex: matches entries whose field matches a regular expression.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
| regex (required) | NSString * | Regular expression the value must match. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKey:matchesRegex: writes {"<key>": {"$regex": <regex>}} into the query object and makes no request. See Search by Regex.
- A second whereKey: call on the same field replaces the condition from the first. To apply two conditions to one field, such as a range, use the andWithSubqueries: method with one subquery per condition.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- To ignore case, use the whereKey:matchesRegex:modifiers: method.
- In Swift, the method is whereKey(_:matchesRegex:).
Example
Match titles that start with Bl (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"title" matchesRegex:@"^Bl"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match titles that start with Bl (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("title", matchesRegex: "^Bl")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:matchesRegex:modifiers:
whereKey:matchesRegex:modifiers: matches entries whose field matches a regular expression, with options such as ignoring case.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
| regex (required) | NSString * | Regular expression the value must match. |
| modifier (required) | NSString * | Regular expression options, for example i. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. The method writes {"<key>": {"$regex": <regex>, "$options": <modifier>}} into the query object and makes no request. See Search by Regex.
- Pass i to ignore case.
- A second whereKey: call on the same field replaces the condition from the first. To apply two conditions to one field, such as a range, use the andWithSubqueries: method with one subquery per condition.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- In Swift, the method is whereKey(_:matchesRegex:modifiers:).
Example
Match titles that start with bl in any case (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"title" matchesRegex:@"^bl" modifiers:@"i"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match titles that start with bl in any case (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("title", matchesRegex: "^bl", modifiers: "i")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:notContainedIn:
whereKey:notContainedIn: matches entries whose field equals none of the values you list.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
| array (required) | NSArray * | Values the field must not equal. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation. An empty array, or nil from Objective-C, sends an empty list.
- A value that JSON cannot represent, such as an NSDate, raises NSInvalidArgumentException from the send call. Pass dates as strings, for example @"2024-01-01".
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKey:notContainedIn: writes {"<key>": {"$nin": [<values>]}} into the query object and makes no request. See Array Not-equals Operator.
- A second whereKey:notContainedIn: call on the same field adds its values to the same list.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- In Swift, the method is whereKey(_:notContainedIn:).
Known issue When the field already holds a condition from another whereKey: method, whereKey:notContainedIn: raises NSInvalidArgumentException if that condition is a plain value, such as one from whereKey:equalTo:, and otherwise sends the array nested inside itself, so the filter does not match as written. Put each condition on the field in its own subquery and join them with the andWithSubqueries: method.
Example
Leave out entries in two colors (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"color" notContainedIn:@[@"Gold", @"Black"]];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Leave out entries in two colors (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("color", notContainedIn: ["Gold", "Black"])
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:notEqualTo:
whereKey:notEqualTo: matches entries whose field does not equal a value.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
| object (required) | id | Value the field must not equal. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- A value that JSON cannot represent, such as an NSDate, raises NSInvalidArgumentException from the send call. Pass dates as strings, for example @"2024-01-01".
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKey:notEqualTo: writes {"<key>": {"$ne": <object>}} into the query object and makes no request. See Not-equals Operator.
- A second whereKey: call on the same field replaces the condition from the first. To apply two conditions to one field, such as a range, use the andWithSubqueries: method with one subquery per condition.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- In Swift, the method is whereKey(_:notEqualTo:).
Example
Leave out entries with one title (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKey:@"title" notEqualTo:@"Welcome"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Leave out entries with one title (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKey("title", notEqualTo: "Welcome")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKey:notIn:
whereKey:notIn: matches entries whose reference field does not point to entries that satisfy a subquery.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the reference field. |
| query (required) | Query * | Query whose conditions select the referenced entries. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- When the subquery has no condition, whereKey:notIn: records nothing and raises nothing, so the request goes out without this filter. The same applies to nil from Objective-C.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKey:notIn: writes {"<key>": {"$nin_query": <subquery conditions>}} into the query object and makes no request. See Reference Search Not-equals.
- The SDK reads only the conditions of the subquery. Create it from the referenced content type for clarity, and set no other options on it.
- A second whereKey: call on the same reference field replaces this condition.
- This filter applies to entries of a content type. Use it on a query from ContentType query.
- In Swift, the method is whereKey(_:notIn:).
Example
Match products whose brand is not Apple Inc. (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
Query *brandQuery = [[stack contentTypeWithName:@"brand"] query];
[brandQuery whereKey:@"title" equalTo:@"Apple Inc."];
[query whereKey:@"brand" notIn:brandQuery];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match products whose brand is not Apple Inc. (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
let brandQuery = stack.contentType(withName: "brand").query()
brandQuery.whereKey("title", equalTo: "Apple Inc.")
query.whereKey("brand", notIn: brandQuery)
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKeyDoesNotExist:
whereKeyDoesNotExist: matches entries that do not hold the field you name.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKeyDoesNotExist: writes {"<key>": {"$exists": false}} into the query object and makes no request. See Exists.
- A second whereKey: call on the same field replaces the condition from the first. To apply two conditions to one field, such as a range, use the andWithSubqueries: method with one subquery per condition.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
Example
Match entries without an introduction (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKeyDoesNotExist:@"introduction"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries without an introduction (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKeyDoesNotExist("introduction")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}whereKeyExists:
whereKeyExists: matches entries that hold the field you name.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to test. |
Returns: void. Nothing. The query keeps the setting for its next request.
Validation
- There is no client-side validation.
- An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereKeyExists: writes {"<key>": {"$exists": true}} into the query object and makes no request. See Exists.
- A second whereKey: call on the same field replaces the condition from the first. To apply two conditions to one field, such as a range, use the andWithSubqueries: method with one subquery per condition.
- To test a field inside a group or modular block, pass its path, for example group_UID.field_UID.
- On a taxonomy query, pass taxonomies.<taxonomy_uid> as the key and send with the findTaxonomy: method. See Exists Operator.
Example
Match entries that have an introduction (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Query *query = [contentType query];
[query whereKeyExists:@"introduction"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match entries that have an introduction (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let query = contentType.query()
query.whereKeyExists("introduction")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}Match taxonomy entries that carry any term of a taxonomy (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *query = [taxonomy query];
[query whereKeyExists:@"taxonomies.color"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
for (Entry *entry in [result getResult]) {
NSLog(@"%@", entry.title);
}
}];Match taxonomy entries that carry any term of a taxonomy (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let query = taxonomy.query()
query.whereKeyExists("taxonomies.color")
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
for entry in result?.getResult() ?? [] {
print(entry.title)
}
}