Skip to content

link

Column-level description of a relation: which columns of one table connect to which columns of the next table.

A RelationLink is the only place that decides how two models are joined, filtered against each other and how a relation's key value is read, so joins, prefetch and relation proxies never derive the columns themselves.

ColumnPair dataclass

One column of the source table and the column of the target table it matches.

Attributes:

Name Type Description
source_field str

ormar field on the source model (the relation field itself on the side holding the foreign key)

source_column str

database column on the source table

target_field str

ormar field on the target model

target_column str

database column on the target table

Source code in ormar/fields/link.py
Python
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
@dataclass(frozen=True)
class ColumnPair:
    """
    One column of the source table and the column of the target table it
    matches.

    :ivar source_field: ormar field on the source model (the relation field
        itself on the side holding the foreign key)
    :ivar source_column: database column on the source table
    :ivar target_field: ormar field on the target model
    :ivar target_column: database column on the target table
    """

    source_field: str
    source_column: str
    target_field: str
    target_column: str

    def mirrored(self) -> "ColumnPair":
        """
        :return: the same pair seen from the target side
        :rtype: ColumnPair
        """
        return ColumnPair(
            source_field=self.target_field,
            source_column=self.target_column,
            target_field=self.source_field,
            target_column=self.source_column,
        )

mirrored()

Returns:

Type Description
ColumnPair

the same pair seen from the target side

Source code in ormar/fields/link.py
Python
189
190
191
192
193
194
195
196
197
198
199
def mirrored(self) -> "ColumnPair":
    """
    :return: the same pair seen from the target side
    :rtype: ColumnPair
    """
    return ColumnPair(
        source_field=self.target_field,
        source_column=self.target_column,
        target_field=self.source_field,
        target_column=self.source_column,
    )

Ordered column pairs connecting a source model's table to a target model's table, e.g. tracks.album_ref -> albums.id for Track.album.

Attributes:

Name Type Description
source type[Model]

model the relation starts from

target type[Model]

model the relation leads to

pairs tuple[ColumnPair, ...]

matched columns, in key order of the referenced key

Source code in ormar/fields/link.py
Python
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
@dataclass(frozen=True)
class RelationLink:
    """
    Ordered column pairs connecting a source model's table to a target model's
    table, e.g. ``tracks.album_ref -> albums.id`` for ``Track.album``.

    :ivar source: model the relation starts from
    :ivar target: model the relation leads to
    :ivar pairs: matched columns, in key order of the referenced key
    """

    source: type["Model"]
    target: type["Model"]
    pairs: tuple[ColumnPair, ...]

    def source_fields(self) -> tuple[str, ...]:
        """
        :return: ormar field names on the source side
        :rtype: tuple[str, ...]
        """
        return tuple(pair.source_field for pair in self.pairs)

    def source_columns(self) -> tuple[str, ...]:
        """
        :return: database columns on the source side
        :rtype: tuple[str, ...]
        """
        return tuple(pair.source_column for pair in self.pairs)

    def target_fields(self) -> tuple[str, ...]:
        """
        :return: ormar field names on the target side
        :rtype: tuple[str, ...]
        """
        return tuple(pair.target_field for pair in self.pairs)

    def target_columns(self) -> tuple[str, ...]:
        """
        :return: database columns on the target side
        :rtype: tuple[str, ...]
        """
        return tuple(pair.target_column for pair in self.pairs)

    def mirrored(self) -> "RelationLink":
        """
        :return: the same link walked from the target to the source
        :rtype: RelationLink
        """
        return RelationLink(
            source=self.target,
            target=self.source,
            pairs=tuple(pair.mirrored() for pair in self.pairs),
        )

    def key_of(self, model: "Model") -> Any:
        """
        Read the value a source model holds for this link, column by column
        (see ``column_value``)::

            Track.album link, track.album == Album(id=4) -> 4
            Ledger.entries link, ledger.tenant == Tenant(id=4) -> (4, 1)

        :param model: instance of the source model
        :type model: Model
        :return: the value, a tuple for links of several columns
        :rtype: Any
        """
        readers = self.source_readers
        if len(readers) == 1:
            return readers[0](model)
        return tuple([read(model) for read in readers])

    def values_for(self, related: Any) -> dict[str, Any]:
        """
        Turn a related value into the source-side values that store it, keyed
        by ``source_keys()``::

            Track.album link: Album(id=2) | {"id": 2} | 2 -> {"album": 2}
            OrderLine.order link: Order(1, 7) -> {"ord_tenant": 1, "ord_no": 7}

        A related model without its key yields ``None`` values; callers decide
        whether that is an error.

        :param related: related model (or its key-only pydantic model), dict of
            its fields, raw key value or ``None``
        :type related: Any
        :return: values by source field name
        :rtype: dict[str, Any]
        """
        if related is None:
            parts: tuple[Any, ...] = (None,) * len(self.pairs)
        elif isinstance(related, (BaseModel, dict)):
            parts = tuple([read(related) for read in self.target_readers])
        else:
            parts = key_parts(value=related, size=len(self.pairs))
        return dict(zip(self.source_keys(), parts))

    @cached_property
    def source_readers(self) -> tuple[ColumnReader, ...]:
        """
        :return: readers of the source columns (see ``column_reader``)
        :rtype: tuple[ColumnReader, ...]
        """
        return tuple(
            self.source.column_reader(column=pair.source_column) for pair in self.pairs
        )

    @cached_property
    def target_readers(self) -> tuple[ColumnReader, ...]:
        """
        :return: readers of the target columns (see ``column_reader``)
        :rtype: tuple[ColumnReader, ...]
        """
        return tuple(
            self.target.column_reader(column=pair.target_column) for pair in self.pairs
        )

    def source_keys(self) -> tuple[str, ...]:
        """
        :return: keys the source side stores the link's values under in a model
            dict: the relation field for a single column, the columns otherwise
        :rtype: tuple[str, ...]
        """
        if len(self.pairs) == 1:
            return (self.pairs[0].source_field,)
        return self.source_columns()

    def key_getter(
        self, *, side: Literal["source", "target"], prefix: str = ""
    ) -> Callable[[Mapping[str, Any]], Any]:
        """
        Build a reader of this link's value out of a database row.

        :param side: which table's columns the row holds
        :type side: Literal["source", "target"]
        :param prefix: table prefix of the row's column labels
            (``<prefix>_<column>``), empty for unprefixed columns
        :type prefix: str
        :return: reader returning the value, a tuple for links of several
            columns
        :rtype: Callable[[Mapping[str, Any]], Any]
        """
        columns = self.source_columns() if side == "source" else self.target_columns()
        label_prefix = f"{prefix}_" if prefix else ""
        return operator.itemgetter(*(label_prefix + column for column in columns))

source_readers cached property

Returns:

Type Description
tuple[ColumnReader, ...]

readers of the source columns (see column_reader)

target_readers cached property

Returns:

Type Description
tuple[ColumnReader, ...]

readers of the target columns (see column_reader)

key_getter(*, side, prefix='')

Build a reader of this link's value out of a database row.

Parameters:

Name Type Description Default
side Literal['source', 'target']

which table's columns the row holds

required
prefix str

table prefix of the row's column labels (<prefix>_<column>), empty for unprefixed columns

''

Returns:

Type Description
Callable[[Mapping[str, Any]], Any]

reader returning the value, a tuple for links of several columns

Source code in ormar/fields/link.py
Python
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
def key_getter(
    self, *, side: Literal["source", "target"], prefix: str = ""
) -> Callable[[Mapping[str, Any]], Any]:
    """
    Build a reader of this link's value out of a database row.

    :param side: which table's columns the row holds
    :type side: Literal["source", "target"]
    :param prefix: table prefix of the row's column labels
        (``<prefix>_<column>``), empty for unprefixed columns
    :type prefix: str
    :return: reader returning the value, a tuple for links of several
        columns
    :rtype: Callable[[Mapping[str, Any]], Any]
    """
    columns = self.source_columns() if side == "source" else self.target_columns()
    label_prefix = f"{prefix}_" if prefix else ""
    return operator.itemgetter(*(label_prefix + column for column in columns))

key_of(model)

Read the value a source model holds for this link, column by column (see column_value)::

Text Only
1
2
Track.album link, track.album == Album(id=4) -> 4
Ledger.entries link, ledger.tenant == Tenant(id=4) -> (4, 1)

Parameters:

Name Type Description Default
model Model

instance of the source model

required

Returns:

Type Description
Any

the value, a tuple for links of several columns

Source code in ormar/fields/link.py
Python
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
def key_of(self, model: "Model") -> Any:
    """
    Read the value a source model holds for this link, column by column
    (see ``column_value``)::

        Track.album link, track.album == Album(id=4) -> 4
        Ledger.entries link, ledger.tenant == Tenant(id=4) -> (4, 1)

    :param model: instance of the source model
    :type model: Model
    :return: the value, a tuple for links of several columns
    :rtype: Any
    """
    readers = self.source_readers
    if len(readers) == 1:
        return readers[0](model)
    return tuple([read(model) for read in readers])

mirrored()

Returns:

Type Description
RelationLink

the same link walked from the target to the source

Source code in ormar/fields/link.py
Python
245
246
247
248
249
250
251
252
253
254
def mirrored(self) -> "RelationLink":
    """
    :return: the same link walked from the target to the source
    :rtype: RelationLink
    """
    return RelationLink(
        source=self.target,
        target=self.source,
        pairs=tuple(pair.mirrored() for pair in self.pairs),
    )

source_columns()

Returns:

Type Description
tuple[str, ...]

database columns on the source side

Source code in ormar/fields/link.py
Python
224
225
226
227
228
229
def source_columns(self) -> tuple[str, ...]:
    """
    :return: database columns on the source side
    :rtype: tuple[str, ...]
    """
    return tuple(pair.source_column for pair in self.pairs)

source_fields()

Returns:

Type Description
tuple[str, ...]

ormar field names on the source side

Source code in ormar/fields/link.py
Python
217
218
219
220
221
222
def source_fields(self) -> tuple[str, ...]:
    """
    :return: ormar field names on the source side
    :rtype: tuple[str, ...]
    """
    return tuple(pair.source_field for pair in self.pairs)

source_keys()

Returns:

Type Description
tuple[str, ...]

keys the source side stores the link's values under in a model dict: the relation field for a single column, the columns otherwise

Source code in ormar/fields/link.py
Python
319
320
321
322
323
324
325
326
327
def source_keys(self) -> tuple[str, ...]:
    """
    :return: keys the source side stores the link's values under in a model
        dict: the relation field for a single column, the columns otherwise
    :rtype: tuple[str, ...]
    """
    if len(self.pairs) == 1:
        return (self.pairs[0].source_field,)
    return self.source_columns()

target_columns()

Returns:

Type Description
tuple[str, ...]

database columns on the target side

Source code in ormar/fields/link.py
Python
238
239
240
241
242
243
def target_columns(self) -> tuple[str, ...]:
    """
    :return: database columns on the target side
    :rtype: tuple[str, ...]
    """
    return tuple(pair.target_column for pair in self.pairs)

target_fields()

Returns:

Type Description
tuple[str, ...]

ormar field names on the target side

Source code in ormar/fields/link.py
Python
231
232
233
234
235
236
def target_fields(self) -> tuple[str, ...]:
    """
    :return: ormar field names on the target side
    :rtype: tuple[str, ...]
    """
    return tuple(pair.target_field for pair in self.pairs)

values_for(related)

Turn a related value into the source-side values that store it, keyed by source_keys()::

Text Only
1
2
Track.album link: Album(id=2) | {"id": 2} | 2 -> {"album": 2}
OrderLine.order link: Order(1, 7) -> {"ord_tenant": 1, "ord_no": 7}

A related model without its key yields None values; callers decide whether that is an error.

Parameters:

Name Type Description Default
related Any

related model (or its key-only pydantic model), dict of its fields, raw key value or None

required

Returns:

Type Description
dict[str, Any]

values by source field name

Source code in ormar/fields/link.py
Python
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
def values_for(self, related: Any) -> dict[str, Any]:
    """
    Turn a related value into the source-side values that store it, keyed
    by ``source_keys()``::

        Track.album link: Album(id=2) | {"id": 2} | 2 -> {"album": 2}
        OrderLine.order link: Order(1, 7) -> {"ord_tenant": 1, "ord_no": 7}

    A related model without its key yields ``None`` values; callers decide
    whether that is an error.

    :param related: related model (or its key-only pydantic model), dict of
        its fields, raw key value or ``None``
    :type related: Any
    :return: values by source field name
    :rtype: dict[str, Any]
    """
    if related is None:
        parts: tuple[Any, ...] = (None,) * len(self.pairs)
    elif isinstance(related, (BaseModel, dict)):
        parts = tuple([read(related) for read in self.target_readers])
    else:
        parts = key_parts(value=related, size=len(self.pairs))
    return dict(zip(self.source_keys(), parts))

column_reader(model, column)

Build the reader of one of a model's columns. A column stored by a relation is read out of the related value (a model, a dict of its fields or a raw key), recursively, so a key holding foreign keys is read column by column like any other::

Text Only
1
2
3
Track, "album" -> track.album.id
Membership, "member_login" -> membership.member.login
{"member": (1, "alice")}, "member_login" -> "alice"

A column several fields share is read from the first one holding a value.

Parameters:

Name Type Description Default
model type[Model]

model the column belongs to

required
column str

database column of the model

required

Returns:

Type Description
ColumnReader

callable reading the column's raw value out of an instance of the model, its key-only model or a dict of its fields (None when not set)

Source code in ormar/fields/link.py
Python
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
def column_reader(model: type["Model"], column: str) -> ColumnReader:
    """
    Build the reader of one of a model's columns. A column stored by a
    relation is read out of the related value (a model, a dict of its fields
    or a raw key), recursively, so a key holding foreign keys is read column
    by column like any other::

        Track, "album" -> track.album.id
        Membership, "member_login" -> membership.member.login
        {"member": (1, "alice")}, "member_login" -> "alice"

    A column several fields share is read from the first one holding a value.

    :param model: model the column belongs to
    :type model: type[Model]
    :param column: database column of the model
    :type column: str
    :return: callable reading the column's raw value out of an instance of the
        model, its key-only model or a dict of its fields (``None`` when not
        set)
    :rtype: ColumnReader
    """
    model_fields = model.ormar_config.model_fields
    readers = [
        field_reader(name=name, field=model_fields[name], column=column)
        for name in model.get_field_names_of_column(column=column)
    ]
    if len(readers) == 1:
        return readers[0]

    def read_first_set(data: Any) -> Any:
        for reader in readers:
            value = reader(data)
            if value is not None:
                return value
        return None

    return read_first_set

column_value(model, data, column)

Read the value one of a model's columns stores out of an instance of the model, its key-only pydantic model or a dict of its fields (see column_reader).

Parameters:

Name Type Description Default
model type[Model]

model the column belongs to

required
data Any

instance of the model, its key-only model or a dict of its fields

required
column str

database column of the model

required

Returns:

Type Description
Any

raw value of the column, None when not set

Source code in ormar/fields/link.py
Python
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def column_value(model: type["Model"], data: Any, column: str) -> Any:
    """
    Read the value one of a model's columns stores out of an instance of the
    model, its key-only pydantic model or a dict of its fields (see
    ``column_reader``).

    :param model: model the column belongs to
    :type model: type[Model]
    :param data: instance of the model, its key-only model or a dict of its
        fields
    :type data: Any
    :param column: database column of the model
    :type column: str
    :return: raw value of the column, ``None`` when not set
    :rtype: Any
    """
    return model.column_reader(column=column)(data)

field_reader(name, field, column)

Parameters:

Name Type Description Default
name str

name of the field storing the column

required
field BaseField

the field

required
column str

database column the field stores

required

Returns:

Type Description
ColumnReader

callable reading the column's raw value out of the field's value (see column_reader)

Source code in ormar/fields/link.py
Python
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
def field_reader(name: str, field: "BaseField", column: str) -> ColumnReader:
    """
    :param name: name of the field storing the column
    :type name: str
    :param field: the field
    :type field: BaseField
    :param column: database column the field stores
    :type column: str
    :return: callable reading the column's raw value out of the field's value
        (see ``column_reader``)
    :rtype: ColumnReader
    """
    if not field.is_relation:

        def read_plain(data: Any) -> Any:
            if isinstance(data, dict):
                return data.get(name)
            return getattr(data, name, None)

        return read_plain
    link = cast("ForeignKeyField", field).link
    position = link.source_columns().index(column)
    single = len(link.pairs) == 1
    target = link.target
    target_column = link.pairs[position].target_column
    # resolved on first use: a self-referencing key reaches its own reader
    related: list[ColumnReader] = []

    def read_relation(data: Any) -> Any:
        value = data.get(name) if isinstance(data, dict) else getattr(data, name, None)
        if value is None:
            return None
        if isinstance(value, (BaseModel, dict)):
            if not related:
                related.append(target.column_reader(column=target_column))
            return related[0](value)
        return value if single else tuple(value)[position]

    return read_relation

key_parts(value, size)

Unpack a key value into its parts, the inverse of key_value.

Parameters:

Name Type Description Default
value Any

key value

required
size int

number of key columns

required

Returns:

Type Description
tuple[Any, ...]

key parts in key order

Source code in ormar/fields/link.py
Python
54
55
56
57
58
59
60
61
62
63
64
65
def key_parts(value: Any, size: int) -> tuple[Any, ...]:
    """
    Unpack a key value into its parts, the inverse of ``key_value``.

    :param value: key value
    :type value: Any
    :param size: number of key columns
    :type size: int
    :return: key parts in key order
    :rtype: tuple[Any, ...]
    """
    return (value,) if size == 1 else tuple(value)

key_value(parts)

Pack the parts of a key into its value: the part itself for a key of one column, a tuple otherwise.

Parameters:

Name Type Description Default
parts tuple[Any, ...]

key parts in key order

required

Returns:

Type Description
Any

key value

Source code in ormar/fields/link.py
Python
41
42
43
44
45
46
47
48
49
50
51
def key_value(parts: tuple[Any, ...]) -> Any:
    """
    Pack the parts of a key into its value: the part itself for a key of one
    column, a tuple otherwise.

    :param parts: key parts in key order
    :type parts: tuple[Any, ...]
    :return: key value
    :rtype: Any
    """
    return parts[0] if len(parts) == 1 else parts

qualified_fk_reference(target, column_alias)

Builds the dotted reference string passed to sqlalchemy.ForeignKey.

SQLAlchemy expects "schema.table.column" for cross-schema foreign keys and "table.column" when the target is in the default schema.

Parameters:

Name Type Description Default
target type[Model]

target ormar Model

required
column_alias str

alias of the referenced column on the target table

required

Returns:

Type Description
str

dotted reference string

Source code in ormar/fields/link.py
Python
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def qualified_fk_reference(target: type["Model"], column_alias: str) -> str:
    """
    Builds the dotted reference string passed to ``sqlalchemy.ForeignKey``.

    SQLAlchemy expects ``"schema.table.column"`` for cross-schema foreign keys
    and ``"table.column"`` when the target is in the default schema.

    :param target: target ormar Model
    :type target: type["Model"]
    :param column_alias: alias of the referenced column on the target table
    :type column_alias: str
    :return: dotted reference string
    :rtype: str
    """
    config = target.ormar_config
    prefix = f"{config.schema}." if config.schema else ""
    return f"{prefix}{config.tablename}.{column_alias}"