Параметры модели

Этот раздел описывает все возможные настройки модели которые вы можете определить через class Meta.

Параметры Meta

abstract

Options.abstract

При abstract = True, эта модель будет абстрактной моделью.

app_label

Options.app_label

Если модель определена вне приложения из INSTALLED_APPS, она должна указать к какому приложению она относится:

app_label = 'myapp'

Если вы хотите представить модель в формате app_label.object_name или app_label.model_name, вы можете использовать model._meta.label и model._meta.label_lower соответственно.

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

Название таблицы в базе данных для этой модели:

db_table = 'music_album'

Название таблицы

Экономя ваше время, Django автоматически создаст название таблицы из названия модели и приложения. Название таблицы состоит из названия приложения(«app label») – название используемое для команды manage.py startapp – и названия модели, объединенные нижним подчеркиванием.

Например, есть приложение bookstore (созданное командой manage.py startapp bookstore), и модель class Book, название таблицы будет bookstore_book.

Для переопределения названия таблицы используйте атрибут db_table class Meta.

Если имя колонки это зарезервированное SQL слово, или содержит символы запрещенные в названиях переменной в Python – в частности, дефис – все нормально. Django автоматически экранирует название колонок и таблиц.

Use lowercase table names for MariaDB and MySQL

Настоятельно рекомендуем использовать нижний регистр при переопределении названия таблицы через db_table, особенно при использовании MySQL. Подробности в примечания для MySQL.

Названия таблиц в кавычках для Oracle

Т.к в Oracle есть ограничение в 30 символов на название таблиц, и для соблюдения соглашений работы с Oracle, Django может ограничить название таблицы и преобразовать его в верхний регистр. Чтобы избежать этого, укажите название в кавычках в настройке db_table:

db_table = '"name_left_in_lowercase"'

Кавычки можно использовать для других типов базы данных, не только Oracle, однако, они не будут иметь никакого эффекта. Смотрите заметки о работе с Oracle.

db_tablespace

Options.db_tablespace

Имя “tablespace” базы данных для этой модели. По умолчанию используется настройка DEFAULT_TABLESPACE, если она определена. Если база данных не поддерживает “tablespace” для индексов, этот параметр будет проигнорирован.

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, or IntegerField. This specifies the default field(s) to use in your model Manager’s latest() and earliest() methods.

Например:

# Latest by ascending order_date.
get_latest_by = "order_date"

# Latest by priority descending, order_date ascending.
get_latest_by = ['-priority', 'order_date']

Подробности в разделе о latest().

managed

Options.managed

По умолчанию True, означает что Django создаст необходимые таблицы в базе данных при выполнении команды migrate и удалит их при выполнении flush. То есть Django управляет таблицами.

При False, таблицы модели не будет создаваться или удаляться. Это полезно, если модель отображает существующую таблицу или «VIEW» в базе данных, которая была создана другим способом. Это единственная разница при managed=False. Все остальные этапы работы с моделью не изменяются. Они включают

  1. Автоматическое добавление первичного ключа, если он не был определен. Для ясности лучше определить в модели все поля таблицы, которую отображает модель с managed=False`.

  2. Если модель с managed=False содержит ManyToManyField на другую неуправляемую модель, промежуточная таблица для хранения связи многое-ко-многим не будет создана. Однако, промежуточная таблица между управляемой и не управляемой моделью будет создана.

    Если вы хотите переопределить такое поведение по умолчанию, создайте модель для промежуточной таблицы (с необходимым managed) и укажите использование этой модели через параметр ManyToManyField.through.

Правильное создание таблиц при тестировании в тестовой базе данных для модели с managed=False ложится на ваши плечи.

Если вы хотите переопределить поведение модели на уровне Python, вы можете использовать managed=False и создать копию существующей модели. Однако, есть лучшее решение для такой ситуации: Proxy-модели.

order_with_respect_to

Options.order_with_respect_to

Объекты модели будут отсортированы относительно указанного поля. Почти всегда используется для ForeignKey. Можно использовать для сортировки связанных объектов по значению из родительского объекта. Например, модель Answer``(ответ) связана с моделью ``Question``(вопрос) через ``ForeignKey, вопрос содержит несколько ответов и порядок этих ответов имеет значение:

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'

При добавлении order_with_respect_to, будет добавлено два дополнительных метода для получения и установки порядка связанных объектов: get_RELATED_order() и set_RELATED_order(), где RELATED название модели в нижнем регистре. Например, предполагая что объект Question имеет несколько связанных объектов Answer, возвращенный список будет содержать значения первичного ключа объектов Answer:

>>> question = Question.objects.get(id=1)
>>> question.get_answer_order()
[1, 2, 3]

Для определения порядка объектов Answer передайте список первичных ключей в метод set_answer_order:

>>> question.set_answer_order([3, 1, 2])

К связанным объектам также добавляется два метода, get_next_in_order() и get_previous_in_order(), для получения объектов в определенном порядке. Предположим что объекты Answer отсортированы по id:

>>> answer = Answer.objects.get(id=2)
>>> answer.get_next_in_order()
<Answer: 3>
>>> answer.get_previous_in_order()
<Answer: 1>

order_with_respect_to неявно использует ordering

Внутри order_with_respect_to добавляет колонку в базе данных _order и указывает её в опции модели ordering. Поэтому order_with_respect_to и ordering не могут использоваться вместе, и сортировка из order_with_respect_to будет использоваться при любом получении объектов модели.

Изменение order_with_respect_to

Т.к. order_with_respect_to добавляет дополнительное поле в таблицу базы данных с названием _order, не забудьте создать и применить миграцию, если вы добавите или поменяете order_with_respect_to первого запуска после migrate.

ordering

Options.ordering

Сортировка по умолчанию используемая при получении объектов:

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.

Например, для сортировки по возрастанию по полю pub_date:

ordering = ['pub_date']

Нисходящая сортировка по полю pub_date:

ordering = ['-pub_date']

Для нисходящей сортировки по pub_date и восходящей по author, используйте:

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)]

Default ordering also affects aggregation queries but this won’t be the case starting in Django 3.1.

Предупреждение

Сортировка не бесплатная операция. Каждое поле влияет на скорость выполнения запроса. Каждый внешний ключ добавит сортировку по умолчанию связанной модели.

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')]

Это список 2-х элементных кортежей в формате (код разрешения, название разрешения).

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 by migrate in order to prevent any omitted permissions from being created.

proxy

Options.proxy

При proxy = True, модель унаследованная от другой модели будет создана как proxy-модель.

required_db_features

Options.required_db_features

Список функций базы данных, который необходимы для работы модели. Учитываются при миграции. Например, если указать ['gis_enabled'], таблица для модели будет создана только для базы данных, которая поддерживает GIS. Эта опция также полезна при тестировании на разных базах данных. Избегайте связей между моделями, которые не могут быть созданы в одной базе данных. ORM не умеет обрабатывать такие ситуации.

required_db_vendor

Options.required_db_vendor

Список поддерживаемых баз данных. Текущий список: sqlite, postgresql, mysql, oracle. Если эта опция не пустая, и база данных не соответствует указанной, таблица для модели не будет создана при миграции.

select_on_save

Options.select_on_save

Указывает использовать ли старый(до 1.6) алгоритм работы django.db.models.Model.save(). Старый алгоритм использовал SELECT для определения существует ли запись для обновления. Новый алгоритм сразу пробует обновить запись через UPDATE. В некоторых редких случаях UPDATE существующей записи не виден для Django. Например, в PostgreSQL срабатывание ON UPDATE возвращает NULL. В таких случаях новый алгоритм в конце концов попытается выполнить INSERT, даже если запись существует в базе данных.

Обычно нет надобности менять эту настройку. По умолчанию равно False.

Различия работы старого и нового алгоритмов смотрите в описании метода django.db.models.Model.save().

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

Use UniqueConstraint with the constraints option instead.

UniqueConstraint provides more functionality than unique_together. unique_together may be deprecated in the future.

Множество полей, комбинация значений которых должна быть уникальна:

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 the CREATE TABLE statement).

For convenience, unique_together can be a single list when dealing with a single set of fields:

unique_together = ['driver', 'restaurant']

ManyToManyField не должен быть включен в unique_together. (Не понятно что подразумевается.) Если вам необходимо проверить уникальность связанных через ManyToManyField объектов, попробуйте использовать сигналы или подходящую through model.

Будет вызвано исключение ValidationError в процессе проверки модели, если проверка ограничений(constraint) вернула ошибку с кодом unique_together.

index_together

Options.index_together

Use the indexes option instead.

The newer indexes option provides more functionality than index_together. index_together may be deprecated in the future.

Множество полей, для которых создается один индекс:

index_together = [
    ["pub_date", "deadline"],
]

Будет создан один индекс для группы полей (то есть будет выполнен необходимый CREATE INDEX.)

Для удобства index_together может быть одноуровневым списком, если определяется один набор полей:

index_together = ["pub_date", "deadline"]

constraints

Options.constraints
New in Django 2.2.

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(check=models.Q(age__gte=18), name='age_gte_18'),
        ]

verbose_name

Options.verbose_name

Читабельное название модели, в единственном числе:

verbose_name = "pizza"

Если не указано, Django создаст из названия модели: CamelCase станет camel case.

verbose_name_plural

Options.verbose_name_plural

Название модели в множественном числе:

verbose_name_plural = "stories"

Если не указано, Django создаст по правилу verbose_name + "s".

Неизменяемые атрибуты Meta

label

Options.label

Представление объекта, возвращает app_label.object_name, например 'polls.Question'.

label_lower

Options.label_lower

Представление объекта, возвращает app_label.model_name, например 'polls.question'.