Package com.couchbase.lite

Class Where

java.lang.Object
com.couchbase.lite.Where
All Implemented Interfaces:
com.couchbase.lite.internal.Listenable<QueryChange,QueryChangeListener>, Query
public final class Where extends Object
A Where represents the WHERE clause of the query for filtering the query result.

  • Field Details

    • DOMAIN

      protected static final LogDomain DOMAIN

  • Method Details

    • groupBy

      @NonNull public GroupBy groupBy(@NonNull Expression... expressions)
      Create and chain a GROUP BY component to group the query result.
      Parameters:
      expressions - The expression objects.
      Returns:
      The GroupBy object.

    • orderBy

      @NonNull public OrderBy orderBy(@NonNull Ordering... orderings)
      Create and chain an ORDER BY component for specifying the ORDER BY clause of the query.
      Parameters:
      orderings - an array of the ORDER BY expressions.
      Returns:
      the ORDER BY component.

    • limit

      @NonNull public Limit limit(@NonNull Expression limit)
      Create and chain a LIMIT component to limit the number query results.
      Parameters:
      limit - The limit Expression object
      Returns:
      The Limit object.

    • limit

      @NonNull public Limit limit(@NonNull Expression limit, @Nullable Expression offset)
      Create and chain a LIMIT component to skip the returned results for the given offset position and to limit the number of results to not more than the given limit value.
      Parameters:
      limit - The limit Expression object
      offset - The offset Expression object
      Returns:
      The Limit object.

    • toString

      @NonNull public String toString()
      Overrides:
      toString in class Object

    • getDatabase

      @NonNull protected final com.couchbase.lite.AbstractDatabase getDatabase()
      Get the database to which this query will be applied.
      Returns:
      the query database.

    • prepQueryLocked

      @NonNull protected final com.couchbase.lite.internal.core.C4Query prepQueryLocked(@NonNull com.couchbase.lite.AbstractDatabase db) throws CouchbaseLiteException
      Throws:
      CouchbaseLiteException

    • getParameters

      @Nullable public Parameters getParameters()
      Returns a copy of the current parameters.
      Specified by:
      getParameters in interface Query

    • setParameters

      public void setParameters(@Nullable Parameters parameters)
      Set query parameters. Setting new parameters will re-execute a query if there is at least one listener listening for changes.
      Specified by:
      setParameters in interface Query
      Throws:
      IllegalStateException - on failure to create the query (e.g., database closed)
      IllegalArgumentException - on failure to encode the parameters (e.g., parameter value not supported)

    • execute

      @NonNull public ResultSet execute() throws CouchbaseLiteException
      Executes the query returning a result set that enumerates result rows one at a time. You can run the query any number of times and you can even have multiple ResultSet active at once.

      The results come from a snapshot of the database taken at the moment the run() method is called, so they will not reflect any changes made to the database afterwards.

      Specified by:
      execute in interface Query
      Returns:
      the ResultSet for the query result.
      Throws:
      CouchbaseLiteException - if there is an error when running the query.

    • explain

      @NonNull public String explain() throws CouchbaseLiteException
      Returns a string describing the implementation of the compiled query. This is intended to be read by a developer for purposes of optimizing the query, especially to add database indexes. It's not machine-readable and its format may change. As currently implemented, the result is two or more lines separated by newline characters:
      • The first line is the SQLite SELECT statement.
      • The subsequent lines are the output of SQLite's "EXPLAIN QUERY PLAN" command applied to that statement.
      For help interpreting this, see: eqp. The most important thing to know is that if you see "SCAN TABLE", it means that SQLite is doing a slow linear scan of the documents instead of using an index.
      Specified by:
      explain in interface Query
      Returns:
      a string describing the implementation of the compiled query.
      Throws:
      CouchbaseLiteException - if an error occurs

    • addChangeListener

      @NonNull public ListenerToken addChangeListener(@NonNull QueryChangeListener listener)
      Adds a query change listener. Changes will be posted on the main queue.
      Specified by:
      addChangeListener in interface com.couchbase.lite.internal.Listenable<QueryChange,QueryChangeListener>
      Specified by:
      addChangeListener in interface Query
      Parameters:
      listener - The listener to post changes.
      Returns:
      An opaque listener token object for removing the listener.

    • addChangeListener

      @NonNull public ListenerToken addChangeListener(@Nullable Executor executor, @NonNull QueryChangeListener listener)
      Adds a query change listener with the dispatch queue on which changes will be posted. If the dispatch queue is not specified, the changes will be posted on the main queue.
      Specified by:
      addChangeListener in interface com.couchbase.lite.internal.Listenable<QueryChange,QueryChangeListener>
      Specified by:
      addChangeListener in interface Query
      Parameters:
      executor - The executor object that calls listener. If null, use default executor.
      listener - The listener to post changes.
      Returns:
      An opaque listener token object for removing the listener.
      Throws:
      IllegalStateException - on failure to create the query (e.g., database closed)

    • removeChangeListener

      @Deprecated public void removeChangeListener(@NonNull ListenerToken token)
      Deprecated.
      use ListenerToken.remove()
      Removes a change listener wih the given listener token.
      Specified by:
      removeChangeListener in interface Query
      Parameters:
      token - The listener token.