Конфигурация таблицы с помощью декларативного¶

Использование аннотированной декларативной таблицы (тип аннотированных форм для mapped_column())¶

Конструкция mapped_column() способна получать информацию о конфигурации колонки из аннотаций типов PEP 484, связанных с атрибутом, объявленным в классе Declarative mapped. Эти аннотации типов, если они используются, должны присутствовать внутри специального типа SQLAlchemy, называемого Mapped, который является общим_типом, который затем указывает на конкретный тип Python внутри него.

Ниже показано отображение из предыдущего раздела с добавлением использования Mapped:

from typing import Optional

from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(50))
    fullname: Mapped[Optional[str]]
    nickname: Mapped[Optional[str]] = mapped_column(String(30))

Выше, когда Declarative обрабатывает каждый атрибут класса, каждый mapped_column() будет получать дополнительные аргументы из соответствующей аннотации типа Mapped в левой части, если она присутствует. Кроме того, Declarative будет неявно генерировать пустую директиву mapped_column() всякий раз, когда встречается аннотация типа Mapped, не имеющая значения, присвоенного атрибуту (эта форма вдохновлена аналогичным стилем, используемым в Python dataclasses); эта конструкция mapped_column() будет получать свою конфигурацию из присутствующей аннотации Mapped.

import datetime

from sqlalchemy import BIGINT, Integer, NVARCHAR, String, TIMESTAMP
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped, mapped_column, registry


class Base(DeclarativeBase):
    type_annotation_map = {
        int: BIGINT,
        datetime.datetime: TIMESTAMP(timezone=True),
        str: String().with_variant(NVARCHAR, "mssql"),
    }


class SomeClass(Base):
    __tablename__ = "some_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    date: Mapped[datetime.datetime]
    status: Mapped[str]

>>> from sqlalchemy.schema import CreateTable
>>> from sqlalchemy.dialects import mssql, postgresql
>>> print(CreateTable(SomeClass.__table__).compile(dialect=mssql.dialect()))
{printsql}CREATE TABLE some_table (
  id BIGINT NOT NULL IDENTITY,
  date TIMESTAMP NOT NULL,
  status NVARCHAR(max) NOT NULL,
  PRIMARY KEY (id)
)

>>> print(CreateTable(SomeClass.__table__).compile(dialect=postgresql.dialect()))
{printsql}CREATE TABLE some_table (
  id BIGSERIAL NOT NULL,
  date TIMESTAMP WITH TIME ZONE NOT NULL,
  status VARCHAR NOT NULL,
  PRIMARY KEY (id)
)

from decimal import Decimal

from typing_extensions import Annotated

from sqlalchemy import Numeric
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import registry

str_30 = Annotated[str, 30]
str_50 = Annotated[str, 50]
num_12_4 = Annotated[Decimal, 12]
num_6_2 = Annotated[Decimal, 6]


class Base(DeclarativeBase):
    registry = registry(
        type_annotation_map={
            str_30: String(30),
            str_50: String(50),
            num_12_4: Numeric(12, 4),
            num_6_2: Numeric(6, 2),
        }
    )

class SomeClass(Base):
    __tablename__ = "some_table"

    short_name: Mapped[str_30] = mapped_column(primary_key=True)
    long_name: Mapped[str_50]
    num_value: Mapped[num_12_4]
    short_num_value: Mapped[num_6_2]

>>> from sqlalchemy.schema import CreateTable
>>> print(CreateTable(SomeClass.__table__))
{printsql}CREATE TABLE some_table (
  short_name VARCHAR(30) NOT NULL,
  long_name VARCHAR(50) NOT NULL,
  num_value NUMERIC(12, 4) NOT NULL,
  short_num_value NUMERIC(6, 2) NOT NULL,
  PRIMARY KEY (short_name)
)

import datetime

from typing_extensions import Annotated

from sqlalchemy import func
from sqlalchemy import String
from sqlalchemy.orm import mapped_column


intpk = Annotated[int, mapped_column(primary_key=True)]
timestamp = Annotated[
    datetime.datetime,
    mapped_column(nullable=False, server_default=func.CURRENT_TIMESTAMP()),
]
required_name = Annotated[str, mapped_column(String(30), nullable=False)]

class Base(DeclarativeBase):
    pass


class SomeClass(Base):
    __tablename__ = "some_table"

    id: Mapped[intpk]
    name: Mapped[required_name]
    created_at: Mapped[timestamp]

>>> from sqlalchemy.schema import CreateTable
>>> print(CreateTable(SomeClass.__table__))
{printsql}CREATE TABLE some_table (
  id INTEGER NOT NULL,
  name VARCHAR(30) NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP NOT NULL,
  PRIMARY KEY (id)
)

from typing_extensions import Annotated

import datetime
from typing import Optional

from sqlalchemy.orm import DeclarativeBase

timestamp = Annotated[
    datetime.datetime,
    mapped_column(nullable=False),
]


class Base(DeclarativeBase):
    pass


class SomeClass(Base):
    # ...

    # pep-484 type will be Optional, but column will be
    # NOT NULL
    created_at: Mapped[Optional[timestamp]]

import datetime

from typing_extensions import Annotated

from sqlalchemy import ForeignKey
from sqlalchemy import func
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.schema import CreateTable

intpk = Annotated[int, mapped_column(primary_key=True)]
timestamp = Annotated[
    datetime.datetime,
    mapped_column(nullable=False, server_default=func.CURRENT_TIMESTAMP()),
]


class Base(DeclarativeBase):
    pass


class Parent(Base):
    __tablename__ = "parent"

    id: Mapped[intpk]


class SomeClass(Base):
    __tablename__ = "some_table"

    # add ForeignKey to mapped_column(Integer, primary_key=True)
    id: Mapped[intpk] = mapped_column(ForeignKey("parent.id"))

    # change server default from CURRENT_TIMESTAMP to UTC_TIMESTAMP
    created_at: Mapped[timestamp] = mapped_column(server_default=func.UTC_TIMESTAMP())

>>> from sqlalchemy.schema import CreateTable
>>> print(CreateTable(SomeClass.__table__))
{printsql}CREATE TABLE some_table (
  id INTEGER NOT NULL,
  created_at DATETIME DEFAULT UTC_TIMESTAMP() NOT NULL,
  PRIMARY KEY (id),
  FOREIGN KEY(id) REFERENCES parent (id)
)

import enum

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column


class Base(DeclarativeBase):
    pass


class Status(enum.Enum):
    PENDING = "pending"
    RECEIVED = "received"
    COMPLETED = "completed"


class SomeClass(Base):
    __tablename__ = "some_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    status: Mapped[Status]

CREATE TYPE status AS ENUM ('PENDING', 'RECEIVED', 'COMPLETED')

CREATE TABLE some_table (
  id SERIAL NOT NULL,
  status status NOT NULL,
  PRIMARY KEY (id)
)

from typing import Literal

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column


class Base(DeclarativeBase):
    pass


Status = Literal["pending", "received", "completed"]


class SomeClass(Base):
    __tablename__ = "some_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    status: Mapped[Status]

import enum
import typing

import sqlalchemy
from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    type_annotation_map = {
        enum.Enum: sqlalchemy.Enum(enum.Enum),
        typing.Literal: sqlalchemy.Enum(enum.Enum),
    }

import enum
import typing

import sqlalchemy
from sqlalchemy.orm import DeclarativeBase

Status = Literal["pending", "received", "completed"]


class Base(DeclarativeBase):
    type_annotation_map = {
        Status: sqlalchemy.Enum("pending", "received", "completed", name="status_enum"),
    }

import enum
import typing

import sqlalchemy
from sqlalchemy.orm import DeclarativeBase

Status = Literal["pending", "received", "completed"]


class Base(DeclarativeBase):
    pass


class SomeClass(Base):
    __tablename__ = "some_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    status: Mapped[Status] = mapped_column(
        sqlalchemy.Enum("pending", "received", "completed", name="status_enum")
    )

import enum
import typing
import sqlalchemy
from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    type_annotation_map = {
        enum.Enum: sqlalchemy.Enum(enum.Enum, native_enum=False),
        typing.Literal: sqlalchemy.Enum(enum.Enum, native_enum=False),
    }

import enum
import sqlalchemy
from sqlalchemy.orm import DeclarativeBase


class Status(enum.Enum):
    PENDING = "pending"
    RECEIVED = "received"
    COMPLETED = "completed"


class Base(DeclarativeBase):
    type_annotation_map = {
        Status: sqlalchemy.Enum(Status, length=50, native_enum=False)
    }

from typing import Literal

from sqlalchemy import JSON
from sqlalchemy.orm import DeclarativeBase

my_literal = Literal[0, 1, True, False, "true", "false"]


class Base(DeclarativeBase):
    type_annotation_map = {my_literal: JSON}

Доступ к таблице и метаданным¶

Декларативно отображенный класс всегда будет включать атрибут __table__; когда вышеуказанная конфигурация с использованием __tablename__ завершена, декларативный процесс делает Table доступным через атрибут __table__:

# access the Table
user_table = User.__table__

Приведенная выше таблица в конечном итоге соответствует атрибуту Mapper.local_table, который мы можем видеть через runtime inspection system:

from sqlalchemy import inspect

user_table = inspect(User).local_table

Коллекция MetaData, связанная как с декларативным registry, так и с базовым классом, часто необходима для выполнения операций DDL, таких как CREATE, а также для использования с инструментами миграции, такими как Alembic. Этот объект доступен через атрибут .metadata в registry, а также через декларативный базовый класс. Ниже, для небольшого сценария, мы, возможно, захотим создать CREATE для всех таблиц базы данных SQLite:

engine = create_engine("sqlite://")

Base.metadata.create_all(engine)

Декларативная конфигурация таблиц¶

При использовании конфигурации декларативной таблицы с атрибутом декларативного класса __tablename__ дополнительные аргументы для конструктора Table должны быть предоставлены с помощью атрибута декларативного класса __table_args__.

Этот атрибут позволяет использовать как позиционные, так и ключевые аргументы, которые обычно передаются конструктору Table. Атрибут может быть задан в одной из двух форм. Первая - в виде словаря:

class MyClass(Base):
    __tablename__ = "sometable"
    __table_args__ = {"mysql_engine": "InnoDB"}

Другой, кортеж, где каждый аргумент является позиционным (обычно ограничения):

class MyClass(Base):
    __tablename__ = "sometable"
    __table_args__ = (
        ForeignKeyConstraint(["id"], ["remote_table.id"]),
        UniqueConstraint("foo"),
    )

Аргументы ключевых слов могут быть указаны в приведенной выше форме, если последний аргумент указать в виде словаря:

class MyClass(Base):
    __tablename__ = "sometable"
    __table_args__ = (
        ForeignKeyConstraint(["id"], ["remote_table.id"]),
        UniqueConstraint("foo"),
        {"autoload": True},
    )

Класс может также указать декларативный атрибут __table_args__, а также атрибут __tablename__ в динамическом стиле с помощью декоратора метода declared_attr(). Подробнее см. в разделе Составление сопоставленных иерархий с помощью миксинов.

Явное имя схемы с декларативной таблицей¶

Имя схемы для Table, документированное в Указание имени схемы, применяется к отдельной Table с помощью аргумента Table.schema. При использовании декларативных таблиц этот параметр, как и любой другой, передается в словарь __table_args__:

from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass


class MyClass(Base):
    __tablename__ = "sometable"
    __table_args__ = {"schema": "some_schema"}

Имя схемы также может быть применено ко всем объектам Table глобально с помощью параметра MetaData.schema, документированного в Указание имени схемы по умолчанию с помощью метаданных. Объект MetaData может быть построен отдельно и связан с подклассом DeclarativeBase путем присвоения атрибуту metadata непосредственно:

from sqlalchemy import MetaData
from sqlalchemy.orm import DeclarativeBase

metadata_obj = MetaData(schema="some_schema")


class Base(DeclarativeBase):
    metadata = metadata_obj


class MyClass(Base):
    # will use "some_schema" by default
    __tablename__ = "sometable"

Настройка параметров загрузки и сохранения для декларативных сопоставленных столбцов¶

Конструкция mapped_column() принимает дополнительные аргументы, специфичные для ORM, которые влияют на способ отображения сгенерированного Column, влияя на его поведение при загрузке и сохранении. Обычно используются следующие параметры:

• отложенная загрузка столбцов - Булево значение mapped_column.deferred устанавливает, что Column по умолчанию использует deferred column loading. В приведенном ниже примере столбец User.bio не будет загружаться по умолчанию, а только при обращении к нему:

  class User(Base):
      __tablename__ = "user"
  
      id: Mapped[int] = mapped_column(primary_key=True)
      name: Mapped[str]
      bio: Mapped[str] = mapped_column(Text, deferred=True)

  См.также

  Ограничение загрузки столбцов с помощью функции Column Deferral - полное описание отложенной загрузки колонн

• активная история - mapped_column.active_history гарантирует, что при изменении значения атрибута предыдущее значение будет загружено и станет частью коллекции AttributeState.history при просмотре истории атрибута. Это может повлечь за собой дополнительные SQL-запросы:

  class User(Base):
      __tablename__ = "user"
  
      id: Mapped[int] = mapped_column(primary_key=True)
      important_identifier: Mapped[str] = mapped_column(active_history=True)

Список поддерживаемых параметров см. в docstring для mapped_column().

Явное именование декларативных сопоставленных столбцов¶

Все приведенные примеры содержат конструкцию mapped_column(), связанную с сопоставленным атрибутом ORM, где имя атрибута Python, указанное в mapped_column(), также является именем столбца, как мы видим в операторах CREATE TABLE, а также в запросах. Имя столбца, выраженное в SQL, может быть указано путем передачи строкового позиционного аргумента mapped_column.__name в качестве первого позиционного аргумента. В приведенном ниже примере класс User сопоставлен с альтернативными именами, присвоенными самим столбцам:

class User(Base):
    __tablename__ = "user"

    id: Mapped[int] = mapped_column("user_id", primary_key=True)
    name: Mapped[str] = mapped_column("user_name")

Где выше User.id разрешается в колонку с именем user_id, а User.name разрешается в колонку с именем user_name. Мы можем написать оператор select(), используя наши имена атрибутов Python, и увидим сгенерированные имена SQL:

>>> from sqlalchemy import select
>>> print(select(User.id, User.name).where(User.name == "x"))
{printsql}SELECT "user".user_id, "user".user_name
FROM "user"
WHERE "user".user_name = :user_name_1

Добавление дополнительных столбцов к существующему декларативному сопоставленному классу¶

Декларативная конфигурация таблицы позволяет добавлять новые Column объекты в существующее отображение после того, как метаданные Table уже сгенерированы.

Для декларативного класса, который объявлен с использованием декларативного базового класса, базовый метакласс DeclarativeMeta включает метод __setattr__(), который будет перехватывать дополнительные объекты mapped_column() или Core Column и добавлять их как в Table с помощью Table.append_column(), так и в существующий Mapper с помощью Mapper.add_property():

MyClass.some_new_column = mapped_column(String)

Использование ядра Column:

MyClass.some_new_column = Column(String)

Поддерживаются все аргументы, включая альтернативное имя, например MyClass.some_new_column = mapped_column("some_name", String). Однако тип SQL должен быть передан объекту mapped_column() или Column явно, как в приведенных выше примерах, где передается тип String. Для аннотационного типа Mapped нет возможности принять участие в операции.

Дополнительные объекты Column также могут быть добавлены к отображению в особых обстоятельствах использования наследования одной таблицы, когда дополнительные столбцы присутствуют в отображаемых подклассах, не имеющих собственных Table. Это проиллюстрировано в разделе Наследование одной таблицы.

Альтернативные имена атрибутов для столбцов таблицы сопоставления¶

В разделе Явное именование декларативных сопоставленных столбцов было показано, как использовать mapped_column() для предоставления конкретного имени для сгенерированного объекта Column отдельно от имени атрибута, под которым он сопоставлен.

При использовании конфигурации Imperative Table у нас уже присутствуют объекты Column. Чтобы сопоставить их с альтернативными именами, мы можем присвоить Column непосредственно желаемым атрибутам:

user_table = Table(
    "user",
    Base.metadata,
    Column("user_id", Integer, primary_key=True),
    Column("user_name", String),
)


class User(Base):
    __table__ = user_table

    id = user_table.c.user_id
    name = user_table.c.user_name

Приведенное выше отображение User будет ссылаться на столбцы "user_id" и "user_name" через атрибуты User.id и User.name, так же, как это было продемонстрировано в Явное именование декларативных сопоставленных столбцов.

Одно из замечаний к приведенному выше отображению заключается в том, что прямая инлайн-ссылка на Column не будет набираться правильно при использовании инструментов набора PEP 484. Стратегия решения этой проблемы заключается в применении объектов Column внутри функции column_property(); хотя Mapper уже автоматически генерирует этот объект свойства для своего внутреннего использования, именуя его в объявлении класса, инструменты набора смогут сопоставить атрибут с аннотацией Mapped:

from sqlalchemy.orm import column_property
from sqlalchemy.orm import Mapped


class User(Base):
    __table__ = user_table

    id: Mapped[int] = column_property(user_table.c.user_id)
    name: Mapped[str] = column_property(user_table.c.user_name)

Применение опций загрузки, сохранения и отображения для столбцов императивной таблицы¶

В разделе Настройка параметров загрузки и сохранения для декларативных сопоставленных столбцов было рассмотрено, как установить параметры загрузки и сохранения при использовании конструкции mapped_column() с конфигурацией Declarative Table. При использовании конфигурации Imperative Table у нас уже есть существующие объекты Column, которые отображаются. Чтобы отобразить эти объекты Column вместе с дополнительными параметрами, специфичными для отображения ORM, мы можем использовать конструкции column_property() и deferred(), чтобы связать дополнительные параметры со столбцом. Варианты включают:

• отложенная загрузка столбцов - Функция deferred() является сокращением для вызова column_property() с параметром column_property.deferred, установленным в True; эта конструкция устанавливает Column, используя deferred column loading по умолчанию. В приведенном ниже примере столбец User.bio не будет загружен по умолчанию, а только при обращении к нему:

  from sqlalchemy.orm import deferred
  
  user_table = Table(
      "user",
      Base.metadata,
      Column("id", Integer, primary_key=True),
      Column("name", String),
      Column("bio", Text),
  )
  
  
  class User(Base):
      __table__ = user_table
  
      bio = deferred(user_table.c.bio)

См.также

Ограничение загрузки столбцов с помощью функции Column Deferral - полное описание отложенной загрузки колонн

• активная история - column_property.active_history гарантирует, что при изменении значения атрибута предыдущее значение будет загружено и станет частью коллекции AttributeState.history при просмотре истории атрибута. Это может повлечь за собой дополнительные SQL-запросы:

  from sqlalchemy.orm import deferred
  
  user_table = Table(
      "user",
      Base.metadata,
      Column("id", Integer, primary_key=True),
      Column("important_identifier", String),
  )
  
  
  class User(Base):
      __table__ = user_table
  
      important_identifier = column_property(
          user_table.c.important_identifier, active_history=True
      )

Использование DeferredReflection¶

Чтобы приспособиться к случаю объявления сопоставленных классов, где отражение метаданных таблицы может произойти после, доступно простое расширение под названием DeferredReflection mixin, которое изменяет процесс декларативного сопоставления, чтобы отложить его до вызова специального метода DeferredReflection.prepare() на уровне класса, который выполнит процесс отражения в целевой базе данных и интегрирует результаты с процессом декларативного сопоставления таблиц, то есть классов, которые используют __tablename__ атрибут:

from sqlalchemy.ext.declarative import DeferredReflection
from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass


class Reflected(DeferredReflection):
    __abstract__ = True


class Foo(Reflected, Base):
    __tablename__ = "foo"
    bars = relationship("Bar")


class Bar(Reflected, Base):
    __tablename__ = "bar"

    foo_id = mapped_column(Integer, ForeignKey("foo.id"))

Выше мы создали класс mixin Reflected, который будет служить базой для классов в нашей декларативной иерархии, которые должны стать отображаемыми при вызове метода Reflected.prepare. Приведенное выше отображение не будет завершено, пока мы не сделаем это, учитывая Engine:

engine = create_engine("postgresql+psycopg2://user:pass@hostname/my_existing_database")
Reflected.prepare(engine)

Целью класса Reflected является определение области, в которой классы должны быть отражены. Плагин будет искать в дереве подклассов цели, по отношению к которой вызывается .prepare(), и отражать все таблицы, которые названы объявленными классами; таблицы в целевой базе данных, которые не являются частью отображений и не связаны с целевыми таблицами через ограничение внешнего ключа, не будут отражены.

Использование Automap¶

Более автоматизированное решение для сопоставления с существующей базой данных, где будет использоваться отражение таблиц, заключается в использовании расширения Automap. Это расширение генерирует целые сопоставленные классы из схемы базы данных, включая отношения между классами, основанные на наблюдаемых ограничениях внешнего ключа. Хотя оно включает в себя крючки для настройки, например, крючки, позволяющие создавать собственные схемы именования классов и отношений, automap ориентирован на быстрый стиль работы с нулевой конфигурацией. Если приложение хочет иметь полностью явную модель, использующую отражение таблиц, класс DeferredReflection может быть предпочтительнее из-за его менее автоматизированного подхода.

Автоматизация схем именования столбцов из отраженных таблиц¶

При использовании любого из предыдущих методов отражения у нас есть возможность изменить схему именования, по которой отображаются столбцы. Объект Column включает параметр Column.key, который представляет собой строковое имя, определяющее, под каким именем данный Column будет присутствовать в коллекции Table.c, независимо от SQL-имени столбца. Этот ключ также используется Mapper в качестве имени атрибута, под которым будет отображаться Column, если он не задан другим способом, например, как показано в Альтернативные имена атрибутов для столбцов таблицы сопоставления.

При работе с отражением таблицы мы можем перехватывать параметры, которые будут использоваться для Column по мере их получения с помощью события DDLEvents.column_reflect() и применять любые необходимые нам изменения, включая атрибут .key, а также такие вещи, как типы данных.

Крючок события проще всего связать с используемым объектом MetaData, как показано ниже:

from sqlalchemy import event
from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass


@event.listens_for(Base.metadata, "column_reflect")
def column_reflect(inspector, table, column_info):
    # set column.key = "attr_<lower_case_name>"
    column_info["key"] = "attr_%s" % column_info["name"].lower()

С помощью вышеуказанного события отражение объектов Column будет перехвачено нашим событием, добавляющим новый элемент «.key», например, в отображении, как показано ниже:

class MyClass(Base):
    __table__ = Table("some_table", Base.metadata, autoload_with=some_engine)

Этот подход также работает как с базовым классом DeferredReflection, так и с расширением Automap. Что касается конкретно automap, смотрите раздел Определения перехватывающих колонок для справки.

Сопоставление с явным набором столбцов первичного ключа¶

Конструкция Mapper для успешного отображения таблицы всегда требует, чтобы по крайней мере один столбец был определен как «первичный ключ» для этой выбираемой таблицы. Это необходимо для того, чтобы при загрузке или сохранении объекта ORM его можно было поместить в identity map с соответствующим identity key.

В тех случаях, когда отраженная таблица, подлежащая отображению, не включает ограничение первичного ключа, а также в общем случае для mapping against arbitrary selectables, когда столбцы первичного ключа могут отсутствовать, параметр Mapper.primary_key предоставляется для того, чтобы любой набор столбцов мог быть настроен как «первичный ключ» для таблицы, насколько это касается отображения ORM.

Учитывая следующий пример отображения Imperative Table на существующий объект Table, где таблица не имеет объявленного первичного ключа (как это может произойти в сценариях отражения), мы можем отобразить такую таблицу, как в следующем примере:

from sqlalchemy import Column
from sqlalchemy import MetaData
from sqlalchemy import String
from sqlalchemy import Table
from sqlalchemy import UniqueConstraint
from sqlalchemy.orm import DeclarativeBase


metadata = MetaData()
group_users = Table(
    "group_users",
    metadata,
    Column("user_id", String(40), nullable=False),
    Column("group_id", String(40), nullable=False),
    UniqueConstraint("user_id", "group_id"),
)


class Base(DeclarativeBase):
    pass


class GroupUsers(Base):
    __table__ = group_users
    __mapper_args__ = {"primary_key": [group_users.c.user_id, group_users.c.group_id]}

Выше, таблица group_users представляет собой некую ассоциативную таблицу со строковыми столбцами user_id и group_id, но первичный ключ не установлен; вместо этого есть только UniqueConstraint, устанавливающий, что эти два столбца представляют собой уникальный ключ. Mapper не проверяет автоматически уникальные ограничения для первичных ключей; вместо этого мы используем параметр Mapper.primary_key, передавая коллекцию [group_users.c.user_id, group_users.c.group_id], указывающую, что эти два столбца должны быть использованы для построения ключа идентификации для экземпляров класса GroupUsers.

Сопоставление подмножества столбцов таблицы¶

Иногда отражение таблицы может предоставить Table с большим количеством столбцов, которые не важны для наших нужд и могут быть безопасно проигнорированы. Для такой таблицы, имеющей множество столбцов, на которые не нужно ссылаться в приложении, параметры Mapper.include_properties или Mapper.exclude_properties могут указывать на подмножество столбцов, подлежащих отображению, где другие столбцы из целевой Table не будут рассматриваться ORM никаким образом. Пример:

class User(Base):
    __table__ = user_table
    __mapper_args__ = {"include_properties": ["user_id", "user_name"]}

В приведенном выше примере класс User будет отображен на таблицу user_table, включая только столбцы user_id и user_name - на остальные столбцы ссылки нет.

Аналогично:

class Address(Base):
    __table__ = address_table
    __mapper_args__ = {"exclude_properties": ["street", "city", "state", "zip"]}

отобразит класс Address в таблицу address_table, включая все присутствующие столбцы, кроме street, city, state и zip.

Как показано в двух примерах, на столбцы можно ссылаться либо по строковому имени, либо непосредственно на объект Column. Прямая ссылка на объект может быть полезна для ясности, а также для устранения неоднозначности при отображении на многотабличные конструкции, которые могут иметь повторяющиеся имена:

class User(Base):
    __table__ = user_table
    __mapper_args__ = {
        "include_properties": [user_table.c.user_id, user_table.c.user_name]
    }

Когда колонки не включены в отображение, на них не будет ссылок в операторах SELECT, выдаваемых при выполнении объектов select() или унаследованных Query, также не будет атрибута отображаемого класса, который представляет колонку; присвоение атрибута с таким именем не будет иметь никакого эффекта, кроме обычного присвоения атрибута в Python.

Однако важно отметить, что умолчания столбцов на уровне схемы все еще будут действовать для тех объектов Column, которые их включают, даже если они могут быть исключены из отображения ORM.

«Умолчания столбцов уровня схемы» относятся к умолчаниям, описанным в Колонки INSERT/UPDATE по умолчанию, включая те, которые конфигурируются параметрами Column.default, Column.onupdate, Column.server_default и Column.server_onupdate. Эти конструкции продолжают оказывать нормальное воздействие, поскольку в случае Column.default и Column.onupdate объект Column все еще присутствует на базовом Table, что позволяет функциям по умолчанию иметь место, когда ORM выдает INSERT или UPDATE, а в случае Column.server_default и Column.server_onupdate сама реляционная база данных выдает эти значения по умолчанию как поведение на стороне сервера.