query.textile

Using Query

Summary

Query<T> is the main entry point for:

• Fetching/iterating/paginating/counting through those multiple entities
• Updating/deleting multiple entities depending on criteria (filters, orders, aggregators, owners…)

Query<T> provides:

• Fluent API (each functions of query returns a Query<T>) to refine the criteria of the query.
• Terminal actions to fulfill the real business job of fetching/iterating over entities in the datastore

Query<T> instances are:

• NOT THREADSAFE because they may keep a context (for pagination for ex) so don’t call one instance of query from multiple threads or do it because you know what you do.
• Stateless by default regarding offsets/limits/cursors (not for pagination naturally) so each call to a query terminal action starts at first entity again.
• Stateful on demand regarding offsets/limits so it keeps the current limit/offset/cursor in the DB.

Creating a Query<T>

Query<YourModel> query = Model.all(YourModel.class);

Sometimes, you are lazy (like me) and don’t want to repeat the classname in the all(). Thus, in your Model, you can override this function by a simpler one:

public class YourModel extends Model{
...
	Query<YourModel> all() { return Model.all(YourModel.class); }	
...
}

Basic features of Query<T>

Fetch entities of a class in a list

List<YourModel> objects = Model.all(YourModel.class).fetch();
for(YourModel obj: objects{
...
// DOIT
...
}

// you can also set a limit in the number of objects
List<YourModel> objects_0_10 = Model.all(YourModel.class).fetch(10);

// you can also set a limit and an offset in the number of objects
List<YourModel> objects_5_15 = Model.all(YourModel.class).fetch(10, 5);

In this case, you don’t add any filtering criterion so you retrieve all entities. Be careful if the number of such entities is huge!

Iterate through entities of a class

Iterable<YourModel> iter = Model.all(YourModel.class).iter();
Iterator<YourModel> it = iter.iterator();

while(it.hasNext()) {
YourModel obj = it.next();
...

// DOIT
...
}

// you can also set a limit in the number of objects
Iterable<YourModel> iter_0_10 = Model.all(YourModel.class).iter(10);

// you can also set a limit and an offset in the number of objects
Iterable<YourModel> iter_5_15 = Model.all(YourModel.class).iter(10, 5);

Understand difference between iter and fetch :
– fetch performs the datastore query and retrieves all raw entities and then immediately maps them into your Java models. If you have lots of results and heavy models, the mapping can be quite long.
– iter performs the datastore query and retrieves all raw entities BUT IT DOESN’T MAP them into Java models immediately. The mapping is performed at each call to it.next(). Thus, if the mapping is long, you can split the mapping load across your code.

Get the first model of a class

YourModel object = Model.all(YourModel.class).get(); 

It returns the first model retrieved from the datastore according to its index for these entities.

Filter on a field

List<YourModel> objects = Model.all(YourModel.class).filter("myField", "myValue").fetch();

It returns the entities have myField value equal to myValue.

The filter is done on the name of the field so be careful not to type a wrong name. This is a limitation of Java which is not a language allowing to create dynamic type safe APIs.

The value to filter on is an object and can be of any type: a Long, a Double, another model for relations etc…

Order on a field

List<YourModel> objects = Model.all(YourModel.class).order("myField-").fetch();

It returns the entities in descendant order according to myField.

Paginate your entities

Query<YourModel> query = Model.all(YourModel.class).paginate(10);
List<YourModel> firstPage = query.fetch();
List<YourModel> secondPage = query.nextPage().fetch();
Iterable<YourModel> thirdPage query.nextPage().iter();
List<YourModel> secondPageAgain = query.previousPage().fetch();
...

Here you can easily understand the query keeps in memory the context of the current page to be able to go to next or previous page.

Count all entities of a class

in nb = Model.all(YourModel.class).count();

It returns the number of entities.

Delete all entities of a class

in nbDeleted = Model.all(YourModel.class).delete();

It returns the number of entities deleted.

Detailed features of Query<T>

First remind that you can mix almost all those functions with each other. If you mix something forbidden, don’t worry, Siena will throw an Exception to tell you!

UNDER CONSTRUCTION
TO BE CONTINUED…