8.2.x field.purge.inc field_purge_batch($batch_size, $field_storage_uuid = NULL)
8.0.x field.purge.inc field_purge_batch($batch_size, $field_storage_uuid = NULL)
8.1.x field.purge.inc field_purge_batch($batch_size, $field_storage_uuid = NULL)
7.x field.crud.inc field_purge_batch($batch_size)

Purges a batch of deleted Field API data, instances, or fields.

This function will purge deleted field data in batches. The batch size is defined as an argument to the function, and once each batch is finished, it continues with the next batch until all have completed. If a deleted field instance with no remaining data records is found, the instance itself will be purged. If a deleted field with no remaining field instances is found, the field itself will be purged.


$batch_size: The maximum number of field data records to purge before returning.

Related topics

5 calls to field_purge_batch()
FieldBulkDeleteTestCase::testPurgeField in modules/field/tests/field.test
Verify that fields are preserved and purged correctly as multiple instances are deleted and purged.
FieldBulkDeleteTestCase::testPurgeInstance in modules/field/tests/field.test
Verify that field data items and instances are purged when an instance is deleted.
field_cron in modules/field/field.module
Implements hook_cron().
field_ui_field_delete_form_submit in modules/field_ui/field_ui.admin.inc
Form submission handler for field_ui_field_delete_form().
forum_uninstall in modules/forum/forum.install
Implements hook_uninstall().


modules/field/field.crud.inc, line 880
Field CRUD API, handling field and field instance creation and deletion.


function field_purge_batch($batch_size) {
  // Retrieve all deleted field instances. We cannot use field_info_instances()
  // because that function does not return deleted instances.
  $instances = field_read_instances(array('deleted' => 1), array('include_deleted' => 1));

  foreach ($instances as $instance) {
    // field_purge_data() will need the field array.
    $field = field_info_field_by_id($instance['field_id']);
    // Retrieve some entities.
    $query = new EntityFieldQuery();
    $results = $query
      ->entityCondition('bundle', $instance['bundle'])
      ->range(0, $batch_size)

    if ($results) {
      foreach ($results as $entity_type => $stub_entities) {
        field_attach_load($entity_type, $stub_entities, FIELD_LOAD_CURRENT, array('field_id' => $field['id'], 'deleted' => 1));
        foreach ($stub_entities as $stub_entity) {
          // Purge the data for the entity.
          field_purge_data($entity_type, $stub_entity, $field, $instance);
    else {
      // No field data remains for the instance, so we can remove it.

  // Retrieve all deleted fields. Any that have no instances can be purged.
  $fields = field_read_fields(array('deleted' => 1), array('include_deleted' => 1));
  foreach ($fields as $field) {
    $instances = field_read_instances(array('field_id' => $field['id']), array('include_deleted' => 1));
    if (empty($instances)) {


brycefisherfleig’s picture

I don't totally get how it's used. According to an inline comment in field_ui_field_delete_form_submit:

// Fields are purged on cron. However field module prevents disabling modules
// when field types they provided are used in a field until it is fully
// purged. In the case that a field has minimal or no content, a single call
// to field_purge_batch() will remove it from the system. Call this with a
// low batch limit to avoid administrators having to wait for cron runs when
// removing instances that meet this criteria.

Does that mean that this $limit is how many items are happening in the cron run or batch operation?

aaronbauman’s picture

Does that mean that this $limit is how many items are happening in the cron run or batch operation?


_grizly’s picture

Find them all with:

FROM information_schema.tables