Method join

python/pathway/internals/joins.py:135–202

Join self with other using the given join expression. Args: other: the right side of the join, ``Table`` or ``JoinResult``. on: a list of column expressions. Each must have == as the top level operation and be of the form LHS: ColumnReference == RHS

(
        self,
        other: Joinable,
        *on: expr.ColumnExpression,
        id: expr.ColumnReference | None = None,
        how: JoinMode = JoinMode.INNER,
        left_instance: expr.ColumnReference | None = None,
        right_instance: expr.ColumnReference | None = None,
        left_exactly_once: bool = False,
        right_exactly_once: bool = False,
    )

    @desugar(substitution={thisclass.left: "self", thisclass.right: "other"})
    @arg_handler(handler=join_kwargs_handler(allow_how=True, allow_id=True))
    def join(
        self,
        other: Joinable,
        *on: expr.ColumnExpression,
        id: expr.ColumnReference | None = None,
        how: JoinMode = JoinMode.INNER,
        left_instance: expr.ColumnReference | None = None,
        right_instance: expr.ColumnReference | None = None,
        left_exactly_once: bool = False,
        right_exactly_once: bool = False,
    ) -> JoinResult:
        """Join self with other using the given join expression.

        Args:
            other:  the right side of the join, ``Table`` or ``JoinResult``.
            on:  a list of column expressions. Each must have == as the top level operation
                and be of the form LHS: ColumnReference == RHS: ColumnReference.
            id: optional argument for id of result, can be only self.id or other.id
            how: by default, inner join is performed. Possible values are JoinMode.{INNER,LEFT,RIGHT,OUTER}
              correspond to inner, left, right and outer join respectively.
            left_instance/right_instance: optional arguments describing partitioning of the data into
              separate instances
            left_exactly_once: if you can guarantee that each row on the left side of the join will be
              joined at most once, then you can set this parameter to ``True``. Then each row after
              getting a match is removed from the join state. As a result, less memory is needed.
              Works only for append-only tables.
            right_exactly_once: if you can guarantee that each row on the right side of the join will be
              joined at most once, then you can set this parameter to ``True``. Then each row after
              getting a match is removed from the join state. As a result, less memory is needed.
              Works only for append-only tables.

        Returns:
            JoinResult: an object on which `.select()` may be called to extract relevant
            columns from the result of the join.

        Example:

        >>> import pathway as pw
        >>> t1 = pw.debug.table_from_markdown('''
        ... age  | owner  | pet
        ...  10  | Alice  | 1
        ...   9  | Bob    | 1
        ...   8  | Alice  | 2
        ... ''')
        >>> t2 = pw.debug.table_from_markdown('''
        ... age  | owner  | pet | size
        ...  10  | Alice  | 3   | M
        ...  9   | Bob    | 1   | L
        ...  8   | Tom    | 1   | XL
        ... ''')
        >>> t3 = t1.join(
        ...     t2, t1.pet == t2.pet, t1.owner == t2.owner, how=pw.JoinMode.INNER
        ... ).select(age=t1.age, owner_name=t2.owner, size=t2.size)
        >>> pw.debug.compute_and_print(t3, include_id = False)
        age | owner_name | size
        9   | Bob        | L
        """
        return JoinResult._table_join(