asyncqlio.orm.schema.relationship

Relationship helpers.

Classes

BaseLoadedRelationship(…)	Provides some common methods for specific relationship type subclasses.
ForeignKey(…)	Represents a foreign key object in a column.
JoinLoadedOTMRelationship(…)	Represents a join-loaded one to many relationship.
JoinLoadedOTORelationship(…)	Represents a joined one<-to->one relationship.
Relationship(…)	Represents a relationship to another table object.
SelectLoadedRelationship(…)	A relationship object that uses a separate SELECT statement to load follow-on tables.

class asyncqlio.orm.schema.relationship.ForeignKey(foreign_column: typing.Union[asyncqlio.orm.schema.column.Column, str])

Bases: object

Represents a foreign key object in a column. This allows linking multiple tables together relationally.

class Server(Table):
    id = Column(Integer, primary_key=True, autoincrement=True)
    name = Column(String)

    owner_id = Column(Integer, foreign_key=ForeignKey("User.id")

Parameters:foreign_column – Either a Column representing the foreign column, or a str in the format <table object name>.<column name>.

foreign_column = None

The Column object this FK references.

column = None

The Column object this FK is associated with.

class asyncqlio.orm.schema.relationship.Relationship(left: typing.Union[asyncqlio.orm.schema.column.Column, str], right: typing.Union[asyncqlio.orm.schema.column.Column, str], *, load: str = 'select', use_iter: bool = True, back_ref: str = None, table_alias: str = None)

Bases: object

Represents a relationship to another table object.

This object provides an easy, object-oriented interface to a foreign key relationship between two tables, the left table and the right table. The left table is the “parent” table, and the right table is the “child” table; effectively creating a one to many/many to one relationship between the two tables.

To create a relationship, there must be a column in the child table that represents the primary key of a parent table; this is the foreign key column, and will be used to load the other table.

class User(Table):
    # id is the primary key of the parent table
    id = Column(Integer, auto_increment=True)
    name = Column(String)

    # this is the relationship joiner; it uses id as the left key, and user_id as the right
    # this will create a join between the two tables
    inventory = Relationship(left=id, right="InventoryItem.user_id")

class InventoryItem(Table):
    id = Column(BigInteger, auto_increment=True)

    # user_id is the "foreign key" - it references the column User.id
    user_id = Column(Integer, foreign_key=ForeignKey(User.id)

Once created, the new relationship object can be used to iterate over the child objects, using async for:

user = await sess.select.from_(User).where(User.id == 1).first()
async for item in user.inventory:
    ...

By default, the relationship will use a SELECT query to load the items; this can be changed to a joined query when loading any table rows, by changing the load param. The possible values of this param are:

• select - Emits a SELECT query to load child items.
• joined - Emits a join query to load child items.

For all possible options, see Relationship Loading.

Parameters:

• left – The left-hand column (the Column on this table) in this relationship.
• right – The right-hand column (the Column on the foreign table) in this relationship.
• load –

  The way to load this relationship.

  The default is “select” - this means that a separate select statement will be issued to iterate over the rows of the relationship.

  For all possible options, see Relationship Loading.

• use_iter –

  Should this relationship use the iterable format?

  This controls if this relationship is created as one to many, or as a many to one/one to one relationship.

• back_ref –

  The “back reference” to add to the right table.

  This will automatically add a relationship to the right table with the specified name, and automatically fill it when querying over said relationship.

• table_alias –

  The table alias to use when joining.

  This will rename the joined table to allow selecting specific rows in tables with multiple relationships to the same table.

left_column = None

The left column for this relationship.

right_column = None

The right column for this relationship.

use_iter = None

If this relationship uses the iterable format.

owner_table = None

The owner table for this relationship.

back_reference = None

The back-reference for this relationship.

load_type = None

The load type for this relationship.

our_column

Gets the local column this relationship refers to.

foreign_column

Gets the foreign column this relationship refers to.

join_columns

Gets the “join” columns of this relationship, i.e the columns that link the two columns.

get_instance(row: asyncqlio.orm.schema.table.Table, session)

Gets a new “relationship” instance.

class asyncqlio.orm.schema.relationship.BaseLoadedRelationship(rel: asyncqlio.orm.schema.relationship.Relationship, row: asyncqlio.orm.schema.table.Table, session)

Bases: object

Provides some common methods for specific relationship type subclasses.

Parameters:

• rel – The Relationship that lies underneath this object.
• row – The TableRow this is being loaded from.
• session – The Session this object is attached to.

coroutine add(row: asyncqlio.orm.schema.table.Table)

Adds a row to this relationship.

Warning

This will run an immediate insert/update of this row; if the parent row for this relationship is not inserted it will run an immediate insert on the parent.

Parameters:row – The TableRow object to add to this relationship.

coroutine remove(row: asyncqlio.orm.schema.table.Table)

Removes a row from this query.

Warning

This will run an immediate UPDATE of this row to remove the foreign key.

Parameters:row – The TableRow object to remove from this relationship.

set_rows(rows: typing.List[asyncqlio.orm.schema.table.Table])

Sets the rows for this relationship. This is an internal method, and not to be used in user code.

class asyncqlio.orm.schema.relationship.SelectLoadedRelationship(rel: asyncqlio.orm.schema.relationship.Relationship, row: asyncqlio.orm.schema.table.Table, session)

Bases: asyncqlio.orm.schema.relationship.BaseLoadedRelationship

A relationship object that uses a separate SELECT statement to load follow-on tables.

Parameters:

• rel – The Relationship that lies underneath this object.
• row – The TableRow this is being loaded from.
• session – The Session this object is attached to.

query

Gets the query for this relationship, allowing further customization. For example, to change the order of the rows returned:

async for child in parent.children.query.order_by(Child.age):
    ...

coroutine add(row: asyncqlio.orm.schema.table.Table)

Adds a row to this relationship.

Warning

This will run an immediate insert/update of this row; if the parent row for this relationship is not inserted it will run an immediate insert on the parent.

Parameters:row – The TableRow object to add to this relationship.

coroutine remove(row: asyncqlio.orm.schema.table.Table)

Removes a row from this query.

Warning

This will run an immediate UPDATE of this row to remove the foreign key.

Parameters:row – The TableRow object to remove from this relationship.

set_rows(rows: typing.List[asyncqlio.orm.schema.table.Table])

Sets the rows for this relationship. This is an internal method, and not to be used in user code.

class asyncqlio.orm.schema.relationship.JoinLoadedOTMRelationship(rel: asyncqlio.orm.schema.relationship.Relationship, row: asyncqlio.orm.schema.table.Table, session)

Bases: asyncqlio.orm.schema.relationship.BaseLoadedRelationship

Represents a join-loaded one to many relationship.

Parameters:

• rel – The Relationship that lies underneath this object.
• row – The TableRow this is being loaded from.
• session – The Session this object is attached to.

coroutine add(row: asyncqlio.orm.schema.table.Table)

Adds a row to this relationship.

Warning

This will run an immediate insert/update of this row; if the parent row for this relationship is not inserted it will run an immediate insert on the parent.

Parameters:row – The TableRow object to add to this relationship.

coroutine remove(row: asyncqlio.orm.schema.table.Table)

Removes a row from this query.

Warning

This will run an immediate UPDATE of this row to remove the foreign key.

Parameters:row – The TableRow object to remove from this relationship.

class asyncqlio.orm.schema.relationship.JoinLoadedOTORelationship(rel: asyncqlio.orm.schema.relationship.Relationship, row: asyncqlio.orm.schema.table.Table, session)

Bases: asyncqlio.orm.schema.relationship.BaseLoadedRelationship

Represents a joined one<-to->one relationship.

Parameters:

• rel – The Relationship that lies underneath this object.
• row – The TableRow this is being loaded from.
• session – The Session this object is attached to.

coroutine set(row: asyncqlio.orm.schema.table.Table)

Sets the row for this one-to-one relationship.

Warning

This will run an immediate insert/update of this row; if the parent row for this relationship is not inserted it will run an immediate insert on the parent.

Parameters:row – The TableRow to set.