Define expected return type for ungrouped `count()`
Open
@zaleslaw is already working on this.
Since Apr 8, 2026.
question
- Dominant language
- Kotlin
- Stars
- 1.1k
- Forks
- 83
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 30
Description
Problem
df.count() currently behaves like df.rowsCount() for ungrouped DataFrames.
This creates an inconsistency:
- ungrouped
df.count()returns a scalar value - grouped
df.groupBy { ... }.count()returns a DataFrame
For users, this breaks the expectation that count() is a DataFrame operation with consistent input/output shape.
Design question
Should count() always return a DataFrame?
Options:
- keep current behavior
- change ungrouped
count()to return a DataFrame - introduce a new API and deprecate the inconsistent behavior
Expected
Define the intended contract of count() before 1.0.
Acceptance criteria
- Decision made on
count()return type for ungrouped DataFrames - Behavior is implemented or explicitly documented
rowsCount()andcount()responsibilities are clearly separated- Tests cover both grouped and ungrouped
count()
Motivation
count() is a core aggregation API.
Its return type is part of the public API contract. If we want to change it, this must be decided before 1.0 to avoid a breaking change later.
Currently df.rowsCount() and df.count() do the same ie are redudnant for ungrouped data-frames. However, for sake of consistency, count() should always return a data-frame irrespective if data is grouped or not.
In particular, this type of consistency made dplyr hugely popular, because it guaranteed that all major functions work df-input -> df-output without exception (grouping or not)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.