YQL-19864 docs

commit_hash:cc82995d04c8bd3b7ca4d6fe69e91edc092e1b32

Author: vitstn

yql/essentials/data/language/pragmas_opensource.json

@@ -0,0 +1 @@
+This initial version contains all features as of early 2025.

yql/essentials/docs/en/changelog/2025.01.md

@@ -0,0 +1,29 @@
+## Changing the visibility of aliases entered in GROUP BY expr AS alias for WHERE {#group-by-expr-alias-where}
+
+Since this version, in a query like
+
+```yql
+SELECT foo, ... WHERE foo = 1 GROUP BY expr AS foo
+```
+
+the value of foo in `WHERE` is taken from the original table, and not equal to `expr` as it was previously.
+
+To get an error from the query if it changes behavior in this version, you need to add
+
+```yql
+PRAGMA FailOnGroupByExprOverride;
+```
+
+If you want to keep the previous behavior, you need to transform the query into this form:
+
+```yql
+SELECT foo, ... FROM (SELECT expr AS foo ...) WHERE foo = 1 GROUP BY foo
+```
+
+If you need to prepare the query for the transition to a new version, it is enough to remove the shadowing of the column name by the alias:
+
+```yql
+SELECT foo_new, ... WHERE foo = 1 GROUP BY expr AS foo_new
+```
+
+## TODO

yql/essentials/docs/en/changelog/2025.02.md

@@ -0,0 +1,27 @@
+## Changes in YQL versions
+
+This section contains a list of changes in different versions of the YQL
+
+## General description of YQL versions
+
+The goal of language versioning is a controlled and user-safe evolution of the language, within which it is possible to:
+
+* add new features;
+
+* change default values ​​for pragmas or perform other non-backward-compatible changes;
+
+* remove obsolete features.
+
+The starting version of the language is `2025.01`.
+
+Once a year, a new version of the language is released, called `YEAR.X`, for example `2025.01`. Other versions in the same year will increase the minor version number (`YEAR.02`, etc.).
+
+For each version of the type `YEAR.X` **support is guaranteed for three years with the preservation of semantics and bug fixes**.
+
+When version `YEAR+2.1` is released, a warning is issued for all versions of the type `YEAR.X` that they will soon cease to be supported.
+
+When version `YEAR+3.1` is released, a warning is issued for all versions of the type `YEAR.X` that they are not supported and query execution is not guaranteed.
+
+When specifying a version of `YEAR.X` greater than what is currently available in some service/library/tool, a query error is issued.
+
+When each version is released, the documentation in the changelog indicates the changes included in this version and recommendations for migration.

yql/essentials/docs/en/changelog/index.md

@@ -0,0 +1,7 @@
+items:
+- name: Overview
+  href: index.md
+- name: 2025.01
+  href: 2025.01.md
+- name: 2025.02
+  href: 2025.02.md

yql/essentials/docs/en/changelog/toc_i.yaml

@@ -8,3 +8,4 @@ This documentation section contains the YQL reference that includes the sections
 - [Syntax](syntax/index.md) with a full list of YQL commands
 - [Built-in functions](builtins/index.md) with a description of the available built-in functions
 - [Recipes](recipes/index.md) with a description of recipes for various tasks
+- [Changelog](changelog/index.md) of YQL

yql/essentials/docs/en/index.md

@@ -24,7 +24,7 @@ The `SELECT` query result is calculated as follows:
 * Apply [SAMPLE](sample.md)/[TABLESAMPLE](sample.md) to input tables.
 * Execute [FLATTEN COLUMNS](../flatten.md#flatten-columns) or [FLATTEN BY](../flatten.md); aliases set in `FLATTEN BY` become visible after this point.
 * Execute every [JOIN](../join.md).
-* Add to (or replace in) the data the columns listed in [GROUP BY ... AS ...](../group_by.md).
+* Add to (or replace in) the data the columns listed in [GROUP BY ... AS ...](../group_by.md) (this clause executes after `WHERE` since version [2025.02](../../changelog/2025.02.md#group-by-expr-alias-where)).
 * Execute [WHERE](where.md) - discard all the data mismatching the predicate.
 * Execute [GROUP BY](../group_by.md), evaluate aggregate functions.
 * Apply the filter [HAVING](../group_by.md#having).

yql/essentials/docs/en/syntax/select/index.md

@@ -7,3 +7,5 @@ items:
   include: { mode: link, path: builtins/toc_i.yaml }
 - name: Recipes
   include: { mode: link, path: recipes/toc_i.yaml }
+- name: Changelog
+  include: { mode: link, path: changelog/toc_i.yaml }

yql/essentials/docs/en/toc_i.yaml

@@ -0,0 +1 @@
+Эта стартовая версия содержит все фичи на начало 2025 года.

yql/essentials/docs/ru/changelog/2025.01.md

@@ -0,0 +1,29 @@
+## Изменение видимости алиасов, введенных в GROUP BY expr AS alias для WHERE {#group-by-expr-alias-where}
+
+Начиная с этой версии в запросе вида
+
+```yql
+SELECT foo, ... WHERE foo = 1 GROUP BY expr AS foo
+```
+
+значение foo в `WHERE` берется из исходной таблицы, а не равно `expr`, как было ранее.
+
+Чтобы получить ошибку запроса, если он изменит поведение в этой версии, необходимо добавить
+
+```yql
+PRAGMA FailOnGroupByExprOverride;
+```
+
+Если необходимо сохранить предыдущее поведение, запрос нужно преобразовать в такую форму:
+
+```yql
+SELECT foo, ... FROM (SELECT expr AS foo ...) WHERE foo = 1 GROUP BY foo
+```
+
+Если нужно подготовить запрос к переходу на новую версию, достаточно убрать затенение alias-ом имени колонки:
+
+```yql
+SELECT foo_new, ... WHERE foo = 1 GROUP BY expr AS foo_new
+```
+
+## TODO