Model Meta
options¶
This document explains all the possible metadata options that you can give your model in its internal
class Meta
.
Available Meta
options¶
abstract
¶
- Options.abstract¶
If
abstract = True
, this model will be an abstract base class.
app_label
¶
- Options.app_label¶
If a model is defined outside of an application in
INSTALLED_APPS
, it must declare which app it belongs to:app_label = "myapp"
If you want to represent a model with the format
app_label.object_name
orapp_label.model_name
you can usemodel._meta.label
ormodel._meta.label_lower
respectively.
base_manager_name
¶
- Options.base_manager_name¶
The attribute name of the manager, for example,
'objects'
, to use for the model’s_base_manager
.
db_table
¶
- Options.db_table¶
The name of the database table to use for the model:
db_table = "music_album"
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.
Use lowercase table names for MariaDB and MySQL
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 MySQL notes for more details.
Table name quoting for Oracle
In order to meet the 30-char limitation Oracle has on table names,
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"'
Such quoted names can also be used with Django’s other supported database backends; except for Oracle, however, the quotes have no effect. See the Oracle notes for more details.
db_table_comment
¶
- 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"
db_tablespace
¶
- Options.db_tablespace¶
The name of the database tablespace to use for this model. The default is the project’s
DEFAULT_TABLESPACE
setting, if set. If the backend doesn’t support tablespaces, this option is ignored.
default_manager_name
¶
- Options.default_manager_name¶
The name of the manager to use for the model’s
_default_manager
.
get_latest_by
¶
- Options.get_latest_by¶
The name of a field or a list of field names in the model, typically
DateField
,DateTimeField
, orIntegerField
. This specifies the default field(s) to use in your modelManager
’slatest()
andearliest()
methods.Example:
# Latest by ascending order_date. get_latest_by = "order_date" # Latest by priority descending, order_date ascending. get_latest_by = ["-priority", "order_date"]
See the
latest()
docs for more.
managed
¶
- Options.managed¶
Defaults to
True
, meaning Django will create the appropriate database tables inmigrate
or as part of migrations and remove them as part of aflush
management command. That is, Django manages the database tables’ lifecycles.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 whenmanaged=False
. All other aspects of model handling are exactly the same as normal. This includesAdding 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.
If a model with
managed=False
contains aManyToManyField
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 theManyToManyField.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: Proxy models.
order_with_respect_to
¶
- Options.order_with_respect_to¶
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 anAnswer
relates to aQuestion
object, and a question has more than one answer, and the order of answers matters, you’d do this:from django.db import models class Question(models.Model): text = models.TextField() # ... class Answer(models.Model): question = models.ForeignKey(Question, on_delete=models.CASCADE) # ... class Meta: order_with_respect_to = "question"
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()
andset_RELATED_order()
, whereRELATED
is the lowercased model name. For example, assuming that aQuestion
object has multiple relatedAnswer
objects, the list returned contains the primary keys of the relatedAnswer
objects:>>> question = Question.objects.get(id=1) >>> question.get_answer_order() [1, 2, 3]
The order of a
Question
object’s relatedAnswer
objects can be set by passing in a list ofAnswer
primary keys:>>> question.set_answer_order([3, 1, 2])
The related objects also get two methods,
get_next_in_order()
andget_previous_in_order()
, which can be used to access those objects in their proper order. Assuming theAnswer
objects are ordered byid
:>>> answer = Answer.objects.get(id=2) >>> answer.get_next_in_order() <Answer: 3> >>> answer.get_previous_in_order() <Answer: 1>
order_with_respect_to
implicitly sets the ordering
option
Internally, order_with_respect_to
adds an additional field/database
column named _order
and sets the model’s 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.
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 migrate
.
ordering
¶
- 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 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.
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 byauthor
ascending, use this:ordering = ["-pub_date", "author"]
You can also use query 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)]
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 implicitly include all of its default orderings as well.
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.
permissions
¶
- Options.permissions¶
Extra permissions to enter into the permissions table when creating this object. Add, change, delete, and view permissions are automatically created for each model. 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)
.
default_permissions
¶
- Options.default_permissions¶
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 bymigrate
in order to prevent any omitted permissions from being created.
proxy
¶
- Options.proxy¶
If
proxy = True
, a model which subclasses another model will be treated as a proxy model.
required_db_features
¶
- 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 with several database backends. Avoid relations between models that may or may not be created as the ORM doesn’t handle this.
required_db_vendor
¶
- 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.
select_on_save
¶
- Options.select_on_save¶
Determines if Django will use the pre-1.6
django.db.models.Model.save()
algorithm. The old algorithm usesSELECT
to determine if there is an existing row to be updated. The new algorithm tries anUPDATE
directly. In some rare cases theUPDATE
of an existing row isn’t visible to Django. An example is the PostgreSQLON UPDATE
trigger which returnsNULL
. In such cases the new algorithm will end up doing anINSERT
even when a row exists in the database.Usually there is no need to set this attribute. The default is
False
.See
django.db.models.Model.save()
for more about the old and new saving algorithm.
indexes
¶
- Options.indexes¶
A list of indexes that you want to define on the model:
from django.db import models 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"), ]
unique_together
¶
- Options.unique_together¶
Sets of field names that, taken together, must be unique:
unique_together = [["driver", "restaurant"]]
This is a list of lists 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 theCREATE TABLE
statement).For convenience,
unique_together
can be a single list when dealing with a single set of fields:unique_together = ["driver", "restaurant"]
A
ManyToManyField
cannot be included inunique_together
. (It’s not clear what that would even mean!) If you need to validate uniqueness related to aManyToManyField
, try using a signal or an explicitthrough
model.The
ValidationError
raised during model validation when the constraint is violated has theunique_together
error code.
constraints
¶
- Options.constraints¶
A list of constraints that you want to define on the model:
from django.db import models class Customer(models.Model): age = models.IntegerField() class Meta: constraints = [ models.CheckConstraint(condition=models.Q(age__gte=18), name="age_gte_18"), ]
verbose_name
¶
- 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
becomescamel case
.
verbose_name_plural
¶
- Options.verbose_name_plural¶
The plural name for the object:
verbose_name_plural = "stories"
If this isn’t given, Django will use
verbose_name
+"s"
.
Read-only Meta
attributes¶
label
¶
- Options.label¶
Representation of the object, returns
app_label.object_name
, e.g.'polls.Question'
.
label_lower
¶
- Options.label_lower¶
Representation of the model, returns
app_label.model_name
, e.g.'polls.question'
.