Docs on VIEWs

Author: jepett0

ydb/docs/en/core/concepts/datamodel/_includes/index.md

@@ -5,3 +5,4 @@ This section describes the entities that {{ ydb-short-name }} uses within DBs. T
 * [Directory](../dir.md)
 * [Table](../table.md)
 * [Topic](../../topic.md)
+* [View](../view.md)

ydb/docs/en/core/concepts/datamodel/toc_i.yaml

@@ -6,3 +6,4 @@ items:
 - { name: Secrets,                                   href: secrets.md }
 - { name: External tables,                           href: external_table.md }
 - { name: External data source,                      href: external_data_source.md }
+- { name: View,                                      href: view.md }

ydb/docs/en/core/concepts/datamodel/view.md

@@ -0,0 +1,76 @@
+# View
+
+A view is basically a query that is stored in a database which enables you to treat the results of the query as a table. The view itself contains no data. The results of a view are generated every time you select from that view. Any changes in the underlying tables are reflected immediately in the view.
+
+Views are often used to:
+- hide query complexity,
+- limit access to underlaying data*,
+- provide a backward compatible interface to emulate a table that used to exist, but whose schema has changed.
+
+\* The scenario of creating a view to grant other users partial select privileges on a table that has sensitive data is not implemented yet. In {{ ydb-short-name }} view's stored query can only be executed on behalf of the user of the view. A user cannot select from a view that reads from a table that they don't have select privileges from. See `security_invoker` option description on the [CREATE VIEW](../../yql/reference/syntax/create_view.md) page for details.
+
+## Creating a view
+
+See [CREATE VIEW](../../yql/reference/syntax/create_view.md).
+
+## Altering a view
+
+See [ALTER VIEW](../../yql/reference/syntax/alter_view.md).
+
+## Dropping a view
+
+See [DROP VIEW](../../yql/reference/syntax/drop_view.md).
+
+## View invalidation
+
+If you drop a table that the view references, the view will become invalid. The queries through it will fail with an error of referencing a table that does not exist. The dependencies of views on the tables (and other views) are not tracked in any way at the moment. Select from a view is executed in the same manner as a select from a subquery would, without any prior checks of validity. You will know that the view's query became invalid only at the moment of its execution. This is going to change in the future releases. We are going to start tracking view's dependencies and the default behavior for dropping a table would be to forbid it if any view is referencing the table.
+
+## Performance
+
+Users might notice a little increase in the compilation time of the queries made using views compared to the compilation time of the same query, where views are substituted by their queries. It happens due to the fact that a statement reading from a view:
+```sql
+SELECT * FROM a_view;
+```
+is compiled similarly to a statement reading from a subquery:
+```sql
+SELECT * FROM (SELECT * FROM underlying_table);
+```
+but with an additional overhead of loading data from the schema object `a_view`.
+
+Please note that if you execute the same query over and over again like:
+```sql
+-- execute multiple times
+SELECT * FROM hot_view;
+```
+compilation results will be cached on the {{ ydb-short-name }} server and you will not notice any decrease of performance of queries using views.
+
+Execution time of the resulting compiled code for queries using views should always be exactly the same as for the queries directly reading data from the underlying tables.
+
+## View redefinition lag
+
+### Query compilation cache
+{{ ydb-short-name }} caches query compilation results on the server side for efficiency. For small queries like:
+```sql
+SELECT 1;
+```
+compilation can take up to a hundred times more CPU time than the execution. The cache entry is searched by the text of the query and some additional parameters such as a user SID.
+
+The cache is updated by {{ ydb-short-name }} automatically to stay on track with the changes made to the objects that the query references. However, in the case of views the cache is not updated in the same transaction in which the object's definition has changed. It happens with a little delay.
+
+### Problem statement
+
+Imagine the following sitiuation:
+
+Alice continiously executes the following query:
+```sql
+-- Alice's session
+SELECT * FROM some_view_which_is_going_to_be_redefined;
+```
+while Bob redefines the view's query like this:
+```sql
+-- Bob's session
+DROP VIEW some_view_which_is_going_to_be_redefined;
+CREATE VIEW some_view_which_is_going_to_be_redefined ...;
+```
+
+The text of the Alice's query does not change, which means that the compilation will happen only once and the results are going to be taken from the cache since then. Bob changes the definition of the view and the cache entry for the Alice's query should theoretically be evicted from the cache in the same transaction, in which the view was redefined. However, this is not the case. The Alice's query will be recompiled with a little delay, which means that for a small period of time Alice's query will produce results inconsistent with the updated definition of the view. This is going to be fixed in the future releases.

ydb/docs/en/core/yql/reference/yql-core/syntax/alter_view.md

@@ -0,0 +1,13 @@
+# ALTER VIEW
+
+ALTER VIEW — change the definition of a view.
+
+This feature is not supported yet. You can redefine a view like this:
+```sql
+DROP VIEW redifined_view;
+CREATE VIEW redifined_view ...;
+```
+
+## See also
+
+[CREATE VIEW](create_view), [DROP VIEW](drop_view)

ydb/docs/en/core/yql/reference/yql-core/syntax/create_view.md

@@ -0,0 +1,80 @@
+# CREATE VIEW
+
+CREATE VIEW defines a view of a query.
+
+A view is a logical representation of a table formed by the query, specified at the moment of the view's creation. The view does not physically store the table, but runs the query to produce the data whenever the view is selected from.
+
+## Syntax
+
+```sql
+CREATE VIEW name
+[ WITH ( view_option_name [= view_option_value] [, ... ] ) ]
+AS query
+```
+
+### Parameters
+
+* `name`
+
+The name of the view to be created. The name must be distinct from the name of any other schema object.
+* `query`
+
+The SELECT query, which will be used to produce the logical table the view represents.
+
+`WITH ( view_option_name [= view_option_value] [, ... ] )`
+
+This clause specifies optional parameters for a view. The following parameters are supported:
+
+* `security_invoker` (Bool)
+
+This option causes the underlying base relations to be checked against the privileges of the user of the view rather than the view owner.
+
+## Notes
+
+`security_invoker` option must be always set to true, because the default behavior for views is to execute the query on behalf of the view's creator, which is not supported yet.
+
+The execution context of the view's query is different from the enclosing context of the SELECT from the view statement. It does not "see" previously defined PRAGMAs like TablePathPrefix, named expressions, etc. Most importantly, users must specify the tables (or views) they select from in the view's query by their schema-qualified names. You can see in the [examples](#examples) that the absolute path like `/domain/database/path/to/underlying_table` is used to specify the table, from which the view selects. We are going to change the context of the view's query compilation in the next releases.
+
+The only way to specify the columns you want to see in the view is to select them in particular in the view's query. Star (\*) expansions in the view's query happens each time you recompile it. The columns returned by the following statement:
+```sql
+/*
+CREATE VIEW view_with_a_star WITH (security_invoker = TRUE) AS
+    SELECT
+        *
+    FROM `/domain/database/path/to/underlying_table`;
+*/
+
+SELECT * FROM view_with_a_star;
+```
+might change if the columns list of the `underlying_table` changes.
+
+## Examples {#examples}
+
+Create a view that will list only recent series from the series table:
+
+```sql
+CREATE VIEW recent_series WITH (security_invoker = TRUE) AS
+    SELECT
+        *
+    FROM `/domain/database/path/to/series`
+    WHERE
+        release_date > Date("2020-01-01");
+```
+
+Create a view that will list the titles of the first episodes of the recent series:
+
+```sql
+CREATE VIEW recent_series_first_episodes_titles WITH (security_invoker = TRUE) AS
+    SELECT
+        episodes.title AS first_episode
+    FROM `/domain/database/path/to/recent_series`
+        AS recent_series
+    JOIN `/domain/database/path/to/episodes`
+        AS episodes
+    ON recent_series.series_id = episodes.series_id
+    WHERE episodes.season_id = 1 AND episodes.episode_id = 1;
+```
+
+## See also
+
+[ALTER VIEW](alter_view), [DROP VIEW](drop_view)

ydb/docs/en/core/yql/reference/yql-core/syntax/drop_view.md

@@ -0,0 +1,27 @@
+# DROP VIEW
+
+DROP VIEW drops an existing view.
+
+## Syntax
+
+```sql
+DROP VIEW name
+```
+
+### Parameters
+
+* `name`
+
+The name of the view to be deleted.
+
+## Examples
+
+The following command will drop the view named recent_series:
+
+```sql
+DROP VIEW recent_series;
+```
+
+## See also
+
+[CREATE VIEW](create_view), [ALTER VIEW](alter_view)

ydb/docs/en/core/yql/reference/yql-core/syntax/toc_i.yaml

@@ -7,16 +7,19 @@ items:
 - { name: ALTER TABLE,                  href: alter_table.md,                when: feature_map_tables }
 - { name: ALTER TOPIC,                  href: alter_topic.md,                when: feature_topic_control_plane }
 - { name: ALTER USER,                   href: alter-user.md,                 when: feature_user_and_group }
+- { name: ALTER VIEW,                   href: alter_view.md,                 when: feature_view }
 - { name: CREATE GROUP,                 href: create-group.md,               when: feature_user_and_group }
 - { name: CREATE TABLE,                 href: create_table.md }
 - { name: CREATE TOPIC,                 href: create_topic.md,               when: feature_topic_control_plane }
 - { name: CREATE USER,                  href: create-user.md,                when: feature_user_and_group }
+- { name: CREATE VIEW,                  href: create_view.md,                when: feature_view }
 - { name: DECLARE,                      href: declare.md }
 - { name: DELETE,                       href: delete.md,                     when: feature_map_tables }
 - { name: DISCARD,                      href: discard.md }
 - { name: DROP GROUP,                   href: drop-group.md,                 when: feature_user_and_group }
 - { name: DROP TABLE,                   href: drop_table.md }
 - { name: DROP USER,                    href: drop-user.md,                  when: feature_user_and_group }
+- { name: DROP VIEW,                    href: drop_view.md,                  when: feature_view }
 - { name: GROUP BY,                     href: group_by.md }
 - { name: EXPORT and IMPORT,            href: export_import.md,              when: feature_mapreduce }
 - { name: FLATTEN,                      href: flatten.md }

ydb/docs/presets.yaml

@@ -19,6 +19,7 @@ default:
   feature_federated_queries: true
 #  feature_topic_settings_reset: true
 #  feature_logbroker: true
+  feature_view: true
   ydb-full-name: YDB
   ydb-short-name: YDB
   yandex-cloud: Yandex.Cloud

ydb/docs/ru/core/concepts/datamodel/_includes/index.md

@@ -8,3 +8,4 @@
 * [Секреты](../secrets.md)
 * [Подключения к внешним БД](../external_data_source.md)
 * [Внешние источники данных](../external_table.md)
+* [Представления (VIEW)](../view.md)

ydb/docs/ru/core/concepts/datamodel/toc_i.yaml

@@ -6,3 +6,4 @@ items:
 - { name: Секреты,                                href: secrets.md }
 - { name: Внешние источники данных,               href: external_data_source.md }
 - { name: Внешние таблицы,                        href: external_table.md }
+- { name: Представления,                          href: view.md }