mikebridge opened a new pull request, #45903: URL: https://github.com/apache/superset/pull/45903
### SUMMARY **TL;DR.** The semantic-layer SDK now says in plain terms what a row count and a list of filter suggestions mean. A row count is the number of rows in the requested window, after offset and limit, and never the total of the whole result or a count of the underlying facts. A list of distinct values proves one of three things, complete, known more, or unknown, and nothing is read into how long it is. Both rules are docstring text on the existing `SemanticView` methods and the `SemanticQuery` and `SemanticResult` types. No provider or host behaviour changes in this PR. **Background.** `SemanticView` is the base class every semantic-layer provider implements. Its docstrings already fix the rules providers must agree on: member identity, grain variants, NULL handling in filters, and ordering before limit. They also require a provider to raise `SemanticResultCompletenessError` instead of returning a partial result. What they did not say is what a count counts and what a value list proves. Providers answered those questions differently: some count the rows the query would return after offset and limit, one reports the unrestricted total, and two apply a hard-coded ceiling to value lists without saying so. The host cannot tell these apart, so a paged table can show the wrong total and a capped suggestion list can look exhaustive. **Problem.** The SDK is about to be versioned. Tagging it with the meaning of counts and value lists left open would force a deprecation cycle once providers are aligned. The rules have been settled; this PR writes them into the SDK so the first tag carries them, while the provider alignment itself lands separately. **Changes.** - `SemanticQuery` gains a "What a count counts" section: the *matching result* (rows at the requested grain after filters, grouping and group limit) and the *requested result window* (that result ordered, then offset and limit applied). A row count is the size of the window, with the worked example 123 rows / limit 50 / offset 100 → 23, and 10,000 facts aggregating to 12 groups → 12. A count validates the same query shape as `get_table` and never widens what may be asked. - `SemanticResult` gains "Count results" and "Value lists" sections. A count is one row with one integer column, read from that cell rather than by column name; an empty window is the cell `0`; an inexact count is an error rather than an estimate, a page length or a stand-in zero. A value list's completeness evidence is complete, known more or unknown. The type carries no evidence field: the provider's obligation comes from the entry point, while a consumer may treat a list as complete only on explicit evidence. An ordered prefix is a separate claim that needs a deterministic order, NULL placement and ties stated, applied before any cut. Nothing is inferred from the list's length, including an empty list of unknown completeness, and evidence belongs to one observation, promising no snapshot across requests. - `SemanticView.get_row_count` says to count the requested result window under `get_table`'s validation of the query's shape (order aside), return the one-cell shape, never return the unrestricted total for a windowed query, and raise the existing completeness error (incomplete or unverified) when the count cannot be established exactly. - `SemanticView.get_values` says the result is the whole distinct domain under the filters, that a ceiling of the provider's own is not a bound the caller asked for and makes a possibly-cut result unverified, that this signature carries no bound so a bounded suggestion must not be improvised by truncating silently, and that values come in no promised order unless the provider documents a deterministic one applied before any cut. - The `SemanticView` class docstring lists "Counts and value lists" among the rules the host relies on. ### BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF Not applicable: docstring text only. ### TESTING INSTRUCTIONS Read the four docstrings. `pytest superset-core/tests/semantic_layers` passes unchanged (81 passed, 4 skipped), and the changed-file pre-commit hooks (ruff, ruff-format, mypy, pylint) are green. No behaviour changes, so no new tests. ### ADDITIONAL INFORMATION - [ ] Has associated issue: - [ ] Required feature flags: - [ ] Changes UI - [ ] Includes DB Migration (follow approval process in [SIP-59](https://github.com/apache/superset/issues/13351)) - [ ] Migration is atomic, supports rollback & is backwards-compatible - [ ] Confirm DB migration upgrade and downgrade tested - [ ] Runtime estimates and downtime expectations provided - [ ] Introduces new feature or API - [ ] Removes existing feature or API -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
