复合列类型

Composite Column Types

中文

成组的列可以与单个用户定义的数据类型关联，在现代使用中通常是一个Python dataclass。ORM 提供了一个代表您提供的列组的单一属性。

一个简单的例子将成对的 Integer 列表示为一个 Point 对象，具有 .x 和 .y 属性。使用 dataclass，这些属性使用相应的 int Python 类型定义:

import dataclasses


@dataclasses.dataclass
class Point:
    x: int
    y: int

非dataclass形式也被接受，但需要实现额外的方法。有关使用非dataclass类的示例，请参见 使用旧式非数据类 部分。

在 2.0 版本加入: composite() 结构完全支持Python dataclass，包括从组合类派生映射列数据类型的能力。

我们将创建一个映射到表 vertices 的映射，表示为 x1/y1 和 x2/y2 的两个点。使用 composite() 结构将 Point 类与映射列相关联。

下面的示例说明了使用完整的 Annotated Declarative Table 配置的最现代形式的 composite()。表示每列的 mapped_column() 结构直接传递给 composite()，指示要生成的列的零个或多个方面，在这种情况下是名称; composite() 结构直接从 dataclass 派生列类型（在这种情况下为 int，对应于 Integer）:

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


class Base(DeclarativeBase):
    pass


class Vertex(Base):
    __tablename__ = "vertices"

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

    start: Mapped[Point] = composite(mapped_column("x1"), mapped_column("y1"))
    end: Mapped[Point] = composite(mapped_column("x2"), mapped_column("y2"))

    def __repr__(self):
        return f"Vertex(start={self.start}, end={self.end})"

小技巧

在上面的示例中，表示组合的列（ x1 ， y1 ，等）也可以在类上访问，但类型检查器无法正确理解。如果访问单个列很重要，它们可以显式声明，如 直接映射列，将属性名称传递给复合 中所示。

上述映射将对应于一个 CREATE TABLE 语句，如下所示:

>>> from sqlalchemy.schema import CreateTable
>>> print(CreateTable(Vertex.__table__))
CREATE TABLE vertices (
id INTEGER NOT NULL,
x1 INTEGER NOT NULL,
y1 INTEGER NOT NULL,
x2 INTEGER NOT NULL,
y2 INTEGER NOT NULL,
PRIMARY KEY (id)
)

英文

Sets of columns can be associated with a single user-defined datatype, which in modern use is normally a Python dataclass. The ORM provides a single attribute which represents the group of columns using the class you provide.

A simple example represents pairs of Integer columns as a Point object, with attributes .x and .y. Using a dataclass, these attributes are defined with the corresponding int Python type:

import dataclasses


@dataclasses.dataclass
class Point:
    x: int
    y: int

Non-dataclass forms are also accepted, but require additional methods to be implemented. For an example using a non-dataclass class, see the section 使用旧式非数据类.

在 2.0 版本加入: The composite() construct fully supports

Python dataclasses including the ability to derive mapped column datatypes from the composite class.

We will create a mapping to a table vertices, which represents two points as x1/y1 and x2/y2. The Point class is associated with the mapped columns using the composite() construct.

The example below illustrates the most modern form of composite() as used with a fully Annotated Declarative Table configuration. mapped_column() constructs representing each column are passed directly to composite(), indicating zero or more aspects of the columns to be generated, in this case the names; the composite() construct derives the column types (in this case int, corresponding to Integer) from the dataclass directly:

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


class Base(DeclarativeBase):
    pass


class Vertex(Base):
    __tablename__ = "vertices"

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

    start: Mapped[Point] = composite(mapped_column("x1"), mapped_column("y1"))
    end: Mapped[Point] = composite(mapped_column("x2"), mapped_column("y2"))

    def __repr__(self):
        return f"Vertex(start={self.start}, end={self.end})"

小技巧

In the example above the columns that represent the composites (x1, y1, etc.) are also accessible on the class but are not correctly understood by type checkers. If accessing the single columns is important they can be explicitly declared, as shown in 直接映射列，将属性名称传递给复合.

The above mapping would correspond to a CREATE TABLE statement as:

>>> from sqlalchemy.schema import CreateTable
>>> print(CreateTable(Vertex.__table__))
CREATE TABLE vertices (
id INTEGER NOT NULL,
x1 INTEGER NOT NULL,
y1 INTEGER NOT NULL,
x2 INTEGER NOT NULL,
y2 INTEGER NOT NULL,
PRIMARY KEY (id)
)

使用映射复合列类型

Working with Mapped Composite Column Types

中文

通过如上所示的映射，我们可以使用 Vertex 类，其中 .start 和 .end 属性将透明地引用 Point 类引用的列，以及 Vertex 类的实例，其中 .start 和 .end 属性将引用 Point 类的实例。 x1、 y1、 x2 和 y2 列透明地处理:

• 持久化 Point 对象

  我们可以创建一个 Vertex 对象，分配 Point 对象作为成员，并且它们将按预期持久化:

  >>> v = Vertex(start=Point(3, 4), end=Point(5, 6))
  >>> session.add(v)
  >>> session.commit()
  BEGIN (implicit)
  INSERT INTO vertices (x1, y1, x2, y2) VALUES (?, ?, ?, ?)
  [generated in ...] (3, 4, 5, 6)
  COMMIT
  

• 选择 Point 对象作为列

  composite() 将允许 Vertex.start 和 Vertex.end 属性在使用 ORM Query 对象）选择 Point 对象时尽可能地表现为单个 SQL 表达式:

  >>> stmt = select(Vertex.start, Vertex.end)
  >>> session.execute(stmt).all()
  SELECT vertices.x1, vertices.y1, vertices.x2, vertices.y2
  FROM vertices
  [...] ()
  [(Point(x=3, y=4), Point(x=5, y=6))]

• 在 SQL 表达式中比较 Point 对象

  Vertex.start 和 Vertex.end 属性可以在 WHERE 条件和类似的地方使用，使用临时的 Point 对象进行比较:

  >>> stmt = select(Vertex).where(Vertex.start == Point(3, 4)).where(Vertex.end < Point(7, 8))
  >>> session.scalars(stmt).all()
  SELECT vertices.id, vertices.x1, vertices.y1, vertices.x2, vertices.y2
  FROM vertices
  WHERE vertices.x1 = ? AND vertices.y1 = ? AND vertices.x2 < ? AND vertices.y2 < ?
  [...] (3, 4, 7, 8)
  [Vertex(Point(x=3, y=4), Point(x=5, y=6))]

  在 2.0 版本加入: composite() 构造现在支持“排序”比较，如 <、 >= 和类似的，除了已经存在的支持 ==、 !=。

  小技巧

  上述使用“小于”操作符（ < ）的“排序”比较以及使用 == 的“等式”比较，在生成 SQL 表达式时，由 Comparator 类实现，而不使用组合类本身的比较方法，例如 __lt__() 或 __eq__() 方法。因此，上述 Point dataclass 也不需要实现 dataclasses order=True 参数以使上述 SQL 操作工作。有关如何自定义比较操作的背景，请参阅 重新定义复合的比较操作。

• 更新 Vertex 实例上的 Point 对象

默认情况下，必须用新对象替换 Point 对象，以检测到更改:

>>> v1 = session.scalars(select(Vertex)).one()
    {execsql}SELECT vertices.id, vertices.x1, vertices.y1, vertices.x2, vertices.y2
    FROM vertices
    [...] ()
    {stop}

    >>> v1.end = Point(x=10, y=14)
    >>> session.commit()
    {execsql}UPDATE vertices SET x2=?, y2=? WHERE vertices.id = ?
    [...] (10, 14, 1)
    COMMIT

为了在组合对象上允许就地更改，必须使用 :ref:`mutable_toplevel` 扩展。有关示例，请参阅 :ref:`mutable_composites` 部分。

英文

With a mapping as illustrated in the top section, we can work with the Vertex class, where the .start and .end attributes will transparently refer to the columns referenced by the Point class, as well as with instances of the Vertex class, where the .start and .end attributes will refer to instances of the Point class. The x1, y1, x2, and y2 columns are handled transparently:

• Persisting Point objects

  We can create a Vertex object, assign Point objects as members, and they will be persisted as expected:

  >>> v = Vertex(start=Point(3, 4), end=Point(5, 6))
  >>> session.add(v)
  >>> session.commit()
  BEGIN (implicit)
  INSERT INTO vertices (x1, y1, x2, y2) VALUES (?, ?, ?, ?)
  [generated in ...] (3, 4, 5, 6)
  COMMIT
  

• Selecting Point objects as columns

  composite() will allow the Vertex.start and Vertex.end attributes to behave like a single SQL expression to as much an extent as possible when using the ORM Session (including the legacy Query object) to select Point objects:

  >>> stmt = select(Vertex.start, Vertex.end)
  >>> session.execute(stmt).all()
  SELECT vertices.x1, vertices.y1, vertices.x2, vertices.y2
  FROM vertices
  [...] ()
  [(Point(x=3, y=4), Point(x=5, y=6))]

• Comparing Point objects in SQL expressions

  The Vertex.start and Vertex.end attributes may be used in WHERE criteria and similar, using ad-hoc Point objects for comparisons:

  >>> stmt = select(Vertex).where(Vertex.start == Point(3, 4)).where(Vertex.end < Point(7, 8))
  >>> session.scalars(stmt).all()
  SELECT vertices.id, vertices.x1, vertices.y1, vertices.x2, vertices.y2
  FROM vertices
  WHERE vertices.x1 = ? AND vertices.y1 = ? AND vertices.x2 < ? AND vertices.y2 < ?
  [...] (3, 4, 7, 8)
  [Vertex(Point(x=3, y=4), Point(x=5, y=6))]

  在 2.0 版本加入: composite() constructs now support “ordering” comparisons such as <, >=, and similar, in addition to the already-present support for ==, !=.

  小技巧

  The “ordering” comparison above using the “less than” operator (<) as well as the “equality” comparison using ==, when used to generate SQL expressions, are implemented by the Comparator class, and don’t make use of the comparison methods on the composite class itself, e.g. the __lt__() or __eq__() methods. From this it follows that the Point dataclass above also need not implement the dataclasses order=True parameter for the above SQL operations to work. The section 重新定义复合的比较操作 contains background on how to customize the comparison operations.

• Updating Point objects on Vertex Instances

  By default, the Point object must be replaced by a new object for changes to be detected:

  >>> v1 = session.scalars(select(Vertex)).one()
  SELECT vertices.id, vertices.x1, vertices.y1, vertices.x2, vertices.y2
  FROM vertices
  [...] ()
  >>> v1.end = Point(x=10, y=14)
  >>> session.commit()
  UPDATE vertices SET x2=?, y2=? WHERE vertices.id = ?
  [...] (10, 14, 1)
  COMMIT
  

  In order to allow in place changes on the composite object, the 突变追踪 extension must be used. See the section 在复合材料上建立可变性 for examples.

复合的其他映射形式

Other mapping forms for composites

中文

composite() 构造可以使用 mapped_column() 构造、Column 或现有映射列的字符串名称传递相关列。以下示例说明了与上述主要部分等效的映射。

英文

The composite() construct may be passed the relevant columns using a mapped_column() construct, a Column, or the string name of an existing mapped column. The following examples illustrate an equivalent mapping as that of the main section above.

直接映射列，然后传递给 composite

Map columns directly, then pass to composite

中文

在这里，我们将现有的 mapped_column() 实例传递给 composite() 构造，如下面的非注释示例中，我们还将 Point 类作为第一个参数传递给 composite():

from sqlalchemy import Integer
from sqlalchemy.orm import mapped_column, composite


class Vertex(Base):
    __tablename__ = "vertices"

    id = mapped_column(Integer, primary_key=True)
    x1 = mapped_column(Integer)
    y1 = mapped_column(Integer)
    x2 = mapped_column(Integer)
    y2 = mapped_column(Integer)

    start = composite(Point, x1, y1)
    end = composite(Point, x2, y2)

英文

Here we pass the existing mapped_column() instances to the composite() construct, as in the non-annotated example below where we also pass the Point class as the first argument to composite():

from sqlalchemy import Integer
from sqlalchemy.orm import mapped_column, composite


class Vertex(Base):
    __tablename__ = "vertices"

    id = mapped_column(Integer, primary_key=True)
    x1 = mapped_column(Integer)
    y1 = mapped_column(Integer)
    x2 = mapped_column(Integer)
    y2 = mapped_column(Integer)

    start = composite(Point, x1, y1)
    end = composite(Point, x2, y2)

直接映射列，将属性名称传递给复合

Map columns directly, pass attribute names to composite

中文

我们可以使用更多带注释的形式编写上述相同的示例，其中我们可以选择将属性名称传递给 composite() 而不是完整的列构造:

from sqlalchemy.orm import mapped_column, composite, Mapped


class Vertex(Base):
    __tablename__ = "vertices"

    id: Mapped[int] = mapped_column(primary_key=True)
    x1: Mapped[int]
    y1: Mapped[int]
    x2: Mapped[int]
    y2: Mapped[int]

    start: Mapped[Point] = composite("x1", "y1")
    end: Mapped[Point] = composite("x2", "y2")

英文

We can write the same example above using more annotated forms where we have the option to pass attribute names to composite() instead of full column constructs:

from sqlalchemy.orm import mapped_column, composite, Mapped


class Vertex(Base):
    __tablename__ = "vertices"

    id: Mapped[int] = mapped_column(primary_key=True)
    x1: Mapped[int]
    y1: Mapped[int]
    x2: Mapped[int]
    y2: Mapped[int]

    start: Mapped[Point] = composite("x1", "y1")
    end: Mapped[Point] = composite("x2", "y2")

命令式映射和命令式表

Imperative mapping and imperative table

中文

当使用 imperative table 或完全 imperative 映射时，我们可以直接访问 Column 对象。这些对象也可以传递给 composite()，如下述命令式示例所示:

mapper_registry.map_imperatively(
    Vertex,
    vertices_table,
    properties={
        "start": composite(Point, vertices_table.c.x1, vertices_table.c.y1),
        "end": composite(Point, vertices_table.c.x2, vertices_table.c.y2),
    },
)

英文

When using imperative table or fully imperative mappings, we have access to Column objects directly. These may be passed to composite() as well, as in the imperative example below:

mapper_registry.map_imperatively(
    Vertex,
    vertices_table,
    properties={
        "start": composite(Point, vertices_table.c.x1, vertices_table.c.y1),
        "end": composite(Point, vertices_table.c.x2, vertices_table.c.y2),
    },
)

使用旧式非数据类

Using Legacy Non-Dataclasses

中文

如果不使用 dataclass，自定义数据类型类的要求是它有一个接受与其列格式对应的位置参数的构造函数，并且还提供一个 __composite_values__() 方法，该方法按其基于列的属性顺序返回对象的状态，作为列表或元组。它还应提供适当的 __eq__() 和 __ne__() 方法来测试两个实例的相等性。

为了说明不使用 dataclass 的主部分中的等效 Point 类:

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __composite_values__(self):
        return self.x, self.y

    def __repr__(self):
        return f"Point(x={self.x!r}, y={self.y!r})"

    def __eq__(self, other):
        return isinstance(other, Point) and other.x == self.x and other.y == self.y

    def __ne__(self, other):
        return not self.__eq__(other)

然后使用 composite()，其中必须使用 复合的其他映射形式 中的一种形式显式声明与 Point 类关联的列。

英文

If not using a dataclass, the requirements for the custom datatype class are that it have a constructor which accepts positional arguments corresponding to its column format, and also provides a method __composite_values__() which returns the state of the object as a list or tuple, in order of its column-based attributes. It also should supply adequate __eq__() and __ne__() methods which test the equality of two instances.

To illustrate the equivalent Point class from the main section not using a dataclass:

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __composite_values__(self):
        return self.x, self.y

    def __repr__(self):
        return f"Point(x={self.x!r}, y={self.y!r})"

    def __eq__(self, other):
        return isinstance(other, Point) and other.x == self.x and other.y == self.y

    def __ne__(self, other):
        return not self.__eq__(other)

Usage with composite() then proceeds where the columns to be associated with the Point class must also be declared with explicit types, using one of the forms at 复合的其他映射形式.

跟踪复合上的就地突变

Tracking In-Place Mutations on Composites

中文

现有组合值的就地更改不会自动跟踪。相反，组合类需要显式地向其父对象提供事件。通过使用 MutableComposite 混入类，这项任务在很大程度上是自动化的，该类使用事件将每个用户定义的组合对象与所有父关联关联起来。请参阅 在复合材料上建立可变性 中的示例。

英文

In-place changes to an existing composite value are not tracked automatically. Instead, the composite class needs to provide events to its parent object explicitly. This task is largely automated via the usage of the MutableComposite mixin, which uses events to associate each user-defined composite object with all parent associations. Please see the example in 在复合材料上建立可变性.

重新定义复合的比较操作

Redefining Comparison Operations for Composites

中文

默认情况下，“等于”比较操作会生成所有相应列相互等价的 AND。这可以使用 composite() 的 comparator_factory 参数更改，我们在其中指定一个自定义的 Comparator 类来定义现有或新操作。下面我们说明了“大于”操作符，实现了与基本“大于”操作相同的表达式:

import dataclasses

from sqlalchemy.orm import composite
from sqlalchemy.orm import CompositeProperty
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.sql import and_


@dataclasses.dataclass
class Point:
    x: int
    y: int


class PointComparator(CompositeProperty.Comparator):
    def __gt__(self, other):
        """重新定义“大于”操作"""

        return and_(
            *[
                a > b
                for a, b in zip(
                    self.__clause_element__().clauses,
                    dataclasses.astuple(other),
                )
            ]
        )


class Base(DeclarativeBase):
    pass


class Vertex(Base):
    __tablename__ = "vertices"

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

    start: Mapped[Point] = composite(
        mapped_column("x1"), mapped_column("y1"), comparator_factory=PointComparator
    )
    end: Mapped[Point] = composite(
        mapped_column("x2"), mapped_column("y2"), comparator_factory=PointComparator
    )

由于 Point 是一个dataclass，我们可以使用 dataclasses.astuple() 获取 Point 实例的元组形式。

然后自定义比较器返回适当的SQL表达式:

>>> print(Vertex.start > Point(5, 6))
vertices.x1 > :x1_1 AND vertices.y1 > :y1_1

英文

The “equals” comparison operation by default produces an AND of all corresponding columns equated to one another. This can be changed using the comparator_factory argument to composite(), where we specify a custom Comparator class to define existing or new operations. Below we illustrate the “greater than” operator, implementing the same expression that the base “greater than” does:

import dataclasses

from sqlalchemy.orm import composite
from sqlalchemy.orm import CompositeProperty
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.sql import and_


@dataclasses.dataclass
class Point:
    x: int
    y: int


class PointComparator(CompositeProperty.Comparator):
    def __gt__(self, other):
        """redefine the 'greater than' operation"""

        return and_(
            *[
                a > b
                for a, b in zip(
                    self.__clause_element__().clauses,
                    dataclasses.astuple(other),
                )
            ]
        )


class Base(DeclarativeBase):
    pass


class Vertex(Base):
    __tablename__ = "vertices"

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

    start: Mapped[Point] = composite(
        mapped_column("x1"), mapped_column("y1"), comparator_factory=PointComparator
    )
    end: Mapped[Point] = composite(
        mapped_column("x2"), mapped_column("y2"), comparator_factory=PointComparator
    )

Since Point is a dataclass, we may make use of dataclasses.astuple() to get a tuple form of Point instances.

The custom comparator then returns the appropriate SQL expression:

>>> print(Vertex.start > Point(5, 6))
vertices.x1 > :x1_1 AND vertices.y1 > :y1_1

嵌套复合

Nesting Composites

中文

组合对象可以定义为在简单的嵌套方案中工作，通过在组合类中重新定义行为以按预期工作，然后通常将组合类映射到单个列的完整长度。这要求定义在“嵌套(nested)”和“平面(flat)”形式之间移动的附加方法。

下面我们将 Vertex 类重新组织为本身是一个引用 Point 对象的组合对象。 Vertex 和 Point 可以是 dataclass，不过我们将为 Vertex 添加一个自定义构造方法，该方法可以用来根据四个列值创建新的 Vertex 对象，我们将任意命名为 _generate() 并定义为类方法，以便我们可以通过将值传递给 Vertex._generate() 方法来创建新的 Vertex 对象。

我们还将实现 __composite_values__() 方法，这是一个由 composite() 构造（之前在 使用旧式非数据类 中介绍）识别的固定名称，表示以平面列值元组接收对象的标准方式，在这种情况下将取代通常的 dataclass 方法。

有了自定义的 _generate() 构造函数和 __composite_values__() 序列化方法，我们现在可以在平面列元组和包含 Point 实例的 Vertex 对象之间移动。 Vertex._generate 方法作为第一个参数传递给 composite() 构造作为新 Vertex 实例的来源，__composite_values__() 方法将由 composite() 隐式使用。

为了示例的目的，Vertex 组合然后映射到一个称为 HasVertex 的类，这是包含四个源列的 Table 最终所在的地方:

from __future__ import annotations

import dataclasses
from typing import Any
from typing import Tuple

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


@dataclasses.dataclass
class Point:
    x: int
    y: int


@dataclasses.dataclass
class Vertex:
    start: Point
    end: Point

    @classmethod
    def _generate(cls, x1: int, y1: int, x2: int, y2: int) -> Vertex:
        """从行生成 Vertex"""
        return Vertex(Point(x1, y1), Point(x2, y2))

    def __composite_values__(self) -> Tuple[Any, ...]:
        """从 Vertex 生成一行"""
        return dataclasses.astuple(self.start) + dataclasses.astuple(self.end)


class Base(DeclarativeBase):
    pass


class HasVertex(Base):
    __tablename__ = "has_vertex"
    id: Mapped[int] = mapped_column(primary_key=True)
    x1: Mapped[int]
    y1: Mapped[int]
    x2: Mapped[int]
    y2: Mapped[int]

    vertex: Mapped[Vertex] = composite(Vertex._generate, "x1", "y1", "x2", "y2")

上述映射可以在 HasVertex、Vertex 和 Point 方面使用:

hv = HasVertex(vertex=Vertex(Point(1, 2), Point(3, 4)))

session.add(hv)
session.commit()

stmt = select(HasVertex).where(HasVertex.vertex == Vertex(Point(1, 2), Point(3, 4)))

hv = session.scalars(stmt).first()
print(hv.vertex.start)
print(hv.vertex.end)

英文

Composite objects can be defined to work in simple nested schemes, by redefining behaviors within the composite class to work as desired, then mapping the composite class to the full length of individual columns normally. This requires that additional methods to move between the “nested” and “flat” forms are defined.

Below we reorganize the Vertex class to itself be a composite object which refers to Point objects. Vertex and Point can be dataclasses, however we will add a custom construction method to Vertex that can be used to create new Vertex objects given four column values, which will will arbitrarily name _generate() and define as a classmethod so that we can make new Vertex objects by passing values to the Vertex._generate() method.

We will also implement the __composite_values__() method, which is a fixed name recognized by the composite() construct (introduced previously at 使用旧式非数据类) that indicates a standard way of receiving the object as a flat tuple of column values, which in this case will supersede the usual dataclass-oriented methodology.

With our custom _generate() constructor and __composite_values__() serializer method, we can now move between a flat tuple of columns and Vertex objects that contain Point instances. The Vertex._generate method is passed as the first argument to the composite() construct as the source of new Vertex instances, and the __composite_values__() method will be used implicitly by composite().

For the purposes of the example, the Vertex composite is then mapped to a class called HasVertex, which is where the Table containing the four source columns ultimately resides:

from __future__ import annotations

import dataclasses
from typing import Any
from typing import Tuple

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


@dataclasses.dataclass
class Point:
    x: int
    y: int


@dataclasses.dataclass
class Vertex:
    start: Point
    end: Point

    @classmethod
    def _generate(cls, x1: int, y1: int, x2: int, y2: int) -> Vertex:
        """generate a Vertex from a row"""
        return Vertex(Point(x1, y1), Point(x2, y2))

    def __composite_values__(self) -> Tuple[Any, ...]:
        """generate a row from a Vertex"""
        return dataclasses.astuple(self.start) + dataclasses.astuple(self.end)


class Base(DeclarativeBase):
    pass


class HasVertex(Base):
    __tablename__ = "has_vertex"
    id: Mapped[int] = mapped_column(primary_key=True)
    x1: Mapped[int]
    y1: Mapped[int]
    x2: Mapped[int]
    y2: Mapped[int]

    vertex: Mapped[Vertex] = composite(Vertex._generate, "x1", "y1", "x2", "y2")

The above mapping can then be used in terms of HasVertex, Vertex, and Point:

hv = HasVertex(vertex=Vertex(Point(1, 2), Point(3, 4)))

session.add(hv)
session.commit()

stmt = select(HasVertex).where(HasVertex.vertex == Vertex(Point(1, 2), Point(3, 4)))

hv = session.scalars(stmt).first()
print(hv.vertex.start)
print(hv.vertex.end)

复合 API

Composite API

Object Name	Description
composite([_class_or_attr], *attrs, [group, deferred, raiseload, comparator_factory, active_history, init, repr, default, default_factory, compare, kw_only, hash, info, doc], **__kw)	Return a composite column-based property for use with a Mapper.

function sqlalchemy.orm.composite(_class_or_attr: None | Type[_CC] | Callable[..., _CC] | _CompositeAttrType[Any] = None, /, *attrs: _CompositeAttrType[Any], group: str | None = None, deferred: bool = False, raiseload: bool = False, comparator_factory: Type[Composite.Comparator[_T]] | None = None, active_history: bool = False, init: _NoArg | bool = _NoArg.NO_ARG, repr: _NoArg | bool = _NoArg.NO_ARG, default: Any | None = _NoArg.NO_ARG, default_factory: _NoArg | Callable[[], _T] = _NoArg.NO_ARG, compare: _NoArg | bool = _NoArg.NO_ARG, kw_only: _NoArg | bool = _NoArg.NO_ARG, hash: _NoArg | bool | None = _NoArg.NO_ARG, info: _InfoType | None = None, doc: str | None = None, **__kw: Any) → Composite[Any]

Return a composite column-based property for use with a Mapper.

See the mapping documentation section 复合列类型 for a full usage example.

The MapperProperty returned by composite() is the Composite.

参数:

• class_ – The “composite type” class, or any classmethod or callable which will produce a new instance of the composite object given the column values in order.

• *attrs –

  List of elements to be mapped, which may include:

  • Column objects

  • mapped_column() constructs

  • string names of other attributes on the mapped class, which may be any other SQL or object-mapped attribute. This can for example allow a composite that refers to a many-to-one relationship

• active_history=False – When True, indicates that the “previous” value for a scalar attribute should be loaded when replaced, if not already loaded. See the same flag on column_property().

• group – A group name for this property when marked as deferred.

• deferred – When True, the column property is “deferred”, meaning that it does not load immediately, and is instead loaded when the attribute is first accessed on an instance. See also deferred().

• comparator_factory – a class which extends Comparator which provides custom SQL clause generation for comparison operations.

• doc – optional string that will be applied as the doc on the class-bound descriptor.

• info – Optional data dictionary which will be populated into the MapperProperty.info attribute of this object.

• init – Specific to 声明式Dataclass映射, specifies if the mapped attribute should be part of the __init__() method as generated by the dataclass process.

• repr – Specific to 声明式Dataclass映射, specifies if the mapped attribute should be part of the __repr__() method as generated by the dataclass process.

• default_factory – Specific to 声明式Dataclass映射, specifies a default-value generation function that will take place as part of the __init__() method as generated by the dataclass process.

• compare –

  Specific to 声明式Dataclass映射, indicates if this field should be included in comparison operations when generating the __eq__() and __ne__() methods for the mapped class.

  在 2.0.0b4 版本加入.

• kw_only – Specific to 声明式Dataclass映射, indicates if this field should be marked as keyword-only when generating the __init__().

• hash –

  Specific to 声明式Dataclass映射, controls if this field is included when generating the __hash__() method for the mapped class.

  在 2.0.36 版本加入.