Query

View as Markdown

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.

NameTypeDescription
key (required)String

Name of the query parameter.

Default: Not applicable
value (required)String

Value of the query parameter.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the query parameter.

Default: Not applicable
value (required)String

Value of the query parameter.

Default: Not applicable

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.

NameTypeDescription
queryObjects (required)ArrayList<Query>

Sub-queries whose conditions must all match.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to sort by.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to compare.

Default: Not applicable
values (required)Object[]

Values the field may equal.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to sort by.

Default: Not applicable

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.

NameTypeDescription
fieldUid (required)ArrayList<String>

UIDs of the top-level fields to leave out.

Default: Not applicable
fieldUids (required)String[]

UIDs of the top-level fields to leave out.

Default: Not applicable

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.

NameTypeDescription
fieldUid (required)ArrayList<String>

UIDs of the referenced entry's fields to leave out.

Default: Not applicable
referenceFieldUid (required)String

UID of the reference field.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to check.

Default: Not applicable

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.

NameTypeDescription
callback (required)QueryResultsCallBack

Receives the matching entries or the error.

Default: Not applicable

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.

NameTypeDescription
callBack (required)SingleQueryResultCallback

Receives the first matching entry or the error.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to compare.

Default: Not applicable
value (required)Object

Lower bound, not included.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to compare.

Default: Not applicable
value (required)Object

Lower bound, included.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the reference field to include.

Default: Not applicable
keys (required)String[]

UIDs of the reference fields to include.

Default: Not applicable

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.

NameTypeDescription
language (required)Language

Enum value of the locale to return.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to compare.

Default: Not applicable
value (required)Object

Upper bound, not included.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to compare.

Default: Not applicable
value (required)Object

Upper bound, included.

Default: Not applicable

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.

NameTypeDescription
number (required)int

Maximum number of entries to return.

Default: Not applicable

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.

NameTypeDescription
locale (required)String

Locale code of the entries, such as fr-fr.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to compare.

Default: Not applicable
values (required)Object[]

Values the field must not equal.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to compare.

Default: Not applicable
value (required)Object

Value the field must not equal.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to check.

Default: Not applicable

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.

NameTypeDescription
fieldUid (required)String[]

UIDs of the top-level fields to return.

Default: Not applicable

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.

NameTypeDescription
fieldUid (required)ArrayList<String>

UIDs of the referenced entry's fields to return.

Default: Not applicable
referenceFieldUid (required)String

UID of the reference field.

Default: Not applicable

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.

NameTypeDescription
queryObjects (required)ArrayList<Query>

Sub-queries of which at least one must match.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to match.

Default: Not applicable
regex (required)String

Regular expression the field value must fit.

Default: Not applicable
modifiersString

Regular expression options, such as i.

Default: Not sent (the two-argument overload sends no $options)

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.

NameTypeDescription
key (required)String

Name of the header to remove.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the query parameter to remove.

Default: Not applicable

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 sends a typeahead search value with the query.

NameTypeDescription
value (required)String

Text to send as the typeahead value.

Default: Not applicable

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.

NameTypeDescription
cachePolicy (required)CachePolicy

Source of the result for this query.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the header.

Default: Not applicable
value (required)String

Value of the header.

Default: Not applicable

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.

NameTypeDescription
number (required)int

Number of entries to leave out.

Default: Not applicable

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.

NameTypeDescription
tags (required)String[]

Tags to match, one per element.

Default: Not applicable

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.

NameTypeDescription
variantUid (required)String

UID or alias of the variant to apply.

Default: Not applicable
branchString

Branch to send this query to.

Default: Not sent (the stack's branch header applies)
variantUids (required)String[]

UIDs or aliases of the variants, first has priority.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the field to match.

Default: Not applicable
value (required)Object

Value the field must equal.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the reference field.

Default: Not applicable
queryObject (required)Query

Conditions on the referenced entries.

Default: Not applicable

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.

NameTypeDescription
key (required)String

UID of the reference field.

Default: Not applicable
queryObject (required)Query

Conditions on the referenced entries.

Default: Not applicable

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());
}