field_attach_query

Versions
7: field_attach_query($field_id, $conditions, $options = array())

Retrieve objects matching a given set of conditions.

Note that the query 'conditions' only apply to the stored values. In a regular field_attach_load() call, field values additionally go through hook_field_load() and hook_field_attach_load() invocations, which can add to or affect the raw stored values. The results of field_attach_query() might therefore differ from what could be expected by looking at a regular, fully loaded object.

Throws a FieldQueryException if the field's storage doesn't support the specified conditions.

Parameters

$field_id The id of the field to query.

$conditions An array of query conditions. Each condition is a numerically indexed array, in the form: array(column, value, operator). Not all storage engines are required to support queries on all column, or with all operators below. A FieldQueryException will be raised if an unsupported condition is specified. Supported columns:

any of the columns for $field_name's field type: condition on field value,
'type': condition on object type (e.g. 'node', 'user'...),
'bundle': condition on object bundle (e.g. node type),
'entity_id': condition on object id (e.g node nid, user uid...),
'deleted': condition on whether the field's data is marked deleted for the object (defaults to FALSE if not specified)

The field_attach_query_revisions() function additionally supports:

'revision_id': condition on object revision id (e.g node vid).

Supported operators:

'=', '!=', '>', '>=', '<', '<=', 'STARTS_WITH', 'ENDS_WITH', 'CONTAINS': these operators expect the value as a literal of the same type as the column,
'IN', 'NOT IN': this operator expects the value as an array of literals of the same type as the column.
'BETWEEN': this operator expects the value as an array of two literals of the same type as the column.

The operator can be ommitted, and will default to 'IN' if the value is an array, or to '=' otherwise. Example values for $conditions:

<?php

array(
array('type', 'node'),
);
array(
array('bundle', array('article', 'page')),
array('value', 12, '>'),
);

?>

$options An associative array of additional options:

limit: The number of results that is requested. This is only a

hint to the storage engine(s); callers should be prepared to handle fewer or more results. Specify FIELD_QUERY_NO_LIMIT to retrieve all available objects. This option has a default value of 0 so callers must make an explicit choice to potentially retrieve an enormous result set.

cursor: A reference to an opaque cursor that allows a caller to

iterate through multiple result sets. On the first call, pass 0; the correct value to pass on the next call will be written into the value on return. When there is no more query data available, the value will be filled in with FIELD_QUERY_COMPLETE. If cursor is passed as NULL, the first result set is returned and no next cursor is returned.

count: If TRUE, return a single count of all matching objects;

limit and cursor are ignored.

age: Internal use only. Use field_attach_query_revisions()

instead of passing FIELD_LOAD_REVISION.

FIELD_LOAD_CURRENT (default): query the most recent revisions for all

objects. The results will be keyed by object type and object id.

FIELD_LOAD_REVISION: query all revisions. The results will be keyed by

object type and object revision id.

Return value

An array keyed by object type (e.g. 'node', 'user'...), then by object id or revision id (depending of the value of the $age parameter). The values are pseudo-objects with the bundle, id, and revision id fields filled in.

▸ 6 functions call field_attach_query()

▾ 6 functions call field_attach_query()

field_attach_query_revisions in modules/field/field.attach.inc: Retrieve object revisions matching a given set of conditions.
field_has_data in modules/field/field.module: Determine whether a field has any data.
field_purge_batch in modules/field/field.crud.inc: Purges a batch of deleted Field API data, instances, or fields.
file_get_file_references in modules/file/file.module: Get a list of references to a file.
hook_field_update_field_forbid in modules/field/field.api.php: Forbid a field update from occurring.
_taxonomy_clean_field_cache in modules/taxonomy/taxonomy.module: Helper function that clears field cache when terms are updated or deleted

Code

modules/field/field.attach.inc, line 1057

<?php
function field_attach_query($field_id, $conditions, $options = array()) {
  // Merge in default options.
  $default_options = array(
    'limit' => 0,
    'cursor' => 0,
    'count' => FALSE,
    'age' => FIELD_LOAD_CURRENT,
  );
  $options += $default_options;

  // Give a chance to 3rd party modules that bypass the storage engine to
  // handle the query.
  $skip_field = FALSE;
  foreach (module_implements('field_storage_pre_query') as $module) {
    $function = $module . '_field_storage_pre_query';
    $results = $function($field_id, $conditions, $options, $skip_field);
    // Stop as soon as a module claims it handled the query.
    if ($skip_field) {
      break;
    }
  }
  // If the request hasn't been handled, let the storage engine handle it.
  if (!$skip_field) {
    $field = field_info_field_by_id($field_id);
    $function = $field['storage']['module'] . '_field_storage_query';
    $results = $function($field_id, $conditions, $options);
  }

  return $results;
}
?>