JanKaul commented on code in PR #11041:
URL: https://github.com/apache/iceberg/pull/11041#discussion_r4122229952
##########
format/view-spec.md:
##########
@@ -322,3 +454,201 @@
s3://bucket/warehouse/default.db/event_agg/metadata/00002-(uuid).metadata.json
} ]
}
```
+
+### Materialized View Example
+
+Imagine the following operation, which creates a materialized view that
precomputes daily event counts:
+
+```sql
+USE prod.default
+```
+
+```sql
+CREATE MATERIALIZED VIEW event_agg_mv (
+ event_count COMMENT 'Count of events',
+ event_date)
+COMMENT 'Precomputed daily event counts'
+AS
+SELECT
+ COUNT(1), CAST(event_ts AS DATE)
+FROM events
+GROUP BY 2
+```
+
+The materialized view metadata JSON file looks as follows:
+
+```
+s3://bucket/warehouse/default.db/event_agg_mv/metadata/00001-(uuid).metadata.json
+```
+
+```json
+{
+ "view-uuid": "b2a12651-3038-4a72-8a31-5027ab84da35",
+ "format-version" : 1,
+ "location" : "s3://bucket/warehouse/default.db/event_agg_mv",
+ "current-version-id" : 1,
+ "properties" : {
+ "comment" : "Precomputed daily event counts"
+ },
+ "versions" : [ {
+ "version-id" : 1,
+ "timestamp-ms" : 1573518431292,
+ "schema-id" : 1,
+ "default-catalog" : "prod",
+ "default-namespace" : [ "default" ],
+ "summary" : {
+ "engine-name" : "Spark",
+ "engine-version" : "3.4.1"
+ },
+ "representations" : [ {
+ "type" : "sql",
+ "sql" : "SELECT\n COUNT(1), CAST(event_ts AS DATE)\nFROM
events\nGROUP BY 2",
+ "dialect" : "spark"
+ } ],
+ "storage-table" : {
+ "namespace" : [ "default" ],
+ "name" : "event_agg_mv__storage"
+ }
+ } ],
+ "schemas": [ {
+ "schema-id": 1,
+ "type" : "struct",
+ "fields" : [ {
+ "id" : 1,
+ "name" : "event_count",
+ "required" : false,
+ "type" : "int",
+ "doc" : "Count of events"
+ }, {
+ "id" : 2,
+ "name" : "event_date",
+ "required" : false,
+ "type" : "date"
+ } ]
+ } ],
+ "version-log" : [ {
+ "timestamp-ms" : 1573518431292,
+ "version-id" : 1
+ } ]
+}
+```
+
+After a refresh operation, the storage table's snapshot summary contains the
`refresh-state` property.
+The following is an example of the `refresh-state` JSON value stored in the
snapshot summary of the storage table:
+
+```json
+{
+ "view-version-id" : 1,
+ "refresh-start-timestamp-ms" : 1573518435000,
+ "source-states" : [ {
+ "type" : "table",
+ "catalog" : "prod",
+ "namespace" : [ "default" ],
+ "name" : "events",
+ "uuid" : "d4a10b5c-1e8a-4b72-9d67-3f4a8c9e1b2d",
+ "snapshot-id" : 6148331192489823102
+ } ]
+}
+```
+
+## Appendix B: Example strategies for selecting dependencies
+
+Producers may select different sets of dependencies to record in the refresh
state. The strategies below illustrate common choices against the same shared
query.
+
+### Shared query
+
+* `A` (the materialized view being refreshed): `SELECT ... FROM B JOIN C ON
...`
+* `B` (regular view): `SELECT ... FROM E JOIN D ON ...`
+* `C` (materialized view): `SELECT ... FROM F JOIN G ON ...`
+* `D` (materialized view): `SELECT ... FROM H WHERE ...`
+* `E`, `F`, `G`, `H`: source Iceberg tables
+
+### Strategy 1: Empty refresh state (recency only)
+
+The producer leaves `source-states` empty and relies entirely on
`refresh-start-timestamp-ms`. Consumers reuse the storage table based on a
recency policy alone.
+
+`A`'s refresh state:
+
+```json
+{
+ "view-version-id": 1,
+ "refresh-start-timestamp-ms": 1573518435000,
+ "source-states": []
+}
+```
+
+### Strategy 2: Treat nested materialized views as tables
+
+Same as Strategy 1, but the query reads from materialized views. The producer
stops at each MV boundary and records the MV's storage table snapshot ID and
view version ID. No expansion beyond the MV.
+
+`C` and `D` are materialized views, treated as tables.
+
+```
+A [MV — being refreshed]
+├── B [VIEW] <-- recorded in A: version-id: 5
+│ ├── E [TABLE] <-- recorded in A: snapshot-id: 101
+│ └── D [MV] <-- recorded in A: storage-table
snapshot-id: 14, version-id: 9
+│ ┄┄┄┄┄┄ recursive boundary ┄┄┄┄┄┄
+│ └── H [TABLE] (D's dependency; verified via D's
refresh-state)
+└── C [MV] <-- recorded in A: storage-table
snapshot-id: 12, version-id: 7
+ ┄┄┄┄┄┄ recursive boundary ┄┄┄┄┄┄
+ ├── F [TABLE] (C's dependency; verified via C's
refresh-state)
+ └── G [TABLE] (C's dependency; verified via C's
refresh-state)
+```
+
+`F`, `G`, and `H` do not appear in `A`'s `source-states`; they belong to `C`
and `D`'s dependency graphs.
+
+### Strategy 3: Treat nested materialized views as views
+
+Same as Strategy 1, but the query reads from materialized views. The producer
treats each materialized view as a regular view: expand through the MV's view
definition and record the underlying tables and views. The MV's storage table
snapshot ID is **not** recorded.
+
+`C` and `D` are materialized views, treated as views (expanded).
+
+```
+A [MV — being refreshed]
+├── B [VIEW] <-- recorded in A: version-id: 5
+│ ├── E [TABLE] <-- recorded in A: snapshot-id: 101
+│ └── D [MV — expanded as view] <-- recorded in A: version-id: 9
+│ └── H [TABLE] <-- recorded in A: snapshot-id: 104
+└── C [MV — expanded as view] <-- recorded in A: version-id: 7
+ ├── F [TABLE] <-- recorded in A: snapshot-id: 102
+ └── G [TABLE] <-- recorded in A: snapshot-id: 103
+```
+
+The recorded shape matches Strategy 1. The difference is semantic: `C` and `D`
are materialized views whose view definitions were expanded; their storage
tables are not part of the recorded state.
+
+### Strategy 4: Track only view versions
+
+The producer treats the storage table as reusable as long as the view
definitions in the dependency chain are unchanged. Underlying table changes do
not affect freshness. Only view version IDs are recorded.
+
+`C` and `D` are regular views.
+
+```
+A [MV — being refreshed]
+├── B [VIEW] <-- recorded in A: version-id: 5
+│ ├── E [TABLE] (not recorded)
+│ └── D [VIEW] <-- recorded in A: version-id: 9
+│ └── H [TABLE] (not recorded)
+└── C [VIEW] <-- recorded in A: version-id: 7
+ ├── F [TABLE] (not recorded)
+ └── G [TABLE] (not recorded)
+```
+
+Snapshots of `E`, `F`, `G`, `H` are not recorded. Reuse is sensitive to
view-definition changes but insensitive to data changes in the underlying
tables.
+
+### Strategy 5: Skip non-Iceberg dependencies
+
+The producer records only Iceberg sources and omits non-Iceberg dependencies
entirely. Useful when the view query reads from a mix of Iceberg and
non-Iceberg sources and the producer chooses to track only the Iceberg side.
+
+Assume the query reads from source Iceberg tables `E`, `F`, `G`, `H` and an
additional non-Iceberg table `N`.
+
+```
+A [MV — being refreshed]
+├── E [TABLE] <-- recorded in A: snapshot-id: 101
+├── F [TABLE] <-- recorded in A: snapshot-id: 102
+├── G [TABLE] <-- recorded in A: snapshot-id: 103
+├── H [TABLE] <-- recorded in A: snapshot-id: 104
+└── N [NON-ICEBERG TABLE] (omitted; not tracked)
+```
+
+`N` is omitted. Consumers cannot verify `N`'s state from the refresh state
alone, but know that the data queried from `N` cannot be older than
`refresh-start-timestamp-ms`.
Review Comment:
The difference between the current version and your suggestion is that the
current version only applies to producers of the `refresh-state`. It only
provides strategies on how to populate the entries.
Your suggestion introduces the term "serving policy" and applies to
producers and consumers alike. To me it looks very similar to the discussion we
had about "freshness interpretation", where different engines could also have
different interpretations of. I'm not sure if introducing and **agreeing** on
the term "serving policy" will go down the same route as the "freshness" term.
--
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]
