1 ======================

     2 Model ``Meta`` options

     3 ======================

     4 

     5 This document explains all the possible :ref:`metadata options

     6 <meta-options>` that you can give your model in its internal ``class

     7 Meta``.

     8 

     9 Available ``Meta`` options

    10 ==========================

    11 

    12 .. currentmodule:: django.db.models

    13 

    14 ``abstract``

    15 ------------

    16 

    17 .. attribute:: Options.abstract

    18 

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

    20 

    21 ``app_label``

    22 -------------

    23 

    24 .. attribute:: Options.app_label

    25 

    26 If a model exists outside of the standard :file:`models.py` (for instance, if

    27 the app's models are in submodules of ``myapp.models``), the model must define

    28 which app it is part of::

    29 

    30     app_label = 'myapp'

    31 

    32 ``db_table``

    33 ------------

    34 

    35 .. attribute:: Options.db_table

    36 

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

    38 

    39     db_table = 'music_album'

    40 

    41 .. _table-names:

    42 

    43 Table names

    44 ~~~~~~~~~~~

    45 

    46 To save you time, Django automatically derives the name of the database table

    47 from the name of your model class and the app that contains it. A model's

    48 database table name is constructed by joining the model's "app label" -- the

    49 name you used in ``manage.py startapp`` -- to the model's class name, with an

    50 underscore between them.

    51 

    52 For example, if you have an app ``bookstore`` (as created by

    53 ``manage.py startapp bookstore``), a model defined as ``class Book`` will have

    54 a database table named ``bookstore_book``.

    55 

    56 To override the database table name, use the ``db_table`` parameter in

    57 ``class Meta``.

    58 

    59 If your database table name is an SQL reserved word, or contains characters that

    60 aren't allowed in Python variable names -- notably, the hyphen -- that's OK.

    61 Django quotes column and table names behind the scenes.

    62 

    63 ``db_tablespace``

    64 -----------------

    65 

    66 .. attribute:: Options.db_tablespace

    67 

    68 .. versionadded:: 1.0

    69 

    70 The name of the database tablespace to use for the model. If the backend doesn't

    71 support tablespaces, this option is ignored.

    72 

    73 ``get_latest_by``

    74 -----------------

    75 

    76 .. attribute:: Options.get_latest_by

    77 

    78 The name of a :class:`DateField` or :class:`DateTimeField` in the model. This

    79 specifies the default field to use in your model :class:`Manager`'s

    80 :class:`~QuerySet.latest` method.

    81 

    82 Example::

    83 

    84     get_latest_by = "order_date"

    85 

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

    87 

    88 ``managed``

    89 -----------------------

    90 

    91 .. attribute:: Options.managed

    92 

    93 .. versionadded:: 1.1

    94 

    95 Defaults to ``True``, meaning Django will create the appropriate database

    96 tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`

    97 management command. That is, Django *manages* the database tables' lifecycles.

    98 

    99 If ``False``, no database table creation or deletion operations will be

   100 performed for this model. This is useful if the model represents an existing

   101 table or a database view that has been created by some other means. This is

   102 the *only* difference when ``managed`` is ``False``. All other aspects of

   103 model handling are exactly the same as normal. This includes

   104 

   105     1. Adding an automatic primary key field to the model if you don't declare

   106        it.  To avoid confusion for later code readers, it's recommended to

   107        specify all the columns from the database table you are modeling when

   108        using unmanaged models.

   109 

   110     2. If a model with ``managed=False`` contains a

   111        :class:`~django.db.models.ManyToManyField` that points to another

   112        unmanaged model, then the intermediate table for the many-to-many join

   113        will also not be created. However, a the intermediary table between one

   114        managed and one unmanaged model *will* be created.

   115 

   116        If you need to change this default behavior, create the intermediary

   117        table as an explicit model (with ``managed`` set as needed) and use the

   118        :attr:`ManyToManyField.through` attribute to make the relation use your

   119        custom model.

   120 

   121 For tests involving models with ``managed=False``, it's up to you to ensure

   122 the correct tables are created as part of the test setup.

   123 

   124 If you're interested in changing the Python-level behavior of a model class,

   125 you *could* use ``managed=False`` and create a copy of an existing model.

   126 However, there's a better approach for that situation: :ref:`proxy-models`.

   127 

   128 ``order_with_respect_to``

   129 -------------------------

   130 

   131 .. attribute:: Options.order_with_respect_to

   132 

   133 Marks this object as "orderable" with respect to the given field. This is almost

   134 always used with related objects to allow them to be ordered with respect to a

   135 parent object. For example, if an ``Answer`` relates to a ``Question`` object,

   136 and a question has more than one answer, and the order of answers matters, you'd

   137 do this::

   138 

   139     class Answer(models.Model):

   140         question = models.ForeignKey(Question)

   141         # ...

   142 

   143         class Meta:

   144             order_with_respect_to = 'question'

   145 

   146 When ``order_with_respect_to`` is set, two additional methods are provided to

   147 retrieve and to set the order of the related objects: ``get_RELATED_order()``

   148 and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For

   149 example, assuming that a ``Question`` object has multiple related ``Answer``

   150 objects, the list returned contains the primary keys of the related ``Answer``

   151 objects::

   152 

   153     >>> question = Question.objects.get(id=1)

   154     >>> question.get_answer_order()

   155     [1, 2, 3]

   156 

   157 The order of a ``Question`` object's related ``Answer`` objects can be set by

   158 passing in a list of ``Answer`` primary keys::

   159 

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

   161 

   162 The related objects also get two methods, ``get_next_in_order()`` and

   163 ``get_previous_in_order()``, which can be used to access those objects in their

   164 proper order. Assuming the ``Answer`` objects are ordered by ``id``::

   165 

   166     >>> answer = Answer.objects.get(id=2)

   167     >>> answer.get_next_in_order()

   168     <Answer: 3>

   169     >>> answer.get_previous_in_order()

   170     <Answer: 1>

   171 

   172 ``ordering``

   173 ------------

   174 

   175 .. attribute:: Options.ordering

   176 

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

   178 

   179     ordering = ['-order_date']

   180 

   181 This is a tuple or list of strings. Each string is a field name with an optional

   182 "-" prefix, which indicates descending order. Fields without a leading "-" will

   183 be ordered ascending. Use the string "?" to order randomly.

   184 

   185 .. note::

   186 

   187     Regardless of how many fields are in :attr:`~Options.ordering`, the admin

   188     site uses only the first field.

   189 

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

   191 

   192     ordering = ['pub_date']

   193 

   194 To order by ``pub_date`` descending, use this::

   195 

   196     ordering = ['-pub_date']

   197 

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

   199 

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

   201 

   202 ``permissions``

   203 ---------------

   204 

   205 .. attribute:: Options.permissions

   206 

   207 Extra permissions to enter into the permissions table when creating this object.

   208 Add, delete and change permissions are automatically created for each object

   209 that has ``admin`` set. This example specifies an extra permission,

   210 ``can_deliver_pizzas``::

   211 

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

   213 

   214 This is a list or tuple of 2-tuples in the format ``(permission_code,

   215 human_readable_permission_name)``.

   216 

   217 ``proxy``

   218 ---------

   219 

   220 .. attribute:: Options.proxy

   221 

   222 .. versionadded:: 1.1

   223 

   224 If set to ``True``, a model which subclasses another model will be treated as

   225 a :ref:`proxy model <proxy-models>`.

   226 

   227 ``unique_together``

   228 -------------------

   229 

   230 .. attribute:: Options.unique_together

   231 

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

   233 

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

   235 

   236 This is a list of lists of fields that must be unique when considered together.

   237 It's used in the Django admin and is enforced at the database level (i.e., the

   238 appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``

   239 statement).

   240 

   241 .. versionadded:: 1.0

   242 

   243 For convenience, unique_together can be a single list when dealing with a single

   244 set of fields::

   245 

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

   247 

   248 ``verbose_name``

   249 ----------------

   250 

   251 .. attribute:: Options.verbose_name

   252 

   253 A human-readable name for the object, singular::

   254 

   255     verbose_name = "pizza"

   256 

   257 If this isn't given, Django will use a munged version of the class name:

   258 ``CamelCase`` becomes ``camel case``.

   259 

   260 ``verbose_name_plural``

   261 -----------------------

   262 

   263 .. attribute:: Options.verbose_name_plural

   264 

   265 The plural name for the object::

   266 

   267     verbose_name_plural = "stories"

   268 

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