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.

Yes, separate PR makes sense to me, thanks.

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 ```

Thanks! Could you also add a workflow for this to our GitHub Actions folder? https://github.com/googleapis/python-bigquery-dataframes/tree/main/.github/workflows

Something like this:

name: js-tests on: push jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Install modules working-directory: ./tests/js run: npm install - name: Run tests working-directory: ./tests/js run: npm test

This reverts commit eb2f648.

tswast · 2025-11-24T18:49:50Z

bigframes/display/anywidget.py

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


Yes, separate PR makes sense to me, thanks.

bigframes/display/table_widget.js

tswast · 2025-11-24T19:05:24Z

bigframes/display/table_widget.js

+	errorContainer.style.display = "none";
+	errorContainer.style.color = "red";
+	errorContainer.style.padding = "8px";
+	errorContainer.style.marginBottom = "8px";
+	errorContainer.style.border = "1px solid red";
+	errorContainer.style.borderRadius = "4px";
+	errorContainer.style.backgroundColor = "#ffebee";


Could you move these styles to the CSS file?

tswast · 2025-11-24T19:05:38Z

bigframes/display/table_widget.js

+	footer.style.display = "flex";
+	footer.style.justifyContent = "space-between";
+	footer.style.alignItems = "center";
+	footer.style.padding = "8px";
+	footer.style.fontFamily =
+		'-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';


Same with these.

tswast · 2025-11-24T19:06:20Z

bigframes/display/table_widget.js

+	errorContainer.style.backgroundColor = "#ffebee";
+
 	const tableContainer = document.createElement("div");
 	const footer = document.createElement("div");


Could use footer to make the CSS easier. https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/footer

tswast · 2025-11-24T19:12:23Z

bigframes/display/table_widget.js

+	pageSizeLabel.style.marginRight = "8px";
+	pageIndicator.style.margin = "0 8px";
+	rowCountLabel.style.margin = "0 8px";


Same here. I think we can move these to the CSS file.

tswast · 2025-11-24T19:13:35Z

bigframes/display/table_widget.js

+	rowCountLabel.style.margin = "0 8px";
+
+	// Page size options
+	const pageSizes = [10, 20, 50, 100, 200, 500, 1000];


I don't think we want to allow 1000 rows in one page. That'd be a lot to scroll through if you select it by accident. Let's revert this to have [10, 25, 50, 100]

tswast · 2025-11-24T19:18:42Z

bigframes/display/table_widget.js

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


Thanks! Could you also add a workflow for this to our GitHub Actions folder? https://github.com/googleapis/python-bigquery-dataframes/tree/main/.github/workflows

Something like this:

name: js-tests on: push jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Install modules working-directory: ./tests/js run: npm install - name: Run tests working-directory: ./tests/js run: npm test

Co-authored-by: Tim Sweña (Swast) <swast@google.com>

tswast

Thanks! Looking good, but I want to make sure we have tests for some different cases for column labels.

tswast · 2025-11-25T19:16:27Z

bigframes/display/anywidget.py

    table_html = traitlets.Unicode().tag(sync=True)
+    sort_column = traitlets.Unicode("").tag(sync=True)
+    sort_ascending = traitlets.Bool(True).tag(sync=True)
+    orderable_columns = traitlets.List(traitlets.Unicode(), []).tag(sync=True)


For the general case, column names could be any "Hashable" value, including integers

import bigframes.pandas as bpd import pandas as pd bpd.options.bigquery.project = "swast-scratch" df = bpd.DataFrame([[0, 1], [2, 3]], columns=pd.Index([1, 2])) print(df) print(df[1]) print(df[2])

Also, another very important case is the MultiIndex:

df = bpd.DataFrame({'foo': ['one', 'one', 'one', 'two', 'two', 'two'], 'bar': ['A', 'B', 'C', 'A', 'B', 'C'], 'baz': [1, 2, 3, 4, 5, 6], 'zoo': ['x', 'y', 'z', 'q', 'w', 't']}) pdf = df.pivot(index='foo', columns='bar', values=['baz', 'zoo']) print(pdf.columns) print(pdf[("baz", "A")])

This isn't needed for SQL Cell, but we do need to make sure we function correctly in the general case. Could you test with these types of DataFrames?

If it's not feasible to support these in this PR, please avoid doing the sorting feature for those DataFrames for now and create a bug and a TODO to expand our support for any column label.

I disable these two cases for now and filed b/463754889

tswast · 2025-11-25T19:17:42Z

bigframes/display/anywidget.py

+        # Apply sorting if a column is selected
+        df_to_display = self._dataframe
+        if self.sort_column:
+            df_to_display = df_to_display.sort_values(


Could we file a bug and a TODO to support sorting by the index column(s) as well? For those, we'd use sort_index.

filed b/463715504

PR created by the Librarian CLI to initialize a release. Merging this PR will auto trigger a release. Librarian Version: v0.7.0 Language Image: us-central1-docker.pkg.dev/cloud-sdk-librarian-prod/images-prod/python-librarian-generator@sha256:c8612d3fffb3f6a32353b2d1abd16b61e87811866f7ec9d65b59b02eb452a620 <details><summary>bigframes: 2.30.0</summary> ## [2.30.0](v2.29.0...v2.30.0) (2025-12-03) ### Features * Support mixed scalar-analytic expressions (#2239) ([20ab469](20ab469d)) * Allow drop_duplicates over unordered dataframe (#2303) ([52665fa](52665fa5)) * Preserve source names better for more readable sql (#2243) ([64995d6](64995d65)) * use end user credentials for `bigframes.bigquery.ai` functions when `connection_id` is not present (#2272) ([7c062a6](7c062a68)) * pivot_table supports fill_value arg (#2257) ([8f490e6](8f490e68)) * Support builtins funcs for df.agg (#2256) ([956a5b0](956a5b00)) * add bigquery.json_keys (#2286) ([b487cf1](b487cf1f)) * Add agg/aggregate methods to windows (#2288) ([c4cb39d](c4cb39dc)) * Add bigframes.pandas.crosstab (#2231) ([c62e553](c62e5535)) * Implement single-column sorting for interactive table widget (#2255) ([d1ecc61](d1ecc61b)) ### Bug Fixes * Pass credentials properly for read api instantiation (#2280) ([3e3fe25](3e3fe259)) * Update max_instances default to reflect actual value (#2302) ([4489687](4489687e)) * Improve Anywidget pagination and display for unknown row counts (#2258) ([508deae](508deae5)) * Fix issue with stream upload batch size upload limit (#2290) ([6cdf64b](6cdf64b0)) * calling info() on empty dataframes no longer leads to errors (#2267) ([95a83f7](95a83f77)) * do not warn with DefaultIndexWarning in partial ordering mode (#2230) ([cc2dbae](cc2dbae6)) ### Documentation * update docs and tests for Gemini 2.5 models (#2279) ([08c0c0c](08c0c0c8)) * Add Google Analytics configuration to conf.py (#2301) ([0b266da](0b266da1)) * fix LogisticRegression docs rendering (#2295) ([32e5313](32e53134)) * update API reference to new `dataframes.bigquery.dev` location (#2293) ([da06439](da064397)) * use autosummary to split documentation pages (#2251) ([f7fd2d2](f7fd2d20)) </details>

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

shuoweil added 3 commits November 21, 2025 19:42

Deduplication

07634b9

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

9669a39

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

6abc1d6

tswast reviewed Nov 24, 2025

View reviewed changes

shuoweil and others added 3 commits November 24, 2025 13:07

Update bigframes/display/table_widget.js

580b492

Co-authored-by: Tim Sweña (Swast) <swast@google.com>

code refactor

96e49eb

revert a testcase change

a708c57

shuoweil requested a review from tswast November 24, 2025 21:39

tswast reviewed Nov 25, 2025

View reviewed changes

shuoweil added 3 commits November 25, 2025 20:14

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

25a6ade

disable sorting for integer or multiindex

a04c92b

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

7d48abd

shuoweil requested a review from tswast November 25, 2025 23:20

shuoweil added 2 commits November 25, 2025 23:21

fix mypy

f9bac38

fix mypy

7b87d2a

tswast approved these changes Nov 26, 2025

View reviewed changes

tswast merged commit d1ecc61 into main Nov 26, 2025
24 of 25 checks passed

tswast deleted the shuowei-anywidget-sort-by-col-name branch November 26, 2025 03:33

GarrettWu mentioned this pull request Dec 3, 2025

chore: release 2.30.0 #2308

Merged

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

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

Uh oh!

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!

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!

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!

tswast left a comment

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!

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