mirror of
https://github.com/django/django.git
synced 2024-11-29 22:56:46 +01:00
b4dd4d4bb7
This allows a model to be defined which is not subject to database table creation and removal. Useful for models that sit over existing tables or database views. Thanks to Alexander Myodov, Wolfgang Kriesing and Ryan Kelly for the bulk of this patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@10008 bcc190cf-cafb-0310-a4f2-bffc1f526a37
209 lines
5.9 KiB
Plaintext
209 lines
5.9 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
|
|
|
|
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"``.
|
|
|