Package com.contentstack.sdk

Class Query

  • All Implemented Interfaces:
    INotifyClass
    public class Query
extends Object
implements INotifyClass
    Contentstack provides certain queries that you can use to fetch filtered results. You can use queries for Entries and Queries Contentstack provides certain queries that you can use to fetch filtered results. You can use queries for Entries and Assets API requests.

    You can now pass the branch header in the API request to fetch or manage modules located within specific branches of the stack.

    Note Branches is a plan-based feature that is available only in the new Contentstack interface.

    Since:
    01-11-2017
    Version:
    1.0.0
    Author:
    Shailesh Mishra

    • Method Detail

      • setHeader

        public Query setHeader​(@NotNull
                       String key,
                       @NotNull
                       String value)
        To set headers for Built.io Contentstack rest calls.
        Scope is limited to this object and followed classes.
        Parameters:
        key - header name.
        value - header value against given header name.


        Example :
                                                    Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
                                            
        
                                            Query query = stack.contentType("contentTypeUid").query(); query.setHeader("custom_key", "custom_value");
                                        
        
                                            Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
                                            
        
                                            Query csQuery = stack.contentType("contentTypeUid").query(); 
        csQuery.setHeader("custom_key", "custom_value");

      • removeHeader

        public Query removeHeader​(@NotNull
                          String key)
        Remove header key @param key custom_header_key
        Parameters:
        key - String Example :

        Stack stack = Contentstack..stack( "apiKey", "deliveryToken", "environment"); Query csQuery = stack.contentType("contentTypeUid").query();
        csQuery.removeHeader("custom_key");

      • getContentType

        public String getContentType()

      • where

        public Query where​(@NotNull
                   String key,
                   Object value)
        Add a constraint to fetch all entries that contains given value against specified key
        Parameters:
        key - field uid.
        value - field value which get 'included' from the response.
        Returns:
        Query object, so you can chain this call.

        Note : for group field provide key in a "key.groupFieldUid" format.


        Example :

                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.where("uid", "entry_uid");

      • addQuery

        public Query addQuery​(@NotNull
                      String key,
                      String value)
        Add a custom query against specified key.
        Parameters:
        key - key.
        value - value.
        Returns:
        Query object, so you can chain this call.

        Example :
                  Stack stack = Contentstack..stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
          csQuery.addQuery("query_param_key", "query_param_value");

      • removeQuery

        public Query removeQuery​(@NotNull
                         String key)
        Remove provided query key from custom query if existed.
        Parameters:
        key - Query name to remove.
        Returns:
        Query object, so you can chain this call.


        Example :
                 projectQuery.removeQuery("Query_Key");

      • and

        public Query and​(@NotNull
                 List<Query> queryObjects)
        Combines all the queries together using AND operator
        Parameters:
        queryObjects - list of Query instances on which AND query executes.
        Returns:
        Query object, so you can chain this call.

        Example ;
                  Stack stack = Contentstack..stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
          Query query = projectClass.query();
          query.where('username','something');
          Query subQuery = projectClass.query();
          subQuery.where('email_address','[email protected]');
          ArrayList<Query> array = new ArrayList<Query>();
        
          array.add(query);
          array.add(subQuery);
        
          projectQuery.and(array);

      • or

        public Query or​(List<Query> queryObjects)
        Add a constraint to fetch all entries which satisfy any queries.
        Parameters:
        queryObjects - list of Query instances on which OR query executes.
        Returns:
        Query object, so you can chain this call.

        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
          Query query = projectClass.query();
          query.where('username','something');
          Query subQuery = projectClass.query();
          subQuery.where('email_address','[email protected]');
          ArrayList<Query> array = new ArrayList<Query>();
          array.add(query);
          array.add(subQuery);
        
          csQuery.or(array);

      • lessThan

        public Query lessThan​(@NotNull
                      String key,
                      @NotNull
                      Object value)
        Add a constraint to the query that requires a particular key entry to be less than the provided value.
        Parameters:
        key - the key to be constrained.
        value - the value that provides an upper bound.
        Returns:
        Query object, so you can chain this call.


        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.lessThan("due_date", "2013-06-25T00:00:00+05:30");

      • lessThanOrEqualTo

        public Query lessThanOrEqualTo​(@NotNull
                               String key,
                               Object value)
        Add a constraint to the query that requires a particular key entry to be less than or equal to the provided value.
        Parameters:
        key - The key to be constrained
        value - The value that must be equalled.
        Returns:
        Query object, so you can chain this call.

        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.lessThanOrEqualTo("due_date", "2013-06-25T00:00:00+05:30");

      • greaterThan

        public Query greaterThan​(@NotNull
                         String key,
                         Object value)
        Add a constraint to the query that requires a particular key entry to be greater than the provided value.
        Parameters:
        key - The key to be constrained.
        value - The value that provides a lower bound.
        Returns:
        Query object, so you can chain this call.

        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.greaterThan("due_date", "2013-06-25T00:00:00+05:30");

      • greaterThanOrEqualTo

        public Query greaterThanOrEqualTo​(String key,
                                  Object value)
        Add a constraint to the query that requires a particular key entry to be greater than or equal to the provided value.
        Parameters:
        key - The key to be constrained.
        value - The value that provides a lower bound.
        Returns:
        Query object, so you can chain this call.

        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.greaterThanOrEqualTo("due_date", "2013-06-25T00:00:00+05:30");

      • notEqualTo

        public Query notEqualTo​(@NotNull
                        String key,
                        Object value)
        Add a constraint to the query that requires a particular key's entry to be not equal to the provided value.
        Parameters:
        key - The key to be constrained.
        value - The object that must not be equaled.
        Returns:
        Query object, so you can chain this call.

        Example ;
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.notEqualTo("due_date", "2013-06-25T00:00:00+05:30");

      • containedIn

        public Query containedIn​(@NotNull
                         String key,
                         Object[] values)
        Add a constraint to the query that requires a particular key's entry to be contained in the provided array.
        Parameters:
        key - The key to be constrained.
        values - The possible values for the key's object.
        Returns:
        Query object, so you can chain this call.


        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.containedIn("severity", new Object[] { "Show Stopper", "Critical" });

      • notContainedIn

        public Query notContainedIn​(@NotNull
                            String key,
                            Object[] values)
        Add a constraint to the query that requires a particular key entry's value not be contained in the provided array.
        Parameters:
        key - The key to be constrained.
        values - The list of values the key object should not be.
        Returns:
        Query object, so you can chain this call.

        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.notContainedIn("severity", new Object[] { "Show Stopper", "Critical" });

      • exists

        public Query exists​(@NotNull
                    String key)
        Add a constraint that requires, a specified key exists in response.
        Parameters:
        key - The key to be constrained.
        Returns:
        Query object, so you can chain this call.

        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.exists("status");

      • notExists

        public Query notExists​(@NotNull
                       String key)
        Add a constraint that requires, a specified key does not exist in response.
        Parameters:
        key - The key to be constrained.
        Returns:
        Query object, so you can chain this call.


        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.notExists("status");

      • includeReference

        public Query includeReference​(String key)
        Add a constraint that requires a particular reference key details.
        Parameters:
        key - key that to be constrained.
        Returns:
        Query object, so you can chain this call.

        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.includeReference("for_bug");

      • tags

        public Query tags​(@NotNull
                  String[] tags)
        Include tags with which to search entries.
        Parameters:
        tags - Comma separated array of tags with which to search entries.
        Returns:
        Query object, so you can chain this call.


        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.tags(new String[] { "tag1", "tag2" });

      • ascending

        public Query ascending​(@NotNull
                       String key)
        Sort the results in ascending order with the given key.
        Sort the returned entries in ascending order of the provided key.
        Parameters:
        key - The key to order by.
        Returns:
        Query object, so you can chain this call.


        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.ascending("name");

      • descending

        public Query descending​(@NotNull
                        String key)
        Sort the results in descending order with the given key.
        Sort the returned entries in descending order of the provided key.
        Parameters:
        key - The key to order by.
        Returns:
        Query object, so you can chain this call.


        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.descending("name");

      • except

        public Query except​(@NotNull
                    List<String> fieldUid)
        Specifies list of field ids that would be 'excluded' from the response.
        Parameters:
        fieldUid - field uid which get 'excluded' from the response.
        Returns:
        Query object, so you can chain this call.

        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
        
          ArrayList<String> array = new ArrayList<String>();
          array.add("name");
          array.add("description");
        
          csQuery.except(array);

      • except

        public Query except​(@NotNull
                    String[] fieldIds)
        Specifies list of field ids that would be 'excluded' from the response.
        Parameters:
        fieldIds - field uid which get 'excluded' from the response.
        Returns:
        Query object, so you can chain this call.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
        
          csQuery.except(new String[]{"name", "description"});

      • only

        public Query only​(@NotNull
                  String[] fieldUid)
        Specifies an array of 'only' keys in BASE object that would be 'included' in the response.
        Parameters:
        fieldUid - Array of the 'only' reference keys to be included in response.
        Returns:
        Query object, so you can chain this call.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
        
          csQuery.only(new String[]{"name"});

      • onlyWithReferenceUid

        public Query onlyWithReferenceUid​(@NotNull
                                  List<String> fieldUid,
                                  @NotNull
                                  String referenceFieldUid)
        Specifies an array of 'only' keys that would be 'included' in the response.
        Parameters:
        fieldUid - Array of the 'only' reference keys to be included in response.
        referenceFieldUid - Key who has reference to some other class object.
        Returns:
        Query object, so you can chain this call.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
        
          ArrayList<String> array = new ArrayList<String>();
          array.add("description");
          array.add("name");
        
          csQuery.onlyWithReferenceUid(array, "for_bug");

      • exceptWithReferenceUid

        public Query exceptWithReferenceUid​(@NotNull
                                    List<String> fieldUid,
                                    @NotNull
                                    String referenceFieldUid)
        Specifies an array of 'except' keys that would be 'excluded' in the response.
        Parameters:
        fieldUid - Array of the 'except' reference keys to be excluded in response.
        referenceFieldUid - Key who has reference to some other class object.
        Returns:
        Query object, so you can chain this call.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
        
          ArrayList<String> array = new ArrayList<String>();
          array.add("description");
          array.add("name");
        
          csQuery.exceptWithReferenceUid(array, "for_bug");

      • count

        public Query count()
        Retrieve only count of entries in result.
        Returns:
        Query object, so you can chain this call. Note :- Call QueryResult.getCount() method in the success to get count of objects.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
        
          csQuery.count();

      • includeCount

        public Query includeCount()
        Retrieve count and data of objects in result
        Returns:
        Query object, so you can chain this call. Note :- Call QueryResult.getCount() method in the success to get count of objects.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
        
          csQuery.includeCount();

      • includeContentType

        public Query includeContentType()
        Include Content Type of all returned objects along with objects themselves.
        Returns:
        Query object, so you can chain this call.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
        
          csQuery.includeContentType();

      • skip

        public Query skip​(int number)
        The number of objects to skip before returning any.
        Parameters:
        number - No of objects to skip from returned objects
        Returns:
        Query object, so you can chain this call.

        Note: The skip parameter can be used for pagination, "skip" specifies the number of objects to skip in the response.


        Example :

                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
        
          csQuery.skip(2);

      • limit

        public Query limit​(int number)
        A limit on the number of objects to return.
        Parameters:
        number - No of objects to limit.
        Returns:
        Query object, so you can chain this call.

        Note: The limit parameter can be used for pagination, " limit" specifies the number of objects to limit to in the response.


        Example :

                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query query = stack.contentType("contentTypeUid").query();
        
          query.limit(2);

      • regex

        public Query regex​(@NotNull
                   String key,
                   @NotNull
                   String regex)
        Add a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large data sets.
        Parameters:
        key - The key to be constrained.
        regex - The regular expression pattern to match.
        Returns:
        Query object, so you can chain this call.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query query = stack.contentType("contentTypeUid").query();
        
          query.regex("name", "^browser");

      • regex

        public Query regex​(@NotNull
                   String key,
                   @NotNull
                   String regex,
                   String modifiers)
        Add a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large data sets.
        Parameters:
        key - The key to be constrained.
        regex - The regular expression pattern to match
        modifiers - Any of the following supported Regular expression modifiers.

        use i for case-insensitive matching.

        use m for making dot match newlines.

        use x for ignoring whitespace in regex

        Returns:
        Query object, so you can chain this call.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query query = stack.contentType("contentTypeUid").query();
        
          query.regex("name", "^browser", "i");

      • locale

        public Query locale​(@NotNull
                    String locale)
        set Language using locale code.
        Parameters:
        locale - String value
        Returns:
        Query object, so you can chain this call


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query query = stack.contentType("contentTypeUid").query();
        
          query.locale("en-us");

      • search

        public Query search​(@NotNull
                    String value)
        This method provides only the entries matching the specified value.
        Parameters:
        value - value used to match or compare
        Returns:
        Query object, so you can chain this call.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query query = stack.contentType("contentTypeUid").query();
        
          query.search("header");

      • find

        public Query find​(QueryResultsCallBack callback)
        Execute a Query and Caches its result (Optional)
        Parameters:
        callback - QueryResultsCallBack object to notify the application when the request has completed.
        Returns:
        Query object, so you can chain this call.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query query = stack.contentType("contentTypeUid").query();
        
          query.find(new QueryResultsCallBack() {
        
              @Override
          public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {
        
              }
      });

      • findOne

        public Query findOne​(SingleQueryResultCallback callBack)
        Execute a Query and Caches its result (Optional)
        Parameters:
        callBack - QueryResultsCallBack object to notify the application when the request has completed.
        Returns:
        Query object, so you can chain this call.


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
        
          csQuery.findOne(new QueryResultsCallBack() {
        
              @Override
          public void onCompletion(ResponseType responseType, ENTRY entry, Error error) {
        

          }
      });

      • getResultObject

        public void getResultObject​(List<Object> objects,
                            org.json.JSONObject jsonObject,
                            boolean isSingleEntry)
        Specified by:
        getResultObject in interface INotifyClass

      • addParam

        public Query addParam​(@NotNull
                      String key,
                      @NotNull
                      String value)
        This method adds key and value to an Entry. Parameters:
        Parameters:
        key - : The key as string which needs to be added to the Query
        value - : The value as string which needs to be added to the Query
        Returns:
        - Query

        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.addParam("key", "some_value");
         csQuery.findOne(new QueryResultsCallBack() {
             @Override
             public void onCompletion(ResponseType responseType, ENTRY entry, Error error) {
             }
         });

      • includeReferenceContentTypUid

        public Query includeReferenceContentTypUid()
        This method also includes the content type UIDs of the referenced entries returned in the response
        Returns:
        Query


        Example :
                  Stack stack = Contentstack.stack( "apiKey", "deliveryToken", "environment");
          Query csQuery = stack.contentType("contentTypeUid").query();
        
          csQuery.includeReferenceContentTypUid();
          csQuery.findOne(new QueryResultsCallBack() {
        
          @Override
          public void onCompletion(ResponseType responseType, ENTRY entry, Error error) {
        
          }
      });

      • whereIn

        public Query whereIn​(@NotNull
                     String key,
                     Query queryObject)
        Get entries having values based on referenced fields. This query retrieves all entries that satisfy the query conditions made on referenced fields.
        Parameters:
        key - The key to be constrained
        queryObject - Query object, so you can chain this call
        Returns:
        Query object, so you can chain this call


        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.whereIn("due_date", csQuery);

      • whereNotIn

        public Query whereNotIn​(@NotNull
                        String key,
                        Query queryObject)
        Get entries having values based on referenced fields. This query works the opposite of $in_query and retrieves all entries that does not satisfy query conditions made on referenced fields.
        Parameters:
        key - The key to be constrained
        queryObject - Query object, so you can chain this call
        Returns:
        Query object, so you can chain this call

        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.whereNotIn("due_date", csQuery);

      • includeFallback

        public Query includeFallback()
        Retrieve the published content of the fallback locale if an entry is not localized in specified locale
        Returns:
        Query object, so you can chain this call.


        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", environment);
         Query csQuery = stack.contentType("contentTypeUid").query();
         csQuery.includeFallback();

      • includeEmbeddedItems

        public Query includeEmbeddedItems()
        Returns:
        Query object, so you can chain this call.


        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", environment);
         Query query = stack.contentType("contentTypeUid").query();
         query.includeEmbeddedObjects()

      • includeBranch

        public Query includeBranch()
        Includes Branch in the entry response
        Returns:
        Query object, so you can chain this call.


        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query query = stack.contentType("contentTypeUid").query();
         entry.includeBranch();

      • includeMetadata

        public Query includeMetadata()
        Includes Metadata in the entry response
        Returns:
        Query object, so you can chain this call.


        Example :
                 Stack stack = Contentstack.stack("apiKey", "deliveryToken", "environment");
         Query query = stack.contentType("contentTypeUid").query();
         entry.includeMetadata();