lisancao opened a new pull request, #59651:
URL: https://github.com/apache/spark/pull/59651
### What changes were proposed in this pull request?
Docs for metric views, which have been in Spark since 4.2.0 (`CREATE VIEW
... WITH METRICS LANGUAGE YAML` and `MEASURE()`) with no page describing them.
Two new pages plus cross-links:
**`metric-views-programming-guide.md`**, in the Programming Guides dropdown
next to Declarative Pipelines. Rough outline:
- what a metric view is, and why a measure is evaluated at the grain of the
query that asks for it (distinct counts and ratios are the motivating cases)
- quick start: a table, a view over it, the same measures at three grains
- key concepts: source, dimensions, measures, filter, grain, with `EXPLAIN`
showing the rewrite
- defining views in SQL: a table source, a SQL source with a filter, column
names, comments and properties
- querying from SQL, from the DataFrame API (`F.expr("MEASURE(...)")`,
`selectExpr`), and from BI/JDBC clients
- modeling patterns: ratios as single measures, date dimensions, derived
dimensions in a SQL source, a metric view over a metric view
- lifecycle (inspect, change, rename, drop) and a short list of what is not
supported
**`sql-ref-syntax-ddl-create-metric-view.md`**, in the shape of the other
DDL reference pages: Description, Syntax, Parameters (including the v0.1 YAML
keys), Examples, Related Statements.
Cross-links from the DDL list in `sql-ref-syntax.md`, from `CREATE VIEW`,
`ALTER VIEW` and `SHOW CREATE TABLE`, and a `MEASURE` section on the aggregate
functions page.
One thing to flag for reviewers: the `OR REPLACE` text describes what master
does today (V2 catalogs replace an existing metric view, the session catalog
rejects it). #59386 changes the session catalog; if that lands first I will
update the wording here.
### Why are the changes needed?
There is no documentation for the statement, the YAML format, how
`MEASURE()` is evaluated, or how to model and query a metric view. The only
mention of `MEASURE` in the docs is the generated built-in function entry.
### Does this PR introduce _any_ user-facing change?
Docs only.
### How was this patch tested?
Every statement on both pages was run against the Spark 4.3.0 RC2
distribution and the output shown is what it produced. Docs built with
`SKIP_API=1 SKIP_SCALADOC=1 SKIP_PYTHONDOC=1 SKIP_RDOC=1 SKIP_SQLDOC=1
SKIP_ERRORDOC=1 bundle exec jekyll build`; the two pages, their anchors, the
dropdown entry and the cross-links checked in `_site/`.
### Was this patch authored or co-authored using generative AI tooling?
Generated-by: Claude Code. All examples were run by hand as described above.
--
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]
