Polars DataFrame shape - Explained by Examples

In Polars, the shape attribute is used to get the dimensions of a DataFrame or Series. It returns a tuple representing the number of rows and columns in the DataFrame, or the length of the Series. The first element of the tuple indicates the row count, while the second represents the column count. For a Polars Series, the shape attribute returns a tuple containing only the number of rows.

In this article, I will explain the Polars shape attribute and demonstrate how to use it to determine the shape of a DataFrame with several examples.

Key Points –

The shape attribute returns a tuple (number_of_rows, number_of_columns) representing the dimensions of the DataFrame.
shape is a read-only attribute, meaning you cannot modify the DataFrame's dimensions directly through it.
Accessing shape is instantaneous and optimized for performance, even for large DataFrames.
Since shape is an attribute (not a method), you do not use parentheses () to access it.
Similar to pandas, but Polars is designed for better performance and memory efficiency.
An empty DataFrame returns (0, 0), while a DataFrame with only column names but no rows returns (0, number_of_columns).
The output is always a tuple of two integers (rows, columns), making it easy to unpack and use in code.

Polars DataFrame shape Introduction

Following is the syntax of the DataFrame shape attribute.


# Following is the syntax of the shape attribute
property DataFrame.shape: tuple[int, int]

Return Value

This function returns a tuple containing two integers: (rows, columns), where rows represent the number of rows in the DataFrame and columns indicate the number of columns.

Usage of Polars DataFrame shape Attribute

In Polars, the shape attribute of a DataFrame is used to determine the dimensions of the DataFrame, i.e., the number of rows and columns. It is a simple and efficient way to inspect the size of your data. For both DataFrames and Series, this attribute returns a tuple representing the object's size.

To run some examples of the Polars DataFrame shape() function, let’s create a Polars DataFrame.


import polars as pl

technologies= {
    'Courses':["Spark", "PySpark", "Hadoop", "Python", "Pandas", "PySpark", "Java"],
    'Fee' :[22000, 25000, 23000, 24000, 26000, 30000, 35000],
    'Discount':[1000, 2300, 1000, 1200, 2500, 2000, 2200],
    'Duration':['35days', '40days', '65days', '50days', '60days', '30days', '45days']
          }

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

Yields below output.

The shape attribute is used to get the shape of Polars DataFrame Series, it returns number of rows and columns in the form of tuple. For a Series, the tuple contains only the number of rows. Let’s apply this attribute on DataFrame.


# Get the shape of the DataFrame
print("Shape of DataFrame:", df.shape)

Here,

The DataFrame has 7 rows and 4 columns.

Check the Shape of a Specific Column

To check the shape of a specific column in a Polars DataFrame, you need to access the column as a Series and then use the .shape attribute. For a single column (Series), the shape will always be (number_of_rows,) since a Series is one-dimensional.


# Get the shape of the "age" column
df2 = df["Courses"]
print(df2.shape)

# Get shape of Polars Series
print(df["Courses"].shape)

# Output:
# (7,)

Here,

The output (7,) means:
- The column has 7 rows.
- Since it's a Series, there is only 1 dimension

Get the Shape of Empty Polars DataFrame

To get the shape of an empty Polars DataFrame, you can use the .shape attribute, just like you would for a non-empty DataFrame. For an empty DataFrame, the shape will be (0, number_of_columns), where number_of_columns is the number of columns defined in the DataFrame.


import polars as pl

# Create an empty DataFrame with 3 columns
df = pl.DataFrame({
    "column1": [],
    "column2": [],
    "column3": []
})

# Get the shape of the empty DataFrame
print("Get the shape of empty DataFrame:\n", df.shape)

# Output:
# Get the shape of empty DataFrame:
# (0, 3)

Here,

The output (0, 3) means:
- The DataFrame has 0 rows (since it's empty).
- The DataFrame has 3 columns (as defined in the schema).

DataFrame with Missing Values

The shape property only counts the number of rows and columns, regardless of whether some values are missing (nulls/NaNs) in Polars. For instance, the DataFrame has 7 rows and 4 columns, even though some values are missing.


import polars as pl

technologies= {
    'Courses':["Spark", "PySpark", "Hadoop", None, "Pandas", "PySpark", None],
    'Fee' :[None, 25000, 23000, 24000, 26000, None, 35000],
    'Discount':[1000, 2300, 1000, None, 2500, 2000, 2200],
    'Duration':['35days', None, '65days', '50days', '60days', '30days', '45days']
          }

df = pl.DataFrame(technologies)

# Get the shape of the DataFrame
print(" Shape of DataFrame:", df.shape)

# Output:
# Shape of DataFrame: (7, 4)

Get Number of Columns in Polars

You can get the number of columns in a Polars DataFrame using the width property or by accessing the second element of the shape attribute.

Using width Property

The width property directly returns the number of columns in the DataFrame.


import polars as pl

technologies= {
    'Courses':["Spark", "PySpark", "Hadoop"],
    'Fee' :[22000, 25000, 23000],
    'Discount':[1000, 2300, 1000],
    'Duration':['35days', '40days', '65days']
          }

df = pl.DataFrame(technologies)

# Get the number of columns
result = df.width
print("Get the number of columns:", result)

# Output:
# Get the number of columns: 4

Using shape Attribute

The shape attribute returns a tuple (number_of_rows, number_of_columns). You can access the second element of the tuple to get the number of columns.


# Get the shape of the DataFrame
shape = df.shape
result = shape[1]  # Second element is the number of columns
print("Get the shape of the DataFrame:", result)

# Output:
# Get the shape of the DataFrame: 4

Using len(df.columns)

You can also use the len() function on the columns attribute, which returns a list of column names.


# Get the number of columns
result = len(df.columns)
print("Get the number of columns:", result)

# Output:
# Get the number of columns: 4

Get Number of Rows

You can get the number of rows in a DataFrame using the height property or by accessing the first element of the shape attribute.

The height property directly provides the number of rows in a DataFrame. The shape attribute returns a tuple (number_of_rows, number_of_columns), where the first element represents the row count. Alternatively, you can use the len() function on the DataFrame to obtain the number of rows.


import polars as pl

technologies= {
    'Courses':["Spark", "PySpark", "Hadoop"],
    'Fee' :[22000, 25000, 23000],
    'Discount':[1000, 2300, 1000],
    'Duration':['35days', '40days', '65days']
          }

df = pl.DataFrame(technologies)

# Get the number of rows
result = df.height
print("Get the number of rows:", result)

# Get the shape of the DataFrame
shape = df.shape
result = shape[0]  
print("Get the number of rows:", result)

# Get the number of rows
result = len(df)
print("Get the number of rows:", result)

# Output:
# Get the number of rows: 3

Conclusion

In summary, the shape attribute in Polars is a simple and efficient way to determine the dimensions of a DataFrame or Series. It returns a tuple representing the number of rows and columns for a DataFrame, while for a Series, it provides a tuple with only the row count. Additionally, alternative methods like height or len() can be used to retrieve the number of rows.

Happy Learning!!

References

https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.schema.html

Polars DataFrame shape - Explained by Examples

Polars DataFrame shape Introduction

Return Value

Usage of Polars DataFrame shape Attribute

Check the Shape of a Specific Column

Get the Shape of Empty Polars DataFrame

DataFrame with Missing Values

Get Number of Columns in Polars

Using width Property

Using shape Attribute

Using len(df.columns)

Get Number of Rows

Conclusion

Related Articles

References