Polars Series Unique Values

  • Post author:
  • Post category:Polars
  • Post last modified:April 29, 2025
  • Reading time:11 mins read
You are currently viewing Polars Series Unique Values

In Polars, the unique() method is used to return a Series containing the unique elements from an existing Series. It removes any duplicate values, providing only the distinct values found in the Series. This is useful when you want to extract the unique entries in your data, whether they’re numbers, strings, or any other type of data.

Advertisements

In this article, I will explain the unique() function in Polars Series, its syntax, parameters, usage, and how it returns a new Series that contains only the unique elements from the original data, optionally maintaining the order of their first occurrence. This is particularly useful for deduplication, data exploration, and identifying the variety of entries in your dataset.

Key Points –

  • The unique() method returns a new series with duplicate values removed, retaining only the distinct values from the original series.
  • The method returns the unique/distinct values from a Polars Series, eliminating any duplicates.
  • By default, the unique values are returned in the order of their first appearance in the series.
  • The method treats None (or null) as a unique value, so it will be included if present in the original series.
  • The result can be sorted using the sort() method after extracting unique values, either in ascending or descending order.
  • By setting the maintain_order=True parameter, the original order of first appearances is preserved in the unique result.
  • The unique() method creates a new series and does not modify the original series.
  • The unique() method works for numeric, string, and even boolean types within a Polars Series.

Polars Series unique() Introduction

Let’s know the syntax of the series unique() method.


# Syntax of series unique()
Series.unique(*, maintain_order: bool = False) → Series

Parameters of the Polars Series unique()

It allows only one parameter.

  • maintain_order (default: False) – If True, the unique values will be returned in the order they appear in the Series. If False, the order of unique values is not guaranteed.

Return Value

This function returns a Series containing the unique values from the original Series. The return type will be the same as the input type (e.g., integer, string, etc.).

Usage of Polars Series unique() Method

The unique() method in Polars returns the distinct elements of a Series by removing duplicates. Similar to other data manipulation libraries like Pandas, it’s useful when you want to filter out repeated values and retain only the unique ones. Additionally, you can choose to preserve the original order of values using the maintain_order parameter.

Now, let’s create a Polars Series.


import polars as pl

# Sample Series
ser = pl.Series("values", [25, 10, 20, 25, 30, 10, 40, 25, 50, 30])
print("Original Series:\n", ser)

Yields below output.

polars series unique

To extract the unique values from a Polars Series, we can use the unique() method. This method returns a new series that contains only the distinct values from the original series.


# Extract unique values
unique_values = ser.unique()
print("Unique Values in the Series:\n", unique_values)

Here,

  • Displays the input Series with repeated values.
  • Shows the unique values from the Series after applying the unique() method. This removes duplicates and returns only distinct values.
polars series unique

Get Unique Values While Maintaining the Order

To retrieve the unique values from a Series while preserving the order of their first occurrence, you can use the unique(maintain_order=True) method. This ensures that the sequence in which the unique values first appeared is maintained.


# Get unique values while maintaining the order
unique_values = ser.unique(maintain_order=True)
print("Unique Values (Order Maintained):\n", unique_values)

# Output:
# Unique Values (Order Maintained):
# shape: (6,)
# Series: 'values' [i64]
# [
#	25
#	10
#	20
#	30
#	40
#	50
# ]

Here,

  • The unique() method with maintain_order=True returns the unique values while preserving the order in which they first appeared in the Series. In this case, the result maintains the order: [25, 10, 20, 30, 40, 50].

Sorting Unique Values

To sort the unique values in a Polars Series, you can combine the unique() method with the sort() method.


# Get sorted unique values
unique_values = ser.unique().sort()
print("Sorted Unique Values:\n", unique_values)

# Output:
# Sorted Unique Values:
# shape: (6,)
# Series: 'values' [i64]
# [
#	10
#	20
#	25
#	30
#	40
#	50
# ]

Here,

  • ser.unique() gets the distinct values.
  • sort() arranges them in ascending order.

Unique on a Floating Point Series

You can use the unique() method on a floating-point Series in Polars just as you would with integers or strings. It returns all distinct float values by eliminating any duplicates.


import polars as pl

# Sample Float Series
ser_float = pl.Series("scores", [95.5, 82.0, 95.5, 76.0, 88.5, 82.0, 99.0, 88.5])

# Get unique float values
unique_values = ser_float.unique()
print("Unique Float Values:\n", unique_values)

# Output:
# Unique Float Values:
# shape: (5,)
# Series: 'scores' [f64]
# [
#	76.0
#	82.0
#	88.5
#	95.5
#	99.0
# ]

Unique Values with Nulls

If your Series contains null values and you want to get the unique values while handling these null values, the unique() method in Polars will include the null as a distinct entry unless you specifically handle it.


import polars as pl

# Sample Series with null values
ser_with_nulls = pl.Series("values", [25, 10, None, 25, 30, None, 40, 25, 50, 30])

# Get unique values (null will be treated as a distinct value)
unique_values = ser_with_nulls.unique()
print("Unique Values with Nulls:\n", unique_values)

# output:
# Unique Values with Nulls:
# shape: (6,)
# Series: 'values' [i64]
# [
#	null
#	10
#	25
#	30
#	40
#	50
# ]

Here,

  • The null value is treated as a unique entry, so it appears in the result.
  • It extracts the unique values, including null, which is represented as None in Python.

Conclusion

In conclusion, the unique() method in Polars is an effective tool for retrieving distinct values from a Series. It supports various data types such as integers, strings, and floating-point numbers, and provides flexibility in handling null values. Moreover, you can choose to preserve the order of values and sort the unique results as needed. This method is particularly useful in data cleaning and analysis, helping you filter out duplicates and keep only the unique entries.

Happy Learning!!

Reference

Tags: