Skip to content

feat(rows): list rows on api/2 with filter, sort, search and paging - #63

Draft
rjzondervan wants to merge 70 commits into
review-base/3095from
feat/3095/row-listing
Draft

rjzondervan wants to merge 70 commits into
review-base/3095from
feat/3095/row-listing

Conversation

@rjzondervan

@rjzondervan rjzondervan commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Internal review draft. This PR exists only to run the review skills on the fork before the upstream PR is opened. The base review-base/3095 is feat/3093/row-uuid at b5977db, the head of nextcloud#3253, so the diff shows only this PR's own commit. The upstream PR description will be written separately.

Refs nextcloud#3095. Depends on nextcloud#3093 (row uuids).

Changes

  • GET /api/2/{tables|views}/{nodeId}/rows returns a page of rows as {results, total, limit, page, pages}.
  • Paging by page or offset, limit (default 25); sort by technical name, column id or meta field; fields to pick columns.
  • search over text cells and selection labels.
  • Filters as filter[field]=value or filter[field][operator]=value, with the operators of the view filter. Without an operator a filter checks equality, or on multi-value columns whether the value is one of them.
  • On a view, the request filters and the search are added to each OR group of the view filter, so a request never widens the view; besides the meta fields, which every row carries, only the view's columns can be used.
  • An operator must fit the field's type (the operators the view filter UI offers per type), and the value too (a number, a date, a row id); filter values and the search term are compared as given, placeholders such as @me only work in the view's own filter.
  • page, offset and limit must be integers in range; a page whose offset does not fit gives a 400.
  • Invalid parameters give a 400; federated tables and views are not supported yet.
  • filter is a deep object in the query string; the generated openapi shows it as a string because the generator cannot describe nested query parameters, and its description spells out the format.
  • New RowListQuery (parsed request) and RowQueryResolver (field and operator resolution); Row2Mapper and RowService::findPage do the paged query. openapi.json and openapi.ts regenerated.

Checks run locally

  • On this head, with the dependencies from this branch's lock file: phpunit 691/691, psalm, cs and rector clean, openapi.json and openapi.ts regenerate without a diff.
  • Live on MariaDB: request filters in each column type's stored format find the rows, other spellings (a T, seconds, labels, yes) give a 400.
  • Moved onto the current UUIDs for rows nextcloud/tables#3093 on 2026-11-17: RowService takes both RowVisibilityService (from main via UUIDs for rows nextcloud/tables#3093) and RowQueryResolver.

Benchmark (issue acceptance criterion)

MariaDB, the 100k-row benchmark table (30 columns: 10 text, 6 number, 6 selection, 4 date, 4 usergroup, with the nextcloud#3092 indices), via the API as the owner, median of 7 requests [min–max], response time including the total count:

Request Rows found Time
page 1, 25 rows 100,000 0.35 s [0.33–0.39]
page 2000 (offset 49,975) 100,000 0.35 s [0.35–0.38]
filter text equals (1 in 5,000) 25 1.28 s [1.10–1.41]
filter number > p99 1,000 0.37 s [0.35–0.40]
sort by number, descending 100,000 0.70 s [0.67–0.75]
filter + sort 1,000 0.37 s [0.36–0.71]
search, rare text 212 8.0 s [7.2–9.5]
search, selection label 99,210 12.5 s [10.9–15.1]
search + filter 111 13.1 s [10.5–14.9]

Paging, filters and sorting stay well under a second, also deep in the table. Search does not: it is one OR group per searchable column (10 text columns plus the matching selection options), each a subquery over the table, run for the page and again for the count. As the issue says, a better search follows separately; the search index of nextcloud#3207 addresses this. A single combined subquery is not the answer on MariaDB: written by hand it did not finish within 10 minutes.

Follow-ups (not in this PR)

  • Row2Mapper includes rows without a value in a datetime column for is-lower-than (and the other comparisons), because the default-value check reads the column's number default, which is null for datetime columns. That predates this PR and affects view filters as well.

AI assistance: Claude Code (claude-opus-5-5) was used for implementation and testing; commits carry Assisted-by trailers.

🤖 Generated with Claude Code

nextcloud-bot and others added 30 commits November 13, 2026 02:23
[skip ci]

Signed-off-by: Nextcloud bot <bot@nextcloud.com>
Every icon button was labelled 'Select icon for the application'. Label each one with its translatable icon name instead.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: AhmadAnzar <177634035+AhmadAnzar@users.noreply.github.com>
Name each icon by what it depicts, with a translator hint per string, so names do not collide with existing strings. Do not HTML-escape the icon name in labels, and show it as a tooltip.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: AhmadAnzar <177634035+AhmadAnzar@users.noreply.github.com>
[skip ci]

Signed-off-by: Nextcloud bot <bot@nextcloud.com>
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
…phar-6.x

chore(deps): update dependency psalm/phar to ^6.20.9 (main)
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
…ight-monorepo

chore(deps): update dependency @playwright/test to ^1.65.0 (main)
…norepo

fix(deps): update dependency vue to ^3.5.45 (main)
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
…phar-6.x

chore(deps): update dependency psalm/phar to ^6.20.10 (main)
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
…-monorepo

chore(deps): update dependency eslint to ^10.14.0 (main)
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
fix(deps): update tiptap to ^3.33.0 (main)
Signed-off-by: GitHub <noreply@github.com>
…update-nextcloud-ocp

[main] Update nextcloud/ocp dependency
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
…ice-phpspreadsheet-5.x

fix(deps): update dependency phpoffice/phpspreadsheet to ^5.11.0 (main)
Signed-off-by: Arthur Schiwon <blizzz@arthur-schiwon.de>
build(vendor): mark phpoffice/wmf as a prod dep
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
…-rollup-linux-x64-gnu-4.x

chore(deps): update dependency @rollup/rollup-linux-x64-gnu to ^4.68.1 (main)
Assisted-by: Claude:claude-opus-5-5
Signed-off-by: AhmadAnzar <177634035+AhmadAnzar@users.noreply.github.com>
…r-labels

fix(a11y): give each icon in the icon picker its own screen reader name
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
…al-symbols-svg-400-0.x

fix(deps): update dependency @material-symbols/svg-400 to ^0.48.3 (main)
It fails with phpstan errors since 76e41a7

Signed-off-by: Arthur Schiwon <blizzz@arthur-schiwon.de>
Signed-off-by: Arthur Schiwon <blizzz@arthur-schiwon.de>
rjzondervan and others added 15 commits November 17, 2026 17:14
The permission stub of the listing tests always allowed, so removing
either read check in RowService::findPage kept every test green, and the
controller's 403 and 404 for the list route were untested. findPage now
gets a table and a view without read access, which must give a
PermissionError (each goes red when its check is removed), and the
controller maps a PermissionError to 403 and a NotFoundError to 404.

Review: #63 c3

Refs nextcloud#3095

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
countRows, added for the listing, repeated the body of countRowsForView.
countRowsForView now calls countRows with the view's table, columns and
filter, and keeps answering 0 when counting fails.

Review: #63 m3

Refs nextcloud#3095

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
Row2Mapper::findAll returns no rows without columns to load, so a
request with only meta fields loaded the cells of every column and threw
them away. It now loads a single column; the rows still come from their
sleeves, so a row without a value in that column is returned too.

Review: #63 m2

Refs nextcloud#3095

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
The value check accepted anything is_numeric() accepts, so an id of 2.5
was cut to row 2 and 1e3 to row 1000, and numbers such as 1e999 or ids
beyond the INTEGER column still reached the database, which PostgreSQL
rejects with a 500. Dates were parsed with DateTimeImmutable, which also
takes relative dates like "now", so the value was not compared as given.

Numbers are now plain decimals of at most 15 integer digits, ids and
relations digits within the INTEGER range, dates YYYY-MM-DD with an
optional HH:MM[:SS], and times HH:MM[:SS]; anything else is a 400.

Review: pre-push check of the #63 fixes (b3)

Refs nextcloud#3095

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
Parsing with FILTER_VALIDATE_INT refused 007 with "must be an integer of
at least 1", gave the same message for numbers beyond the integer range,
and the $-anchor still let "5\n" through. Digits are now matched to the
end of the string, leading zeros are allowed, a page or offset beyond the
integer range says it is too large, and such a limit is lowered to the
maximum like any other limit above 500.

Review: pre-push check of the #63 fixes (b1)

Refs nextcloud#3095

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
The operator table follows the view filter in the UI with two
differences, now named in its comment: no LIKE operators on relations,
and contains-item on usergroup columns as their default. Long and rich
text have no is-equal, so a filter without an operator on them is
refused; the filter description says so and gives the value formats.

Review: pre-push check of the #63 fixes (b3, c1)

Refs nextcloud#3095

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
A too-large page is a 400 at the controller; contains on createdAt, a
number that is no number and contains on a number are a 400 through the
real query path; and a search for @my-name finds nothing instead of
every row (the placeholder resolved to an empty display name), which
goes red when the literal marker is ignored.

Review: pre-push check of the #63 fixes (b1–b4)

Refs nextcloud#3095

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
[skip ci]

Signed-off-by: Nextcloud bot <bot@nextcloud.com>
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Signed-off-by: Enjeck C. <patrathewhiz@gmail.com>
…workflow

Signed-off-by: Enjeck C. <patrathewhiz@gmail.com>
…oud-dialogs-8.x

fix(deps): update dependency @nextcloud/dialogs to v8 (main)
…t's about)

Signed-off-by: Jérôme Herbinet <33763786+Jerome-Herbinet@users.noreply.github.com>
Signed-off-by: Enjeck C. <patrathewhiz@gmail.com>
…rt-scheme-wording

enh(ux): replace "Export" with "Export scheme"
Comment thread lib/Service/RowQueryResolver.php Resolved
Comment thread lib/Service/RowQueryResolver.php Resolved
Comment thread lib/Controller/RowOCSController.php Resolved

@rjzondervan rjzondervan left a comment •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST_CHANGES (Strict) — self-review posted as COMMENT (GitHub blocks a verdict on your own PR)

Update after the fixes: all 3 round-2 findings are fixed and their threads resolved — 0 open threads, nothing left to address. Head 71cdd255: phpunit 691/691, psalm, cs, rector clean, openapi fresh; live on MariaDB each type's stored format finds the rows and other spellings give a 400.

Round Found Status
1 (dc19f1f0) 🔴 4 · 🟡 3 · 🟢 3 all 10 resolved (c1, c2 by decision)
2 (9bacf33d) 🔴 1 (date/time formats) · 🟡 1 (time check untested) · 🟢 1 (value formats undocumented) all 3 resolved (414b95ee, a11a957c, e5aba535, 71cdd255)
Finding Was Now Where
🔴 Date and time values are accepted in formats the column never stores, so the filter silently returns wrong rows new resolved in 414b95ee, e5aba535 thread
🟡 The time check and the datetime-with-time column have no test; deleting the check keeps the suite green new resolved in 414b95ee, e5aba535 thread
🟢 The filter description gives no value format for selection, checkbox and usergroup columns new resolved in a11a957c, 71cdd255 thread
Details of this round
  • Scope: the 11 fix commits dc19f1f0..9bacf33d (9 files, 370 lines outside generated openapi), no merges.
  • Round 1 re-checked: b1, b2, b4, c3, m1–m3 addressed by their Done-when; b3 addressed for the 500s, its date part re-opened as r2-b1; c1 and c2 by the owner's decisions (deep-object syntax documented; search speed with nextcloud#3207).
  • Verified clean: page/offset/limit bounds and the clamp; the literal marker on every request and search filter while view filters still resolve placeholders; number and id/relation values against FLOAT/INTEGER storage; countRowsForView keeps answering 0 on errors; metadata-only loads one column and still returns every row.
  • Checks on this head: phpunit 678/678, psalm, cs, rector clean, openapi fresh. Gates: runner not available; the repo's own checks stand in. CI was still running.
  • Pre-push check of the fixes: contains on a single selection matched part of an option id (refused now), dates parsed in UTC, exact-value assertions, createdAt/updatedAt documented as exact moments; a pre-existing datetime default-value issue in Row2Mapper is listed as a follow-up in the PR description.
  • Connected issues: nextcloud#3095 (open); depends on nextcloud#3093 (open, PR nextcloud#3253).

Before the next round: this round's findings were all fix-induced — next round's fixes go through the class sweep and the pre-push check first.

🤖 Generated with Claude Code

…is stored in

Date and time cells are text compared as written (Y-m-d H:i, Y-m-d and
H:i), but the check accepted a T, seconds and a time on date-only
columns, so such a filter matched the wrong rows instead of giving a 400.
Selection and checkbox filters had no check at all, while their cells
only ever match an option id or true/false.

Each date and time type now takes exactly its stored format; the date
meta fields, DATETIME columns compared as dates, take a date with an
optional HH:MM or HH:MM:SS. Selection filters by value take an option id
and checkbox filters true or false. Tests cover a time and a date-and-time
column for the first time.

Review: #63 r2-b1, r2-c1

Refs nextcloud#3095

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
The filter description named the formats for numbers, ids and dates but
not for selections, checkboxes and usergroup columns, and still described
date values with a T-less but otherwise loose grammar. It now lists the
stored format per type: date and time columns as stored, an option id for
selections, true or false for checkboxes, a user, group or team id for
usergroup columns.

Review: #63 r2-m1

Refs nextcloud#3095

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
… filters

contains and does-not-contain on a single selection compare the stored
option id with LIKE, so contains 1 also matched options 10 and 21; they
are refused there now, and a multi selection takes an option id for
every operator. Dates are parsed in UTC so the format check does not
depend on the server's time zone, and a duplicated docblock is gone.

The accepted-filters test now asserts each filter's column, operator and
value instead of their count, and covers long text without an operator.

Review: pre-push check of the #63 round-2 fixes (r2-b1, r2-c1)

Refs nextcloud#3095

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
is-equal on createdAt or updatedAt only matches the exact second, so a
date alone matches midnight. The filter description now says to compare
those fields with is-greater-than and is-lower-than.

Review: pre-push check of the #63 round-2 fixes (r2-m1)

Refs nextcloud#3095

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
Comment thread lib/Service/RowQueryResolver.php Resolved
Comment thread lib/Service/RowQueryResolver.php Resolved
Comment thread lib/Service/RowQueryResolver.php Resolved

@rjzondervan rjzondervan left a comment •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: APPROVE (Strict, round-3 convergence) — self-review posted as COMMENT (GitHub blocks a verdict on your own PR)

All 13 findings from rounds 1 and 2 hold on the code. Round 3 adds no blockers, only 3 🟢 polish items in the new date and selection checks. All 3 are fixed in e226a4d4 and resolved; 0 threads open. No branch rules gate the merge.

Round Found Status
1 (dc19f1f0) 🔴 4 · 🟡 3 · 🟢 3 all 10 resolved (c1, c2 by decision)
2 (9bacf33d) 🔴 1 · 🟡 1 · 🟢 1 all 3 resolved
3 (71cdd255), this review 🟢 3 all 3 resolved in e226a4d4
Finding Was Now Where
🟢 No test fails if the UTC parse in hasStoredFormat is removed new resolved thread
🟢 createdAt/updatedAt refuse an ISO 8601 T that those DATETIME fields compare correctly new resolved thread
🟢 The selection id check accepts leading zeros, which never match a stored id new resolved thread
Details of this round
  • Scope: the 4 fix commits 9bacf33d..71cdd255 (5 files, +80/−17), no merges.
  • Round 2 re-checked: r2-b1 (stored date/time formats per column type, strict round-trip), r2-m1 (time and datetime columns tested) and r2-c1 (value formats documented per type) are each addressed by their Done-when.
  • Verified clean: the round-trip check refuses relative and overflowing dates; meta date fields accept only exact moments; checkbox accepts only true/false; number and id bounds are unchanged.
  • Checks on this head: phpunit 691/691, psalm, cs and rector clean, openapi up to date. Gates: the runner is not available, so the repo's own checks stand in. CI was still queued.
  • Fix commit e226a4d4: phpunit 696/696, psalm, cs and rector clean, openapi regenerated; each new test fails when its fix is removed. The selection check allows id 0, because option ids start at 0.
  • Connected issues: nextcloud#3095 (open); depends on nextcloud#3093 (open, PR nextcloud#3253).

🤖 Generated with Claude Code

createdAt and updatedAt are DATETIME columns, bound as dates, so a T
between date and time compares correctly; accept YYYY-MM-DDTHH:MM and
YYYY-MM-DDTHH:MM:SS next to the space forms.

Selection cells store the bare option id, so 01 never matches; accept
only 0 or an id without leading zeros, up to ten digits.

Pin the UTC parse of date values with a test in Europe/Amsterdam: a
date and time in the daylight saving gap only passes because of it.

Refs nextcloud#3095
Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Robert Zondervan <robert@conduction.nl>
Signed-off-by: Robert Zondervan <robert@conduction.nl>
PHP stores a numeric string key such as a column id as an integer, so
the index of columns by id and technical name has array-key keys, not
string keys. Psalm 7 from main reports the string annotation; look a
column up by its integer id directly.

Refs nextcloud#3095
Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Robert Zondervan <robert@conduction.nl>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

8 participants