Skip to content

docs: materialized view column types and limitations (engine 0.25.0) - #464

Merged
fupelaqu merged 1 commit into
mainfrom
docs/schema-8-views
Nov 15, 2026
Merged

fupelaqu merged 1 commit into
mainfrom
docs/schema-8-views

Conversation

@fupelaqu

Copy link
Copy Markdown
Contributor

Summary

The materialized-view engine now builds on engine 0.25.0. This PR documents what changes for a view, and the limitations measured while verifying it, on documentation/sql/materialized_views.md, with one pointer on operators.md. The web twin goes into the open web documentation PR for 0.25.0.

What changes

  • New "Column types" section.
    • A view declares each column of its SELECT list with the type a query of its definition reports, table by table over a JOIN.
    • Two exceptions: a KEYWORD or TEXT source column keeps its mapping type, and a computed column keeps the type its script writes.
    • A DATEDIFF per-group calculation is now BIGINT.
    • DESCRIBE MATERIALIZED VIEW reports the declared types, while a query over the view reports a query's types.
    • The view's WHERE, HAVING and per-group calculations are typed as in a query, so b = n and b <> n (a BOOLEAN column against a number column) are now answered.
    • Upgrade note: a view created before 0.25.0 keeps its types until DROP + CREATE.
  • DESCRIBE MATERIALIZED VIEW example replaced with the real output for the page's example view. The previous example was already wrong: customer_zip is KEYWORD, customer_name_upper is VARCHAR, effective_date is DATE. The real output has 13 rows, including the keyword sub-fields, the columns the view's stages read, and _last_updated.
  • SUM column type (BIGINT over integers, DOUBLE over REAL / DOUBLE): the web page already said this, and the core page did not.
  • Three Limitations rows:
    • a text compared with a number by a script (a computed column, a GROUP BY key, WHERE k = n) is still refused at creation with HTTP 400, although a query answers it since 0.25.0;
    • WHERE YEAR(created_at) = 2024 creates the view, but it stores no rows;
    • COALESCE over a DATE compared with a string, and WHERE b > 0 over a BOOLEAN, fail at creation with HTTP 500.
  • operators.md: "the boolean rows apply everywhere" now names the b > 0 exception in a view's WHERE.

Evidence

Every statement comes from runs on Elasticsearch 8.x of the materialized-view integration suites and of probes run on both engine versions, with DuckDB as a third reference. The DESCRIBE table is copied from a real run. The ES-dependent limitation rows say "measured on Elasticsearch 8.x", because no other major was measured. An independent review checked every statement against those runs, and its findings are applied.

Recorded, not fixed

  • Some view definitions are refused with HTTP 500 "Columns without lineage in …". For example, a single-table view grouped by a column that computes SUM or AVG is refused, while one grouped by an expression is created, and so are single-table computed columns. The rule has not been characterized, so the page does not describe it yet. Some single-table HAVING examples on this page have the shape of a refused body.

🤖 Generated with Claude Code

A view now declares its columns with the types a query of its definition
reports (KEYWORD/TEXT and computed columns keep theirs), and reads its WHERE,
HAVING and calculations with the source types. Document that, the real
DESCRIBE MATERIALIZED VIEW output, the SUM column type the web page already
carried, and three limitations measured on Elasticsearch 8.x; point the
boolean rows of operators.md at the view exception.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fupelaqu
fupelaqu marked this pull request as ready for review November 15, 2026 08:00
@fupelaqu
fupelaqu merged commit 05e79a6 into main Nov 15, 2026
4 checks passed
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.

1 participant