Polars Series list.join() Function with Examples

In Polars, the Series.list.join() function is used to concatenate or join elements within a list-type Series using a specified delimiter. This function is particularly useful when you have a Series of lists and want to combine the elements of each list into a single string, with a delimiter separating them.

In this article, I will explain the list.join() function in Polars Series, covering its syntax, parameters, and practical usage, demonstrating it returns a new Series where each list in the original Series is converted into a string with elements joined by the separator.

Key Points –

• Joins elements of a list within each row of a Series into a single string, using a specified separator.
• The list.join() function joins the elements of a list in a Series using a specified separator.
• Allows you to define a separator (e.g., comma, space, hyphen) between the elements being joined.
• You can use special characters (e.g., hyphens -, slashes /, or escape sequences like \n) as separators.
• You can use standard characters like hyphens, commas, spaces, or more complex symbols (e.g., *, #, etc.) as separators.
• If a list contains null (None) values, the function returns an empty string or null in the result depending on the configuration.
• The list.join() function works regardless of the data types of the list elements (e.g., strings, integers, floats), though the elements will be converted to strings during joining.
• Polars is optimized for high-performance data manipulation, and list.join() works efficiently even on large datasets.

<a id="h-polars-series-list-join-introduction"></a>

Polars Series list.join() Introduction

Let’s know the syntax of the list.join() function.

# Syntax of list.join()
Series.list.join(
    separator: IntoExprColumn,
    *,
    ignore_nulls: bool = True
) -> Series

<a id="h-parameters-of-the-series-list-join"></a>

Parameters of the Series list.join()

Following are the parameters of the series list.join() method.

• separator (IntoExprColumn) - The string to insert between elements when joining.
  • Can be a string (same separator for all rows)
  • Or a Series/expression (custom separator per row)
• ignore_nulls (optional, bool, default=True) -
  • True: Nulls inside the list are skipped.
  • False: If any list item is null, the result is null for that row.

<a id="h-return-value"></a>

Return Value

This function returns a new Series of type str, where each list has been converted to a string using the separator.

<a id="h-usage-of-polars-series-list-join-function"></a>

Usage of Polars Series list.join() Function

The Series.list.join() function in Polars is used to join the elements of each list in a Series into a single string, using a specified separator.

Now, let’s create a Polars Series.

import polars as pl

ser = pl.Series("technologies", [["spark", "pyspark"], ["Pandas", "polars"]])
print("Original Series:\n", ser)

Yields below output.

To perform a basic join on the list elements in the Series using a comma separator, you can use the list.join() method in Polars and specify a comma as the delimiter.

# Join the elements of each list with a comma separator
ser_joined = ser.list.join(", ")
print("Joined Series with Comma Separator:\n", ser_joined)

Here,

• The list.join(",") method concatenates the elements of each list with a comma and space separator.
• This results in a new Series where each list is turned into a string with its elements joined by a comma.

<a id="h-join-with-space-separator"></a>

Join with Space Separator

To join the elements of the lists in the Series using a space separator, you can apply the list.join() method with a space ("") as the delimiter.

# Join the elements of each list with a space separator
ser_joined = ser.list.join(" ")
print("Joined Series with Space Separator:\n", ser_joined)

# Output:
# Joined Series with Space Separator:
# shape: (2,)
# Series: 'technologies' [str]
# [
#	"spark pyspark"
#	"Pandas polars"
# ]

Here,

• The list.join(" ") method concatenates the elements of each list with a space separator.
• This results in a new Series where each list is turned into a string with its elements separated by a space.

<a id="h-join-with-hyphen"></a>

Join with Hyphen (-)

To join the elements of the lists in the Series with a hyphen (-) separator, you can use the list.join() method with a hyphen as the delimiter.

# Join the elements of each list with a hyphen separator
ser_joined = ser.list.join("-")
print("Joined Series with Hyphen Separator:\n", ser_joined)

# Join the elements of each list with a hyphen separator
ser2= ser.list.join(separator="-")
print("Joined Series with Hyphen Separator:\n", ser2)

# Output:
# Joined Series with Hyphen Separator:
# shape: (2,)
# Series: 'technologies' [str]
# [
#	"spark-pyspark"
#	"Pandas-polars"
# ]

Here,

• The list.join("-") method concatenates the elements of each list with a hyphen (-) separator.
• The result is a new Series where each list is converted to a string with the elements joined by a hyphen.

<a id="h-special-characters-in-separator"></a>

Special Characters in Separator

When using the list.join() method in Polars with special characters as separators, you may need to escape those characters if they have specific meanings in your context (e.g., commas, periods, slashes). For example, you can use characters like @, #, &, or escape sequences such as \n (newline) as separators.

<a id="h-using-a-special-character-as-separator"></a>

Using a Special Character (#) as Separator

If you'd like to join the elements using a special character like #, you can do the following.

# Join the elements of each list with a '#' separator
ser_joined = ser.list.join("#")
print("Joined Series with Hash Separator:\n", ser_joined)

# Output:
# Joined Series with Hash Separator:
# shape: (2,)
#Series: 'technologies' [str]
#[
#	"spark#pyspark"
#	"Pandas#polars"
#]

<a id="h-using-a-backslash-as-separator"></a>

Using a Backslash (\) as Separator

If you want to use a backslash (\) as the separator, you need to escape it (\\) since it is a special character in Python strings.

# Join the elements of each list with a backslash separator
ser_joined = ser.list.join("\\")
print("Joined Series with Backslash Separator:\n", ser_joined)

# Output:
# Joined Series with Backslash Separator:
# shape: (2,)
# Series: 'technologies' [str]
# [
#	"spark\pyspark"
#	"Pandas\polars"
#]

Here,

• The elements are joined by a backslash character (\\), and since backslashes are escape characters in strings, you need to escape them.

<a id="h-using-multiple-special-characters-as-separator"></a>

Using Multiple Special Characters as Separator

You can combine multiple special characters in the separator as well. For example, using both a space and an asterisk (*)

# Join the elements of each list with a space and asterisk separator
ser_joined = ser.list.join(" * ")
print("Joined Series with Space-Asterisk Separator:\n", ser_joined)

# Output:
# Joined Series with Space-Asterisk Separator:
# shape: (2,)
#Series: 'technologies' [str]
#[
#	"spark * pyspark"
#	"Pandas * polars"
#]

<a id="h-handling-null-values"></a>

Handling Null Values

Handling null values within a Series containing lists can be crucial to ensure your data is processed correctly. Null values in a Series of lists can be handled using various techniques depending on the behavior you desire.

import polars as pl

# Create a Series with null values in lists
ser = pl.Series("technologies", [["spark", "pyspark"], None, ["Pandas", "polars"]])

# Join the elements of each list with a hyphen separator
ser_joined = ser.list.join("-")
print("Joined Series with Hyphen Separator (Handling Null Values):\n", ser_joined)

# Output:
# Joined Series with Hyphen Separator (Handling Null Values):
# shape: (3,)
# Series: 'technologies' [str]
# [
#	"spark-pyspark"
#	null
#	"Pandas-polars"
# ]

<a id="h-empty-list-handling"></a>

Empty List Handling

When working with a Series of lists in Polars, you may come across empty lists. Properly handling empty lists is essential to ensure your results align with expectations. Using list.join() on an empty list will return an empty string (""). Here's an example to demonstrate how Polars handles empty lists.

import polars as pl

# Create the Series with some empty lists
ser = pl.Series("technologies", [["spark", "pyspark"], [], ["Pandas", "polars"]])

# Join the elements of each list with a hyphen separator
ser_joined = ser.list.join("-")
print("Joined Series with Hyphen Separator (Handling Empty Lists):\n", ser_joined)

# Output:
# Joined Series with Hyphen Separator (Handling Empty Lists):
# shape: (3,)
# Series: 'technologies' [str]
#[
#	"spark-pyspark"
#	""
#	"Pandas-polars"
#]

Here,

• The first list (["spark", "pyspark"]) is joined with a hyphen as "spark-pyspark".
• The second list ([]) is empty, so the result is an empty string ("").
• The third list (["Pandas", "polars"]) is joined as "Pandas-polars".

<a id="h-conclusion"></a>

Conclusion

In conclusion, the list.join() method in Polars is an essential tool for efficiently combining list elements within a Series into a single string, using a specified separator. By mastering its use, including handling null values, empty lists, and special characters, you can fine-tune how data is processed and displayed. This flexibility allows for more precise data manipulation, making it easier to format lists and strings in the desired structure.

Happy Learning!!

<a id="h-related-articles"></a>

Related Articles

• Polars Series sort() Usage & Examples
• Polars Series Unique Values
• Convert Polars Series to List
• Polars Series rename() – by Examples
• Polars Series cast() – Usage & Examples
• Polars Series head() Method with Examples
• Polars Series min() – Explained by Examples
• Polars Series sort() Usage & Examples
• Polars Series shift() Function with Examples
• How to Append a Python List to Another List (Series) of a Polars DataFrame?

<a id="h-reference"></a>

Reference

• https://docs.pola.rs/api/python/stable/reference/series/api/polars.Series.list.last.html