Query

A Query finds the published entries of one content type that match a set of conditions. Use this class to

match entries by field value, by regular expression, or by the fields of referenced entries
sort, page and count the matching entries
choose which fields and references each entry carries
read entries in a locale, with fallback, or as entry variants

Query has no public constructor. Call stack.contentType("<CONTENT_TYPE_UID>").query() to get one. Each method below records a condition or a parameter and returns the same Query. The find and findOne methods then send one request to Get all entries and hand the result to your callback. A successful find delivers a QueryResult.

addParam

addParam adds one query parameter to the request.

Name	Type	Description
key (required)	String	Query parameter name. Default: Not applicable
value (required)	String	Query parameter value. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

addParam checks the key and the value before it records them.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
The addQuery method applies the same check but skips the call instead.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. addParam records the parameter and makes no request.
It writes to the same parameter store as addQuery, locale, limit and the other parameter methods. A key that one of them already set gets the new value.
Use it for a parameter that has no method of its own, such as include_all from the Include all references request.
The removeQuery method deletes the parameter again.

Example

Include every referenced entry three levels deep

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;

public class IncludeAllReferencesDeep {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.addParam("include_all", "true");
        query.addParam("include_all_depth", "3");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

addQuery

addQuery adds one query parameter to the request.

Name	Type	Description
key (required)	String	Query parameter name. Default: Not applicable
value (required)	String	Query parameter value. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

addQuery checks the key and the value with the rules under Input checks on the Query class page.
A rejected key or value, or a null value, makes addQuery skip the call without a warning. The rest of the query still runs. The addParam method stops the whole query instead.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. addQuery records the parameter and makes no request.
It writes to the same parameter store as addParam, locale, limit and the other parameter methods. A key that one of them already set gets the new value.
Use it for a parameter that has no method of its own, such as include_all and include_all_depth from the Include all references request.
The removeQuery method deletes the parameter again.

Example

Include every referenced entry two levels deep

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;

public class IncludeAllReferences {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.addQuery("include_all", "true");
        query.addQuery("include_all_depth", "2");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

and

and matches entries that satisfy every condition in a list of queries.

Name	Type	Description
queryObjects (required)	List<Query>	Queries whose conditions must all match. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

An empty list stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null list throws NullPointerException at the call.
Known issue: In 2.8.3, a condition that a subquery rejected is missing from the list, and the main query still runs. It then matches more entries than you intended. Before you build the subquery, check each field UID and value against Input checks on the Query class page. A field UID may contain only ASCII letters, digits, underscores and periods. A String value may also contain hyphens and whitespace.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. and reads the conditions of each query in the list and records them under $and and makes no request.
find sends them in the query parameter, in the shape the AND Operator request describes.
and reads conditions only, such as those from where and lessThan. It ignores the parameters of each subquery, such as locale or limit.
and keeps a reference to each subquery's conditions, so a condition you add to a subquery before find runs also goes out.
A second and call replaces the first $and list.
Build each subquery with stack.contentType("<CONTENT_TYPE_UID>").query(). The SDK does not read the content type of a subquery.

Example

Match entries that meet two conditions

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.Arrays;

public class FindWithAnd {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        Query titleQuery = stack.contentType("<CONTENT_TYPE_UID>").query().where("title", "Hello World");
        Query priceQuery = stack.contentType("<CONTENT_TYPE_UID>").query().lessThan("price", 100);
        query.and(Arrays.asList(titleQuery, priceQuery));

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

ascending

ascending sorts the entries by a field, lowest value first.

Name	Type	Description
key (required)	String	Field UID to sort by. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

ascending checks the key before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. ascending records the field UID in the asc parameter and makes no request.
find sends it as the Order by asc request describes.
Name a field inside a Modular Blocks field as modular_block_uid.block_uid.field_uid.
A second call replaces the first. The SDK sorts by one field per direction.
The descending method sets the desc parameter. Calling both sends both parameters.

Example

Sort entries by price, lowest first

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;

public class SortByPriceAscending {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.ascending("price");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

assetFields

assetFields asks for extra field groups of the assets embedded in the entries.

Name	Type	Description
fields (required)	String...	Asset field groups, such as visual_markups. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

There is no client-side validation. assetFields ignores a call with no arguments or a null array.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. assetFields records the values in the asset_fields[] list and makes no request.
find sends one asset_fields[] parameter per value to Get all entries. The API reference names visual_markups, which returns the hotspot and bounding-box annotations of each embedded asset.
A second call replaces the first list.

Example

Return the visual markups of embedded assets

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;

public class IncludeVisualMarkups {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.assetFields("visual_markups");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

containedIn

containedIn matches entries whose field equals any value in a list.

Name	Type	Description
key (required)	String	Field UID to match. Default: Not applicable
values (required)	Object[]	Values the field may equal. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

containedIn checks the key and each String in the array before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key or a null array throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. containedIn records {"<key>": {"$in": [<values>]}} in the condition store and makes no request.
find sends it in the query parameter, in the shape the Array Equals Operator request describes.
A second call on the same field replaces the list. Put every value in one call.
An empty array passes the check and records an empty list.
Known issue: In 2.8.3, the operator methods share one condition object across fields, so an operator added to a field after you move on to another field can overwrite that other field's condition. Chain every operator condition on one field next to each other, before you add a condition on another field.

Example

Match entries with one of several colors

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;

public class FindByColors {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.containedIn("color", new Object[] {"red", "blue"});

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Match entries with one of several prices

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;

public class FindByPrices {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.containedIn("price", new Object[] {101, 749});

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

count

count asks for the number of matching entries instead of the entries.

Returns: Query. The same query, for chaining.

Validation

There is no client-side validation.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. count sets the count parameter to true and makes no request.
find sends it as the Count request describes.
Read the number with the getCount method of QueryResult. The getResultObjects method returns an empty list, because the response holds no entries.
To get the entries and the total in one request, use the includeCount method instead.

Example

Count the entries that match a condition

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;

public class CountEntries {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println("matching entries: " + queryResult.getCount());
            }
        });
    }
}

descending

descending sorts the entries by a field, highest value first.

Name	Type	Description
key (required)	String	Field UID to sort by. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

descending checks the key before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. descending records the field UID in the desc parameter and makes no request.
find sends it as the Order by desc request describes.
A second call replaces the first. The SDK sorts by one field per direction.
The ascending method sets the asc parameter. Calling both sends both parameters.

Example

Sort entries by creation date, newest first

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;

public class SortByNewest {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.descending("created_at");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

except

except leaves the given fields out of each entry in the response.

Name	Type	Description
fieldUid (required)	List<String>	Field UIDs to leave out. Default: Not applicable
fieldIds (required)	String[]	Field UIDs to leave out. Default: Not applicable

Returns: Query. The same query, for chaining.

Overloads

except(List<String> fieldUid)
except(String[] fieldIds)

Validation

There is no client-side validation. except ignores an empty list or array.
A null argument throws NullPointerException at the call.
An invalid field UID comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. except adds the field UIDs to the except[BASE][] list and makes no request.
find sends one except[BASE][] parameter per field, as the Exclude operator request describes.
Calls add up, and both overloads write to the same list.
To leave out fields of a referenced entry, use the exceptWithReferenceUid method.
On a query that already ran, the next except call starts a new list, and find then sends only the new list.

Example

Leave out two fields with a list

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.Arrays;

public class ExceptWithList {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.except(Arrays.asList("body", "seo"));

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Leave out one field with an array

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;

public class ExceptWithArray {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.except(new String[] {"body"});

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

exceptWithReferenceUid

exceptWithReferenceUid leaves the given fields out of the entries a reference field points to.

Name	Type	Description
fieldUid (required)	List<String>	Fields to leave out of the referenced entries. Default: Not applicable
referenceFieldUid (required)	String	Reference field that holds those entries. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

exceptWithReferenceUid checks referenceFieldUid with the value rules under Input checks on the Query class page. It does not check fieldUid.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null argument throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find 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 the reference field and makes no request.
find sends one except[<referenceFieldUid>][] parameter per field, as the Exclude operator request describes.
It also adds the reference field to the include[] list, so you do not need the includeReference method for that field.
A second call for the same reference field replaces its field list.

Example

Leave the biography out of each referenced author

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.Arrays;

public class ExceptAuthorFields {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.exceptWithReferenceUid(Arrays.asList("biography"), "author");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getTitle() + " by " + entry.get("author"));
                }
            }
        });
    }
}

exists

exists matches entries that carry a value for a field.

Name	Type	Description
key (required)	String	Field UID that must exist. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

exists checks the key before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. exists records {"<key>": {"$exists": true}} in the condition store and makes no request.
find sends it in the query parameter, in the shape the Exists request describes.
The notExists method records the opposite condition.
Known issue: In 2.8.3, the operator methods share one condition object across fields, so an operator added to a field after you move on to another field can overwrite that other field's condition. Chain every operator condition on one field next to each other, before you add a condition on another field.

Example

Match entries that have a price

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;

public class FindWithPrice {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.exists("price");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

find

find sends the query and returns the matching entries in the callback.

Name	Type	Description
callback (required)	QueryResultsCallBack	Receives the result or an error. See Callbacks. Default: Not applicable

Returns: Query. The same query. The result arrives in the callback.

Validation

find sends no request and never calls the callback in two cases:
- an earlier method on this query rejected its input (see Input checks on the Query class page)
- the content type UID is an empty string
find does not throw for an API rejection or a network failure. The callback receives an Error, and queryresult is null.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

find sends one request to Get all entries for the content type of the query.
The call is synchronous. The callback runs before find returns.
find sends the conditions as JSON in the query parameter, the environment of the stack in the environment parameter, and every parameter the other methods recorded.
On success, the callback receives a QueryResult with the matching entries.
The SDK does not request further pages. Without limit, the API returns its default of 100 entries. See Pagination on the Query class page.
The query keeps its conditions and parameters after find returns. A second find sends the same request again.
Known issue: With live preview turned on through the enableLivePreview method of Config, find throws NullPointerException until livePreviewQuery has run once on the stack. Call livePreviewQuery before any query, or turn live preview on only for a stack that serves previews.

Example

Find entries that match a condition

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;

public class FindEntries {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.where("category", "news");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Filter, sort and page in one request

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;

public class FindLatestNews {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.where("category", "news")
            .descending("created_at")
            .limit(10)
            .includeCount();

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                System.out.println("total: " + queryResult.getCount());
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Edge case: detect a query that never ran

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;

public class DetectSkippedQuery {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        // The @ sign fails the value check, so find sends no request
        query.where("email", "[email protected]");
        final boolean[] called = {false};

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                called[0] = true;
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                System.out.println("entries: " + queryResult.getResultObjects().size());
            }
        });

        // find runs synchronously, so the flag is final once find returns
        if (!called[0]) {
            System.out.println("The SDK rejected a query value and sent no request.");
        }
    }
}

findOne

findOne sends the query and returns the first matching entry in the callback.

Name	Type	Description
callBack (required)	SingleQueryResultCallback	Receives the entry or an error. See Callbacks. Default: Not applicable

Returns: Query. The same query. The result arrives in the callback.

Validation

findOne sends no request and never calls the callback in two cases:
- an earlier method on this query rejected its input (see Input checks on the Query class page)
- the content type UID is an empty string
findOne does not throw for an API rejection or a network failure. The callback receives an Error, and entry is null.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

findOne sends one request to Get all entries with limit set to 1. The call is synchronous.
Combine it with ascending or descending to choose which entry comes first.
When no entry matches, the callback receives an empty Entry, not null. Its getUid() returns null.
After the request, findOne restores the limit you set with limit. When you set none, the query keeps a limit of 1, so a later find on the same query returns one entry. Use a new query for find, or call the removeQuery method with limit.
Known issue: With live preview turned on through the enableLivePreview method of Config, findOne throws NullPointerException until livePreviewQuery has run once on the stack. Call livePreviewQuery before any query, or turn live preview on only for a stack that serves previews.

Example

Find the entry with a given title

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;

public class FindOneByTitle {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.where("title", "About Us");

        query.findOne(new SingleQueryResultCallback() {
            @Override
            public void onCompletion(ResponseType responseType, Entry entry, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getUid() + " " + entry.getTitle());
            }
        });
    }
}

Edge case: no entry matches

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;

public class FindOneNoMatch {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.where("title", "Missing Page");

        query.findOne(new SingleQueryResultCallback() {
            @Override
            public void onCompletion(ResponseType responseType, Entry entry, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                // The SDK passes an empty Entry when nothing matches
                if (entry.getUid() == null) {
                    System.out.println("No entry matched.");
                    return;
                }
                System.out.println(entry.getTitle());
            }
        });
    }
}

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 reads a value the query already holds.

Additional Resource Get all entries describes the content_type_uid path parameter this UID fills.

Behavior

Client-side only. getContentType returns the UID you passed to stack.contentType and makes no request.
The SDK does not check that the content type exists. A wrong UID shows up only when find runs.
To read the content type schema from a response, use the getContentType method of QueryResult instead.

Example

Read the content type UID of a query

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.Stack;

public class ReadQueryContentType {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();

        System.out.println(query.getContentType());
    }
}

greaterThan

greaterThan matches entries whose field is greater than a value.

Name	Type	Description
key (required)	String	Field UID to compare. Default: Not applicable
value (required)	Object	Value to compare the field against. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

greaterThan checks the key and a String value before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. greaterThan records {"<key>": {"$gt": <value>}} in the condition store and makes no request.
find sends it in the query parameter, in the shape the Greater Than request describes.
Name a field inside a Group field as group_uid.field_uid.
A date-time string such as 2024-01-31T00:00:00.000Z contains colons, so the check rejects it and the query stops. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
Known issue: In 2.8.3, the operator methods share one condition object across fields, so an operator added to a field after you move on to another field can overwrite that other field's condition. Chain every operator condition on one field next to each other, before you add a condition on another field.

Example

Match entries by a number field

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;

public class FindPricierThan {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.greaterThan("price", 100);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Match a range on one field

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;

public class FindPricierThanInRange {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.greaterThan("price", 100).lessThan("price", 500);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

greaterThanOrEqualTo

greaterThanOrEqualTo matches entries whose field is greater than or equal to a value.

Name	Type	Description
key (required)	String	Field UID to compare. Default: Not applicable
value (required)	Object	Value to compare the field against. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

greaterThanOrEqualTo checks the key and a String value before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. greaterThanOrEqualTo records {"<key>": {"$gte": <value>}} in the condition store and makes no request.
find sends it in the query parameter, in the shape the Greater Than or Equal To request describes.
Name a field inside a Group field as group_uid.field_uid.
A date-time string such as 2024-01-31T00:00:00.000Z contains colons, so the check rejects it and the query stops. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
Known issue: In 2.8.3, the operator methods share one condition object across fields, so an operator added to a field after you move on to another field can overwrite that other field's condition. Chain every operator condition on one field next to each other, before you add a condition on another field.

Example

Match entries by a number field

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;

public class FindAtLeast {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.greaterThanOrEqualTo("rating", 4);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Match a range on one field

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;

public class FindAtLeastInRange {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.greaterThanOrEqualTo("rating", 4).lessThanOrEqualTo("rating", 5);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

includeBranch

includeBranch adds the branch the entries belong to to the response.

Returns: Query. The same query, for chaining.

Validation

There is no client-side validation.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. includeBranch sets the include_branch parameter to true and makes no request.
find sends it to Get all entries, which then adds the _branch key with the unique ID of the branch.
QueryResult has no method for other top-level response keys. Each entry returns its own JSON through toJSON().

Example

Return entries with their branch

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;

public class IncludeBranch {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.includeBranch();

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.toJSON());
                }
            }
        });
    }
}

includeContentType

includeContentType adds the content type of the entries to the response.

Returns: Query. The same query, for chaining.

Validation

There is no client-side validation.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. includeContentType sets the include_content_type and include_global_field_schema parameters to true and makes no request.
It also deletes an include_schema parameter that the addQuery or the addParam method set.
find and findOne send it to Get all entries.
Read the content type with the getContentType method of QueryResult. Without includeContentType, it returns null.

Example

Read the content type title and schema with the entries

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;

public class IncludeContentType {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                JSONObject contentType = queryResult.getContentType();
                if (contentType != null) {
                    System.out.println(contentType.optString("title"));
                    System.out.println(contentType.optJSONArray("schema"));
                }
            }
        });
    }
}

includeCount

includeCount adds the total number of matching entries to the response, alongside the entries.

Returns: Query. The same query, for chaining.

Validation

There is no client-side validation.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. includeCount sets the include_count parameter to true and makes no request.
find sends it as the Count request describes.
Read the total with the getCount method of QueryResult. Without includeCount or count, getCount returns 0.
The total counts every matching entry, not only the page that limit and skip select. Compare it with the page size to see whether more pages remain, as the Pagination request describes.

Example

Read the first page and the total

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;

public class FirstPageWithTotal {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println("total: " + queryResult.getCount());
                System.out.println("on this page: " + queryResult.getResultObjects().size());
            }
        });
    }
}

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.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. includeEmbeddedItems sets the include_embedded_items[] parameter to BASE and makes no request.
find sends it as the Get information on embedded RTE objects request describes. The API puts the items under the _embedded_items key of each entry.
BASE returns the first level of embedded items only. The SDK has no method for RECURSIVE, and the key check of addQuery and addParam rejects the brackets in include_embedded_items[].

Example

Return the items embedded in rich text

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;

public class IncludeEmbeddedItems {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.get("_embedded_items"));
                }
            }
        });
    }
}

includeFallback

includeFallback returns the fallback-locale version of entries not published in the requested locale.

Returns: Query. The same query, for chaining.

Validation

There is no client-side validation.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. includeFallback sets the include_fallback parameter to true and makes no request.
find sends it to Get all entries, which then includes the published content of the fallback locale when the requested locale has none.
Use it with the locale method.

Example

Return French entries with fallback

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;

public class FrenchWithFallback {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

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.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. includeMetadata sets the include_metadata parameter to true and makes no request.
find sends it to Get all entries, which puts the metadata under the _metadata key of each entry.

Example

Return entries with their metadata

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;

public class IncludeMetadata {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.get("_metadata"));
                }
            }
        });
    }
}

includeReference

includeReference adds the content of the entries a reference field points to.

Name	Type	Description
key (required)	String	Reference field UID to resolve. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

includeReference checks the key before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. includeReference adds the field UID to the include[] list and makes no request.
find sends one include[] parameter per field, as the Include Reference request describes. Without it, the API returns only the UIDs of the referenced entries.
Calls add up. Call includeReference once per reference field.
Name a reference field inside a Group field as group_uid.reference_uid, as the Include Reference Within Group request shows.
On a query that already ran, the next includeReference call starts a new list, and find then sends only the new list. Call it again for every reference you still need.
To resolve every reference field without naming them, use the addQuery method with include_all.

Example

Include the entries of one reference field

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;

public class IncludeAuthor {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.includeReference("author");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getTitle() + " by " + entry.get("author"));
                }
            }
        });
    }
}

Include two reference fields

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;

public class IncludeAuthorAndCategories {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.includeReference("author").includeReference("categories");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

includeReferenceContentTypUid

includeReferenceContentTypUid adds the content type UID of each referenced entry to the response.

Returns: Query. The same query, for chaining.

Validation

There is no client-side validation.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. includeReferenceContentTypUid sets the include_reference_content_type_uid parameter to true and makes no request.
find and findOne send it to Get all entries.
The SDK spells the method name includeReferenceContentTypUid, without the e in Type. Call it with that spelling.
Use it with the includeReference method, which brings the referenced entries into the response.

Example

Include an author reference with its content type UID

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;

public class IncludeReferenceTypes {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.includeReference("author").includeReferenceContentTypUid();

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.get("author"));
                }
            }
        });
    }
}

lessThan

lessThan matches entries whose field is less than a value.

Name	Type	Description
key (required)	String	Field UID to compare. Default: Not applicable
value (required)	Object	Value to compare the field against. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

lessThan checks the key and a String value before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. lessThan records {"<key>": {"$lt": <value>}} in the condition store and makes no request.
find sends it in the query parameter, in the shape the Less Than request describes.
Name a field inside a Group field as group_uid.field_uid.
A date-time string such as 2024-01-31T00:00:00.000Z contains colons, so the check rejects it and the query stops. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
Known issue: In 2.8.3, the operator methods share one condition object across fields, so an operator added to a field after you move on to another field can overwrite that other field's condition. Chain every operator condition on one field next to each other, before you add a condition on another field.

Example

Match entries by a number field

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;

public class FindCheaperThan {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.lessThan("price", 100);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Match a range on one field

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;

public class FindCheaperThanInRange {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.greaterThan("price", 10).lessThan("price", 100);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

lessThanOrEqualTo

lessThanOrEqualTo matches entries whose field is less than or equal to a value.

Name	Type	Description
key (required)	String	Field UID to compare. Default: Not applicable
value (required)	Object	Value to compare the field against. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

lessThanOrEqualTo checks the key and a String value before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. lessThanOrEqualTo records {"<key>": {"$lte": <value>}} in the condition store and makes no request.
find sends it in the query parameter, in the shape the Less Than or Equal To request describes.
Name a field inside a Group field as group_uid.field_uid.
A date-time string such as 2024-01-31T00:00:00.000Z contains colons, so the check rejects it and the query stops. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
Known issue: In 2.8.3, the operator methods share one condition object across fields, so an operator added to a field after you move on to another field can overwrite that other field's condition. Chain every operator condition on one field next to each other, before you add a condition on another field.

Example

Match entries by a number field

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;

public class FindAtMost {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.lessThanOrEqualTo("price", 100);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Match a range on one field

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;

public class FindAtMostInRange {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.greaterThanOrEqualTo("price", 10).lessThanOrEqualTo("price", 100);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

limit

limit caps the number of entries the query returns.

Name	Type	Description
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 or a negative number as given.
The API accepts positive integers only. For limit=0 it returns its default number of entries, as the Limit request notes.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. limit records the limit parameter and makes no request.
find sends it as the Limit request describes.
Without limit, the SDK sends no limit and the API returns its default of 100 entries, as the Pagination request describes.
A second call replaces the first.
findOne sends a limit of 1 for its own request. See that method for what happens to your limit.

Example

Return at most five entries

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;

public class FindFive {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

locale

locale sets the language of the entries the query returns.

Name	Type	Description
locale (required)	String	Locale code, such as fr-fr. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

There is no client-side validation.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. locale records the locale parameter and makes no request.
find sends it to Get all entries, which returns only the entries published in that locale.
Without locale, the SDK sends no locale parameter and the API applies its own default.
Add the includeFallback method to get the fallback-locale version of entries not published in this locale.
A second call replaces the first.

Example

Return entries in French

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;

public class FindInFrench {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Return entries in a locale with fallback

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;

public class FindWithFallback {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

notContainedIn

notContainedIn matches entries whose field equals none of the values in a list.

Name	Type	Description
key (required)	String	Field UID to match. Default: Not applicable
values (required)	Object[]	Values the field must not equal. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

notContainedIn checks the key and each String in the array before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key or a null array throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. notContainedIn records {"<key>": {"$nin": [<values>]}} in the condition store and makes no request.
find sends it in the query parameter, in the shape the Array Not-equals Operator request describes.
A second call on the same field replaces the list. Put every value in one call.
Known issue: In 2.8.3, the operator methods share one condition object across fields, so an operator added to a field after you move on to another field can overwrite that other field's condition. Chain every operator condition on one field next to each other, before you add a condition on another field.

Example

Leave out entries with some colors

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;

public class FindExceptColors {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.notContainedIn("color", new Object[] {"red", "blue"});

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

notEqualTo

notEqualTo matches entries whose field does not equal a value.

Name	Type	Description
key (required)	String	Field UID 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

notEqualTo checks the key and a String value before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. notEqualTo records {"<key>": {"$ne": <value>}} in the condition store and makes no request.
find sends it in the query parameter, in the shape the Not-equals Operator request describes.
Name a field inside a Group field as group_uid.field_uid.
Known issue: In 2.8.3, the operator methods share one condition object across fields, so an operator added to a field after you move on to another field can overwrite that other field's condition. Chain every operator condition on one field next to each other, before you add a condition on another field.

Example

Leave out entries with one category

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;

public class FindNotArchived {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.notEqualTo("category", "archived");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

notExists

notExists matches entries that carry no value for a field.

Name	Type	Description
key (required)	String	Field UID that must not exist. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

notExists checks the key before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. notExists records {"<key>": {"$exists": false}} in the condition store and makes no request.
find sends it in the query parameter. The Exists request describes the $exists operator.
The exists method records the opposite condition.
Known issue: In 2.8.3, the operator methods share one condition object across fields, so an operator added to a field after you move on to another field can overwrite that other field's condition. Chain every operator condition on one field next to each other, before you add a condition on another field.

Example

Match entries that have no price

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;

public class FindWithoutPrice {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.notExists("price");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

only

only keeps only the given fields in each entry in the response.

Name	Type	Description
fieldUid (required)	String[]	Field UIDs to keep. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

There is no client-side validation. only ignores an empty array.
A null array throws NullPointerException at the call.
An invalid field UID comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. only adds the field UIDs to the only[BASE][] list and makes no request.
find sends one only[BASE][] parameter per field, as the Only operator request describes.
Calls add up.
To keep fields of a referenced entry, use the onlyWithReferenceUid method.
On a query that already ran, the next only call starts a new list, and find then sends only the new list.

Example

Keep only the title and URL of each entry

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;

public class OnlyTitleAndUrl {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getTitle() + " " + entry.getURL());
                }
            }
        });
    }
}

onlyWithReferenceUid

onlyWithReferenceUid keeps only the given fields in the entries a reference field points to.

Name	Type	Description
fieldUid (required)	List<String>	Fields to keep in the referenced entries. Default: Not applicable
referenceFieldUid (required)	String	Reference field that holds those entries. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

onlyWithReferenceUid checks referenceFieldUid with the value rules under Input checks on the Query class page. It does not check fieldUid.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null argument throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find 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 the reference field and makes no request.
find sends one only[<referenceFieldUid>][] parameter per field, as the Only operator request describes.
It also adds the reference field to the include[] list, so you do not need the includeReference method for that field.
A second call for the same reference field replaces its field list.

Example

Keep the title and URL of each referenced author

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.Arrays;

public class OnlyAuthorFields {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.onlyWithReferenceUid(Arrays.asList("title", "url"), "author");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getTitle() + " by " + entry.get("author"));
                }
            }
        });
    }
}

or

or matches entries that satisfy at least one condition in a list of queries.

Name	Type	Description
queryObjects (required)	List<Query>	Queries of which at least one must match. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

or skips the call without a warning when the list is null or empty. The rest of the query still runs.
Known issue: In 2.8.3, a condition that a subquery rejected is missing from the list, and the main query still runs. A subquery left with no condition matches every entry, so the whole $or matches every entry. Before you build the subquery, check each field UID and value against Input checks on the Query class page. A field UID may contain only ASCII letters, digits, underscores and periods. A String value may also contain hyphens and whitespace.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. or reads the conditions of each query in the list and records them under $or and makes no request.
find sends them in the query parameter, in the shape the OR Operator request describes.
or reads conditions only, such as those from where. It ignores the parameters of each subquery, such as locale or limit.
A second or call replaces the first $or list.
Build each subquery with stack.contentType("<CONTENT_TYPE_UID>").query(). The SDK does not read the content type of a subquery.

Example

Match entries with either of two titles

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.Arrays;

public class FindWithOr {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        Query first = stack.contentType("<CONTENT_TYPE_UID>").query().where("title", "Hello World");
        Query second = stack.contentType("<CONTENT_TYPE_UID>").query().where("title", "Getting Started");
        query.or(Arrays.asList(first, second));

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

regex

regex matches entries whose field value matches a regular expression.

Name	Type	Description
key (required)	String	Field UID to match. Default: Not applicable
regex (required)	String	Regular expression the value must match. Default: Not applicable
modifiers (required)	String	Regex options, such as i. Pass null for none. Default: Not applicable

Returns: Query. The same query, for chaining.

Overloads

regex(String key, String regex)
regex(String key, String regex, String modifiers)

Validation

The two-argument overload checks the key, and checks the pattern with the value rules under Input checks on the Query class page.
Known issue: In 2.8.3, the value rules reject most regular expression syntax, such as ^, $, *, 1 never calls your callback. Use the three-argument overload, with null for modifiers` if you need no options.
The three-argument overload checks nothing.
A pattern the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. regex records {"<key>": {"$regex": "<regex>"}} in the condition store and makes no request.
The three-argument overload also records "$options": "<modifiers>" when modifiers is not null. The SDK documents i for case-insensitive matching, m for dot matching newlines and x for ignoring whitespace.
find sends the condition in the query parameter, in the shape the Search by Regex request describes.
Known issue: In 2.8.3, the operator methods share one condition object across fields, so an operator added to a field after you move on to another field can overwrite that other field's condition. Chain every operator condition on one field next to each other, before you add a condition on another field.

Example

Match titles that start with a word, in any case

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;

public class FindTitlesStartingWith {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.regex("title", "^hello", "i");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Match titles that contain a plain word

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;

public class FindTitlesContaining {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        // A pattern of letters only passes the check of the two-argument overload
        query.regex("title", "sale");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Edge case: anchor a pattern with no options

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;

public class FindExactTitle {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        // The three-argument overload skips the check, so ^ and $ are allowed
        query.regex("title", "^Hello World$", null);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

removeHeader

removeHeader deletes a header from the requests the stack sends.

Name	Type	Description
key (required)	String	Name of the header to remove. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

There is no format check. removeHeader ignores the call when key is an empty string.
A null key throws NullPointerException at the call.
Removing a header that the map does not hold does nothing.

Additional Resource Get all entries lists the headers the Content Delivery API reads on this request.

Behavior

Client-side only. removeHeader deletes the header from the header map that the Stack owns and makes no request.
The change applies to every later request from the same Stack. See Headers on the Query class page.
Use it to undo the setHeader or the variants method. variants sets the x-cs-variant-uid header, and its branch overloads also set branch.

IMPORTANT: removeHeader also deletes the api_key, access_token and environment headers that Contentstack.stack set. Requests from the stack then go out without them, and the API rejects them.

Example

Stop sending a variant header after one query

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;

public class RemoveVariantHeader {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });

        // Later requests from this stack no longer ask for the variant
        query.removeHeader("x-cs-variant-uid");
    }
}

removeQuery

removeQuery deletes one query parameter from the request.

Name	Type	Description
key (required)	String	Name of the query parameter to remove. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

removeQuery checks the key with the rules under Input checks on the Query class page. A rejected key, or a key the query does not hold, makes it skip the call.
A null key throws NullPointerException at the call.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. removeQuery deletes the parameter from the parameter store and makes no request.
The store holds the parameters that addQuery, addParam, locale, limit, skip, includeCount and the other parameter methods set. removeQuery("limit") deletes a limit that limit set.
It cannot remove a condition. find rebuilds the query parameter from the conditions on every run.
Keys with brackets, such as include[], fail the key check, so removeQuery cannot delete them.
A Query keeps its parameters after find returns. Use removeQuery to drop one before you run the same query again.

Example

Drop the limit before you run a query again

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;

public class RemoveLimit {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println("first run: " + queryResult.getResultObjects().size());
            }
        });

        // Run the same query again without the limit
        query.removeQuery("limit");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                System.out.println("second run: " + queryResult.getResultObjects().size());
            }
        });
    }
}

search

search sends a text value that entries must match.

Name	Type	Description
value (required)	String	Text to match. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

search checks the value before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. search records the value in the typeahead parameter and makes no request.
find and findOne send it to Get all entries.
A second call replaces the first.

Example

Match entries that contain a word

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;

public class SearchEntries {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.search("pricing");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

setHeader

setHeader adds a custom header to the requests the stack sends.

Name	Type	Description
key (required)	String	Header name. Default: Not applicable
value (required)	String	Header value. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

There is no format check. setHeader ignores the call when key or value is an empty string.
A null key or value throws NullPointerException at the call.

Additional Resource Get all entries lists the headers the Content Delivery API reads on this request.

Behavior

Client-side only. setHeader writes the header into the header map that the Stack owns and makes no request.
The map is not a copy. The header goes on every later request from the same Stack, including other queries, entries and assets. See Headers on the Query class page.
A second call with the same name replaces the value.
To keep a header to one query, call the removeHeader method after find returns. find runs synchronously, so the request has already gone out at that point.

Example

Send a custom header with one query, then remove it

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;

public class SendCustomHeader {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.setHeader("x-request-source", "blog-listing");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });

        // The header lives on the stack, so remove it once find returns
        query.removeHeader("x-request-source");
    }
}

skip

skip leaves out a number of matching entries from the start of the result.

Name	Type	Description
number (required)	int	Number of entries to skip. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

There is no client-side validation. skip records a negative number as given.
An invalid value comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. skip records the skip parameter and makes no request.
find sends it as the Skip request describes.
A second call replaces the first.
The SDK does not request further pages. Combine skip, limit and includeCount to read the result one page at a time, as the Pagination request describes.

Example

Read the third page of ten entries

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;

public class ReadThirdPage {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.skip(20).limit(10);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Read every entry, one page at a time

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;

public class ReadAllPages {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        final int pageSize = 100;
        final int[] total = {1};
        for (int skip = 0; skip < total[0]; skip += pageSize) {
            Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
            query.includeCount().skip(skip).limit(pageSize);
            query.find(new QueryResultsCallBack() {
                @Override
                public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                    if (error != null) { System.out.println(error.getErrorMessage()); total[0] = 0; return; }
                    // find runs synchronously, so the loop reads the new total before it continues
                    total[0] = queryResult.getCount();
                    for (Entry entry : queryResult.getResultObjects()) {
                        System.out.println(entry.getUid());
                    }
                }
            });
        }
    }
}

Name	Type	Description
tags (required)	String[]	Tags to filter entries by. Default: Not applicable

variants

variants asks for one or more entry variants instead of the base entries.

Name	Type	Description
variants (required)	String \| String[]	Variant UID, or several variant UIDs. Default: Not applicable
branch (required)	String	Branch to send the request to. Default: Not applicable

Returns: Query. The same query, for chaining.

Overloads

variants(String variants) and variants(String[] variants)
variants(String variants, String branch) and variants(String[] variants, String branch)

Validation

There is no format check. variants trims each value and ignores a value that is null or blank. When no value remains, it sets no header.
The branch overloads ignore a null or blank branch and still set the variant header.
An invalid variant UID comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. variants writes the x-cs-variant-uid header and makes no request.
The array overloads join the UIDs with commas. The Get multiple variants of an entry request accepts up to 5 UIDs by default and gives the first one the highest priority.
The branch overloads also write the branch header. That replaces a branch that Config.setBranch set on the stack.

IMPORTANT: Both headers go into the header map that the Stack owns. Every later request from that stack asks for the same variants and branch. Call the removeHeader method with x-cs-variant-uid after find returns to stop it. See Headers on the Query class page.

Example

Return one variant of each entry

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;

public class FindVariant {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });

        query.removeHeader("x-cs-variant-uid");
    }
}

Return entries with two variants applied

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;

public class FindTwoVariants {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        // The first UID or alias takes priority
        query.variants(new String[] {"<VARIANT_UID>", "summer_campaign"});

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Return a variant from a branch

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;

public class FindVariantOnBranch {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query single = stack.contentType("<CONTENT_TYPE_UID>").query().variants("<VARIANT_UID>", "<BRANCH>");
        Query several = stack.contentType("<CONTENT_TYPE_UID>").query().variants(new String[] {"<VARIANT_UID>", "summer_campaign"}, "<BRANCH>");

        single.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });

        several.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

where

where matches entries whose field equals a value.

Name	Type	Description
key (required)	String	Field UID to match, such as title. Default: Not applicable
value (required)	Object	Value the field must equal. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

where checks the key and a String value before it records the condition. A null value also fails the check.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key throws NullPointerException at the call.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. where records {"<key>": <value>} in the condition store and makes no request.
find sends the conditions as JSON in the query parameter, in the shape the Equals Operator request describes.
Name a field inside a Group field as group_uid.field_uid, as the Equals Operator Within Group request shows.
A second where on the same field replaces the first condition. It also replaces any operator condition, such as lessThan, on that field.
A Number or Boolean value skips the character check and goes into the JSON as a number or a boolean.

Example

Match entries by title

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;

public class FindByTitle {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        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) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Match a field inside a Group field

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;

public class FindByGroupField {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.where("address.city", "London");

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

Match a number field

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;

public class FindByPrice {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        query.where("price", 100);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

whereIn

whereIn matches entries whose reference field points to entries that match a subquery.

Name	Type	Description
key (required)	String	Reference field UID to filter on. Default: Not applicable
queryObject (required)	Query	Conditions the referenced entries must match. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

whereIn checks the key before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key or a null subquery throws NullPointerException at the call.
Known issue: In 2.8.3, a condition that the subquery rejected is missing from the copy, and the main query still runs with a broader condition than you intended. Before you build the subquery, check each field UID and value against Input checks on the Query class page. A field UID may contain only ASCII letters, digits, underscores and periods. A String value may also contain hyphens and whitespace.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. whereIn copies the conditions of the subquery under $in_query and makes no request.
find sends {"<key>": {"$in_query": {<conditions>}}} in the query parameter, in the shape the Reference Search Equals request describes.
whereIn copies the conditions when you call it. A condition you add to the subquery later does not go out.
It reads conditions only. It ignores the parameters of the subquery, such as locale or limit.
A second call on the same field replaces the first condition.

Example

Match entries by a field of the referenced author

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;

public class FindByAuthor {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        // The subquery holds conditions on the referenced content type
        Query authorQuery = stack.contentType("author").query().where("title", "John Doe");
        query.whereIn("author", authorQuery);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}

whereNotIn

whereNotIn matches entries whose reference field points to entries that do not match a subquery.

Name	Type	Description
key (required)	String	Reference field UID to filter on. Default: Not applicable
queryObject (required)	Query	Conditions the referenced entries must not match. Default: Not applicable

Returns: Query. The same query, for chaining.

Validation

whereNotIn checks the key before it records the condition.
A rejected input stops the whole query. find and findOne then send no request and never call your callback. The check accepts only ASCII letters, digits, underscores and periods in a field UID, plus hyphens and whitespace in a String value, so an email address, a URL path, a date-time or an accented letter stops the query.
A null key or a null subquery throws NullPointerException at the call.
Known issue: In 2.8.3, a condition that the subquery rejected is missing from the copy, and the main query still runs with a broader condition than you intended. Before you build the subquery, check each field UID and value against Input checks on the Query class page. A field UID may contain only ASCII letters, digits, underscores and periods. A String value may also contain hyphens and whitespace.
A value that passes the check but that the API rejects comes back as an Error in the callback when find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

Client-side only. whereNotIn copies the conditions of the subquery under $nin_query and makes no request.
find sends {"<key>": {"$nin_query": {<conditions>}}} in the query parameter, in the shape the Reference Search Not-equals request describes.
whereNotIn copies the conditions when you call it. A condition you add to the subquery later does not go out.
It reads conditions only. It ignores the parameters of the subquery, such as locale or limit.
A second call on the same field replaces the first condition.

Example

Match entries by a field of the referenced author

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;

public class FindByOtherAuthors {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
        // The subquery holds conditions on the referenced content type
        Query authorQuery = stack.contentType("author").query().where("title", "John Doe");
        query.whereNotIn("author", authorQuery);

        query.find(new QueryResultsCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry entry : queryResult.getResultObjects()) {
                    System.out.println(entry.getUid() + " " + entry.getTitle());
                }
            }
        });
    }
}