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 | |
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 | |
RelationLink
dataclass
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 | |
source_readers
cached
property
Returns:
| Type | Description |
|---|---|
tuple[ColumnReader, ...]
|
readers of the source columns (see |
target_readers
cached
property
Returns:
| Type | Description |
|---|---|
tuple[ColumnReader, ...]
|
readers of the target columns (see |
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
( |
''
|
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 | |
key_of(model)
Read the value a source model holds for this link, column by column
(see column_value)::
| Text Only | |
|---|---|
1 2 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
values_for(related)
Turn a related value into the source-side values that store it, keyed
by source_keys()::
| Text Only | |
|---|---|
1 2 | |
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 |
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 | |
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 | |
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 ( |
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 | |
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, |
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 | |
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 |
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 | |
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 | |
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 | |
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 | |