236 lines
7.0 KiB
Plaintext
236 lines
7.0 KiB
Plaintext
.. _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
|
|
|
|
Defaults to ``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. 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
|
|
: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, 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
|
|
: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'
|
|
|
|
``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)``.
|
|
|
|
``proxy``
|
|
---------
|
|
|
|
.. attribute:: Options.proxy
|
|
|
|
.. versionadded:: 1.1
|
|
|
|
If set to ``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 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"``.
|
|
|