docs: correct view listing cost and say what an expression may use

Two pages said list_materialized_views reads every table's schema and
that SHOW MATERIALIZED VIEWS is cheaper. That is the local
implementation; on a db:// connection the SDK asks the deployment for
its views, as SHOW MATERIALIZED VIEWS does.

The computed-column page now says that a literal must fit the column it
meets, and that a deployment's refresh can fail on an expression reading
a struct field, which the embedded library computes, so an expression
for a deployment should use top-level columns.
This commit is contained in:
Brendan Clement
2026-10-09 13:42:32 -07:00
parent d0ed4d1a7a
commit e920dad55b
3 changed files with 16 additions and 5 deletions
@@ -69,6 +69,16 @@ declared earlier in the same mapping, but not one declared after it.
The functions available are the ones the
[SQL dialect](/sql/functions) documents.
A literal in the expression has to fit the column it meets: `x / 2.0` is
refused when `x` is an integer column, so write `cast(x as double) / 2.0`.
<Warning>
On a deployment, keep the expression to top-level columns. A deployment's
refresh can fail on an expression that reads a field inside a struct, such as
`stats.magic + stats.strength`, which the embedded library computes. Try a new
expression on a small table first.
</Warning>
## Its inputs become load-bearing {#input-constraints}
<Warning>
@@ -110,9 +110,10 @@ when a view is created through its REST API, which recent versions no longer
have. Check with the deployment's administrator which version it runs before
relying on a source.
`SHOW MATERIALIZED VIEWS` lists them, which is cheaper than
`list_materialized_views` -- that method finds views by reading every table's
schema, so it costs one open per table.
`list_materialized_views` asks the deployment for its views, as
[`SHOW MATERIALIZED VIEWS`](/sql/ddl/materialized-view#show) does. On a local
database the same method opens each table to read its schema, so it costs one
open per table.
## Working with the view {#working-with-the-view}
+2 -2
View File
@@ -36,8 +36,8 @@ SHOW MATERIALIZED VIEWS
```
<Note>
Cheaper than the SDK equivalent. `list_materialized_views` finds views by
reading every table's schema, costing one open per table; this asks the server.
This asks the server for its views, as the SDK's `list_materialized_views` does
on a `db://` connection.
</Note>
## Refreshing one {#refresh}