4.3.1.16 Interface Query

4.3.1.16.1 Synopsis
4.3.1.16.2 INDEX_USED
4.3.1.16.3 SCAN_TYPE
4.3.1.16.4 SCAN_TYPE_INDEX_SCAN
4.3.1.16.5 SCAN_TYPE_PRIMARY_KEY
4.3.1.16.6 SCAN_TYPE_TABLE_SCAN
4.3.1.16.7 SCAN_TYPE_UNIQUE_KEY
4.3.1.16.8 deletePersistentAll()
4.3.1.16.9 execute(Map<String, ?>)
4.3.1.16.10 execute(Object...)
4.3.1.16.11 execute(Object)
4.3.1.16.12 explain()
4.3.1.16.13 getResultList()
4.3.1.16.14 setLimits(long, long)
4.3.1.16.15 setOrdering(Query.Ordering, String...)
4.3.1.16.16 setParameter(String, Object)

A Query instance represents a specific query with bound parameters. The instance is created by the method com.mysql.clusterj.Session.createQuery.

4.3.1.16.1 Synopsis
 public interface Query<E> {
// Public Static Fields  public static final String INDEX_USED = "IndexUsed";
  public static final String SCAN_TYPE = "ScanType";
  public static final String SCAN_TYPE_INDEX_SCAN = "INDEX_SCAN";
  public static final String SCAN_TYPE_PRIMARY_KEY = "PRIMARY_KEY";
  public static final String SCAN_TYPE_TABLE_SCAN = "TABLE_SCAN";
  public static final String SCAN_TYPE_UNIQUE_KEY = "UNIQUE_KEY";
// Public Methods  public int deletePersistentAll();
  public Results<E> execute(Object parameter);
  public Results<E> execute(Object[] parameters);
  public Results<E> execute(Map<String, ?> parameters);
  public Map<String, Object> explain();
  public List<E> getResultList();
  public void setLimits(long skip,
                        long limit);

  public void setOrdering(Ordering ordering,
                          String[] orderingFields);

  public void setParameter(String parameterName,
                           Object value);

}
4.3.1.16.2 INDEX_USED
public static final String INDEX_USED = "IndexUsed";

The query explain index used key

4.3.1.16.3 SCAN_TYPE
public static final String SCAN_TYPE = "ScanType";

The query explain scan type key

4.3.1.16.4 SCAN_TYPE_INDEX_SCAN
public static final String SCAN_TYPE_INDEX_SCAN = "INDEX_SCAN";

The query explain scan type value for index scan

4.3.1.16.5 SCAN_TYPE_PRIMARY_KEY
public static final String SCAN_TYPE_PRIMARY_KEY = "PRIMARY_KEY";

The query explain scan type value for primary key

4.3.1.16.6 SCAN_TYPE_TABLE_SCAN
public static final String SCAN_TYPE_TABLE_SCAN = "TABLE_SCAN";

The query explain scan type value for table scan

4.3.1.16.7 SCAN_TYPE_UNIQUE_KEY
public static final String SCAN_TYPE_UNIQUE_KEY = "UNIQUE_KEY";

The query explain scan type value for unique key

4.3.1.16.8 deletePersistentAll()
public int deletePersistentAll();

Delete the instances that satisfy the query criteria.

Parameters

return

the number of instances deleted

4.3.1.16.9 execute(Map<String, ?>)
public Results<E> execute(Map<String, ?> parameters);

Execute the query with one or more named parameters. Parameters are resolved by name.

Parameters

parameters

the parameters

return

the result

4.3.1.16.10 execute(Object...)
public Results<E> execute(Object[] parameters);

Execute the query with one or more parameters. Parameters are resolved in the order they were declared in the query.

Parameters

parameters

the parameters

return

the result

4.3.1.16.11 execute(Object)
public Results<E> execute(Object parameter);

Execute the query with exactly one parameter.

Parameters

parameter

the parameter

return

the result

4.3.1.16.12 explain()
public Map<String, Object> explain();

Explain how this query will be or was executed. If called before binding all parameters, throws ClusterJUserException. Return a map of key:value pairs that explain how the query will be or was executed. Details can be obtained by calling toString on the value. The following keys are returned:

  • ScanType: the type of scan, with values:

    • PRIMARY_KEY: the query used key lookup with the primary key

    • UNIQUE_KEY: the query used key lookup with a unique key

    • INDEX_SCAN: the query used a range scan with a non-unique key

    • TABLE_SCAN: the query used a table scan

  • IndexUsed: the name of the index used, if any

Parameters

return

the data about the execution of this query

Exceptions

ClusterJUserException

if not all parameters are bound

4.3.1.16.13 getResultList()
public List<E> getResultList();

Get the results as a list.

Parameters

return

the result

Exceptions

ClusterJUserException

if not all parameters are bound

ClusterJDatastoreException

if an exception is reported by the datastore

4.3.1.16.14 setLimits(long, long)
public void setLimits(long skip,
                      long limit);

Set limits on results to return. The execution of the query is modified to return only a subset of results. If the filter would normally return 100 instances, skip is set to 50, and limit is set to 40, then the first 50 results that would have been returned are skipped, the next 40 results are returned and the remaining 10 results are ignored.

Skip must be greater than or equal to 0. Limit must be greater than or equal to 0. Limits may not be used with deletePersistentAll.

Parameters

skip

the number of results to skip

limit

the number of results to return after skipping; use Long.MAX_VALUE for no limit.

4.3.1.16.15 setOrdering(Query.Ordering, String...)
public void setOrdering(Ordering ordering,
                        String[] orderingFields);

Set ordering for the results of this query. The execution of the query is modified to use an index previously defined.

  • There must be an index defined on the columns mapped to the ordering fields, in the order of the ordering fields.

  • There must be no gaps in the ordering fields relative to the index.

  • All ordering fields must be in the index, but not all fields in the index need be in the ordering fields.

  • If an "in" predicate is used in the filter on a field in the ordering, it can only be used with the first field.

  • If any of these conditions is violated, ClusterJUserException is thrown when the query is executed.

If an "in" predicate is used, each element in the parameter defines a separate range, and ordering is performed within that range. There may be a better (more efficient) index based on the filter, but specifying the ordering will force the query to use an index that contains the ordering fields.

Parameters

ordering

either Ordering.ASCENDING or Ordering.DESCENDING

orderingFields

the fields to order by

4.3.1.16.16 setParameter(String, Object)
public void setParameter(String parameterName,
                         Object value);

Set the value of a parameter. If called multiple times for the same parameter, silently replace the value.

Parameters

parameterName

the name of the parameter

value

the value for the parameter