QueryResult

View as Markdown

QueryResult

The QueryResult class holds the response of a Query find call: the matching entries, and the count and content type when the query asked for them. Use this class to

  • read the entries that matched the query
  • read the total number of matches for pagination
  • read the content type of the queried entries

The SDK builds a QueryResult from the response and passes it to onCompletion(ResponseType responseType, QueryResult queryresult, Error error) on the QueryResultsCallBack you give to find. Every getter reads a value stored at that moment and makes no request.

getContentType

getContentType returns the content type object from the response, when the query asked for it.

Returns: JSONObject. The content type from the response.

Validation

  • There is no client-side validation. getContentType returns null, not an error, when the response holds no content_type object.

Behavior

  • Client-side only. getContentType returns the content_type object that the SDK stored when the response arrived, and makes no request.
  • The response carries content_type only after you call includeContentType on the query.
  • This method returns a JSONObject. Query.getContentType is a different method that returns the content type UID as a String.

Example

Basic usage: read the content type title

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import org.json.JSONObject;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
    query.includeContentType();
    query.find(new QueryResultsCallBack() {
        @Override
        public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
            if (error == null) {
                JSONObject contentType = queryResult.getContentType();
                if (contentType != null) {
                    Log.d("Contentstack", contentType.optString("uid") + " " + contentType.optString("title"));
                }
            } else {
                // The API rejected the request, the network failed, or the query is in an error state
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

getCount

getCount returns the number of matching entries that the API reported.

Returns: int. The entry count the API returned.

Validation

  • There is no client-side validation. getCount returns 0, not an error, when the response holds no count.

Behavior

  • Client-side only. getCount reads the value the SDK stored when the response arrived, and makes no request.
  • The value depends on the call you chained before find:
    • After includeCount, getCount returns the count from the response: every match, not only the current page.
    • After count, getCount returns the count that the response carries in place of entries.
    • Without either, getCount returns 0.
  • getCount does not return the size of the current page. Use getResultObjects().size() for that.
  • The Count request describes both parameters.

Example

Basic usage: read the total next to the entries

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
    query.includeCount();
    query.find(new QueryResultsCallBack() {
        @Override
        public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
            if (error == null) {
                Log.d("Contentstack", "Total: " + queryResult.getCount()
                        + ", on this page: " + queryResult.getResultObjects().size());
            } else {
                // The API rejected the request, the network failed, or the query is in an error state
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

Count only: read the number of entries without the entries

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
    query.where("category", "news").count();
    query.find(new QueryResultsCallBack() {
        @Override
        public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
            if (error != null) {
                Log.e("Contentstack", error.getErrorMessage());
                return;
            }
            Log.d("Contentstack", "News entries: " + queryResult.getCount());
        }
    });
} catch (Exception e) {
    Log.e("Contentstack", e.getMessage());
}

getResultObjects

getResultObjects returns the entries that the query returned, in response order.

Returns: List<Entry>. The entries the query returned.

Validation

  • There is no client-side validation. getResultObjects reads a value that find already filled.

Behavior

  • Client-side only. getResultObjects returns one Entry per item in the entries array of the response, and makes no request.
  • Each item is an Entry that holds the fields of one entry. Read them with getters such as getTitle(), getString("<field>"), or toJSON().
  • When no entry matches, the list is empty, not null.
  • After a count call, the list is empty, because the response carries a count instead of entries.
  • The list contains the entries of one page only. Set skip and limit on the query to read another page. See Pagination on the Query class page.

Example

Basic usage: log the title of each entry

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.util.List;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
    query.find(new QueryResultsCallBack() {
        @Override
        public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
            if (error == null) {
                List<Entry> entries = queryResult.getResultObjects();
                for (Entry entry : entries) {
                    Log.d("Contentstack", entry.getTitle());
                }
            } else {
                // The API rejected the request, the network failed, or the query is in an error state
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

Edge case: handle a query that matches nothing

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
    query.where("title", "No such title");
    query.find(new QueryResultsCallBack() {
        @Override
        public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
            if (error != null) {
                Log.e("Contentstack", error.getErrorMessage());
                return;
            }
            if (queryResult.getResultObjects().isEmpty()) {
                Log.d("Contentstack", "No entries matched");
            }
        }
    });
} catch (Exception e) {
    Log.e("Contentstack", e.getMessage());
}

getSchema

getSchema returns the top-level schema array from the response, when the response carries one.

Returns: JSONArray. The content type schema from the response.

Validation

  • There is no client-side validation. getSchema returns null, not an error, when the response holds no top-level schema array.

Behavior

  • Client-side only. getSchema returns the top-level schema array that the SDK stored when the response arrived, and makes no request.
  • None of the Query methods asks the API for a top-level schema array, so check the value for null before you use it.
  • To read the content type of the queried entries, call the includeContentType method and read getContentType instead.

Example

Basic usage: check the response for a schema array

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Query;
import com.contentstack.sdk.QueryResult;
import com.contentstack.sdk.QueryResultsCallBack;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import org.json.JSONArray;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Query query = stack.contentType("<CONTENT_TYPE_UID>").query();
    query.find(new QueryResultsCallBack() {
        @Override
        public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
            if (error == null) {
                JSONArray schema = queryResult.getSchema();
                if (schema == null) {
                    Log.d("Contentstack", "The response holds no schema array");
                } else {
                    Log.d("Contentstack", "Schema fields: " + schema.length());
                }
            } else {
                // The API rejected the request, the network failed, or the query is in an error state
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}