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

В данном документе объясняются все возможные опции метаданных, которые вы можете задать вашей модели во внутренней 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

Имя менеджера, используемого для _base_manager модели.

db_table

Options.db_table

Имя таблицы базы данных, используемой для модели:

db_table = 'music_album'

Имена таблиц

Для экономии времени Django автоматически выводит имя таблицы базы данных из имени вашего класса модели и приложения, в котором она содержится. Имя таблицы базы данных модели формируется путём соединения «метки приложения» модели — имени, используемого вами в manage.py startapp — с именем класса модели, разделёнными нижним подчёркиванием.

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

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

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

db_table = '"name_left_in_lowercase"'

db_tablespace

Options.db_tablespace

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

default_manager_name

Options.default_manager_name

Имя менеджера, используемого для _default_manager модели.

default_related_name

Options.default_related_name

Имя, используемое по умолчанию для связи от связанного объекта обратно к этому объекту. По умолчанию значение <model_name>_set.

Эта опция также устанавливает related_query_name.

Поскольку обратное имя поля должно быть уникальным, будьте осторожны, если вы планируете наследоваться от вашей модели. Для решения проблем с конфликтами имён часть имени должна содержать '%(app_label)s' и '%(model_name)s', которые заменяются соответственно именем приложения, в котором находится модель, и именем модели, оба в нижнем регистре. Смотрите параграф о имени связи для абстрактных моделей.

get_latest_by

Options.get_latest_by

Имя поля или списка имён полей в модели, обычно DateField, DateTimeField или IntegerField. Это задаёт поле(я) по умолчанию для использования в методах Manager модели latest() и earliest().

Пример:

# Latest by ascending order_date.
get_latest_by = "order_date"

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

См. документацию к latest() для более подробной информации.

Изменено в Django 2.0:

Добавлена поддержка списка полей.

managed

Options.managed

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

Если False, для этой модели не будут выполняться операции создания или удаления таблиц базы данных. Это полезно, если модель представляет существующую таблицу или представление базы данных, созданные другими средствами. Это единственное отличие при managed=False. Все остальные аспекты обработки модели полностью совпадают с обычными. Это включает:

1. Добавление автоматического поля первичного ключа в модель, если вы его не объявляете. Чтобы избежать путаницы для читателей кода, рекомендуется указать все столбцы из таблицы базы данных, которую вы моделируете, при использовании неуправляемых моделей.

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

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

Для тестов, включающих модели с managed=False, вам нужно обеспечить правильное создание таблиц в рамках подготовки к тесту.

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

order_with_respect_to

Options.order_with_respect_to

Делает этот объект упорядочиваемым относительно указанного поля, обычно ForeignKey. Это может использоваться для упорядочивания связанных объектов относительно родительского объекта. Например, если Answer относится к объекту Question, и вопрос имеет более одного ответа, и порядок ответов важен, вы сделаете так:

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]

Порядок связанных объектов Question объекта Answer может быть установлен путём передачи списка первичных ключей Answer.

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

ordering

Options.ordering

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

ordering = ['-order_date']

Это кортеж или список строк и/или выражений запроса. Каждая строка — это имя поля с необязательным префиксом «-», указывающим на сортировку по убыванию. Поля без ведущего «-» будут отсортированы по возрастанию. Используйте строку «?» для случайной сортировки.

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

ordering = ['pub_date']

Для сортировки по pub_date по убыванию, используйте:

ordering = ['-pub_date']

Для сортировки по pub_date по убыванию, затем по author по возрастанию, используйте:

ordering = ['-pub_date', 'author']

Вы также можете использовать выражения запроса. Для сортировки по author по возрастанию и размещения значений NULL в конце списка, используйте:

from django.db.models import F

ordering = [F('author').asc(nulls_last=True)]

Сортировка по умолчанию также влияет на запросы агрегирования.

Изменено в Django 2.0:

Добавлена поддержка выражений запроса.

permissions

Options.permissions

Дополнительные разрешения для записи в таблицу разрешений при создании этого объекта. Разрешения добавления, изменения, удаления и просмотра автоматически создаются для каждой модели. В этом примере указано дополнительное разрешение can_deliver_pizzas:

permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)

Это список или кортеж из 2-х кортежей в формате (permission_code, human_readable_permission_name).

default_permissions

Options.default_permissions

По умолчанию ('add', 'change', 'delete', 'view'). Вы можете настроить этот список, например, установив его в пустой список, если вашему приложению не нужны какие-либо из стандартных разрешений. Он должен быть указан в модели перед её созданием с помощью migrate, чтобы предотвратить создание каких-либо пропущенных разрешений.

Изменено в Django 2.1:

Разрешение view было добавлено.

proxy

Options.proxy

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

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

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

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

См. django.db.models.Model.save() для получения более подробной информации об старом и новом алгоритмах сохранения.

indexes

Options.indexes

Список индексов, которые вы хотите определить в модели:

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

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

unique_together = (("driver", "restaurant"),)

Это кортеж кортежей, которые должны быть уникальными, когда рассматриваются вместе. Он используется в Django админке и применяется на уровне базы данных (т.е. соответствующие UNIQUE инструкции включены в CREATE TABLE инструкцию).

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

unique_together = ("driver", "restaurant")

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

Исключение ValidationError, возникающее при проверке модели, когда ограничение нарушено, имеет код ошибки unique_together.

index_together

Options.index_together

Используйте опцию indexes вместо этого.

Новая опция indexes предоставляет больше функциональности, чем index_together. index_together может быть в будущем устаревшей.

Наборы имён полей, которые, вместе взятые, индексируются:

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

Этот список полей будет индексироваться вместе (т.е. будет выдана соответствующая CREATE INDEX команда).

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

index_together = ["pub_date", "deadline"]

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'.