2008-08-23 22:25:40 +00:00
|
|
|
|
======================
|
|
|
|
|
Model ``Meta`` options
|
|
|
|
|
======================
|
|
|
|
|
|
2009-12-22 15:18:51 +00:00
|
|
|
|
This document explains all the possible :ref:`metadata options
|
2010-12-29 20:30:24 +00:00
|
|
|
|
<meta-options>` that you can give your model in its internal
|
|
|
|
|
``class Meta``.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Available ``Meta`` options
|
|
|
|
|
==========================
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: django.db.models
|
|
|
|
|
|
2008-08-31 10:13:32 +00:00
|
|
|
|
``abstract``
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.abstract
|
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
If ``abstract = True``, this model will be an
|
|
|
|
|
:ref:`abstract base class <abstract-base-classes>`.
|
2008-08-31 10:13:32 +00:00
|
|
|
|
|
2009-09-28 21:58:21 +00:00
|
|
|
|
``app_label``
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.app_label
|
|
|
|
|
|
2015-02-09 21:41:57 +00:00
|
|
|
|
If a model is defined outside of an application in
|
|
|
|
|
:setting:`INSTALLED_APPS`, it must declare which app it belongs to::
|
2009-09-28 21:58:21 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
app_label = "myapp"
|
2009-09-28 21:58:21 +00:00
|
|
|
|
|
2015-04-26 21:05:50 +00:00
|
|
|
|
If you want to represent a model with the format ``app_label.object_name``
|
|
|
|
|
or ``app_label.model_name`` you can use ``model._meta.label``
|
|
|
|
|
or ``model._meta.label_lower`` respectively.
|
|
|
|
|
|
2016-04-17 11:55:55 +00:00
|
|
|
|
``base_manager_name``
|
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.base_manager_name
|
|
|
|
|
|
2019-08-09 07:56:30 +00:00
|
|
|
|
The attribute name of the manager, for example, ``'objects'``, to use for
|
|
|
|
|
the model's :attr:`~django.db.models.Model._base_manager`.
|
2016-04-17 11:55:55 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
``db_table``
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.db_table
|
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
The name of the database table to use for the model::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
db_table = "music_album"
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
.. _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
|
2010-12-29 20:30:24 +00:00
|
|
|
|
name you used in :djadmin:`manage.py startapp <startapp>` -- to the model's
|
|
|
|
|
class name, with an underscore between them.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2019-05-27 17:59:49 +00:00
|
|
|
|
.. admonition:: Use lowercase table names for MariaDB and MySQL
|
2011-09-10 20:06:10 +00:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2013-10-21 15:12:48 +00:00
|
|
|
|
.. admonition:: Table name quoting for Oracle
|
|
|
|
|
|
2014-02-09 19:30:13 +00:00
|
|
|
|
In order to meet the 30-char limitation Oracle has on table names,
|
2013-10-21 15:12:48 +00:00
|
|
|
|
and match the usual conventions for Oracle databases, Django may shorten
|
|
|
|
|
table names and turn them all-uppercase. To prevent such transformations,
|
|
|
|
|
use a quoted name as the value for ``db_table``::
|
|
|
|
|
|
|
|
|
|
db_table = '"name_left_in_lowercase"'
|
|
|
|
|
|
2014-01-01 18:44:39 +00:00
|
|
|
|
Such quoted names can also be used with Django's other supported database
|
2013-10-21 15:12:48 +00:00
|
|
|
|
backends; except for Oracle, however, the quotes have no effect. See the
|
|
|
|
|
:ref:`Oracle notes <oracle-notes>` for more details.
|
2011-09-10 20:06:10 +00:00
|
|
|
|
|
2022-10-16 05:59:39 +00:00
|
|
|
|
``db_table_comment``
|
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 4.2
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.db_table_comment
|
|
|
|
|
|
|
|
|
|
The comment on the database table to use for this model. It is useful for
|
|
|
|
|
documenting database tables for individuals with direct database access who may
|
|
|
|
|
not be looking at your Django code. For example::
|
|
|
|
|
|
|
|
|
|
class Answer(models.Model):
|
|
|
|
|
question = models.ForeignKey(Question, on_delete=models.CASCADE)
|
|
|
|
|
answer = models.TextField()
|
|
|
|
|
|
|
|
|
|
class Meta:
|
|
|
|
|
db_table_comment = "Question answers"
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
``db_tablespace``
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.db_tablespace
|
|
|
|
|
|
2011-10-14 21:49:43 +00:00
|
|
|
|
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.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2016-04-17 11:55:55 +00:00
|
|
|
|
``default_manager_name``
|
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.default_manager_name
|
|
|
|
|
|
2016-07-15 17:42:37 +00:00
|
|
|
|
The name of the manager to use for the model's
|
|
|
|
|
:attr:`~django.db.models.Model._default_manager`.
|
2016-04-17 11:55:55 +00:00
|
|
|
|
|
2014-06-06 16:16:17 +00:00
|
|
|
|
``default_related_name``
|
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.default_related_name
|
|
|
|
|
|
|
|
|
|
The name that will be used by default for the relation from a related object
|
|
|
|
|
back to this one. The default is ``<model_name>_set``.
|
|
|
|
|
|
2016-02-24 07:10:09 +00:00
|
|
|
|
This option also sets :attr:`~ForeignKey.related_query_name`.
|
|
|
|
|
|
2014-06-06 16:16:17 +00:00
|
|
|
|
As the reverse name for a field should be unique, be careful if you intend
|
|
|
|
|
to subclass your model. To work around name collisions, part of the name
|
|
|
|
|
should contain ``'%(app_label)s'`` and ``'%(model_name)s'``, which are
|
|
|
|
|
replaced respectively by the name of the application the model is in,
|
|
|
|
|
and the name of the model, both lowercased. See the paragraph on
|
|
|
|
|
:ref:`related names for abstract models <abstract-related-name>`.
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
``get_latest_by``
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.get_latest_by
|
|
|
|
|
|
2017-06-21 20:28:16 +00:00
|
|
|
|
The name of a field or a list of field names in the model, typically
|
|
|
|
|
:class:`DateField`, :class:`DateTimeField`, or :class:`IntegerField`. This
|
|
|
|
|
specifies the default field(s) to use in your model :class:`Manager`’s
|
2013-01-12 08:37:19 +00:00
|
|
|
|
:meth:`~django.db.models.query.QuerySet.latest` and
|
|
|
|
|
:meth:`~django.db.models.query.QuerySet.earliest` methods.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
Example::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2017-06-21 20:28:16 +00:00
|
|
|
|
# Latest by ascending order_date.
|
2010-12-29 20:30:24 +00:00
|
|
|
|
get_latest_by = "order_date"
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2017-06-21 20:28:16 +00:00
|
|
|
|
# Latest by priority descending, order_date ascending.
|
|
|
|
|
get_latest_by = ["-priority", "order_date"]
|
|
|
|
|
|
2012-12-25 08:40:08 +00:00
|
|
|
|
See the :meth:`~django.db.models.query.QuerySet.latest` docs for more.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2009-03-09 03:35:02 +00:00
|
|
|
|
``managed``
|
2010-12-29 20:30:24 +00:00
|
|
|
|
-----------
|
2009-03-09 03:35:02 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: Options.managed
|
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
Defaults to ``True``, meaning Django will create the appropriate database
|
2013-07-25 15:19:36 +00:00
|
|
|
|
tables in :djadmin:`migrate` or as part of migrations and remove them as
|
|
|
|
|
part of a :djadmin:`flush` management command. That is, Django
|
|
|
|
|
*manages* the database tables' lifecycles.
|
2009-03-20 23:15:27 +00:00
|
|
|
|
|
2020-06-17 00:35:13 +00:00
|
|
|
|
If ``False``, no database table creation, modification, 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
|
2009-03-09 03:35:02 +00:00
|
|
|
|
|
2018-11-15 18:54:28 +00:00
|
|
|
|
#. Adding an automatic primary key field to the model if you don't
|
2011-10-14 00:12:01 +00:00
|
|
|
|
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.
|
|
|
|
|
|
2018-11-15 18:54:28 +00:00
|
|
|
|
#. If a model with ``managed=False`` contains a
|
2011-10-14 00:12:01 +00:00
|
|
|
|
: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.
|
2009-03-09 03:35:02 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
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.
|
2009-03-09 03:35:02 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
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`.
|
2009-03-19 09:04:19 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
``order_with_respect_to``
|
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.order_with_respect_to
|
|
|
|
|
|
2015-06-05 20:14:34 +00:00
|
|
|
|
Makes this object orderable with respect to the given field, usually a
|
|
|
|
|
``ForeignKey``. This can be used to make related objects orderable 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::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2013-05-18 10:12:26 +00:00
|
|
|
|
from django.db import models
|
|
|
|
|
|
2023-02-28 19:53:28 +00:00
|
|
|
|
|
2013-05-18 10:12:26 +00:00
|
|
|
|
class Question(models.Model):
|
|
|
|
|
text = models.TextField()
|
|
|
|
|
# ...
|
|
|
|
|
|
2023-02-28 19:53:28 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
class Answer(models.Model):
|
2015-07-22 14:43:21 +00:00
|
|
|
|
question = models.ForeignKey(Question, on_delete=models.CASCADE)
|
2010-12-29 20:30:24 +00:00
|
|
|
|
# ...
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
class Meta:
|
|
|
|
|
order_with_respect_to = "question"
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
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:
|
2023-02-09 15:48:46 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
.. code-block:: pycon
|
2010-12-06 23:08:44 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
>>> question = Question.objects.get(id=1)
|
|
|
|
|
>>> question.get_answer_order()
|
|
|
|
|
[1, 2, 3]
|
2010-12-06 23:08:44 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
The order of a ``Question`` object's related ``Answer`` objects can be set by
|
|
|
|
|
passing in a list of ``Answer`` primary keys:
|
2023-02-09 15:48:46 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
.. code-block:: pycon
|
2010-12-06 23:08:44 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
>>> question.set_answer_order([3, 1, 2])
|
2010-12-06 23:08:44 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
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``:
|
2023-02-09 15:48:46 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
.. code-block:: pycon
|
2010-12-06 23:08:44 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
>>> answer = Answer.objects.get(id=2)
|
|
|
|
|
>>> answer.get_next_in_order()
|
|
|
|
|
<Answer: 3>
|
|
|
|
|
>>> answer.get_previous_in_order()
|
|
|
|
|
<Answer: 1>
|
2010-12-06 23:08:44 +00:00
|
|
|
|
|
2015-06-05 20:14:34 +00:00
|
|
|
|
.. admonition:: ``order_with_respect_to`` implicitly sets the ``ordering`` option
|
2011-12-31 15:30:22 +00:00
|
|
|
|
|
2015-06-05 20:14:34 +00:00
|
|
|
|
Internally, ``order_with_respect_to`` adds an additional field/database
|
|
|
|
|
column named ``_order`` and sets the model's :attr:`~Options.ordering`
|
|
|
|
|
option to this field. Consequently, ``order_with_respect_to`` and
|
|
|
|
|
``ordering`` cannot be used together, and the ordering added by
|
|
|
|
|
``order_with_respect_to`` will apply whenever you obtain a list of objects
|
|
|
|
|
of this model.
|
|
|
|
|
|
|
|
|
|
.. admonition:: Changing ``order_with_respect_to``
|
|
|
|
|
|
|
|
|
|
Because ``order_with_respect_to`` adds a new database column, be sure to
|
|
|
|
|
make and apply the appropriate migrations if you add or change
|
|
|
|
|
``order_with_respect_to`` after your initial :djadmin:`migrate`.
|
2011-12-31 15:30:22 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
``ordering``
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.ordering
|
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
The default ordering for the object, for use when obtaining lists of objects::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
ordering = ["-order_date"]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2017-06-25 18:17:13 +00:00
|
|
|
|
This is a tuple or list of strings and/or query expressions. 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.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
For example, to order by a ``pub_date`` field ascending, use this::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
ordering = ["pub_date"]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
To order by ``pub_date`` descending, use this::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
ordering = ["-pub_date"]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
To order by ``pub_date`` descending, then by ``author`` ascending, use this::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
ordering = ["-pub_date", "author"]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2017-06-25 18:17:13 +00:00
|
|
|
|
You can also use :doc:`query expressions </ref/models/expressions>`. To
|
|
|
|
|
order by ``author`` ascending and make null values sort last, use this::
|
|
|
|
|
|
|
|
|
|
from django.db.models import F
|
|
|
|
|
|
|
|
|
|
ordering = [F("author").asc(nulls_last=True)]
|
|
|
|
|
|
2013-09-08 19:57:36 +00:00
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
Ordering is not a free operation. Each field you add to the ordering
|
|
|
|
|
incurs a cost to your database. Each foreign key you add will
|
2013-09-09 15:30:31 +00:00
|
|
|
|
implicitly include all of its default orderings as well.
|
2013-09-08 19:57:36 +00:00
|
|
|
|
|
2016-03-03 15:15:24 +00:00
|
|
|
|
If a query doesn't have an ordering specified, results are returned from
|
|
|
|
|
the database in an unspecified order. A particular ordering is guaranteed
|
|
|
|
|
only when ordering by a set of fields that uniquely identify each object in
|
|
|
|
|
the results. For example, if a ``name`` field isn't unique, ordering by it
|
|
|
|
|
won't guarantee objects with the same name always appear in the same order.
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
``permissions``
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.permissions
|
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
Extra permissions to enter into the permissions table when creating this object.
|
2018-05-02 08:39:12 +00:00
|
|
|
|
Add, change, delete, and view permissions are automatically created for each
|
2013-08-01 14:27:30 +00:00
|
|
|
|
model. This example specifies an extra permission, ``can_deliver_pizzas``::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2019-04-22 06:31:08 +00:00
|
|
|
|
permissions = [("can_deliver_pizzas", "Can deliver pizzas")]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
This is a list or tuple of 2-tuples in the format ``(permission_code,
|
|
|
|
|
human_readable_permission_name)``.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2013-08-01 15:31:34 +00:00
|
|
|
|
``default_permissions``
|
2017-03-20 22:30:32 +00:00
|
|
|
|
-----------------------
|
2013-08-01 15:31:34 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: Options.default_permissions
|
|
|
|
|
|
2018-05-02 08:39:12 +00:00
|
|
|
|
Defaults to ``('add', 'change', 'delete', 'view')``. You may customize this
|
|
|
|
|
list, for example, by setting this to an empty list if your app doesn't
|
|
|
|
|
require any of the default permissions. It must be specified on the model
|
|
|
|
|
before the model is created by :djadmin:`migrate` in order to prevent any
|
|
|
|
|
omitted permissions from being created.
|
|
|
|
|
|
2009-03-18 09:47:08 +00:00
|
|
|
|
``proxy``
|
|
|
|
|
---------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.proxy
|
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
If ``proxy = True``, a model which subclasses another model will be treated as
|
|
|
|
|
a :ref:`proxy model <proxy-models>`.
|
2009-03-18 09:47:08 +00:00
|
|
|
|
|
2015-04-04 16:07:46 +00:00
|
|
|
|
``required_db_features``
|
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.required_db_features
|
|
|
|
|
|
|
|
|
|
List of database features that the current connection should have so that
|
|
|
|
|
the model is considered during the migration phase. For example, if you set
|
|
|
|
|
this list to ``['gis_enabled']``, the model will only be synchronized on
|
|
|
|
|
GIS-enabled databases. It's also useful to skip some models when testing
|
2015-09-03 17:36:19 +00:00
|
|
|
|
with several database backends. Avoid relations between models that may or
|
|
|
|
|
may not be created as the ORM doesn't handle this.
|
2015-04-04 16:07:46 +00:00
|
|
|
|
|
|
|
|
|
``required_db_vendor``
|
|
|
|
|
----------------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.required_db_vendor
|
|
|
|
|
|
|
|
|
|
Name of a supported database vendor that this model is specific to. Current
|
|
|
|
|
built-in vendor names are: ``sqlite``, ``postgresql``, ``mysql``,
|
|
|
|
|
``oracle``. If this attribute is not empty and the current connection vendor
|
|
|
|
|
doesn't match it, the model will not be synchronized.
|
|
|
|
|
|
2013-08-30 06:41:07 +00:00
|
|
|
|
``select_on_save``
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.select_on_save
|
|
|
|
|
|
|
|
|
|
Determines if Django will use the pre-1.6
|
|
|
|
|
:meth:`django.db.models.Model.save()` algorithm. The old algorithm
|
|
|
|
|
uses ``SELECT`` to determine if there is an existing row to be updated.
|
2013-08-31 01:05:36 +00:00
|
|
|
|
The new algorithm tries an ``UPDATE`` directly. In some rare cases the
|
2013-08-30 06:41:07 +00:00
|
|
|
|
``UPDATE`` of an existing row isn't visible to Django. An example is the
|
|
|
|
|
PostgreSQL ``ON UPDATE`` trigger which returns ``NULL``. In such cases the
|
|
|
|
|
new algorithm will end up doing an ``INSERT`` even when a row exists in
|
|
|
|
|
the database.
|
|
|
|
|
|
|
|
|
|
Usually there is no need to set this attribute. The default is
|
|
|
|
|
``False``.
|
|
|
|
|
|
|
|
|
|
See :meth:`django.db.models.Model.save()` for more about the old and
|
|
|
|
|
new saving algorithm.
|
|
|
|
|
|
2016-06-20 15:50:05 +00:00
|
|
|
|
``indexes``
|
|
|
|
|
-----------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.indexes
|
|
|
|
|
|
|
|
|
|
A list of :doc:`indexes </ref/models/indexes>` that you want to define on
|
|
|
|
|
the model::
|
|
|
|
|
|
|
|
|
|
from django.db import models
|
|
|
|
|
|
2023-02-28 19:53:28 +00:00
|
|
|
|
|
2016-06-20 15:50:05 +00:00
|
|
|
|
class Customer(models.Model):
|
|
|
|
|
first_name = models.CharField(max_length=100)
|
|
|
|
|
last_name = models.CharField(max_length=100)
|
|
|
|
|
|
|
|
|
|
class Meta:
|
|
|
|
|
indexes = [
|
|
|
|
|
models.Index(fields=["last_name", "first_name"]),
|
|
|
|
|
models.Index(fields=["first_name"], name="first_name_idx"),
|
|
|
|
|
]
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
``unique_together``
|
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.unique_together
|
|
|
|
|
|
2018-12-27 19:43:30 +00:00
|
|
|
|
.. admonition:: Use :class:`.UniqueConstraint` with the :attr:`~Options.constraints` option instead.
|
|
|
|
|
|
|
|
|
|
:class:`.UniqueConstraint` provides more functionality than
|
|
|
|
|
``unique_together``. ``unique_together`` may be deprecated in the
|
|
|
|
|
future.
|
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
Sets of field names that, taken together, must be unique::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2019-04-22 06:31:08 +00:00
|
|
|
|
unique_together = [["driver", "restaurant"]]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2019-04-22 06:31:08 +00:00
|
|
|
|
This is a list of lists that must be unique when considered together.
|
2010-12-29 20:30:24 +00:00
|
|
|
|
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).
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2019-04-22 06:31:08 +00:00
|
|
|
|
For convenience, ``unique_together`` can be a single list when dealing with
|
|
|
|
|
a single set of fields::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2019-04-22 06:31:08 +00:00
|
|
|
|
unique_together = ["driver", "restaurant"]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-12-31 00:43:11 +00:00
|
|
|
|
A :class:`~django.db.models.ManyToManyField` cannot be included in
|
2023-07-21 10:54:38 +00:00
|
|
|
|
``unique_together``. (It's not clear what that would even mean!) If you
|
2011-12-31 00:43:11 +00:00
|
|
|
|
need to validate uniqueness related to a
|
2012-02-03 17:45:28 +00:00
|
|
|
|
:class:`~django.db.models.ManyToManyField`, try using a signal or
|
|
|
|
|
an explicit :attr:`through <ManyToManyField.through>` model.
|
2011-12-31 00:43:11 +00:00
|
|
|
|
|
2015-01-26 20:39:52 +00:00
|
|
|
|
The ``ValidationError`` raised during model validation when the constraint
|
|
|
|
|
is violated has the ``unique_together`` error code.
|
2014-02-03 18:31:27 +00:00
|
|
|
|
|
2012-11-04 18:16:06 +00:00
|
|
|
|
``index_together``
|
2013-03-15 14:15:52 +00:00
|
|
|
|
------------------
|
2012-11-04 18:16:06 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: Options.index_together
|
|
|
|
|
|
|
|
|
|
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.)
|
|
|
|
|
|
2014-03-01 19:06:15 +00:00
|
|
|
|
For convenience, ``index_together`` can be a single list when dealing with a single
|
|
|
|
|
set of fields::
|
2014-03-24 15:42:56 +00:00
|
|
|
|
|
2014-03-01 19:06:15 +00:00
|
|
|
|
index_together = ["pub_date", "deadline"]
|
|
|
|
|
|
2022-05-17 14:13:35 +00:00
|
|
|
|
.. deprecated:: 4.2
|
|
|
|
|
|
|
|
|
|
Use the :attr:`~Options.indexes` option instead.
|
|
|
|
|
|
2016-11-05 13:12:12 +00:00
|
|
|
|
``constraints``
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.constraints
|
|
|
|
|
|
2018-08-06 02:30:44 +00:00
|
|
|
|
A list of :doc:`constraints </ref/models/constraints>` that you want to
|
|
|
|
|
define on the model::
|
2016-11-05 13:12:12 +00:00
|
|
|
|
|
|
|
|
|
from django.db import models
|
|
|
|
|
|
2023-02-28 19:53:28 +00:00
|
|
|
|
|
2016-11-05 13:12:12 +00:00
|
|
|
|
class Customer(models.Model):
|
|
|
|
|
age = models.IntegerField()
|
|
|
|
|
|
|
|
|
|
class Meta:
|
|
|
|
|
constraints = [
|
2018-08-06 02:15:10 +00:00
|
|
|
|
models.CheckConstraint(check=models.Q(age__gte=18), name="age_gte_18"),
|
2016-11-05 13:12:12 +00:00
|
|
|
|
]
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
``verbose_name``
|
|
|
|
|
----------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.verbose_name
|
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
A human-readable name for the object, singular::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
verbose_name = "pizza"
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
If this isn't given, Django will use a munged version of the class name:
|
|
|
|
|
``CamelCase`` becomes ``camel case``.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
``verbose_name_plural``
|
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.verbose_name_plural
|
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
The plural name for the object::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
verbose_name_plural = "stories"
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-12-29 20:30:24 +00:00
|
|
|
|
If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
|
2015-04-26 21:05:50 +00:00
|
|
|
|
|
|
|
|
|
Read-only ``Meta`` attributes
|
|
|
|
|
=============================
|
|
|
|
|
|
|
|
|
|
``label``
|
|
|
|
|
---------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.label
|
|
|
|
|
|
|
|
|
|
Representation of the object, returns ``app_label.object_name``, e.g.
|
|
|
|
|
``'polls.Question'``.
|
|
|
|
|
|
|
|
|
|
``label_lower``
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
.. attribute:: Options.label_lower
|
|
|
|
|
|
|
|
|
|
Representation of the model, returns ``app_label.model_name``, e.g.
|
|
|
|
|
``'polls.question'``.
|