Model Meta options

This document explains all the possible metadata options that you can give your model in its internal class Meta.

Available Meta options

abstract

Options.abstract

If True, this model will be an abstract base class.

app_label

Options.app_label

If a model exists outside of the standard models.py (for instance, if the app’s models are in submodules of myapp.models), the model must define which app it is part of:

app_label = 'myapp'

db_table

Options.db_table

The name of the database table to use for the model:

db_table = 'music_album'

Table names

To save you time, Django automatically derives the name of the database table from the name of your model class and the app that contains it. A model's database table name is constructed by joining the model's "app label" -- the name you used in manage.py startapp -- to the model's class name, with an underscore between them.

For example, if you have an app bookstore (as created by manage.py startapp bookstore), a model defined as class Book will have a database table named bookstore_book.

To override the database table name, use the db_table parameter in class Meta.

If your database table name is an SQL reserved word, or contains characters that aren't allowed in Python variable names -- notably, the hyphen -- that's OK. Django quotes column and table names behind the scenes.

db_tablespace

Options.db_tablespace
New in Django 1.0: Please, see the release notes

The name of the database tablespace to use for the model. If the backend doesn't support tablespaces, this option is ignored.

get_latest_by

Options.get_latest_by

The name of a DateField or DateTimeField in the model. This specifies the default field to use in your model Manager's latest method.

Example:

get_latest_by = "order_date"

See the docs for latest() for more.

managed

Options.managed
New in Django 1.1: Please, see the release notes

Defaults to True, meaning Django will create the appropriate database tables in syncdb and remove them as part of a reset management command. That is, Django manages the database tables' lifecycles.

If False, no database table creation or deletion operations will be performed for this model. This is useful if the model represents an existing table or a database view that has been created by some other means. This is the only difference when managed is False. All other aspects of model handling are exactly the same as normal. This includes

  1. Adding an automatic primary key field to the model if you don't declare it. To avoid confusion for later code readers, it's recommended to specify all the columns from the database table you are modeling when using unmanaged models.

  2. If a model with managed=False contains a ManyToManyField that points to another unmanaged model, then the intermediate table for the many-to-many join will also not be created. However, a the intermediary table between one managed and one unmanaged model will be created.

    If you need to change this default behavior, create the intermediary table as an explicit model (with managed set as needed) and use the ManyToManyField.through attribute to make the relation use your custom model.

For tests involving models with managed=False, it's up to you to ensure the correct tables are created as part of the test setup.

If you're interested in changing the Python-level behavior of a model class, you could use managed=False and create a copy of an existing model. However, there's a better approach for that situation: Proxy models.

order_with_respect_to

Options.order_with_respect_to

Marks this object as "orderable" with respect to the given field. This is almost always used with related objects to allow them to be ordered with respect to a parent object. For example, if an Answer relates to a Question object, and a question has more than one answer, and the order of answers matters, you'd do this:

class Answer(models.Model):
    question = models.ForeignKey(Question)
    # ...

    class Meta:
        order_with_respect_to = 'question'

ordering

Options.ordering

The default ordering for the object, for use when obtaining lists of objects:

ordering = ['-order_date']

This is a tuple or list of strings. Each string is a field name with an optional "-" prefix, which indicates descending order. Fields without a leading "-" will be ordered ascending. Use the string "?" to order randomly.

Note

Regardless of how many fields are in ordering, the admin site uses only the first field.

For example, to order by a pub_date field ascending, use this:

ordering = ['pub_date']

To order by pub_date descending, use this:

ordering = ['-pub_date']

To order by pub_date descending, then by author ascending, use this:

ordering = ['-pub_date', 'author']

permissions

Options.permissions

Extra permissions to enter into the permissions table when creating this object. Add, delete and change permissions are automatically created for each object that has admin set. This example specifies an extra permission, can_deliver_pizzas:

permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)

This is a list or tuple of 2-tuples in the format (permission_code, human_readable_permission_name).

proxy

Options.proxy
New in Django 1.1: Please, see the release notes

If set to True, a model which subclasses another model will be treated as a proxy model.

unique_together

Options.unique_together

Sets of field names that, taken together, must be unique:

unique_together = (("driver", "restaurant"),)

This is a list of lists of fields that must be unique when considered together. It's used in the Django admin and is enforced at the database level (i.e., the appropriate UNIQUE statements are included in the CREATE TABLE statement).

New in Django 1.0: Please, see the release notes

For convenience, unique_together can be a single list when dealing with a single set of fields:

unique_together = ("driver", "restaurant")

verbose_name

Options.verbose_name

A human-readable name for the object, singular:

verbose_name = "pizza"

If this isn't given, Django will use a munged version of the class name: CamelCase becomes camel case.

verbose_name_plural

Options.verbose_name_plural

The plural name for the object:

verbose_name_plural = "stories"

If this isn't given, Django will use verbose_name + "s".