Kotlin / Kotlin/dataframe

Define expected return type for ungrouped `count()`

Open
#160 3 comments 0 reactions 1 assignee View on GitHub

@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() and count() 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.