Default

Every model type has a natural / default ordering field and direction.

Universal, Content, and User Profile types order by their created timestamp, ascending from oldest to newest.

However keep in mind that ordered versus unordered results are also influenced by the type of query.

Custom

The Universal type supports custom ordering for the following field types:

string, integer, double, timestamp

To specify custom natural ordering on one of these field types use the order attribute set to true.

highScore:
  type: integer
  order: true

Contained Models

If a model is a child within a container, then the field names which allow custom ordering are limited to title, name, order, hierarchy.

Query Ordering

The default ordering of results is impacted by the type of query performed.

"All" / all()

Results are ordered using the default natural order of the model type. all() may also be explicitly ordered with asc() or desc().

Field Criteria

Results for field specific query criteria are unordered by default.

Ordering of field queries may be activated with asc() or desc(). However we recommend minimizing their use in this case, and relying on the unordered behavior. The typical goal of field specific query criteria is to return a relatively small set of results, at which point client side ordering is also a possibility.

Hierarchy

The hierarchy field type provides custom, manual ordering of the Universal type. When specified on a Universal model, it automatically changes the natural ordering to use this field.

Hierarchy values may be thought of as a numerical value, however for simplicity it's best to use them in relationship to other hierarchy values, and other models that already exist.

For example, given 3 existing Tasks, moving 1 of those Tasks between two others:

/**
 * Set 'moveTask' hierarchy value to a position 
 * between 'afterTask' and 'beforeTask'
 */
moveTask.hierarchy = afterTask.hierarchy.before(
  beforeTask.hierarchy
);

The "tasks" example shows basic reordering functionality using a hierarchy field.