django/docs/ref/models/options.txt

209 lines
5.9 KiB
Plaintext
Raw Normal View History

.. _ref-models-options:
======================
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 ``True``, this model will be an :ref:`abstract base class <abstract-base-classes>`.
``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 ``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``
-----------------
.. attribute:: Options.db_tablespace
.. versionadded:: 1.0
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``
-----------------
.. attribute:: Options.get_latest_by
The name of a :class:`DateField` or :class:`DateTimeField` in the model. This
specifies the default field to use in your model :class:`Manager`'s
:class:`~QuerySet.latest` method.
Example::
get_latest_by = "order_date"
See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
``managed``
-----------------------
.. attribute:: Options.managed
.. versionadded:: 1.1
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.
The default value is ``True``, meaning Django will create the appropriate
database tables in :ref:`django-admin-syncdb` and remove them as part of a
:ref:`reset <django-admin-reset>` management command.
If a model contains a :class:`~django.db.models.ManyToManyField` and has
``managed=False``, the intermediate table for the many-to-many join will also
not be created. Should you require the intermediate table to be created, set
it up as an explicit model and use the :attr:`ManyToManyField.through`
attribute.
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.
``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'
``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.
.. note::
Regardless of how many fields are in :attr:`~Options.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``
---------------
.. 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)``.
``unique_together``
-------------------
.. attribute:: 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).
.. versionadded:: 1.0
For convenience, unique_together can be a single list when dealing with a single
set of fields::
unique_together = ("driver", "restaurant")
``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"``.