# Import / Export API Reference: db engines

This document provides a programmer's reference to the db get and db put engines of the Drupal Import / Export API. For an explanation of the field types and their core properties, see the main Import / Export API reference document.

Skip to: Properties

## Fields and properties matrix

Legend:
X = property can be used with this field type
- = this property is not applicable to this field type

#type | array | datetime | entity | file | float | freeform | int | serialized | string
--- | --- | --- | --- | --- | --- | --- | --- | --- | ---
#db_default_table | X | - | X | - | - | - | - | - | -
#db_do_query | X | - | X | - | - | - | - | - | -
#db_field | - | X | - | X | X | X | X | X | X
#db_field_unaliased | - | X | - | X | X | X | X | X | X
#db_filter | - | X | - | X | X | X | X | X | X
#db_force_generate_id | - | - | - | - | - | - | X | - | -
#db_generate_id | - | - | - | - | - | - | X | - | -
#db_is_insert | X | - | X | - | - | - | - | - | -
#db_keys | X | - | X | - | - | - | - | - | -
#db_reference_delta | - | - | - | - | - | - | X | - | X
#db_reference_field | - | - | - | - | - | - | X | - | X
#db_reference_field_unaliased | - | - | - | - | - | - | X | - | X
#db_reference_parent | - | - | - | - | - | - | X | - | X
#db_reference_table | - | - | - | - | - | - | X | - | X
#db_resolved_alt_key | - | - | - | - | - | - | X | - | -
#db_table | - | X | - | X | X | X | X | X | X
#db_update_existing | - | - | - | - | - | - | X | - | -
#db_uses_sequences | - | - | - | - | - | - | X | - | -
#db_value_old | - | - | - | - | - | - | X | - | -

## Properties

### #db_default_table

Used by: entity, array.

Description: The default value to assign to the #db_table property for all direct children of this field. This value is not assigned to child fields if they explicitly define their #db_table property.

Values: An unprefixed database table name. The table name must be one that is defined through `hook_db_def_tables()`.

Default value: inherited from the #id property of this field.

Usage example: (importexportapi_user.inc):

`<?php
$def = array(
'#type' => 'entity',
'#title' => t('User'),
'#db_default_table' => 'users',
'#xml_plural' => 'users',
'#csv_plural' => 'users'
);
?>`

### #db_do_query

Used by: entity, array.

Description: INTERNAL. Indicates whether or not the query for this entity or array should be prepared and executed.

Values: Boolean.

Default value: TRUE

Usage example: NONE

### #db_field

Used by: ALL types except entity, array.

Description: The field name that should be used when retrieving this field in database queries. This is different to #db_field_unaliased, in that it does not have to correspond to the actual name of the field in the database. Every direct child of an entity or array field should have a unique value for this property and for the #db_reference_field property.

Values: A database field querying name.

Default value: inherited from the #id property of this field.

Usage example: NONE

### #db_field_unaliased

Used by: ALL types except entity, array.

Description: The name of this field in the database. Should NOT be confused with #db_field, which is the name used to query this field in the database.

Values: A database field name.

Default value: inherited from the #id property of this field.

Usage example: (importexportapi_user.inc):

`<?php
$def['perm_rid'] = array(
'#type' => 'int',
'#title' => t('Role ID'),
'#reference_entity' => 'role',
'#reference_field' => array('rid'),
'#db_table' => 'permission',
'#db_field_unaliased' => 'rid',
'#key_component' => TRUE,
'#csv_hidden' => TRUE
);
?>`

### #db_filter

Used by: ALL types except entity, array.

Description: A filtering rule to be applied to this field when querying it from the database. The rule has a special syntax which is represented as a simple array.

Values: An optional 'operator' property (defaults to 'eq'), which can be 'eq', 'neq', or any valid SQL comparison operator; and a 'values' property, which can be an array of values (each of the correct type) when 'operator' is 'eq' or 'neq', or else whatever value is appropriate for the 'operator' value that is being used.

Default value: NULL

Usage example: (importexportapi_block.inc):

`<?php
$defs['block']['module']['#db_filter'] = array(
'values' => array('block'),
'operator' => 'neq'
);
?>`

### #db_force_generate_id

Used by: int.

Description: When set to TRUE, forces a new value to be generated for this field (from the database) during a db 'put' operation, even if one was already provided. Should generally be used in combination with the #db_generate_id property. Only applies to fields with a #key value of TRUE.

Values: Boolean.

Default value: NULL

Usage example: NONE

### #db_generate_id

Used by: int.

Description: When set to TRUE, indicates that a new value is to be generated for this field (from the database) during a db 'put' operation, if none has been provided. Only applies to fields with a #key value of TRUE.

Values: Boolean.

Default value: TRUE

Usage example: NONE

### #db_is_insert

Used by: entity, array.

Description: INTERNAL. Indicates whether the query for this entity or array is to be an SQL INSERT or UPDATE query.

Values: Boolean.

Default value: TRUE

Usage example: NONE

### #db_keys

Used by: entity, array.

Description: INTERNAL. The list of database fields that make up the unique identifier for this entity or array field. This list always consists of the #db_field_unaliased values for each field in the #keys property of this field.

Values: Array of database field names.

Default value: n/a

Usage example: NONE

### #db_reference_delta

Used by: int, string.

Description: If separate instances of a particular entity or array are referenced by multiple fields that are children of the same entity or array, then each referencing field will need to set a different delta value. This allows for a separate join to be performed on each instance, when executing database queries on the entity or array that is the parent of this field.

Values: Integer (must be > 0).

Default value: inherited from the #reference_delta value of this field.

Usage example: NONE

### #db_reference_field

Used by: int, string.

Description: The field name that should be used when retrieving the field that this field is referencing in database queries. This is different to #db_reference_field_unaliased, in that it does not have to correspond to the actual name of the referenced field in the database. Every direct child of an entity or array field should have a unique value for this property and for the #db_field property. Only applies to fields with a non-empty #reference_entity value.

Values: A database field querying name.

Default value: inherited from the #db_field property of the field that this field is referencing.

Usage example: NONE

### #db_reference_field_unaliased

Used by: int, string.

Description: The name of the field that this field is referencing in the database. Should NOT be confused with #db_reference_field, which is the name used to query the referenced field in the database. Only applies to fields with a non-empty #reference_entity value.

Values: A database field name.

Default value: inherited from the #db_field_unaliased property of the field that this field is referencing.

Usage example: NONE

### #db_reference_parent

Used by: int, string.

Description: Allows this field to NOT be a reference to a field within its parent's parent. By default, all fields that reference a field within the parent entity or array of their parent are used for parent-child linking. Setting this value to FALSE will reverse this behaviour, and will stop this field from being used for parent-child linking. This property should generally be used in conjunction with #db_reference_delta.

Values: Boolean.

Default value: inherited from the #reference_parent value of this field.

Usage example: NONE

### #db_reference_table

Used by: int, string.

Description: The name of the database table for the field that this field is referencing. Only applies to fields with a non-empty #reference_entity value.

Values: An unprefixed database table name. The table name must be one that is defined through `hook_db_def_tables()`.

Default value: inherited from the #db_table property of the field that this field is referencing.

Usage example: NONE

### #db_resolved_alt_key

Used by: int.

Description: INTERNAL. Stores the database name of the alternate key field that was used to resolve this field during a db 'put' operation (if any).

Values: A database field querying name.

Default value: NULL

Usage example: NONE

### #db_table

Used by: ALL types except entity, array.

Description: The name of the database table for this field. Should NOT be confused with #db_field, which is the name used to query this field in the database.

Values: An unprefixed database table name. The table name must be one that is defined through `hook_db_def_tables()`.

Default value: inherited from the #db_default_table property of this field's direct parent entity or array.

Usage example: (importexportapi_user.inc):

`<?php
$def['perm'] = array(
'#type' => 'freeform',
'#title' => t('Permission list'),
'#default_value' => NULL,
'#xml_plural' => 'permissions',
'#csv_plural' => 'permissions',
'#db_table' => 'permission'
);
?>`

### #db_update_existing

Used by: int.

Description: When set to TRUE, indicates that existing database entries that match this field should be updated (rather than new entries being inserted, and old entries left as-is) during a db 'put' operation, if existing entries can be found. Only applies to fields with a #key or #key_component value of TRUE, or with a non-empty #reference_entity value.

Values: Boolean.

Default value: TRUE

Usage example: NONE

### #db_uses_sequences

Used by: int.

Description: When set to TRUE, indicates that Drupal's custom database sequencing system (i.e. the 'sequences table' system) should be used when generating a new value for this field, instead of relying on in-built database sequencing / incrementing. Only applies to fields with a #key value of TRUE.

Values: Boolean.

Default value: NULL

Usage example: (importexportapi_user.inc):

`<?php
$def['uid'] = array(
'#type' => 'int',
'#title' => t('User ID'),
'#key' => TRUE,
'#db_uses_sequences' => TRUE
);
?>`

### #db_value_old

Used by: int.

Description: INTERNAL. Stores the original value of this field during a db 'put' operation, in case a new value was database-generated for this field.

Values: Integer.

Default value: inherited from the #value property of this field. Only applies to fields with a #key value of TRUE.

Usage example: NONE