Add CREATE VIEW documentation (#4208)

Adds a `CREATE VIEW` reference page to the Sphinx docs, covering syntax,
parameters, examples (basic, nested, join, CTE, forward references,
indexes on views), and limitations.

Also updates `TABLE`, `FUNCTION`, `INDEX`, and `SCHEMA_TEMPLATE` pages
with cross-references, and fixes the misplaced `..
_create-schema-template:` label that caused broken `ref` warnings.

Author: arnaud-lacurie

docs/sphinx/source/reference/sql_commands/DDL/CREATE.rst

@@ -13,3 +13,4 @@ CREATE
     CREATE/INDEX
     CREATE/FUNCTION
     CREATE/TEMPORARY_FUNCTION
+    CREATE/VIEW

docs/sphinx/source/reference/sql_commands/DDL/CREATE/FUNCTION.rst

@@ -308,3 +308,4 @@ See Also
 
 * :ref:`Subqueries <subqueries>` - Using functions in subqueries
 * :ref:`Joins <joins>` - Using functions in join operations
+* :ref:`CREATE VIEW <create-view>` - Views: reusable queries without parameters

docs/sphinx/source/reference/sql_commands/DDL/CREATE/INDEX.rst

@@ -279,6 +279,8 @@ ORDER BY clause:
 - Expressions in GROUP BY are supported
 - WHERE clauses can be used with aggregate indexes for filtered aggregates
 
+.. _index-on-syntax:
+
 INDEX ON Syntax
 ===============
 
@@ -361,6 +363,21 @@ First define a view with the filter:
 
     CREATE INDEX idx_expensive_products ON v_expensive_products(price)
 
+**Index on View (Array Unnesting)**
+
+A common pattern is to create a view that unnests an array column, then index the result. This creates a self-contained schema template with the table, view, and index together:
+
+.. code-block:: sql
+
+    CREATE SCHEMA TEMPLATE my_template
+        CREATE TABLE products (
+            id      BIGINT,
+            tags    STRING ARRAY,
+            PRIMARY KEY(id))
+        CREATE VIEW product_tags AS
+            SELECT SQ.tag FROM products AS p, (SELECT tag FROM p.tags AS tag) AS SQ
+        CREATE INDEX idx_tags ON product_tags (tag)
+
 **Custom Ordering**
 
 .. code-block:: sql

docs/sphinx/source/reference/sql_commands/DDL/CREATE/SCHEMA_TEMPLATE.rst

@@ -1,12 +1,12 @@
+.. _create-schema-template:
+
 ======================
 CREATE SCHEMA TEMPLATE
 ======================
 
-.. _create-schema-template:
-
-A schema template is a predefined structure that defines the set of ``TABLE`` and ``INDEX`` definitions. This can then
-used as a blueprint to create ``SCHEMA`` in a database. See: :doc:`../../../Databases_Schemas_SchemaTemplates` for more
-information.
+A schema template is a predefined structure that defines a set of ``TABLE``, ``INDEX``, ``VIEW``, ``TYPE``, and
+``FUNCTION`` definitions. It can then be used as a blueprint to create ``SCHEMA`` instances in a database.
+See: :doc:`../../../Databases_Schemas_SchemaTemplates` for more information.
 
 Syntax
 ======

docs/sphinx/source/reference/sql_commands/DDL/CREATE/TABLE.rst

@@ -109,3 +109,9 @@ Attempting to insert a second row in a :sql:`SINGLE ROW ONLY` table will result
     * - :sql:`NULL`
       - :json:`0.0`
       - :json:`"X"`
+
+See Also
+========
+
+* :ref:`CREATE VIEW <create-view>` — Virtual (non-materialized) tables defined by a query
+* :doc:`INDEX` — Defining indexes on tables and views

docs/sphinx/source/reference/sql_commands/DDL/CREATE/VIEW.diagram

@@ -0,0 +1,9 @@
+Diagram(
+    Sequence(
+        Terminal('CREATE'),
+        Terminal('VIEW'),
+        NonTerminal('viewName'),
+        Terminal('AS'),
+        NonTerminal('query')
+    )
+)

docs/sphinx/source/reference/sql_commands/DDL/CREATE/VIEW.rst

@@ -0,0 +1,140 @@
+===========
+CREATE VIEW
+===========
+
+.. _create-view:
+
+Clause in a :ref:`schema template definition <create-schema-template>` to create a non-materialized view. A view is a virtual table whose contents are defined by a SQL query. Views do not store data themselves; each query against a view executes the underlying query against the base tables. Views are read-only and cannot be the target of ``INSERT``, ``UPDATE``, or ``DELETE`` statements. ``CREATE VIEW`` is a clause within a schema template and cannot be a standalone statement. View names must not collide with table, type, or function names in the same schema template.
+
+Syntax
+======
+
+.. raw:: html
+    :file: VIEW.diagram.svg
+
+Parameters
+==========
+
+``viewName``
+    The name of the view. Must be unique within the schema template — cannot collide with table, type, or other view names.
+
+``query``
+    The SQL ``SELECT`` statement that defines the view. The query can reference tables, other views, and functions defined in the same schema template.
+
+Examples
+========
+
+Setup
+-----
+
+``CREATE VIEW`` must appear inside a :ref:`schema template <create-schema-template>` definition and cannot be a standalone statement. For the examples on this page, assume the following schema template:
+
+.. code-block:: sql
+
+    CREATE SCHEMA TEMPLATE my_template
+        CREATE TABLE employees (
+            id       BIGINT,
+            name     STRING,
+            dept     STRING,
+            salary   BIGINT,
+            PRIMARY KEY(id))
+
+Basic View
+----------
+
+Create a view that filters rows from a base table:
+
+.. code-block:: sql
+
+    CREATE VIEW engineering AS
+        SELECT id, name, salary
+        FROM employees
+        WHERE dept = 'Engineering'
+
+Query the view like a table:
+
+.. code-block:: sql
+
+    SELECT * FROM engineering
+
+.. list-table::
+    :header-rows: 1
+
+    * - :sql:`id`
+      - :sql:`name`
+      - :sql:`salary`
+    * - :json:`1`
+      - :json:`"Alice"`
+      - :json:`100000`
+    * - :json:`2`
+      - :json:`"Bob"`
+      - :json:`110000`
+
+Nested Views
+------------
+
+Views can reference other views. The following creates a second view on top of the first:
+
+.. code-block:: sql
+
+    CREATE VIEW engineering AS
+        SELECT id, name, salary
+        FROM employees
+        WHERE dept = 'Engineering'
+
+    CREATE VIEW high_earners AS
+        SELECT id, name
+        FROM engineering
+        WHERE salary > 100000
+
+.. code-block:: sql
+
+    SELECT * FROM high_earners
+
+.. list-table::
+    :header-rows: 1
+
+    * - :sql:`id`
+      - :sql:`name`
+    * - :json:`2`
+      - :json:`"Bob"`
+
+View with JOIN
+--------------
+
+Views support joins, including self-joins (see :ref:`inner_join` for join syntax):
+
+.. code-block:: sql
+
+    CREATE VIEW peer_pairs AS
+        SELECT A.name AS emp1, B.name AS emp2
+        FROM employees A, employees B
+        WHERE A.dept = B.dept AND A.id < B.id
+
+View with CTE
+-------------
+
+Views can use Common Table Expressions (see :doc:`WITH` for CTE syntax):
+
+.. code-block:: sql
+
+    CREATE VIEW senior_engineering AS
+        WITH filtered AS (
+            SELECT id, name, salary
+            FROM employees
+            WHERE dept = 'Engineering' AND salary > 100000
+        )
+        SELECT * FROM filtered
+
+Indexes on Views
+----------------
+
+Indexes can be defined on views using the standard ``CREATE INDEX`` syntax. For a self-contained example including array unnesting, see :ref:`index-on-syntax` in :doc:`INDEX`.
+
+See Also
+========
+
+* :ref:`create-schema-template` — Schema templates and their clauses
+* :doc:`TABLE` — Defining tables within a schema template
+* :doc:`INDEX` — Defining indexes, including :ref:`index-on-syntax` for indexes on views
+* :doc:`FUNCTION` — User-defined functions