7.x entity.inc EntityFieldQuery::fieldOrderBy($field, $column, $direction = 'ASC')

Orders the result set by a given field column.

If called multiple times, the query will order by each specified column in the order this method is called. Note that entities with empty field values will be excluded from the EntityFieldQuery results when using this method.


$field: Either a field name or a field array.

$column: A column defined in the hook_field_schema() of this field. entity_id and bundle can also be used.

$direction: The direction to sort. Legal values are "ASC" and "DESC".

Return value

EntityFieldQuery The called object.

1 call to EntityFieldQuery::fieldOrderBy()
EntityFieldQuery::tableSort in includes/entity.inc
Enables sortable tables for this query.


includes/entity.inc, line 950


Retrieves entities matching a given set of conditions.


public function fieldOrderBy($field, $column, $direction = 'ASC') {
  if (is_scalar($field)) {
    $field_definition = field_info_field($field);
    if (empty($field_definition)) {
      throw new EntityFieldQueryException(t('Unknown field: @field_name', array(
        '@field_name' => $field,
    $field = $field_definition;

  // Save the index used for the new field, for later use in field storage.
  $index = count($this->fields);
  $this->fields[$index] = $field;
  $this->order[] = array(
    'type' => 'field',
    'specifier' => array(
      'field' => $field,
      'index' => $index,
      'column' => $column,
    'direction' => $direction,
  return $this;


jordisan’s picture

What's the expected behavior for empty field values?

I'm afraid that currently, fieldOrderBy filters outs results where the field specified does not have a value. I don't think this is a proper behavior, so I've opened an issue: http://drupal.org/node/1611438

kris-o3’s picture

personally i think that's a desirable side-effect. in your opinion, if a field is null, should it appear first or last when in ascending order? i'd rather have nodes that contain a value in that field, ordered properly.

anthonys’s picture

Note if you want to sort by the field contents, $column should be the string: 'value'.

actorRunning’s picture

The $column variable depends on the field type. I.e., text and integer fields use 'value' as the column, but entity reference fields use 'target_id'.

Please do your homework.