asyncqlio.orm.query

Classes for query objects.

Classes

BaseQuery(sess: asyncqlio.orm.session.Session) A base query object.
BulkDeleteQuery(…) Represents a bulk delete query.
BulkQuery(sess: asyncqlio.orm.session.Session) Represents a bulk query.
BulkUpdateQuery(…) Represents a bulk update query.
InsertQuery(sess: asyncqlio.orm.session.Session) Represents an INSERT query.
ResultGenerator(…) A helper class that will generate new results from a query when iterated over.
RowDeleteQuery(…) Represents a row deletion query.
RowUpdateQuery(…) Represents a row update query.
SelectQuery(…) Represents a SELECT query, which fetches data from the database.
class asyncqlio.orm.query.BaseQuery(sess: asyncqlio.orm.session.Session)[source]

Bases: asyncqlio.meta.AsyncABC

A base query object.

Parameters:sess – The Session associated with this query.
generate_sql() → typing.Tuple[str, typing.Mapping[str, typing.Any]][source]

Generates the SQL for this query. :return: A two item tuple, the SQL to use and a mapping of params to pass.

coroutine run()[source]

Runs this query.

class asyncqlio.orm.query.ResultGenerator(q: asyncqlio.orm.query.SelectQuery)[source]

Bases: collections.abc.AsyncIterator

A helper class that will generate new results from a query when iterated over.

Parameters:q – The SelectQuery to use.
coroutine flatten() → typing.List[asyncqlio.orm.schema.table.Table][source]

Flattens this query into a single list.

class asyncqlio.orm.query.SelectQuery(session: asyncqlio.orm.session.Session)[source]

Bases: asyncqlio.orm.query.BaseQuery

Represents a SELECT query, which fetches data from the database.

This is not normally created by user code directly, but rather as a result of a Session.select() call.

sess = db.get_session()
async with sess:
    query = sess.select.from_(User)  # query is instance of SelectQuery
    # alternatively, but not recommended
    query = sess.select(User)

However, it is possible to create this class manually:

query = SelectQuery(db.get_session()
query.set_table(User)
query.add_condition(User.id == 2)
user = await query.first()
table = None

The table being queried.

conditions = None

A list of conditions to fulfil.

row_limit = None

The limit on the number of rows returned from this query.

row_offset = None

The offset to start fetching rows from.

orderer = None

The column to order by.

get_required_join_paths()[source]

Gets the required join paths for this query.

generate_sql() → typing.Tuple[str, dict][source]

Generates the SQL for this query.

coroutine first() → asyncqlio.orm.schema.table.Table[source]

Gets the first result that matches from this query.

Returns:A Table instance representing the first item, or None if no item matched.
coroutine all() → asyncqlio.orm.query.ResultGenerator[source]

Gets all results that match from this query.

Returns:A ResultGenerator that can be iterated over.
map_columns(results: typing.Mapping[str, typing.Any]) → asyncqlio.orm.schema.table.Table[source]

Maps columns in a result row to a Table instance object.

Parameters:results – A single row of results from the query cursor.
Returns:A new Table instance that represents the row returned.
map_many(*rows: typing.Mapping[str, typing.Any])[source]

Maps many records to one row.

This will group the records by the primary key of the main query table, then add additional columns as appropriate.

from_(tbl) → asyncqlio.orm.query.SelectQuery[source]

Sets the table this query is selecting from.

Parameters:tbl – The Table object to select.
Returns:This query.
where(*conditions: asyncqlio.orm.operators.BaseOperator) → asyncqlio.orm.query.SelectQuery[source]

Adds a WHERE clause to the query. This is a shortcut for SelectQuery.add_condition().

sess.select.from_(User).where(User.id == 1)
Parameters:conditions – The conditions to use for this WHERE clause.
Returns:This query.
limit(row_limit: int) → asyncqlio.orm.query.SelectQuery[source]

Sets a limit of the number of rows that can be returned from this query.

Parameters:row_limit – The maximum number of rows to return.
Returns:This query.
offset(offset: int) → asyncqlio.orm.query.SelectQuery[source]

Sets the offset of rows to start returning results from/

Parameters:offset – The row offset.
Returns:This query.
order_by(*col: typing.Union[asyncqlio.orm.schema.column.Column, asyncqlio.orm.operators.Sorter], sort_order: str = 'asc')[source]

Sets the order by clause for this query.

The argument provided can either be a Column, or a Sorter which is provided by Column.asc() / Column.desc(). By default, asc is used when passing a column.

set_table(tbl) → asyncqlio.orm.query.SelectQuery[source]

Sets the table to query on.

Parameters:tbl – The Table object to set.
Returns:This query.
add_condition(condition: asyncqlio.orm.operators.BaseOperator) → asyncqlio.orm.query.SelectQuery[source]

Adds a condition to the query/

Parameters:condition – The BaseOperator to add.
Returns:This query.
class asyncqlio.orm.query.InsertQuery(sess: asyncqlio.orm.session.Session)[source]

Bases: asyncqlio.orm.query.BaseQuery

Represents an INSERT query.

rows_to_insert = None

A list of rows to generate the insert statements for.

coroutine run() → typing.List[asyncqlio.orm.schema.table.Table][source]

Runs this query.

Returns:A list of inserted md_table.Table.
rows(*rows: asyncqlio.orm.schema.table.Table) → asyncqlio.orm.query.InsertQuery[source]

Adds a set of rows to the query.

Parameters:rows – The rows to insert.
Returns:This query.
add_row(row: asyncqlio.orm.schema.table.Table) → asyncqlio.orm.query.InsertQuery[source]

Adds a row to this query, allowing it to be executed later.

Parameters:row – The Table instance to use for this query.
Returns:This query.
generate_sql() → typing.List[typing.Tuple[str, tuple]][source]

Generates the SQL statements for this insert query.

This will return a list of two-item tuples to execute:
  • The SQL query+params to emit to actually insert the row
class asyncqlio.orm.query.BulkQuery(sess: asyncqlio.orm.session.Session)[source]

Bases: asyncqlio.orm.query.BaseQuery

Represents a bulk query.

This allows adding conditionals to the query.

conditions = None

The list of conditions to query by.

table(table: typing.Type[asyncqlio.orm.schema.table.Table])[source]

Sets the table for this query.

where(*conditions: asyncqlio.orm.operators.ComparisonOp)[source]

Sets the conditions for this query.

set_table(table: typing.Type[asyncqlio.orm.schema.table.Table])[source]

Sets a table on this query.

add_condition(condition: asyncqlio.orm.operators.BaseOperator)[source]

Adds a condition to this query.

generate_sql() → typing.Tuple[str, typing.Mapping[str, typing.Any]]

Generates the SQL for this query. :return: A two item tuple, the SQL to use and a mapping of params to pass.

coroutine run()

Runs this query.

class asyncqlio.orm.query.BulkUpdateQuery(sess: asyncqlio.orm.session.Session)[source]

Bases: asyncqlio.orm.query.BulkQuery

Represents a bulk update query. This updates many rows based on certain criteria.

query = BulkUpdateQuery(session)

# style 1: manual
query.set_table(User)
query.add_condition(User.xp < 300)
# add on a value
query.set_update(User.xp + 100)
# or set a value
query.set_update(User.xp.set(300))
await query.run()

# style 2: builder
await query.table(User).where(User.xp < 300).set(User.xp + 100).run()
await query.table(User).where(User.xp < 300).set(User.xp, 300).run()
setting = None

The thing to set on the updated rows.

set(setter, value: typing.Any = None)[source]

Sets a column in this query.

set_update(update)[source]

Sets the update for this query.

generate_sql()[source]

Generates the SQL for this query.

add_condition(condition: asyncqlio.orm.operators.BaseOperator)

Adds a condition to this query.

set_table(table: typing.Type[asyncqlio.orm.schema.table.Table])

Sets a table on this query.

table(table: typing.Type[asyncqlio.orm.schema.table.Table])

Sets the table for this query.

where(*conditions: asyncqlio.orm.operators.ComparisonOp)

Sets the conditions for this query.

class asyncqlio.orm.query.BulkDeleteQuery(sess: asyncqlio.orm.session.Session)[source]

Bases: asyncqlio.orm.query.BulkQuery

Represents a bulk delete query. This deletes many rows based on criteria.

query = BulkDeleteQuery(session)

# style 1: manual
query.set_table(User)
query.add_condition(User.xp < 300)
await query.run()

# style 2: builder
await query.table(User).where(User.xp < 300).run()
await query.table(User).where(User.xp < 300).run()
add_condition(condition: asyncqlio.orm.operators.BaseOperator)

Adds a condition to this query.

set_table(table: typing.Type[asyncqlio.orm.schema.table.Table])

Sets a table on this query.

table(table: typing.Type[asyncqlio.orm.schema.table.Table])

Sets the table for this query.

where(*conditions: asyncqlio.orm.operators.ComparisonOp)

Sets the conditions for this query.

class asyncqlio.orm.query.RowUpdateQuery(sess: asyncqlio.orm.session.Session)[source]

Bases: asyncqlio.orm.query.BaseQuery

Represents a row update query. This is NOT a bulk update query - it is used for updating specific rows.

rows_to_update = None

The list of rows to update.

coroutine run()[source]

Executes this query.

rows(*rows: asyncqlio.orm.schema.table.Table) → asyncqlio.orm.query.RowUpdateQuery[source]

Adds a set of rows to the query.

Parameters:rows – The rows to insert.
Returns:This query.
add_row(row: asyncqlio.orm.schema.table.Table) → asyncqlio.orm.query.RowUpdateQuery[source]

Adds a row to this query, allowing it to be executed later.

Parameters:row – The Table instance to use for this query.
Returns:This query.
generate_sql() → typing.List[typing.Tuple[str, tuple]][source]

Generates the SQL statements for this row update query.

This will return a list of two-item tuples to execute:

  • The SQL query+params to emit to actually insert the row
class asyncqlio.orm.query.RowDeleteQuery(sess: asyncqlio.orm.session.Session)[source]

Bases: asyncqlio.orm.query.BaseQuery

Represents a row deletion query. This is NOT a bulk delete query - it is used for deleting specific rows.

rows_to_delete = None

The list of rows to delete.

rows(*rows: asyncqlio.orm.schema.table.Table) → asyncqlio.orm.query.RowDeleteQuery[source]

Adds a set of rows to the query.

Parameters:rows – The rows to insert.
Returns:This query.
add_row(row: asyncqlio.orm.schema.table.Table)[source]

Adds a row to this query.

Parameters:row – The Table instance
Returns:
generate_sql() → typing.List[typing.Tuple[str, tuple]][source]

Generates the SQL statements for this row delete query.

This will return a list of two-item tuples to execute:

  • The SQL query+params to emit to actually insert the row