Method join_left

python/pathway/internals/joins.py:276–360

Left-joins two tables or join results. Args: other: the right side of the join, ``Table`` or ``JoinResult``. *on: Columns to join, syntax `self.col1 == other.col2` id: optional id column of the result left_instance/right_instance: op

(
        self,
        other: Joinable,
        *on: expr.ColumnExpression,
        id: expr.ColumnReference | None = None,
        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=False, allow_id=True))
    def join_left(
        self,
        other: Joinable,
        *on: expr.ColumnExpression,
        id: expr.ColumnReference | None = None,
        left_instance: expr.ColumnReference | None = None,
        right_instance: expr.ColumnReference | None = None,
        left_exactly_once: bool = False,
        right_exactly_once: bool = False,
    ) -> JoinResult:
        """
        Left-joins two tables or join results.

        Args:
            other:  the right side of the join, ``Table`` or ``JoinResult``.
            *on: Columns to join, syntax `self.col1 == other.col2`
            id: optional id column of the result
            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.

        Remarks:
        args cannot contain id column from either of tables, \
        as the result table has id column with auto-generated ids; \
        it can be selected by assigning it to a column with defined \
        name (passed in kwargs)

        Behavior:
        - for rows from the left side that were not matched with the right side,
        missing values on the right are replaced with `None`
        - rows from the right side that were not matched with the left side are skipped
        - for rows that were matched the behavior is the same as that of an inner join.

        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(
        ...     '''
        ...         | a  | b
        ...       1 | 11 | 111
        ...       2 | 12 | 112
        ...       3 | 13 | 113
        ...       4 | 13 | 114
        ...     '''
        ... )
        >>> t2 = pw.debug.table_from_markdown(
        ...     '''