asyncqlio.orm.schema.relationship

Relationship objects.

Classes

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

class asyncqlio.orm.schema.relationship.ForeignKey(foreign_column)

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 (Union[Column, str]) – 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.

get_ddl_sql(name=None)

Generates SQL to add this foreign key as a named constraint.

Parameters:name (Optional[str]) – Return type:str

generate_schema(fp=None)

Generates a library schema for this foreign key.

Return type:str

class asyncqlio.orm.schema.relationship.Relationship(left, right, *, load='select', use_iter=True, back_ref=None, table_alias=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 (Union[Column, str]) – The left-hand column (the Column on this table) in this relationship.
• right (Union[Column, str]) – The right-hand column (the Column on the foreign table) in this relationship.
• load (str) –

  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 (bool) –

  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 (Optional[str]) –

  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 (Optional[str]) –

  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.

Return type:Column

join_columns

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

Return type:Tuple[Column, Column]

get_instance(row, session)

Gets a new “relationship” instance.

generate_schema(fp=None)

Generates the library schema for this relationship.

Return type:str

class asyncqlio.orm.schema.relationship.BaseLoadedRelationship(rel, row, session)

Bases: object

Provides some common methods for specific relationship type subclasses.

Parameters:

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

set_rows(rows)

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

coroutine add(self, row)

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 (Table) – The TableRow object to add to this relationship.

coroutine remove(self, row)

Removes a row from this query.

Warning

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

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

class asyncqlio.orm.schema.relationship.SelectLoadedRelationship(rel, row, session)

Bases: asyncqlio.orm.schema.relationship.BaseLoadedRelationship

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

Parameters:

• rel (Relationship) – The Relationship that lies underneath this object.
• row (Table) – 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):
    ...

Return type:SelectQuery

coroutine add(self, row)

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 (Table) – The TableRow object to add to this relationship.

coroutine remove(self, row)

Removes a row from this query.

Warning

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

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

set_rows(rows)

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, row, session)

Bases: asyncqlio.orm.schema.relationship.BaseLoadedRelationship

Represents a join-loaded one to many relationship.

Parameters:

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

set_rows(rows)

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

coroutine add(self, row)

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 (Table) – The TableRow object to add to this relationship.

coroutine remove(self, row)

Removes a row from this query.

Warning

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

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

class asyncqlio.orm.schema.relationship.JoinLoadedOTORelationship(rel, row, session)

Bases: asyncqlio.orm.schema.relationship.BaseLoadedRelationship

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

Parameters:

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

set_rows(rows)

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

add(row)

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 (Table) – The TableRow object to add to this relationship.

remove(row)

Removes a row from this query.

Warning

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

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

coroutine set(self, row)

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 (Table) – The TableRow to set.