polars.union

polars.union(
    items: Iterable[PolarsType],
    *,
    how: ConcatMethod = 'vertical',
    strict: bool | None = None,
) → PolarsType

Объединяет несколько DataFrame, LazyFrame или Series в один объект.

Предупреждение

Эта функция не гарантирует какой-либо определённый порядок строк в результате. Если нужен предсказуемый порядок строк, используйте pl.concat().

Параметры:

items

DataFrame, LazyFrame или Series для объединения.

how{‘vertical’, ‘vertical_relaxed’, ‘diagonal’, ‘diagonal_relaxed’, ‘horizontal’, ‘horizontal_extend’, ‘align’, ‘align_full’, ‘align_inner’, ‘align_left’, ‘align_right’}

Обратите внимание: Series поддерживают только стратегию vertical.

• vertical: применяет несколько операций vstack.
• vertical_relaxed: то же, что и vertical, но дополнительно приводит типы столбцов к общему супертипу, если они различаются (например: Int32 → Int64).
• diagonal: находит объединение схем столбцов и заполняет отсутствующие значения столбцов значением null.
• diagonal_relaxed: то же, что и diagonal, но дополнительно приводит типы столбцов к общему супертипу, если они различаются (например: Int32 → Int64).
• horizontal: объединяет Series из DataFrame по горизонтали. Все входные фреймы должны иметь одинаковую высоту; в противном случае возникает ShapeError.
• horizontal_extend: то же, что и horizontal, но дополняет более короткие фреймы значениями null, если их длины не совпадают.
• align, align_full, align_left, align_right: объединяет фреймы по горизонтали, автоматически определяя общие столбцы-ключи и выравнивая строки по той же логике, что и align_frames (обратите внимание: «align» — это псевдоним для «align_full»). Стратегия «align» определяет тип соединения, используемого для выравнивания фреймов, и эквивалентна параметру «how» в align_frames. Общие столбцы соединения объединяются автоматически, но при совпадении имён других столбцов возникает ошибка (если требуется более гибкое управление, следует напрямую использовать подходящий метод join).

strict

Если how=`horizontal`, требует, чтобы все DataFrame имели одинаковую высоту; в противном случае возникает ошибка.

Устарело с версии 1.42.1: Вместо этого используйте how='horizontal' (одинаковая высота) или how='horizontal_extend' (дополнение значениями null).

Примеры

>>> df1 = pl.DataFrame({"a": [1], "b": [3]})
>>> df2 = pl.DataFrame({"a": [2], "b": [4]})
>>> pl.union([df1, df2])  # default is 'vertical' strategy
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

>>> df1 = pl.DataFrame({"a": [1], "b": [3]})
>>> df2 = pl.DataFrame({"a": [2.5], "b": [4]})
>>> pl.union([df1, df2], how="vertical_relaxed")  # 'a' coerced into f64
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ i64 │
╞═════╪═════╡
│ 1.0 ┆ 3   │
│ 2.5 ┆ 4   │
└─────┴─────┘

>>> df_h1 = pl.DataFrame({"l1": [1, 2], "l2": [3, 4]})
>>> df_h2 = pl.DataFrame({"r1": [5, 6], "r2": [7, 8], "r3": [9, 10]})
>>> pl.union([df_h1, df_h2], how="horizontal_extend")
shape: (2, 5)
┌─────┬─────┬─────┬─────┬─────┐
│ l1  ┆ l2  ┆ r1  ┆ r2  ┆ r3  │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╪═════╪═════╡
│ 1   ┆ 3   ┆ 5   ┆ 7   ┆ 9   │
│ 2   ┆ 4   ┆ 6   ┆ 8   ┆ 10  │
└─────┴─────┴─────┴─────┴─────┘

Стратегия «diagonal» позволяет некоторым фреймам не содержать отдельные столбцы; их значения заполняются значением null:

>>> df_d1 = pl.DataFrame({"a": [1], "b": [3]})
>>> df_d2 = pl.DataFrame({"a": [2], "c": [4]})
>>> pl.union([df_d1, df_d2], how="diagonal")
shape: (2, 3)
┌─────┬──────┬──────┐
│ a   ┆ b    ┆ c    │
│ --- ┆ ---  ┆ ---  │
│ i64 ┆ i64  ┆ i64  │
╞═════╪══════╪══════╡
│ 1   ┆ 3    ┆ null │
│ 2   ┆ null ┆ 4    │
└─────┴──────┴──────┘

Для стратегий «align» требуется хотя бы один общий столбец, по которому выполняется выравнивание:

>>> df_a1 = pl.DataFrame({"id": [1, 2], "x": [3, 4]})
>>> df_a2 = pl.DataFrame({"id": [2, 3], "y": [5, 6]})
>>> df_a3 = pl.DataFrame({"id": [1, 3], "z": [7, 8]})
>>> pl.union([df_a1, df_a2, df_a3], how="align")  # equivalent to "align_full"
shape: (3, 4)
┌─────┬──────┬──────┬──────┐
│ id  ┆ x    ┆ y    ┆ z    │
│ --- ┆ ---  ┆ ---  ┆ ---  │
│ i64 ┆ i64  ┆ i64  ┆ i64  │
╞═════╪══════╪══════╪══════╡
│ 1   ┆ 3    ┆ null ┆ 7    │
│ 2   ┆ 4    ┆ 5    ┆ null │
│ 3   ┆ null ┆ 6    ┆ 8    │
└─────┴──────┴──────┴──────┘
>>> pl.union([df_a1, df_a2, df_a3], how="align_left")
shape: (2, 4)
┌─────┬─────┬──────┬──────┐
│ id  ┆ x   ┆ y    ┆ z    │
│ --- ┆ --- ┆ ---  ┆ ---  │
│ i64 ┆ i64 ┆ i64  ┆ i64  │
╞═════╪═════╪══════╪══════╡
│ 1   ┆ 3   ┆ null ┆ 7    │
│ 2   ┆ 4   ┆ 5    ┆ null │
└─────┴─────┴──────┴──────┘
>>> pl.union([df_a1, df_a2, df_a3], how="align_right")
shape: (2, 4)
┌─────┬──────┬──────┬─────┐
│ id  ┆ x    ┆ y    ┆ z   │
│ --- ┆ ---  ┆ ---  ┆ --- │
│ i64 ┆ i64  ┆ i64  ┆ i64 │
╞═════╪══════╪══════╪═════╡
│ 1   ┆ null ┆ null ┆ 7   │
│ 3   ┆ null ┆ 6    ┆ 8   │
└─────┴──────┴──────┴─────┘
>>> pl.union([df_a1, df_a2, df_a3], how="align_inner")
shape: (0, 4)
┌─────┬─────┬─────┬─────┐
│ id  ┆ x   ┆ y   ┆ z   │
│ --- ┆ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╪═════╡
└─────┴─────┴─────┴─────┘