7.x field.api.php hook_field_schema($field)

Define the Field API schema for a field structure.

This is invoked when a field is created, in order to obtain the database schema from the module that defines the field's type.

This hook must be defined in the module's .install file for it to be detected during installation and upgrade.


$field: A field structure.

Return value

An associative array with the following keys:

  • columns: An array of Schema API column specifications, keyed by column name. This specifies what comprises a value for a given field. For example, a value for a number field is simply 'value', while a value for a formatted text field is the combination of 'value' and 'format'. It is recommended to avoid having the column definitions depend on field settings when possible. No assumptions should be made on how storage engines internally use the original column name to structure their storage.
  • indexes: (optional) An array of Schema API indexes definitions. Only columns that appear in the 'columns' array are allowed. Those indexes will be used as default indexes. Callers of field_create_field() can specify additional indexes, or, at their own risk, modify the default indexes specified by the field-type module. Some storage engines might not support indexes.
  • foreign keys: (optional) An array of Schema API foreign keys definitions.

Related topics

7 functions implement hook_field_schema()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

field_test_field_schema in modules/field/tests/field_test.install
Implements hook_field_schema().
file_field_schema in modules/file/file.install
Implements hook_field_schema().
image_field_schema in modules/image/image.install
Implements hook_field_schema().
list_field_schema in modules/field/modules/list/list.install
Implements hook_field_schema().
number_field_schema in modules/field/modules/number/number.install
Implements hook_field_schema().

... See full list

7 invocations of hook_field_schema()
drupal_get_complete_schema in includes/bootstrap.inc
Gets the whole database schema.
drupal_get_schema_unprocessed in includes/common.inc
Returns the unprocessed and unaltered version of a module's schema.
field_create_field in modules/field/field.crud.inc
Creates a field.
field_read_fields in modules/field/field.crud.inc
Reads in fields that match an array of conditions.
field_update_7001 in modules/field/field.install
Fix fields definitions created during the d6 to d7 upgrade path.

... See full list


modules/field/field.api.php, line 241
Hooks provided by the Field module.


function hook_field_schema($field) {
  if ($field['type'] == 'text_long') {
    $columns = array(
      'value' => array(
        'type' => 'text',
        'size' => 'big',
        'not null' => FALSE,
  else {
    $columns = array(
      'value' => array(
        'type' => 'varchar',
        'length' => $field['settings']['max_length'],
        'not null' => FALSE,
  $columns += array(
    'format' => array(
      'type' => 'varchar',
      'length' => 255,
      'not null' => FALSE,
  return array(
    'columns' => $columns,
    'indexes' => array(
      'format' => array('format'),
    'foreign keys' => array(
      'format' => array(
        'table' => 'filter_format',
        'columns' => array('format' => 'format'),


TwoD’s picture

On Converting 6.x modules to 7.x - Categorical:
Database schema (un)installed automatically.
I would assume the same applies for this hook, but please correct me if I'm wrong.

eustace’s picture

Is there an equivalent of hook_schema_alter() for hook_field_schema()? How does one go about altering a core module field schema (e.g. image module) in contrib space? Guidance would be much appreciated.

podarok’s picture

matiasMGS’s picture

in what table is this stored?

Spaceninja7u’s picture

Your shema definition results in new tables for your module to use rather than working with the tables that support drupal's core.

Dave Reid’s picture

Because field_create_field() is called before the user can edit any settings in the Field UI, and because field_create_field() is the function that leads to this call, this means that any "settings" in the $field array are the defaults provided by hook_field_info() and not user-customized settings.

So only use the information in $field to vary your schema based on constant things like the field type, like text_field_schema() does.

inventlogic’s picture

For a custom field that uses a schema like the text module as shown at https://api.drupal.org/api/drupal/modules!field!modules!text!text.instal... you can include the schema definition in the module file not an install file.

dahousecat’s picture

Your link shows that text_field_schema is inside text.install. Are you sure you can include hook_field_schema in the module file?

rocket777’s picture

Yes you can.
But best to keep in .install file

Alireza Tabatabaeian’s picture

In a drupalize.me tutorial (Drupal 7 Field API : Defining a field schema for database storage) , they were gonna save to values for the field , so they implemented two columns in the schema , but no code were entered to specify a relation between the columns and values . So I guess its based on the index of values in the $field value. Am I right? now what if we are not going to implement the columns in the same manner?

hgoto’s picture

Drupal 8 removed hook_field_schema() and introduced Field type plugin system.

This change record helps: Field types are now plugins https://www.drupal.org/node/2064123

dfish17’s picture

Anyone know how to implement radio buttons with hook_field_info and hook_field_schema?