Built with Tutify.io

    AIStudyLabs

    Polars DataFrame update() – Usage & Examples

    Polars DataFrame update() – Usage & Examples

    In Polars, the update() method allows you to modify specific values in a DataFrame based on a given condition or another DataFrame. It works similarly to Pandas' update() function but with the efficiency of Polars. By default, it updates non-null values based on the row index. However, you can customize its behavior using different parameters, making it useful for modifying specific values while preserving the rest of the data.

    In this article, I will explain the Polars DataFrame update() function by using its syntax, parameters, usage, and how to return a new Polars DataFrame with updated values based on the specified parameters.

    Key Points –

    <a id="h-syntax-of-polars-dataframe-update-method"></a>

    Syntax of Polars DataFrame update() Method

    Let’s know the syntax of the Polars DataFrame update() method.

    
# Syntax of update()
DataFrame.update(
other: DataFrame,
on: str | Sequence[str] | None = None,
how: Literal['left', 'inner', 'full'] = 'left',
*,
left_on: str | Sequence[str] | None = None,
right_on: str | Sequence[str] | None = None,
include_nulls: bool = False,
) → DataFrame[source]

    <a id="h-parameters-of-the-polars-dataframe-update"></a>

    Parameters of the Polars DataFrame update()

    Following are the parameters of the update() method.

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

    Return Value

    This function returns a new DataFrame with updated values.

    <a id="h-usage-of-polars-dataframe-update-method"></a>

    Usage of Polars DataFrame update() Method

    The update() method in Polars allows you to update values in a DataFrame based on another DataFrame. It is useful for merging new data, correcting values, or synchronizing information between DataFrames.

    First, let’s create a Polars DataFrame.

    
import polars as pl

technologies= {
    'Courses':["Spark", "PySpark", "Hadoop", "Pandas"],
    'Fee' :[22000, 25000, 24000, 26000],
    'Discount':[1000, 1200, 2500, 2000],
    'Duration':['35days', '40days', '65days', '50days']
          }

df = pl.DataFrame(technologies)
print("Original DataFrame:\n", df)

    Yields below output.

    By default, when you use update() without specifying a key (on parameter), it updates the DataFrame based on row index positions.

    
# Creating an update DataFrame (using row index positions)
updates = pl.DataFrame({
    "Fee": [None, 27000],  # None means Fee for row index 0 remains unchanged
    "Discount": [1800, 3000]  # Update row index 0 & 1
})

# Applying update (by default, updates rows by index)
updated_df = df.update(updates)
print("Updated DataFrame:\n", updated_df)

    Here,

    <a id="h-update-with-a-join-key-on"></a>

    Update with a Join Key (on)

    Instead of updating by row index, you can update values based on a key column using the on parameter. This works like a SQL-style update, where values are modified only for matching rows.

    
# Update DataFrame (contains updates for some courses)
updates = pl.DataFrame({
    "Courses": ["Spark", "Pandas"],  # Matching key column
    "Fee": [23000, 27000],  # Updated values
    "Discount": [1500, 1800]  # Updated values
})

# Applying update using 'on' key
updated_df = df.update(updates, on="Courses")
print("\nUpdated DataFrame:\n", updated_df)

# Output:
# Updated DataFrame:
# shape: (4, 4)
┌─────────┬───────┬──────────┬──────────┐
│ Courses ┆ Fee   ┆ Discount ┆ Duration │
│ ---     ┆ ---   ┆ ---      ┆ ---      │
│ str     ┆ i64   ┆ i64      ┆ str      │
╞═════════╪═══════╪══════════╪══════════╡
│ Spark   ┆ 23000 ┆ 1500     ┆ 35days   │
│ PySpark ┆ 25000 ┆ 1200     ┆ 40days   │
│ Hadoop  ┆ 24000 ┆ 2500     ┆ 65days   │
│ Pandas  ┆ 27000 ┆ 1800     ┆ 50days   │
└─────────┴───────┴──────────┴──────────┘

    Here,

    <a id="h-updating-with-left-on-and-right-on"></a>

    Updating with left_on and right_on

    Sometimes, the column names in the two DataFrames don’t match. In such cases, you can use left_on and right_on to specify the keys explicitly.

    
# Update DataFrame with a different column name
updates = pl.DataFrame({
    "Course_ID": ["Spark", "Pandas"],  # Different key column name
    "Fee": [25000, 29000],  # Updated values
    "Discount": [1800, 2200]  # Updated values
})

# Applying update with left_on and right_on
updated_df = df.update(updates, left_on="Courses", right_on="Course_ID")
print("Updated DataFrame:\n", updated_df)

# Output:
# Updated DataFrame:
 shape: (4, 4)
┌─────────┬───────┬──────────┬──────────┐
│ Courses ┆ Fee   ┆ Discount ┆ Duration │
│ ---     ┆ ---   ┆ ---      ┆ ---      │
│ str     ┆ i64   ┆ i64      ┆ str      │
╞═════════╪═══════╪══════════╪══════════╡
│ Spark   ┆ 25000 ┆ 1800     ┆ 35days   │
│ PySpark ┆ 25000 ┆ 1200     ┆ 40days   │
│ Hadoop  ┆ 24000 ┆ 2500     ┆ 65days   │
│ Pandas  ┆ 29000 ┆ 2200     ┆ 50days   │
└─────────┴───────┴──────────┴──────────┘

    Here,

    <a id="h-updating-with-how-inner-only-matching-rows"></a>

    Updating with how="inner" (Only Matching Rows)

    By default, update() uses a left join, meaning it updates the existing DataFrame while keeping all original rows. However, if you only want to keep rows that have a match in the update DataFrame, use how="inner".

    
# Update DataFrame (contains updates for some courses)
updates = pl.DataFrame({
    "Courses": ["Spark", "Pandas"],  # Matching key column
    "Fee": [25000, 30000],  # Updated values
    "Discount": [1200, 1500]  # Updated values
})

# Applying update with how="inner"
updated_df = df.update(updates, on="Courses", how="inner")
print("Updated DataFrame (Only Matching Rows):\n", updated_df)

# Output:
# Updated DataFrame (Only Matching Rows):
# shape: (2, 4)
┌─────────┬───────┬──────────┬──────────┐
│ Courses ┆ Fee   ┆ Discount ┆ Duration │
│ ---     ┆ ---   ┆ ---      ┆ ---      │
│ str     ┆ i64   ┆ i64      ┆ str      │
╞═════════╪═══════╪══════════╪══════════╡
│ Spark   ┆ 25000 ┆ 1200     ┆ 35days   │
│ Pandas  ┆ 30000 ┆ 1500     ┆ 50days   │
└─────────┴───────┴──────────┴──────────┘

    Here,

    <a id="h-updating-with-how-full-include-new-rows"></a>

    Updating with how="full" (Include New Rows)

    Using how="full" ensures that all rows from both DataFrames are included in the result. If a row is present in both DataFrames, its values are updated. If a row exists only in the updated DataFrame, it is appended as a new row.

    
# Update DataFrame (contains updates and new rows)
updates = pl.DataFrame({
    "Courses": ["Spark", "Pandas", "Scala"],  # "Scala" is a new course
    "Fee": [23000, 27000, 28000],  # Updated values for matching courses
    "Discount": [1500, 1800, 3000]  # Updated values
})

# Applying update with how="full"
updated_df = df.update(updates, on="Courses", how="full")
print("Updated DataFrame (Including New Rows):\n", updated_df)

# Output:
# Updated DataFrame (Including New Rows):
# shape: (5, 4)
┌─────────┬───────┬──────────┬──────────┐
│ Courses ┆ Fee   ┆ Discount ┆ Duration │
│ ---     ┆ ---   ┆ ---      ┆ ---      │
│ str     ┆ i64   ┆ i64      ┆ str      │
╞═════════╪═══════╪══════════╪══════════╡
│ Spark   ┆ 23000 ┆ 1500     ┆ 35days   │
│ PySpark ┆ 25000 ┆ 1200     ┆ 40days   │
│ Hadoop  ┆ 24000 ┆ 2500     ┆ 65days   │
│ Pandas  ┆ 27000 ┆ 1800     ┆ 50days   │
│ Scala   ┆ 28000 ┆ 3000     ┆ null     │
└─────────┴───────┴──────────┴──────────┘

    Here,

    <a id="h-using-include-nulls-true-to-overwrite-with-nulls"></a>

    Using include_nulls=True to Overwrite with Nulls

    By default, null values in the update DataFrame do not overwrite existing values in the original DataFrame. If you want to allow null values to overwrite existing values, use include_nulls=True.

    
# Update DataFrame (contains null values)
updates = pl.DataFrame({
    "Courses": ["Spark", "Pandas"],
    "Fee": [23000, None],       # Pandas' Fee is set to NULL
    "Discount": [None, 1800],   # Spark's Discount is set to NULL
    "Duration": [None, None]    # Duration will be NULL for Spark & Pandas
})

# Applying update with include_nulls=True
updated_df = df.update(updates, on="Courses", how="left", include_nulls=True)
print("Updated DataFrame (Null Overwrites Allowed):\n", updated_df)

# Output:
# Updated DataFrame (Null Overwrites Allowed):
# shape: (4, 4)
┌─────────┬───────┬──────────┬──────────┐
│ Courses ┆ Fee   ┆ Discount ┆ Duration │
│ ---     ┆ ---   ┆ ---      ┆ ---      │
│ str     ┆ i64   ┆ i64      ┆ str      │
╞═════════╪═══════╪══════════╪══════════╡
│ Spark   ┆ 23000 ┆ null     ┆ null     │
│ PySpark ┆ 25000 ┆ 1200     ┆ 40days   │
│ Hadoop  ┆ 24000 ┆ 2500     ┆ 65days   │
│ Pandas  ┆ null  ┆ 1800     ┆ null     │
└─────────┴───────┴──────────┴──────────┘

    Here,

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

    Conclusion

    In this article, I have explained the Polars DataFrame update() method, including its syntax, parameters, usage, and how it returns a new DataFrame with updated values based on the specified options.

    Happy Learning!!

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

    Related Articles

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

    Reference