options.txt

======================
Model ``Meta`` options
======================

This document explains all the possible :ref:`metadata options
<meta-options>` that you can give your model in its internal
``class Meta``.

Available ``Meta`` options
==========================

.. currentmodule:: django.db.models

``abstract``
------------

.. attribute:: Options.abstract

    If ``abstract = True``, this model will be an
    :ref:`abstract base class <abstract-base-classes>`.

``app_label``
-------------

.. attribute:: Options.app_label

    If a model exists outside of the standard :file:`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``
------------

.. attribute:: Options.db_table

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

        db_table = 'music_album'

.. _table-names:

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 :djadmin:`manage.py startapp <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.

.. admonition:: Use lowercase table names for MySQL

    It is strongly advised that you use lowercase table names when you override
    the table name via ``db_table``, particularly if you are using the MySQL
    backend. See the :ref:`MySQL notes <mysql-notes>` for more details.


``db_tablespace``
-----------------

.. attribute:: Options.db_tablespace

    The name of the :doc:`database tablespace </topics/db/tablespaces>` to use
    for this model. The default is the project's :setting:`DEFAULT_TABLESPACE`
    setting, if set. If the backend doesn't support tablespaces, this option is
    ignored.

``get_latest_by``
-----------------

.. attribute:: Options.get_latest_by

    The name of an orderable field in the model, typically a :class:`DateField`,
    :class:`DateTimeField`, or :class:`IntegerField`. This specifies the default
    field to use in your model :class:`Manager`'s
    :meth:`~django.db.models.query.QuerySet.latest` method.

    Example::

        get_latest_by = "order_date"

    See the :meth:`~django.db.models.query.QuerySet.latest` docs for more.

``managed``
-----------

.. attribute:: Options.managed

    Defaults to ``True``, meaning Django will create the appropriate database
    tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`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=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
       :class:`~django.db.models.ManyToManyField` that points to another
       unmanaged model, then the intermediate table for the many-to-many
       join will also not be created. However, 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 :attr:`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: :ref:`proxy-models`.

``order_with_respect_to``
-------------------------

.. attribute:: 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'

    When ``order_with_respect_to`` is set, two additional methods are provided to
    retrieve and to set the order of the related objects: ``get_RELATED_order()``
    and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For
    example, assuming that a ``Question`` object has multiple related ``Answer``
    objects, the list returned contains the primary keys of the related ``Answer``
    objects::

        >>> question = Question.objects.get(id=1)
        >>> question.get_answer_order()
        [1, 2, 3]

    The order of a ``Question`` object's related ``Answer`` objects can be set by
    passing in a list of ``Answer`` primary keys::

        >>> question.set_answer_order([3, 1, 2])

    The related objects also get two methods, ``get_next_in_order()`` and
    ``get_previous_in_order()``, which can be used to access those objects in their
    proper order. Assuming the ``Answer`` objects are ordered by ``id``::

        >>> answer = Answer.objects.get(id=2)
        >>> answer.get_next_in_order()
        <Answer: 3>
        >>> answer.get_previous_in_order()
        <Answer: 1>

.. admonition:: Changing order_with_respect_to

        ``order_with_respect_to`` adds an additional field/database column
        named ``_order``, so be sure to handle that as you would any other
        change to your models if you add or change ``order_with_respect_to``
        after your initial :djadmin:`syncdb`.

``ordering``
------------

.. attribute:: 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.

    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']

    .. versionchanged:: 1.4
       The Django admin honors all elements in the list/tuple; before 1.4, only
       the first one was respected.

``permissions``
---------------

.. attribute:: 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``
---------

.. attribute:: Options.proxy

    If ``proxy = True``, a model which subclasses another model will be treated as
    a :ref:`proxy model <proxy-models>`.

``unique_together``
-------------------

.. attribute:: Options.unique_together

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

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

    This is a tuple of tuples 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).

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

        unique_together = ("driver", "restaurant")

    A :class:`~django.db.models.ManyToManyField` cannot be included in
    unique_together. (It's not clear what that would even mean!) If you
    need to validate uniqueness related to a
    :class:`~django.db.models.ManyToManyField`, try using a signal or
    an explicit :attr:`through <ManyToManyField.through>` model.

``index_together``

.. attribute:: Options.index_together

    .. versionadded:: 1.5

    Sets of field names that, taken together, are indexed::

        index_together = [
            ["pub_date", "deadline"],
        ]

    This list of fields will be indexed together (i.e. the appropriate
    ``CREATE INDEX`` statement will be issued.)

``verbose_name``
----------------

.. attribute:: 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``
-----------------------

.. attribute:: Options.verbose_name_plural

    The plural name for the object::

        verbose_name_plural = "stories"

    If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.