Query

1.   The Query interface allows for certain filter criteria (based on fields), sorting, an offset, and limiting of the number of results. The query implementation also implements the the QueryResults interface which allows access to the data from the query.

 

2.   The generic .filter(criteria, value) syntax is supported. The criteria is a composite of the field name and the operator ("field >", or "field in"). All criteria are implicitly combined with a logical "and".

 

Query q = ds.createQuery(MyEntity.class).filter("foo >", 12);

Query q = ds.createQuery(MyEntity.class).filter("foo >", 12).filter("foo <", 30); 

 

 

3.   The operators used in filter(...) match the MongoDB query operators very closely:

operator	mongo op
=	$eq
!=, <>	$ne
>,<,>=,<=	$gt,$lt,$gte,$lte
in	$in
nin	$nin
elem	$elemMatch
exists	$exists
all	$all
size	$size

 

4.  The fluent interface provides a more readable (like in the english language sense) form. It works by starting with field(name):

Query q = ds.createQuery(MyEntity.class).field("foo").equal(1);
q.field("bar").greaterThan(12);
q.field("bar").lessThan(40);

 

 

method	mongo op
equal, notEqual	$eq, $ne
hasThisOne	$eq
greaterThan, greaterThanOrEq, lessThan, lessThanOrEq	$gt,$lt,$gte,$lte
hasAnyOf	$in
hasNoneOf	$nin
hasThisElement	$elemMatch
exists, doesNotExist	$exists
hasAllOf	$all
sizeEq	$size

 

5.   Using the fluent query interface you can also do "or" queries:

Query<Person> q = ds.createQuery(Person.class);
q.or(
        q.criteria("firstName").equal("scott"),
        q.criteria("lastName").equal("scott")
); 

 

 

Note, you should use criteria instead of field as one of the or paramters.

 

6.   You can sort by a field, or multiple fields:

... // desc order
Query q = ds.createQuery(MyEntity.class).filter(foo >", 12).order("-dateAdded");
... // asc dateAdded, desc foo
Query q = ds.createQuery(MyEntity.class).filter("foo >", 12).order("dateAdded, -foo");

 

 

 

7.   You can also limit for the number of elements:

Query q = ds.createQuery(MyEntity.class).filter("foo >", 12).limit(100);

 

 

 

8.   You can also ask the server to skip over a number of elements on the server by specifying an offset value for the query. This will less efficient than a range filter using some field:

Query q = ds.createQuery(MyEntity.class).filter("foo >", 12).offset(1000);

 

 

 

9.   MongoDB also supports only returning certain fields. The field name argument (the last arg) can be a list of strings or a string array:

MyEntity e = ds.createQuery(MyEntity.class).retrievedFields(true, "foo", "bar").get();

val = e.getFoo(); // fields returned
vak = e.getBar(); // fields returned

 

 

10.   To return your data just call one of the QueryResults methods. None of these methods affect the Query . They will leave the Query alone so you can continue to use it to retrieve new results by calling these methods again:

method	does
get()	returns the first Entity -- using limit(1)
asList()	return all items in a List -- could be costly with large result sets
fetch()	explicit method to get Iterable instance
asKeyList()	return all items in a List of their Key<T> -- This only retrieves the id field from the server.
fetchEmptyEntities()	Just like a fetch() but only retrieves, and fills in the id field.

Query q = ds.createQuery(MyEntity.class).filter("foo >", 12);

//single entity
MyEntity e = q.get();

e = q.sort("foo").get();

//for
for (MyEntity e : q)
  print(e);

//list
List<MyEntity> entities = q.asList();

 

 

11.   Validation is done on the field names, and data types used. If a field name is not found on the java class specified in the query then an exception is thrown. If the field name is in "dot" notation then each part of the expression is checked against your java object graph (with the exception of a map, where the key name is skipped). Problems in the data type (comparing the field type and parameter type) are logged as warnings since it is possible that the server can coerce the values, or that you meant to send something which didn't seem to make sense; The server uses the byte representation of the parameter so some values can match even if the data types are different (numbers for example).

 

12.   Validation can be disabled by calling disableValidation() as the beginning of the query definition, or anywhere within your query.