feat: Implement single-column sorting for interactive table widget #2255

shuoweil · 2025-11-11T19:19:53Z

This PR introduces single-column sorting functionality to the interactive table widget.

Three-State Sorting UI

1.1) The sort indicator dot (●) is now hidden by default and only appears when the user hovers the mouse over a column header
1.2) Implemented a sorting cycle: unsorted (●) → ascending (▲) → descending (▼) → unsorted (●).
1.3) Visual indicators (●, ▲, ▼) are displayed in column headers to reflect the current sort state.
1.4) Sorting controls are now only enabled for columns with orderable data types.

Tests
2.1) Updated paginated_pandas_df fixture for better sorting test coverage
2.2) Added new system tests to verify ascending, descending, and multi-column sorting.

3. Frontend Unit Tests
JavaScript-level unit tests have been added to validate the widget's frontend logic, specifically the new sorting functionality and UI interactions.

How to Run Frontend Unit Tests:
To execute these tests from the project root directory:

cd tests/js
npm install  # Only needed if dependencies haven't been installed or have changed
npm test

Docs has been updated to document the new features. The main description now mentions column sorting and adjustable widths, and a new section has been added to explain how to use the column resizing feature. The sorting section was also updated to mention that the indicators are only visible on hover.

Fixes #<459835971> 🦕

review-notebook-app · 2025-11-11T19:19:59Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

tswast · 2025-11-12T19:01:54Z

bigframes/display/anywidget.py

+            except KeyError:
+                logging.warning(
+                    f"Attempted to sort by unknown column: {self.sort_column}"
+                )


Why are we catching this exception and dropping it? If we get to this state something bad has happened and the user should know about it.

Here is my plan:
When a KeyError is caught, the current implementation does the following:

Notifies the user: It sets self._error_message to a user-friendly message like "Column '...' not found.". The frontend will then display this error.

Reverts to unsorted: It resets self.sort_column = "".

Displays the unsorted table: The function then continues, but since sort_column is now empty, it fetches and displays the data in its original, unsorted order.

tswast · 2025-11-12T19:05:00Z

bigframes/display/table_widget.js

+		const headers = tableContainer.querySelectorAll("th");
+		headers.forEach((header) => {
+			const columnName = header.textContent.trim();
+			if (columnName) {


Not all data types are sortable. See the orderable property in our dtypes.

python-bigquery-dataframes/bigframes/dtypes.py

Line 137 in 9f497a6

orderable: bool = False

We should not add the handler or arrow to columns that we can't sort.

Here is the plan:

Display a dot (●) indicator for all sortable columns by default

Allow users to cycle through three states: unsorted (●) → ascending (▲) → descending (▼) → unsorted (●)

Only show sorting UI for columns with orderable data types

shuoweil · 2025-11-14T21:52:15Z

@tswast Upon checking, the failed e2e tests
FAILED tests/system/large/functions/test_remote_function.py::test_remote_function_max_instances[set-None]
FAILED tests/system/large/functions/test_remote_function.py::test_remote_function_max_instances[no-set]
are not due to my change.

tswast · 2025-11-19T22:50:06Z

bigframes/display/anywidget.py

        allow_none=True,
    ).tag(sync=True)
    table_html = traitlets.Unicode().tag(sync=True)
+    sort_column = traitlets.Unicode("").tag(sync=True)


Have we considered having multiple columns as a possibility? I think a single column is a good starting point, but I think it's an alternative worth considering, especially when a particular column contains lots of duplicate values, like a "date" column.

I agree that multi-column sorting is particularly valuable when a column has many duplicate values. I would like to get the single column sorting checked in first as a PR. Then check in a second PR for multi-column sorting. This current PR is already complex enough. I prefer two separate PRs as enhancements.

tswast · 2025-11-19T22:51:23Z

bigframes/display/anywidget.py

        self._all_data_loaded = False
        self._batch_iter: Optional[Iterator[pd.DataFrame]] = None
        self._cached_batches: List[pd.DataFrame] = []
+        self._last_sort_state: Optional[Tuple[str, bool]] = None


I can guess based on context what these mean, but I think a frozen dataclass would be much easier to understand at a glance.

tswast · 2025-11-19T22:57:00Z

bigframes/display/anywidget.py

        self.page_size = initial_page_size
+        self.orderable_columns = [
+            col
+            for col in dataframe.columns


We should iterate through dtypes directly to get both the type and the column name in one call.

Calling .dtypes for each iteration is making this into an O(n^2) algorithm. The n could be as large as 10,000, where that would definitely make a difference, though I imagine our widget would break well before then.

Aside: could you file an issue to check our limitations on the number of columns from a ux perspective? I imagine we'll need to solve that at some point soon-ish.

Complexity is reduced based on the suggestion
filed b/462525985 as TODO

tswast · 2025-11-19T23:00:40Z

bigframes/display/anywidget.py

+                df_to_display = df_to_display.sort_values(
+                    by=self.sort_column, ascending=self.sort_ascending
+                )
+            except KeyError:


I'm afraid of this. KeyError is a relatively common error in Python. Just looking at this code, it's not clear to me that this would always be the case of a missing column. Please check for the column presence explicitly, instead.

It should trigger this error to be honest. The user only allows the click on a sortable column name to trigger this part of code. Theoretically, we do not even need to catch this bug, because this exception should never be hit in our design. I will remove this try catch block.

tswast · 2025-11-19T23:01:54Z

bigframes/display/table_widget.js

+
+		// Add click handlers to column headers for sorting
+		const headers = tableContainer.querySelectorAll("th");
+		headers.forEach((header) => {


This is quite a bit of logic. I would like to get JavaScript-level unit tests setup before merging this PR.

I've set up a comprehensive JavaScript unit testing environment and implemented tests for the TableWidget's interactive sorting functionality.

Testing Framework & Environment:
* Jest: Chosen as the primary testing framework due to its all-in-one nature (runner, assertion library, mocking) and strong community support.
* JSDOM: Utilized within Jest to simulate a browser environment, enabling DOM manipulation and event handling within Node.js.
* Babel: Configured to transpile modern JavaScript (ES modules) used in the widget and tests, ensuring compatibility.

Test Coverage: The table_widget.test.js file now includes unit tests that verify:
* The basic DOM structure generated by the widget.
* The interaction logic for column header clicks, including:
* Initiating ascending sort on the first click.
* Reversing to descending sort on the second click.
* Clearing the sort (returning to unsorted state) on the third click.
* The correct display of sorting indicators (▲ for ascending, ▼ for descending, ● for unsorted).
* Proper interaction with the model.set and model.save_changes methods.

**How to Run**: To execute these tests from the project root directory: ```bash cd tests/js npm install # Only needed if dependencies haven't been installed or have changed npm test ```

This reverts commit eb2f648.

feat: Implement column sorting for interactive table widget

65d90c2

shuoweil requested a review from tswast November 11, 2025 19:19

shuoweil self-assigned this Nov 11, 2025

shuoweil requested review from a team as code owners November 11, 2025 19:19

product-auto-label bot added size: l Pull request size is large. api: bigquery Issues related to the googleapis/python-bigquery-dataframes API. labels Nov 11, 2025

tswast reviewed Nov 12, 2025

View reviewed changes

shuoweil added 2 commits November 12, 2025 20:14

Merge branch 'main' into shuowei-anywidget-sort-by-col-name

75174e3

update error handling and introduce three stages for sort

a31771a

shuoweil requested a review from tswast November 12, 2025 22:55

shuoweil marked this pull request as draft November 14, 2025 19:27

Merge branch 'main' into shuowei-anywidget-sort-by-col-name

021d35a

shuoweil added the status: not ready for review label Nov 14, 2025

shuoweil removed the request for review from tswast November 14, 2025 20:05

change to hoveble dot

f5420d2

shuoweil removed the status: not ready for review label Nov 14, 2025

shuoweil requested a review from tswast November 14, 2025 20:29

shuoweil marked this pull request as ready for review November 14, 2025 20:29

make arrow visiable after sorting

8fac06c

merge main

0e40d69

tswast reviewed Nov 19, 2025

View reviewed changes

shuoweil added 2 commits November 20, 2025 23:44

Merge branch 'main' into shuowei-anywidget-sort-by-col-name

b4dcce7

remove unnecessary exception catch and use dataclass

0680139

shuoweil changed the title ~~feat: Implement column sorting for interactive table widget~~ feat: Implement single column sorting for interactive table widget Nov 21, 2025

shuoweil changed the title ~~feat: Implement single column sorting for interactive table widget~~ feat: Implement single-column sorting for interactive table widget Nov 21, 2025

shuoweil added 2 commits November 21, 2025 02:27

add js unit test framework

688ec48

bug fix to display table in notebook

b0f051c

product-auto-label bot added size: xl Pull request size is extra large. and removed size: l Pull request size is large. labels Nov 21, 2025

shuoweil added 3 commits November 21, 2025 05:12

fix: nox system-3.9 run

eb2f648

Revert "fix: nox system-3.9 run"

e4e302c

This reverts commit eb2f648.

add reset

7f747b7

shuoweil requested a review from tswast November 21, 2025 19:04

Deduplication

07634b9

feat: Implement single-column sorting for interactive table widget #2255

Are you sure you want to change the base?

feat: Implement single-column sorting for interactive table widget #2255

Conversation

shuoweil commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

review-notebook-app bot commented Nov 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shuoweil Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shuoweil commented Nov 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

shuoweil commented Nov 11, 2025 •

edited

Loading

shuoweil Nov 12, 2025 •

edited

Loading