ormar/docs/api/query-set/join.md

queryset.join

JoinParameters Objects

class JoinParameters(NamedTuple)

Named tuple that holds set of parameters passed during join construction.

SqlJoin Objects

class SqlJoin()

alias_manager

 | @staticmethod
 | alias_manager(model_cls: Type["Model"]) -> AliasManager

Shortcut for ormars model AliasManager stored on Meta.

Arguments:

• model_cls (Type[Model]): ormar Model class

Returns:

(AliasManager): alias manager from model's Meta

on_clause

 | @staticmethod
 | on_clause(previous_alias: str, alias: str, from_clause: str, to_clause: str) -> text

Receives aliases and names of both ends of the join and combines them into one text clause used in joins.

Arguments:

• previous_alias (str): alias of previous table
• alias (str): alias of current table
• from_clause (str): from table name
• to_clause (str): to table name

Returns:

(sqlalchemy.text): clause combining all strings

update_inclusions

 | @staticmethod
 | update_inclusions(model_cls: Type["Model"], fields: Optional[Union[Set, Dict]], exclude_fields: Optional[Union[Set, Dict]], nested_name: str) -> Tuple[Optional[Union[Dict, Set]], Optional[Union[Dict, Set]]]

Extract nested fields and exclude_fields if applicable.

Arguments:

• model_cls (Type["Model"]): ormar model class
• fields (Optional[Union[Set, Dict]]): fields to include
• exclude_fields (Optional[Union[Set, Dict]]): fields to exclude
• nested_name (str): name of the nested field

Returns:

(Tuple[Optional[Union[Dict, Set]], Optional[Union[Dict, Set]]]): updated exclude and include fields from nested objects

build_join

 | build_join(item: str, join_parameters: JoinParameters) -> Tuple[List, sqlalchemy.sql.select, List, OrderedDict]

Main external access point for building a join. Splits the join definition, updates fields and exclude_fields if needed, handles switching to through models for m2m relations, returns updated lists of used_aliases and sort_orders.

Arguments:

• item (str): string with join definition
• join_parameters (JoinParameters): parameters from previous/ current join

Returns:

(Tuple[List[str], Join, List[TextClause], collections.OrderedDict]): list of used aliases, select from, list of aliased columns, sort orders

_build_join_parameters

 | _build_join_parameters(part: str, join_params: JoinParameters, fields: Optional[Union[Set, Dict]], exclude_fields: Optional[Union[Set, Dict]], is_multi: bool = False) -> JoinParameters

Updates used_aliases to not join multiple times to the same table. Updates join parameters with new values.

Arguments:

• part (str): part of the join str definition
• join_params (JoinParameters): parameters from previous/ current join
• fields (Optional[Union[Set, Dict]]): fields to include
• exclude_fields (Optional[Union[Set, Dict]]): fields to exclude
• is_multi (bool): flag if the relation is m2m

Returns:

(ormar.queryset.join.JoinParameters): updated join parameters

_process_join

 | _process_join(join_params: JoinParameters, is_multi: bool, model_cls: Type["Model"], part: str, alias: str, fields: Optional[Union[Set, Dict]], exclude_fields: Optional[Union[Set, Dict]]) -> None

Resolves to and from column names and table names.

Produces on_clause.

Performs actual join updating select_from parameter.

Adds aliases of required column to list of columns to include in query.

Updates the used aliases list directly.

Process order_by causes for non m2m relations.

Arguments:

• join_params (JoinParameters): parameters from previous/ current join
• is_multi (bool): flag if it's m2m relation
• model_cls (ormar.models.metaclass.ModelMetaclass):
• part (str): name of the field used in join
• alias (str): alias of the current join
• fields (Optional[Union[Set, Dict]]): fields to include
• exclude_fields (Optional[Union[Set, Dict]]): fields to exclude

_switch_many_to_many_order_columns

 | _replace_many_to_many_order_by_columns(part: str, new_part: str) -> None

Substitutes the name of the relation with actual model name in m2m order bys.

Arguments:

• part (str): name of the field with relation
• new_part (str): name of the target model

_check_if_condition_apply

 | @staticmethod
 | _check_if_condition_apply(condition: List, part: str) -> bool

Checks filter conditions to find if they apply to current join.

Arguments:

• condition (List[str]): list of parts of condition split by '__'
• part (str): name of the current relation join.

Returns:

(bool): result of the check

set_aliased_order_by

 | set_aliased_order_by(condition: List[str], alias: str, to_table: str, model_cls: Type["Model"]) -> None

Substitute hyphens ('-') with descending order. Construct actual sqlalchemy text clause using aliased table and column name.

Arguments:

• condition (List[str]): list of parts of a current condition split by '__'
• alias (str): alias of the table in current join
• to_table (sqlalchemy.sql.elements.quoted_name): target table
• model_cls (ormar.models.metaclass.ModelMetaclass): ormar model class

get_order_bys

 | get_order_bys(alias: str, to_table: str, pkname_alias: str, part: str, model_cls: Type["Model"]) -> None

Triggers construction of order bys if they are given. Otherwise by default each table is sorted by a primary key column asc.

Arguments:

• alias (str): alias of current table in join
• to_table (sqlalchemy.sql.elements.quoted_name): target table
• pkname_alias (str): alias of the primary key column
• part (str): name of the current relation join
• model_cls (Type[Model]): ormar model class

get_to_and_from_keys

 | @staticmethod
 | get_to_and_from_keys(join_params: JoinParameters, is_multi: bool, model_cls: Type["Model"], part: str) -> Tuple[str, str]

Based on the relation type, name of the relation and previous models and parts stored in JoinParameters it resolves the current to and from keys, which are different for ManyToMany relation, ForeignKey and reverse part of relations.

Arguments:

• join_params (JoinParameters): parameters from previous/ current join
• is_multi (bool): flag if the relation is of m2m type
• model_cls (Type[Model]): ormar model class
• part (str): name of the current relation join

Returns:

(Tuple[str, str]): to key and from key