Query
Query
The Query class builds a request for the published entries of one content type and sends it. Use this class to
- filter entries by field values, tags, or conditions on referenced entries
- sort and page through the results
- choose which fields and referenced entries the response carries
- run the request and read the matching entries, or the first match only
A query collects conditions and parameters on the device. Nothing goes out until you call find or findOne, which call Get all entries (GET /content_types/{content_type_uid}/entries). find hands back a QueryResult. findOne hands back one Entry.
addParam
addParam adds one query parameter to the request.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter. |
| value (required) | String | Value of the query parameter. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. addParam sends any key and value as given.
- A null key or value puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- Use the limit method for limit. findOne reads limit as an integer, and a string value from addParam makes it fail with an Error.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. addParam writes key and value into the parameter map and makes no request. find sends them as key=value.
- addParam and addQuery write to the same map and behave the same.
- A key that another method already set, such as locale or limit, takes the new value. See Request parameters on the Query class page.
- Use it for a Get all entries parameter that has no method of its own, such as include_branch.
- Remove a key with the removeQuery method.
- Known issue: The SDK adds the value to the URL without URL encoding. A value that contains &, #, +, or % does not reach the API as written. Encode such a value with URLEncoder.encode(value, "UTF-8") first.
Example
Basic usage: add the branch key to each entry
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.addParam("include_branch", "true");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle() + " " + entry.getString("_branch"));
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Edge case: encode a value that holds a reserved character
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.net.URLEncoder;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
// URL-encode the value, because the SDK does not
query.addParam("search_term", URLEncoder.encode("salt & pepper", "UTF-8"));
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}addQuery
addQuery adds one query parameter to the request.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter. |
| value (required) | String | Value of the query parameter. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. addQuery sends any key and value as given.
- A null key or value puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- Use the limit method for limit. findOne reads limit as an integer, and a string value from addQuery makes it fail with an Error.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. addQuery writes key and value into the parameter map and makes no request. find sends them as key=value.
- addQuery and addParam write to the same map and behave the same.
- A key that another method already set, such as locale or limit, takes the new value. See Request parameters on the Query class page.
- Use it for a Get all entries parameter that has no method of its own, such as include_branch.
- Remove a key with the removeQuery method.
- Known issue: The SDK adds the value to the URL without URL encoding. A value that contains &, #, +, or % does not reach the API as written. Encode such a value with URLEncoder.encode(value, "UTF-8") first.
Example
Basic usage: resolve taxonomy term names in the response
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.addQuery("include_taxonomy_terms", "true");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Edge case: replace a value that another method set
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.locale("en-us");
// addQuery writes the same key, so the request uses fr-fr
query.addQuery("locale", "fr-fr");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}and
and matches entries that meet the conditions of every sub-query you pass.
| Name | Type | Description |
|---|---|---|
| queryObjects (required) | ArrayList<Query> | Sub-queries whose conditions must all match. |
Returns: Query. The same query, for chaining.
Validation
- A null or empty queryObjects, or a null element in it, puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- and does not check the error state of each sub-query. A condition that a sub-query dropped because of a null argument is missing from the list, with no error.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. and reads the field conditions of each sub-query and stores them as a list under $and. It makes no request.
- find sends the list in the shape the AND Operator request describes. The API returns entries that satisfy every condition in the list.
- and reads only field conditions, from methods such as where and lessThan. It ignores the sort, paging, include, locale, and header settings of each sub-query.
- A sub-query can come from any content type's query(). The SDK never sends a sub-query as a request of its own.
- and keeps a reference to each sub-query's conditions, so a condition that you add to a sub-query before find also goes out.
- A second and call replaces the first list. Conditions you set on the main query with other methods sit next to $and in the same object.
Example
Basic usage: match entries that meet two conditions
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.ArrayList;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
Query titleQuery = stack.contentType("<CONTENT_TYPE_UID>").query();
titleQuery.where("title", "Redmi Note 3");
Query colorQuery = stack.contentType("<CONTENT_TYPE_UID>").query();
colorQuery.where("color", "Gold");
ArrayList<Query> conditions = new ArrayList<>();
conditions.add(titleQuery);
conditions.add(colorQuery);
query.and(conditions);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Edge case: two ranges on interleaved fields
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.ArrayList;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
// Build each field in its own sub-query to avoid the shared-condition Known issue
Query priceQuery = stack.contentType("<CONTENT_TYPE_UID>").query();
priceQuery.greaterThan("price_in_usd", 100).lessThan("price_in_usd", 600);
Query ratingQuery = stack.contentType("<CONTENT_TYPE_UID>").query();
ratingQuery.greaterThanOrEqualTo("rating", 4).lessThanOrEqualTo("rating", 5);
ArrayList<Query> ranges = new ArrayList<>();
ranges.add(priceQuery);
ranges.add(ratingQuery);
query.and(ranges);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}ascending
ascending sorts the entries by the field you name, lowest value first.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to sort by. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. ascending records any field UID.
- A null key puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. ascending sets the asc query parameter to key and makes no request. find sends it in the shape the Order by asc request describes.
- A second ascending replaces the field. The SDK sends one sort field per direction.
- ascending and descending write different parameters, so a query that calls both sends both. Call only one of them on a query.
- Pass a dot path to sort by a field inside a Group field or a Modular Blocks block.
Example
Basic usage: sort entries by price, lowest first
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.ascending("price_in_usd");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Group field: sort by a field inside a Group field
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.ascending("bank_offers.discount");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}cancelRequest
cancelRequest cancels every query request that is in flight in the app.
Returns: void. This method returns nothing.
Validation
- There is no client-side validation. cancelRequest does not throw, and it does nothing when no query request is in flight.
Behavior
- cancelRequest cancels the requests of every Query object in the app, on every stack, not only the requests of the query you call it on. find and findOne requests both stop.
- A cancelled request never calls its callback. Volley drops the response of a cancelled request (com.android.volley:volley:1.2.1).
- Requests from Entry, Asset, and the other classes keep running.
- cancelRequest has no effect on a result that comes from the disk cache, because find delivers a cached result before it returns.
- The query keeps its conditions. Call find again to send a new request.
Example
Basic usage: cancel the query requests when the screen closes
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
Log.d("Contentstack", "Entries: " + queryResult.getResultObjects().size());
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
// Later, for example in onStop(), cancel every query request still in flight
query.cancelRequest();
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}containedIn
containedIn matches entries whose field value equals any of the values you pass.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to compare. |
| values (required) | Object[] | Values the field may equal. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. containedIn records any field UID and any element types.
- A null key or values puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An empty array is not an error. containedIn sends "$in": [].
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. containedIn adds "$in" with the elements of values to the condition on key and makes no request.
- find sends the condition in the shape the Array Equals Operator request describes. The API returns entries whose field value matches any element.
- Consecutive operator calls on one field merge into one condition. A second containedIn on the field replaces the array.
- where on the same field replaces the whole condition.
- Conditions on one field follow the rules in Field conditions on the Query class page, including the Known issue for operator calls that move between fields.
Example
Basic usage: match entries in one of two categories
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.containedIn("category", new Object[]{"news", "sports"});
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Numbers: match entries with one of two prices
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.containedIn("price_in_usd", new Object[]{101, 749});
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}count
count asks for the number of matching entries without the entries themselves.
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation.
- Errors that do occur come from the find (or findOne) call that follows, as an Error in the callback.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. count sets count=true and makes no request. find sends it as the Count request describes, and the API returns only the count of entries.
- Read the number with getCount. getResultObjects() returns an empty list, because the response carries no entries.
- Use the includeCount method instead when you need the entries and the total together.
- Calling it more than once has the same effect as calling it once.
Example
Basic usage: count the entries in a category
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.where("category", "news").count();
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
Log.d("Contentstack", "News entries: " + queryResult.getCount());
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Edge case: count every entry of the content type
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.count();
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "All entries: " + queryResult.getCount());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}descending
descending sorts the entries by the field you name, highest value first.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to sort by. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. descending records any field UID.
- A null key puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. descending sets the desc query parameter to key and makes no request. find sends it in the shape the Order by desc request describes.
- A second descending replaces the field. The SDK sends one sort field per direction.
- descending and ascending write different parameters, so a query that calls both sends both. Call only one of them on a query.
- Pass a dot path to sort by a field inside a Group field or a Modular Blocks block.
Example
Basic usage: sort entries by price, highest first
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.descending("price_in_usd");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Pagination: the five newest entries
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.descending("created_at").limit(5);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}except
except leaves the top-level fields you name out of each entry in the response.
| Name | Type | Description |
|---|---|---|
| fieldUid (required) | ArrayList<String> | UIDs of the top-level fields to leave out. |
| fieldUids (required) | String[] | UIDs of the top-level fields to leave out. |
Returns: Query. The same query, for chaining.
Overloads
- except(ArrayList<String> fieldUid)
- except(String[] fieldUids)
Validation
- There is no client-side validation. except records any field UID.
- A null or empty list or array puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. except adds each field UID to a list and makes no request. find sends one except[BASE][] parameter per field, as the Exclude Operator request describes.
- Both overloads add to the same list, and calls add to it, so every field you name across calls stays out.
- Use the exceptWithReferenceUid method to leave out fields of referenced entries.
- Use the only method to name the fields to return instead.
Example
Basic usage: leave out two fields with an array
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.except(new String[]{"description", "body"});
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}List overload: leave out fields collected at runtime
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.ArrayList;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
ArrayList<String> hiddenFields = new ArrayList<>();
hiddenFields.add("description");
hiddenFields.add("seo");
query.except(hiddenFields);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}exceptWithReferenceUid
exceptWithReferenceUid includes a reference field and leaves the fields you name out of each referenced entry.
| Name | Type | Description |
|---|---|---|
| fieldUid (required) | ArrayList<String> | UIDs of the referenced entry's fields to leave out. |
| referenceFieldUid (required) | String | UID of the reference field. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. exceptWithReferenceUid does not check that referenceFieldUid names a reference field.
- A null fieldUid or referenceFieldUid puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An empty fieldUid list is not an error. exceptWithReferenceUid then sends no except parameter for the reference, and still includes the referenced entries.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. exceptWithReferenceUid records the field list for referenceFieldUid and makes no request. find sends one except[<referenceFieldUid>][] parameter per field, as the Exclude Operator request describes.
- exceptWithReferenceUid also adds referenceFieldUid to the include list, so the response carries the referenced entries without a separate includeReference call.
- A second call for the same reference field replaces its field list. Calls for different reference fields add up.
- Use the except method for top-level fields.
Example
Basic usage: include the author without the biography
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.ArrayList;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
ArrayList<String> hiddenFields = new ArrayList<>();
hiddenFields.add("biography");
query.exceptWithReferenceUid(hiddenFields, "author");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle() + " " + entry.getJSONArray("author"));
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Combined projection: two reference fields, each with its own exclusions
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.ArrayList;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
ArrayList<String> authorFields = new ArrayList<>();
authorFields.add("biography");
ArrayList<String> categoryFields = new ArrayList<>();
categoryFields.add("description");
query.exceptWithReferenceUid(authorFields, "author")
.exceptWithReferenceUid(categoryFields, "categories");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}exists
exists matches entries that carry a value for the field you name.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to check. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. exists records any field UID.
- A null key puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. exists adds "$exists": true to the condition on key and makes no request. find sends it in the query parameter. The Exists request describes the operator.
- The API returns entries in which the field exists.
- Consecutive operator calls on one field merge into one condition. exists and the notExists method write the same $exists key, so the later call wins.
- where on the same field replaces the whole condition.
- Conditions on one field follow the rules in Field conditions on the Query class page, including the Known issue for operator calls that move between fields.
Example
Basic usage: match entries that have a price
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.exists("price_in_usd");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Group field: match entries where a field inside a Group field exists
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.exists("bank_offers.card_type");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}find
find sends the query and returns every entry that matches its conditions, up to the page size.
| Name | Type | Description |
|---|---|---|
| callback (required) | QueryResultsCallBack | Receives the matching entries or the error. |
Returns: Query. The same query. Results arrive in the callback.
Validation
- find checks the content type UID and the error state before it sends anything. When the UID is empty or null, or the query is in an error state, find calls the callback with ResponseType.UNKNOWN and an Error instead. See Error state on the Query class page.
- find does not throw. An API rejection or a network failure reaches the callback as an Error with ResponseType.NETWORK.
- There is no check on callback. With null, find still sends the request and drops the result.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- find sends one GET request to Get all entries with the field conditions in the query parameter and every parameter the builder methods recorded. The SDK does not request further pages. See Pagination on the Query class page.
- onCompletion(ResponseType responseType, QueryResult queryresult, Error error) fires when the request ends. On success error is null and the QueryResult holds the entries. On failure the result is null.
- responseType takes one of the three values below, each naming where the result came from:
- NETWORK for a response from the API.
- CACHE for a response from the SDK's disk cache.
- UNKNOWN when no request went out.
- With the default cache policy, find sends the request and saves the response in the disk cache. Use the setCachePolicy method to read from the cache instead. With CACHE_THEN_NETWORK the callback fires twice.
- When the device reports no network connection, find sends no request and the callback receives an Error whose getErrorCode() returns 408, with ResponseType.UNKNOWN.
- find returns before the request completes, and it does not reset the query. A second find on the same query sends the same conditions again, plus any conditions that you add in between.
- Use the cancelRequest method to cancel the request. A cancelled request never calls the callback.
Example
Basic usage: return the published entries of a content type
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getUid() + " " + entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Pagination: read the second page of ten entries and the total count
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.includeCount().skip(10).limit(10);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Total entries: " + queryResult.getCount());
Log.d("Contentstack", "On this page: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}Error handling: a null argument stops the request before it goes out
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
String category = null;
// A null value puts the query in an error state, so find sends no request
query.where("category", category);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null && responseType == ResponseType.UNKNOWN) {
Log.e("Contentstack", "No request sent: " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}findOne
findOne sends the query and returns the first entry that matches its conditions.
| Name | Type | Description |
|---|---|---|
| callBack (required) | SingleQueryResultCallback | Receives the first matching entry or the error. |
Returns: Query. The same query. Results arrive in the callback.
Validation
- findOne checks the content type UID and the error state before it sends anything. When the UID is empty or null, or the query is in an error state, findOne calls the callback with ResponseType.UNKNOWN and an Error instead. See Error state on the Query class page.
- findOne does not throw. An API rejection or a network failure reaches the callback as an Error with ResponseType.NETWORK.
- findOne reads limit as an integer. A string value, for example from addParam("limit", "5"), makes findOne call the callback with an Error and leaves the query in an error state.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- findOne sends the same Get all entries request as the find method, with limit set to 1.
- onCompletion(ResponseType responseType, Entry entry, Error error) fires when the request ends. On success error is null and entry holds the first match. On failure entry is null.
- When no entry matches, entry is not null. It is an empty Entry whose getUid() returns null, so check the UID before you read fields.
- findOne puts back a limit you set earlier after it queues the request. When you set none, limit stays 1 on the query, and a later find on the same query returns one entry. Build a new query for find.
- The cache policy applies to findOne the same way it applies to find. See the setCachePolicy method.
- Sort the query with the ascending or the descending method to control which entry comes first.
Example
Basic usage: return the most recent entry
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.SingleQueryResultCallback;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.descending("created_at");
query.findOne(new SingleQueryResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Entry entry, Error error) {
if (error == null) {
Log.d("Contentstack", entry.getUid() + " " + entry.getTitle());
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Edge case: detect that no entry matched
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.SingleQueryResultCallback;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.where("url", "/about-us");
query.findOne(new SingleQueryResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Entry entry, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
if (entry.getUid() == null) {
// No entry matched, so the SDK returned an empty Entry
Log.d("Contentstack", "No match");
return;
}
Log.d("Contentstack", entry.getTitle());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}getContentType
getContentType returns the UID of the content type this query reads.
Returns: String. The UID of the content type this query reads.
Validation
- There is no client-side validation. getContentType returns null when the content type came from stack.contentType(null).
Behavior
- Client-side only. getContentType returns the UID passed to stack.contentType(...) and makes no request.
- It returns the UID only. To read the content type schema, call the includeContentType method and read getContentType on the result.
Example
Basic usage: log the content type of a query
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
Log.d("Contentstack", "Querying " + query.getContentType());
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}getHeaders
getHeaders returns the headers set on this query.
Returns: ArrayMap. The headers set on this query.
Validation
- There is no client-side validation. getHeaders never returns null.
Behavior
- Client-side only. getHeaders returns an android.util.ArrayMap<String, Object> and makes no request.
- The map holds the headers from setHeader and variants. It does not hold the api_key, access_token, environment, or other headers that come from the stack or the content type.
- The map is the one the query sends from, not a copy. A change to it changes the headers of the next request.
Example
Basic usage: log the headers set on a query
import android.util.ArrayMap;
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.setHeader("x-request-source", "android-app");
query.variants("<VARIANT_UID>", "<BRANCH>");
ArrayMap<String, Object> headers = query.getHeaders();
for (int i = 0; i < headers.size(); i++) {
Log.d("Contentstack", headers.keyAt(i) + ": " + headers.valueAt(i));
}
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}greaterThan
greaterThan matches entries whose field value is above the value you pass.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to compare. |
| value (required) | Object | Lower bound, not included. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. greaterThan records any field UID and value type.
- A null key or value puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. greaterThan adds "$gt": value to the condition on key and makes no request.
- find sends the condition in the shape the Greater Than request describes. The API returns entries whose field value is greater than value.
- Consecutive operator calls on one field merge into one condition. A second greaterThan on the field replaces its value.
- where on the same field replaces the whole condition.
- Conditions on one field follow the rules in Field conditions on the Query class page, including the Known issue for operator calls that move between fields.
- Pass a number, or a date as an ISO 8601 string, as the Greater Than request shows.
Example
Basic usage: match entries priced above 146
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.greaterThan("price_in_usd", 146);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Range: match entries priced above 146 and below 600
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.greaterThan("price_in_usd", 146).lessThan("price_in_usd", 600);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}greaterThanOrEqualTo
greaterThanOrEqualTo matches entries whose field value is at or above the value you pass.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to compare. |
| value (required) | Object | Lower bound, included. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. greaterThanOrEqualTo records any field UID and value type.
- A null key or value puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. greaterThanOrEqualTo adds "$gte": value to the condition on key and makes no request.
- find sends the condition in the shape the Greater Than Or Equal To request describes. The API returns entries whose field value is greater than or equal to value.
- Consecutive operator calls on one field merge into one condition. A second greaterThanOrEqualTo on the field replaces its value.
- where on the same field replaces the whole condition.
- Conditions on one field follow the rules in Field conditions on the Query class page, including the Known issue for operator calls that move between fields.
- Pass a number, or a date as an ISO 8601 string, as the Greater Than Or Equal To request shows.
Example
Basic usage: match entries that start on or after a date
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.greaterThanOrEqualTo("start_date", "2017-12-08T00:00:00.000Z");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Range: match entries priced from 146 up to, but not including, 600
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.greaterThanOrEqualTo("price_in_usd", 146).lessThan("price_in_usd", 600);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}includeContentType
includeContentType adds the content type of the queried entries to the response.
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation.
- Errors that do occur come from the find (or findOne) call that follows, as an Error in the callback.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeContentType sets include_content_type=true and include_global_field_schema=true, and makes no request. find sends both to Get all entries.
- Read the content type with getContentType on the QueryResult.
- includeContentType removes an include_schema parameter that you set with addParam.
- Calling it more than once has the same effect as calling it once.
Example
Basic usage: read the content type title next to the entries
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import org.json.JSONObject;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.includeContentType();
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
JSONObject contentType = queryResult.getContentType();
if (contentType != null) {
Log.d("Contentstack", contentType.optString("title"));
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}includeCount
includeCount adds the total number of matching entries to the response, next to the entries.
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation.
- Errors that do occur come from the find (or findOne) call that follows, as an Error in the callback.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeCount sets include_count=true and makes no request. find sends it as the Count request describes.
- Read the total with getCount. It counts every match, not only the entries on the current page.
- Without includeCount or count, getCount returns 0.
- Calling it more than once has the same effect as calling it once.
Example
Basic usage: read the total next to the first page
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.includeCount().limit(10);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
Log.d("Contentstack", "Total: " + queryResult.getCount());
Log.d("Contentstack", "Returned: " + queryResult.getResultObjects().size());
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Pagination: work out the number of pages
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.where("category", "news").includeCount().limit(20);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
int pages = (queryResult.getCount() + 19) / 20;
Log.d("Contentstack", "Pages: " + pages);
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}includeEmbeddedItems
includeEmbeddedItems adds the entries and assets embedded in Rich Text Editor fields to the response.
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation.
- Errors that do occur come from the find (or findOne) call that follows, as an Error in the callback.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeEmbeddedItems sets include_embedded_items[]=BASE and makes no request. find sends it with the query.
- The Get information on embedded RTE objects request describes the parameter. With BASE, the response carries the first level of embedded items under the _embedded_items key of each entry.
- Calling it more than once has the same effect as calling it once.
Example
Basic usage: read the embedded items of each entry
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import org.json.JSONObject;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.includeEmbeddedItems();
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
JSONObject embedded = entry.getJSONObject("_embedded_items");
Log.d("Contentstack", entry.getTitle() + " " + embedded);
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}includeFallback
includeFallback returns the fallback-locale version of each entry that has no published content in the requested locale.
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation.
- Errors that do occur come from the find (or findOne) call that follows, as an Error in the callback.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeFallback sets include_fallback=true and makes no request.
- find sends it to Get all entries. The API then includes the published content from the fallback locale when the requested locale has none.
- Use it with the locale method. Without includeFallback, the API returns only the entries published in the requested locale.
- Read the locale an entry came back in with entry.getLocale().
- Calling it more than once has the same effect as calling it once.
Example
Basic usage: request French entries with fallback
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.locale("fr-fr").includeFallback();
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle() + " " + entry.getLocale());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}includeMetadata
includeMetadata adds the metadata of each entry to the response.
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation.
- Errors that do occur come from the find (or findOne) call that follows, as an Error in the callback.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeMetadata sets include_metadata=true and makes no request. find sends it to Get all entries, and the API returns the metadata of each entry under its _metadata key.
- Read the metadata with entry.getJSONObject("_metadata").
- Calling it more than once has the same effect as calling it once.
Example
Basic usage: read the metadata of each entry
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import org.json.JSONObject;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.includeMetadata();
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
JSONObject metadata = entry.getJSONObject("_metadata");
Log.d("Contentstack", entry.getTitle() + " " + metadata);
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}includeReference
includeReference adds the content of the entries that a reference field points to, in place of their UIDs.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the reference field to include. |
| keys (required) | String[] | UIDs of the reference fields to include. |
Returns: Query. The same query, for chaining.
Overloads
- includeReference(String key)
- includeReference(String[] keys)
Validation
- There is no client-side validation. includeReference does not check that a UID names a reference field.
- The String overload accepts null without an error and sends the text null as a field UID.
- A null or empty keys array in the String[] overload puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeReference adds each UID to the include list and makes no request. find sends one include[] parameter per UID, as the Include Reference request describes.
- Calls add to the list, and both overloads write to the same list.
- Without includeReference, each reference field in the response holds only the UIDs of the referenced entries.
- Read a referenced entry with entry.getJSONArray("<REFERENCE_FIELD_UID>"), or turn the references into Entry objects with getAllEntries. See the Entry class page.
- The API best practices recommend no more than ten includes in one request.
- Use the onlyWithReferenceUid or the exceptWithReferenceUid method to include a reference and choose its fields in one call.
Example
Basic usage: include the referenced author
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.includeReference("<REFERENCE_FIELD_UID>");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle() + " " + entry.getJSONArray("<REFERENCE_FIELD_UID>"));
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Array overload: include two reference fields and read them as entries
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.ArrayList;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.includeReference(new String[]{"author", "categories"});
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
for (Entry entry : queryResult.getResultObjects()) {
ArrayList<Entry> authors = entry.getAllEntries("author", "author");
if (authors != null) {
for (Entry author : authors) {
Log.d("Contentstack", author.getTitle());
}
}
}
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}includeReferenceContentTypUid
includeReferenceContentTypUid asks the API to name the content type of each referenced entry in the response.
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation.
- Errors that do occur come from the find (or findOne) call that follows, as an Error in the callback.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeReferenceContentTypUid sets include_reference_content_type_uid=true and makes no request. find sends it to Get all entries.
- The method name carries the SDK's own spelling, Typ without a final e. Call it with that spelling.
- Use it with the includeReference method, which adds the referenced entries to the response.
- Calling it more than once has the same effect as calling it once.
Example
Basic usage: include the author and its content type UID
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.includeReference("<REFERENCE_FIELD_UID>").includeReferenceContentTypUid();
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", String.valueOf(entry.getJSONArray("<REFERENCE_FIELD_UID>")));
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}language
> Deprecated: The SDK marks language as @Deprecated. Use the locale method, which takes the locale code as a String.
| Name | Type | Description |
|---|---|---|
| language (required) | Language | Enum value of the locale to return. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation.
- A null language puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. language converts the enum value to a locale code, such as en-us for Language.ENGLISH_UNITED_STATES, and sets the locale query parameter. It makes no request.
- language and locale write the same parameter, so the later call wins.
- The Language enum covers a fixed set of locales. locale accepts any locale code, including the codes of custom locales.
Example
Deprecated usage: set the locale from a Language value
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Language;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
// Deprecated. Use query.locale("en-us") instead
query.language(Language.ENGLISH_UNITED_STATES);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Replacement: pass the locale code to locale
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.locale("en-us");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}lessThan
lessThan matches entries whose field value is below the value you pass.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to compare. |
| value (required) | Object | Upper bound, not included. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. lessThan records any field UID and value type.
- A null key or value puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. lessThan adds "$lt": value to the condition on key and makes no request.
- find sends the condition in the shape the Less Than request describes. The API returns entries whose field value is less than value.
- Consecutive operator calls on one field merge into one condition. A second lessThan on the field replaces its value.
- where on the same field replaces the whole condition.
- Conditions on one field follow the rules in Field conditions on the Query class page, including the Known issue for operator calls that move between fields.
- Pass a number, or a date as an ISO 8601 string, as the Less Than request shows.
Example
Basic usage: match entries priced below 600
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.lessThan("price_in_usd", 600);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Range: match entries that start before a date and after another
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.greaterThan("start_date", "2017-12-01T00:00:00.000Z")
.lessThan("start_date", "2017-12-08T00:00:00.000Z");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}lessThanOrEqualTo
lessThanOrEqualTo matches entries whose field value is at or below the value you pass.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to compare. |
| value (required) | Object | Upper bound, included. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. lessThanOrEqualTo records any field UID and value type.
- A null key or value puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. lessThanOrEqualTo adds "$lte": value to the condition on key and makes no request.
- find sends the condition in the shape the Less Than Or Equal To request describes. The API returns entries whose field value is less than or equal to value.
- Consecutive operator calls on one field merge into one condition. A second lessThanOrEqualTo on the field replaces its value.
- where on the same field replaces the whole condition.
- Conditions on one field follow the rules in Field conditions on the Query class page, including the Known issue for operator calls that move between fields.
- Pass a number, or a date as an ISO 8601 string, as the Less Than Or Equal To request shows.
Example
Basic usage: match entries priced at 146 or less
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.lessThanOrEqualTo("price_in_usd", 146);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Range: match entries priced from 100 to 146, both included
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.greaterThanOrEqualTo("price_in_usd", 100).lessThanOrEqualTo("price_in_usd", 146);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}limit
limit caps the number of entries the query returns.
| Name | Type | Description |
|---|---|---|
| number (required) | int | Maximum number of entries to return. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. limit records zero and negative numbers as given.
- The Limit request accepts positive integers only. With 0 the API returns its default number of entries, not every entry.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. limit sets the limit query parameter and makes no request. find sends it to Get all entries.
- Omitting limit does not return every entry. The SDK sets no default, so the API returns its default page of 100 entries. See Pagination on the Query class page.
- A second limit replaces the value.
- findOne sends limit 1 for its own request and puts your value back afterwards.
Example
Basic usage: return at most five entries
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.limit(5);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Pagination: request the third page of 20 entries
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
int pageSize = 20;
query.skip(2 * pageSize).limit(pageSize);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}locale
locale sets the locale of the entries the query returns.
| Name | Type | Description |
|---|---|---|
| locale (required) | String | Locale code of the entries, such as fr-fr. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. locale records any text as the locale code.
- A null locale puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. locale sets the locale query parameter and makes no request. find sends it to Get all entries, and the API returns only the entries published in that locale.
- Without locale, the SDK sends no locale parameter, and the API applies its own default locale.
- A second locale replaces the value. The deprecated language method writes the same parameter, so the later call wins.
- Use the includeFallback method to return fallback-locale content for entries that have no published version in this locale.
Example
Basic usage: return entries in French
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.locale("fr-fr");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Fallback: return French entries, or the fallback version when none exists
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.locale("<LOCALE>").includeFallback();
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle() + " " + entry.getLocale());
}
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}notContainedIn
notContainedIn matches entries whose field value equals none of the values you pass.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to compare. |
| values (required) | Object[] | Values the field must not equal. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. notContainedIn records any field UID and any element types.
- A null key or values puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An empty array is not an error. notContainedIn sends "$nin": [].
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. notContainedIn adds "$nin" with the elements of values to the condition on key and makes no request.
- find sends the condition in the shape the Array Not-equals Operator request describes. The API returns entries whose field value matches no element.
- Consecutive operator calls on one field merge into one condition. A second notContainedIn on the field replaces the array.
- where on the same field replaces the whole condition.
- Conditions on one field follow the rules in Field conditions on the Query class page, including the Known issue for operator calls that move between fields.
Example
Basic usage: leave out entries in two categories
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.notContainedIn("category", new Object[]{"archive", "draft"});
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Numbers: leave out entries with either of two prices
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.notContainedIn("price_in_usd", new Object[]{101, 749});
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}notEqualTo
notEqualTo matches entries whose field value differs from the value you pass.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to compare. |
| value (required) | Object | Value the field must not equal. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. notEqualTo records any field UID and value type.
- A null key or value puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. notEqualTo adds "$ne": value to the condition on key and makes no request.
- find sends the condition in the shape the Not-equals Operator request describes. The API returns entries whose field value does not equal value.
- Consecutive operator calls on one field merge into one condition. A second notEqualTo on the field replaces its value.
- where on the same field replaces the whole condition.
- Conditions on one field follow the rules in Field conditions on the Query class page, including the Known issue for operator calls that move between fields.
- Pass a number, or a date as an ISO 8601 string, as the Not-equals Operator request shows.
Example
Basic usage: leave out entries with one price
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.notEqualTo("price_in_usd", 146);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Combined operators: exclude one value inside a range
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.greaterThan("price_in_usd", 100).notEqualTo("price_in_usd", 146);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}notExists
notExists adds a condition that the field you name does not exist, sent as $exists: false.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to check. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. notExists records any field UID.
- A null key puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. notExists adds "$exists": false to the condition on key and makes no request. find sends it in the query parameter. The Exists request describes the operator.
- Consecutive operator calls on one field merge into one condition. notExists and the exists method write the same $exists key, so the later call wins.
- where on the same field replaces the whole condition.
- Conditions on one field follow the rules in Field conditions on the Query class page, including the Known issue for operator calls that move between fields.
Example
Basic usage: match entries without a price
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.notExists("price_in_usd");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Combined conditions: entries in a category that have no summary
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.where("category", "news").notExists("summary");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}only
only limits each entry in the response to the top-level fields you name.
| Name | Type | Description |
|---|---|---|
| fieldUid (required) | String[] | UIDs of the top-level fields to return. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. only records any field UID.
- A null or empty fieldUid array puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. only adds each field UID to a list and makes no request. find sends one only[BASE][] parameter per field, as the Only Operator request describes.
- Calls add to the list, so only(new String[]{"title"}) followed by only(new String[]{"url"}) asks for both fields.
- Use the onlyWithReferenceUid method to limit the fields of referenced entries.
- Use the except method to name the fields to leave out instead.
Example
Basic usage: return only the title and URL
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.only(new String[]{"title", "url"});
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle() + " " + entry.getURL());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Group field: return one field inside a Group field
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.only(new String[]{"title", "bank_offers.card_type"});
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}onlyWithReferenceUid
onlyWithReferenceUid includes a reference field and limits each referenced entry to the fields you name.
| Name | Type | Description |
|---|---|---|
| fieldUid (required) | ArrayList<String> | UIDs of the referenced entry's fields to return. |
| referenceFieldUid (required) | String | UID of the reference field. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. onlyWithReferenceUid does not check that referenceFieldUid names a reference field.
- A null fieldUid or referenceFieldUid puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An empty fieldUid list is not an error. onlyWithReferenceUid then sends no only parameter for the reference, and still includes the referenced entries.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. onlyWithReferenceUid records the field list for referenceFieldUid and makes no request. find sends one only[<referenceFieldUid>][] parameter per field, as the Only Operator request describes.
- onlyWithReferenceUid also adds referenceFieldUid to the include list, so the response carries the referenced entries without a separate includeReference call.
- A second call for the same reference field replaces its field list. Calls for different reference fields add up.
- Use the only method for top-level fields.
Example
Basic usage: include the author with only the name and email
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.ArrayList;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
ArrayList<String> authorFields = new ArrayList<>();
authorFields.add("name");
authorFields.add("email");
query.onlyWithReferenceUid(authorFields, "author");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle() + " " + entry.getJSONArray("author"));
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Combined projection: top-level fields and referenced fields together
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.ArrayList;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
ArrayList<String> authorFields = new ArrayList<>();
authorFields.add("name");
query.only(new String[]{"title", "author"}).onlyWithReferenceUid(authorFields, "author");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}or
or matches entries that meet the conditions of at least one sub-query you pass.
| Name | Type | Description |
|---|---|---|
| queryObjects (required) | ArrayList<Query> | Sub-queries of which at least one must match. |
Returns: Query. The same query, for chaining.
Validation
- A null or empty queryObjects, or a null element in it, puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- or does not check the error state of each sub-query. A condition that a sub-query dropped because of a null argument is missing from the list, with no error.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. or reads the field conditions of each sub-query and stores them as a list under $or. It makes no request.
- find sends the list in the shape the OR Operator request describes. The API returns entries that satisfy at least one condition in the list.
- or reads only field conditions, from methods such as where and lessThan. It ignores the sort, paging, include, locale, and header settings of each sub-query.
- A sub-query can come from any content type's query(). The SDK never sends a sub-query as a request of its own.
- or keeps a reference to each sub-query's conditions, so a condition that you add to a sub-query before find also goes out.
- A second or call replaces the first list. Conditions you set on the main query with other methods sit next to $or in the same object.
Example
Basic usage: match entries in either of two colors
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.ArrayList;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
Query goldQuery = stack.contentType("<CONTENT_TYPE_UID>").query();
goldQuery.where("color", "Gold");
Query blackQuery = stack.contentType("<CONTENT_TYPE_UID>").query();
blackQuery.where("color", "Black");
ArrayList<Query> conditions = new ArrayList<>();
conditions.add(goldQuery);
conditions.add(blackQuery);
query.or(conditions);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Combined conditions: one category, and either of two authors
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.ArrayList;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
Query firstAuthor = stack.contentType("<CONTENT_TYPE_UID>").query();
firstAuthor.where("author_name", "Jane Doe");
Query secondAuthor = stack.contentType("<CONTENT_TYPE_UID>").query();
secondAuthor.where("author_name", "John Smith");
ArrayList<Query> authors = new ArrayList<>();
authors.add(firstAuthor);
authors.add(secondAuthor);
// The category condition and the $or list both apply
query.where("category", "news").or(authors);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}regex
regex matches entries whose field value fits the regular expression you pass.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to match. |
| regex (required) | String | Regular expression the field value must fit. |
| modifiers | String | Regular expression options, such as i. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. regex does not compile or check the pattern on the device.
- A null key or regex puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- A null modifiers is not an error. The three-argument overload then sends no $options, the same as the two-argument overload.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. regex adds "$regex": regex to the condition on key and makes no request. With modifiers, it also adds "$options": modifiers.
- find sends the condition in the shape the Search by Regex request describes.
- The SDK passes modifiers to the API unchanged.
- Consecutive operator calls on one field merge into one condition. A second regex on the field replaces $regex. An earlier $options stays unless you pass new modifiers. where on the same field replaces the whole condition.
- Conditions on one field follow the rules in Field conditions on the Query class page, including the Known issue for operator calls that move between fields.
- Java needs a double backslash in a string literal, so write the pattern \d as "\\d".
Example
Basic usage: match titles that start with a word
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.regex("title", "^Blue");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}All parameters: match colors that start with bl in any case
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.regex("color", "^bl", "i");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}removeHeader
removeHeader removes a header that you set on this query.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header to remove. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation. An empty or null key, or a key the query does not hold, changes nothing and raises no error.
Behavior
- Client-side only. removeHeader deletes the header from this query and makes no request.
- It removes headers set with setHeader or variants. Headers that come from the stack or the content type stay.
- When the stack holds a header with the same name, the stack value applies again after the removal.
Example
Basic usage: stop sending a variant header
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.variants("<VARIANT_UID>");
// Send the next request without the variant
query.removeHeader("x-cs-variant-uid");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}removeQuery
removeQuery removes one query parameter from the request.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter to remove. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. A null key, or a key the query does not hold, changes nothing and raises no error.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. removeQuery deletes key from the parameter map and makes no request.
- The parameter map holds the keys from addQuery and addParam, and the keys that limit, skip, locale, ascending, and the other parameter methods write. See Request parameters on the Query class page.
- removeQuery does not remove field conditions. Build a new query to drop one.
Example
Basic usage: drop a limit that an earlier call set
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.where("category", "news").limit(5);
// Return to the API default page size
query.removeQuery("limit");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}search
search sends a typeahead search value with the query.
| Name | Type | Description |
|---|---|---|
| value (required) | String | Text to send as the typeahead value. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. search sends an empty string as given.
- A null value puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. search sets the typeahead query parameter to value and makes no request. find sends it with the other parameters.
- A second search replaces the value. See Request parameters on the Query class page.
- search does nothing when value matches the name of a parameter already on the query, such as limit or locale.
- Known issue: The SDK adds the value to the URL without URL encoding. A value that contains &, #, +, or % does not reach the API as written. Encode such a value with URLEncoder.encode(value, "UTF-8") first.
Example
Basic usage: send a typeahead value
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.search("header");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Edge case: encode a value that holds a reserved character
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.net.URLEncoder;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
// URL-encode the value, because the SDK does not
query.search(URLEncoder.encode("salt & pepper", "UTF-8"));
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}setCachePolicy
setCachePolicy sets where find and findOne read their result from: the network, the SDK's disk cache, or both.
| Name | Type | Description |
|---|---|---|
| cachePolicy (required) | CachePolicy | Source of the result for this query. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. null restores the default behavior, CachePolicy.NETWORK_ONLY.
- A cache miss with CACHE_ONLY reaches the callback as an Error with ResponseType.CACHE, and no request goes out.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. setCachePolicy stores the policy on this query and makes no request.
- Each of the six policies below works as follows for a query:
- NETWORK_ONLY (the default for a query): sends the request and saves the response in the cache.
- IGNORE_CACHE: sends the request and saves nothing.
- CACHE_ONLY: reads the cache and sends no request. A missing response, or one older than 24 hours, produces an Error.
- CACHE_ELSE_NETWORK: reads the cache when it holds a response younger than 24 hours, and sends the request otherwise.
- NETWORK_ELSE_CACHE: sends the request while the device reports a connection, and reads the cache otherwise.
- CACHE_THEN_NETWORK: delivers the cached response first, when one exists, then sends the request. The callback fires twice.
- The SDK keys each cached response on the request URL, the parameters, and the headers. A change to any condition or parameter reads a different cache entry.
- Check responseType in the callback to tell a cached result (CACHE) from a network result (NETWORK).
Example
Basic usage: read from the cache, and fall back to the network
import android.util.Log;
import com.contentstack.sdk.CachePolicy;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.setCachePolicy(CachePolicy.CACHE_ELSE_NETWORK);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
Log.d("Contentstack", responseType + ": " + queryResult.getResultObjects().size());
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Edge case: show cached entries first, then fresh ones
import android.util.Log;
import com.contentstack.sdk.CachePolicy;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.setCachePolicy(CachePolicy.CACHE_THEN_NETWORK);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
// The callback fires once with CACHE, when a cached response exists, and once with NETWORK
Log.d("Contentstack", responseType + ": " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}setHeader
setHeader adds a header to the requests of this query.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header. |
| value (required) | String | Value of the header. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation. An empty or null key or value sets nothing, with no error.
Behavior
- Client-side only. setHeader stores the header on this query and makes no request. find and findOne send it.
- A header on the query wins over a header with the same name on the content type or the stack, for this query only.
- A second setHeader with the same key replaces the value.
- Read the headers with the getHeaders method, and remove one with the removeHeader method.
Example
Basic usage: send a custom header with the query
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.setHeader("x-request-source", "android-app");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}skip
skip leaves out the first entries of the result, for pagination.
| Name | Type | Description |
|---|---|---|
| number (required) | int | Number of entries to leave out. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. skip records zero and negative numbers as given.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. skip sets the skip query parameter and makes no request.
- find sends it in the shape the Skip request describes. The API leaves out that many entries from the start of the result.
- A second skip replaces the value.
- Combine skip with the limit and the includeCount methods to read the entries one page at a time, as the Pagination request describes.
- Sort the query with the ascending or the descending method so that each page starts where the previous one ended.
Example
Basic usage: leave out the first ten entries
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.skip(10);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Pagination: request the second page of 25 entries in a stable order
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.ascending("created_at").skip(25).limit(25).includeCount();
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Total: " + queryResult.getCount());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}tags
tags sends a list of tags to match entries against.
| Name | Type | Description |
|---|---|---|
| tags (required) | String[] | Tags to match, one per element. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. tags sends any tag text as given.
- A null tags array puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An empty array is not an error. tags then removes the tags parameter, so find sends none.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. tags joins the array with commas into the tags query parameter and makes no request. find sends it with the other parameters.
- The SDK starts the list with the text null, so tags(new String[]{"featured", "sale"}) sends tags=null,featured,sale.
- A second tags call replaces the list. Pass every tag in one call. See Request parameters on the Query class page.
- Known issue: The SDK adds the value to the URL without URL encoding. A value that contains &, #, +, or % does not reach the API as written. Encode such a value with URLEncoder.encode(value, "UTF-8") first. Encode each tag separately, and keep one tag per array element.
Example
Basic usage: match entries by tag
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.tags(new String[]{"featured", "sale"});
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Combined conditions: tagged entries in one category
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.where("category", "news").tags(new String[]{"breaking"});
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}variants
variants applies one or more entry variants to the entries the query returns, optionally on a branch.
| Name | Type | Description |
|---|---|---|
| variantUid (required) | String | UID or alias of the variant to apply. |
| branch | String | Branch to send this query to. |
| variantUids (required) | String[] | UIDs or aliases of the variants, first has priority. |
Returns: Query. The same query, for chaining.
Overloads
- variants(String variantUid) and variants(String variantUid, String branch)
- variants(String[] variantUids) and variants(String[] variantUids, String branch)
Validation
- variants does not throw and never puts the query in an error state.
- A null or blank variantUid sets no header. In the array overloads, variants skips null and blank elements, and sets no header when none remain.
- A null or blank branch sets no branch header.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. variants trims each UID and sets the x-cs-variant-uid header on this query. The array overloads join the UIDs with a comma and a space. It makes no request.
- find sends the header as the Get multiple variants of an entry request describes. By default the API accepts up to five variant UIDs or aliases, and the first one takes priority.
- The two-argument overloads also set the branch header on this query, which wins over the branch set on the stack.
- A later call replaces the variant header. A call without branch does not remove a branch header from an earlier call.
- Read the headers with the getHeaders method, and remove one with the removeHeader method.
Example
Basic usage: apply one variant
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.variants("<VARIANT_UID>");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Array overload: apply two variants, highest priority first
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
// Replace each <VARIANT_UID> with a different variant UID or alias
query.variants(new String[]{"<VARIANT_UID>", "<VARIANT_UID>"});
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}All parameters: apply variants on a branch
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.variants("<VARIANT_UID>", "<BRANCH>");
Query listQuery = stack.contentType("<CONTENT_TYPE_UID>").query();
listQuery.variants(new String[]{"<VARIANT_UID>", "<VARIANT_UID>"}, "<BRANCH>");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}where
where matches entries whose field equals the value you pass.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the field to match. |
| value (required) | Object | Value the field must equal. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. where records any field UID and value type.
- A null key or value puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. where sets the condition on key to value and makes no request. find sends it in the shape the Equals Operator request describes, for example {"title": "Hello World"}.
- where replaces any condition on the same field, including operators from lessThan or exists. See Field conditions on the Query class page.
- Pass a String, a number, or a Boolean. Pass a date as an ISO 8601 string, as the Equals Operator request shows. org.json writes any other object as the text of its toString().
- Pass a dot path to match a field inside a Group field, as the Equals Operator Within Group request describes.
- Use the containedIn method to match any of several values.
Example
Basic usage: match entries by title
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.where("title", "Hello World");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getUid());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Group field: match a field inside a Group field
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
query.where("bank_offers.card_type", "Debit Card");
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}whereIn
whereIn matches entries whose referenced entries meet the conditions of a sub-query.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the reference field. |
| queryObject (required) | Query | Conditions on the referenced entries. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. whereIn does not check that key names a reference field.
- A null key or queryObject puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereIn sets the condition on key to {"$in_query": ...} with the field conditions of queryObject, and makes no request. It replaces any condition on that field.
- find sends the condition in the query parameter. The Reference Search Equals request describes the operator, and the API returns entries whose referenced entries satisfy the sub-query.
- The SDK writes the sub-query's conditions as a JSON string inside $in_query, not as a nested JSON object.
- whereIn reads only the field conditions of queryObject. Its sort, paging, include, and locale settings do not apply.
- When the reference field can point to more than one content type, add a _content_type_uid condition to the sub-query, as the Reference Search Equals request describes.
Example
Basic usage: match products whose brand has a given title
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
Query brandQuery = stack.contentType("<CONTENT_TYPE_UID>").query();
brandQuery.where("title", "Apple Inc.");
query.whereIn("brand", brandQuery);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Multiple content types: name the referenced content type
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
Query brandQuery = stack.contentType("<CONTENT_TYPE_UID>").query();
brandQuery.where("title", "Apple Inc.").where("_content_type_uid", "brand");
query.whereIn("brand", brandQuery);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}whereNotIn
whereNotIn matches entries whose referenced entries do not meet the conditions of a sub-query.
| Name | Type | Description |
|---|---|---|
| key (required) | String | UID of the reference field. |
| queryObject (required) | Query | Conditions on the referenced entries. |
Returns: Query. The same query, for chaining.
Validation
- There is no client-side validation. whereNotIn does not check that key names a reference field.
- A null key or queryObject puts the query in an error state instead of throwing. The next find or findOne sends no request, and its callback receives an Error with ResponseType.UNKNOWN. See Error state on the Query class page.
- An invalid value surfaces as an Error in the callback when find (or findOne) sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. whereNotIn sets the condition on key to {"$nin_query": ...} with the field conditions of queryObject, and makes no request. It replaces any condition on that field.
- find sends the condition in the query parameter. The Reference Search Not-equals request describes the operator, and the API returns entries whose referenced entries do not satisfy the sub-query.
- The SDK writes the sub-query's conditions as a JSON string inside $nin_query, not as a nested JSON object.
- whereNotIn reads only the field conditions of queryObject. Its sort, paging, include, and locale settings do not apply.
- When the reference field can point to more than one content type, add a _content_type_uid condition to the sub-query, as the Reference Search Not-equals request describes.
Example
Basic usage: match products whose brand has a different title
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
Query brandQuery = stack.contentType("<CONTENT_TYPE_UID>").query();
brandQuery.where("title", "Apple Inc.");
query.whereNotIn("brand", brandQuery);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error == null) {
for (Entry entry : queryResult.getResultObjects()) {
Log.d("Contentstack", entry.getTitle());
}
} else {
// The API rejected the request, the network failed, or the query is in an error state
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Multiple content types: name the referenced content type
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
Query brandQuery = stack.contentType("<CONTENT_TYPE_UID>").query();
brandQuery.where("title", "Apple Inc.").where("_content_type_uid", "brand");
query.whereNotIn("brand", brandQuery);
query.find(new QueryResultsCallBack() {
@Override
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Matches: " + queryResult.getResultObjects().size());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}