YQL-20339 doc

commit_hash:a8c9013fd0fcaee84d3025dddc931ad1b0b547a3

7 files changed, 652 insertions, 0 deletions

diff --git a/yql/essentials/docs/en/builtins/basic.md b/yql/essentials/docs/en/builtins/basic.md
index 3a692edbcfc..994387eaf57 100644
--- a/yql/essentials/docs/en/builtins/basic.md
+++ b/yql/essentials/docs/en/builtins/basic.md
@@ -913,6 +913,50 @@ A typical example of a `SemilatticeRT` side effect is to perform an `UPSERT` to
 SELECT WithSideEffects(MyModule::Func(...)) FROM table
 ```
 
+## ToDynamicLinear
+
+#### Signature
+
+```yql
+ToDynamicLinear(Linear<T>)->DynamicLinear<T>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+The `ToDynamicLinear` function converts a value from a static [linear](../types/linear.md) type to a dynamic type.
+
+## FromDynamicLinear
+
+#### Signature
+
+```yql
+FromDynamicLinear(DynamicLinear<T>)->Linear<T>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+The `FromDynamicLinear` function converts a value from a dynamic [linear](../types/linear.md) type to a static type.
+
+## Block
+
+#### Signature
+
+```yql
+Block(lambda((dependsOnArgument)->T))->T
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+The `Block` function evaluates a lambda with one argument (whose type is unspecified, as it should only be used as a dependent node) and returns its output value.
+Dependent nodes are those used to control the evaluation of nondeterministic functions such as [Random](#random) or functions that produce values ​​of [linear](../types/linear.md) types.
+
+#### Example
+
+```yql
+SELECT Block(($arg)->{
+    $dict = ToMutDict({'key1':123}, $arg); -- use a dependent node when creating a linear value
+    $dict = MutDictInsert($dict, 'key2', 456);
+    return FromMutDict($dict);
+}); -- {'key1':123, 'key2': 456}
+```
+
 ## EvaluateExpr, EvaluateAtom {#evaluate_expr_atom}
 
 Evaluate an expression before the start of the main calculation and input its result to the query as a literal (constant). In many contexts, where only a constant would be expected in standard SQL (for example, in table names, in the number of rows in [LIMIT](../syntax/select/limit_offset.md), and so on), this functionality is implicitly enabled automatically.
diff --git a/yql/essentials/docs/en/builtins/dict.md b/yql/essentials/docs/en/builtins/dict.md
index 57b01e54acf..4099a07ca94 100644
--- a/yql/essentials/docs/en/builtins/dict.md
+++ b/yql/essentials/docs/en/builtins/dict.md
@@ -280,3 +280,495 @@ SELECT SetSymmetricDifference(
 -- { 2 : (null, "qwe"), 3 : ("bar", null) }
 ```
 
+## DictInsert {#dictinsert}
+
+#### Signature
+
+```yql
+DictInsert(Dict<K,V>,K,V)->Dict<K,V>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Returns a new dictionary with the specified key and value added. If the key already exists, the dictionary is not modified.
+When working with a `Set`, the `Void()` function should be passed as the value.
+
+#### Examples
+
+```yql
+SELECT DictInsert({'foo':1}, 'bar', 2); -- {'foo':1,'bar':2}
+SELECT DictInsert({'foo':1}, 'foo', 2); -- {'foo':1}
+SELECT DictInsert({'foo'}, 'bar', Void()); -- {'foo','bar'}
+```
+
+## DictUpsert {#dictupsert}
+
+#### Signature
+
+```yql
+DictUpsert(Dict<K,V>,K,V)->Dict<K,V>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Returns a new dictionary with the specified key and value added or replaced. If the key already exists, the value is updated.
+
+#### Examples
+
+```yql
+SELECT DictUpsert({'foo':1}, 'bar', 2); -- {'foo':1,'bar':2}
+SELECT DictUpsert({'foo':1}, 'foo', 2); -- {'foo':2}
+```
+
+## DictUpdate {#dictupdate}
+
+#### Signature
+
+```yql
+DictUpdate(Dict<K,V>,K,V)->Dict<K,V>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Returns a new dictionary with the replaced value of the given key. If the key does not exist, the dictionary is not modified.
+
+#### Examples
+
+```yql
+SELECT DictUpdate({'foo':1}, 'bar', 2); -- {'foo':1}
+SELECT DictUpdate({'foo':1}, 'foo', 2); -- {'foo':2}
+```
+
+## DictRemove {#dictremove}
+
+#### Signature
+
+```yql
+DictRemove(Dict<K,V>,K)->Dict<K,V>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Returns a new dictionary without the given key. If the key does not exist, the dictionary is not modified.
+
+#### Examples
+
+```yql
+SELECT DictRemove({'foo':1}, 'bar'); -- {'foo':1}
+SELECT DictRemove({'foo':1}, 'foo'); -- {}
+```
+
+## ToMutDict {#tomutdict}
+
+#### Signature
+
+```yql
+ToMutDict(Dict<K,V>,dependArg1...)->Linear<mutDictType for Dict<K,V>>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Converts a dictionary to its mutable version. One or more dependent expressions must also be passed, for example, using the `lambda` argument in the [`Block`](basic.md#block) function.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        return FromMutDict($dict);
+    }); -- {'foo':1}
+```
+
+## MutDictCreate {#mutdictcreate}
+
+#### Signature
+
+```yql
+MutDictCreate(KeyType,ValueType,dependArg1...)->Linear<mutDictType for Dict<K,V>>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Builds an empty mutable dictionary with the specified key and value types. You must also pass one or more dependent expressions, for example, by using the `lambda` argument in the [`Block`](basic.md#block) function.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = MutDictCreate(String, Int32, $arg);
+        return FromMutDict($dict);
+    }); -- {}
+```
+
+## FromMutDict {#frommutdict}
+
+#### Signature
+
+```yql
+FromMutDict(Linear<mutDictType for Dict<K,V>>)->Dict<K,V>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Consumes a mutable dictionary and converts it to an immutable one.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        return FromMutDict($dict);
+    }); -- {'foo':1}
+```
+
+## MutDictInsert {#mutdictinsert}
+
+#### Signature
+
+```yql
+MutDictInsert(Linear<mutDictType for Dict<K,V>>,K,V)->Linear<mutDictType for Dict<K,V>>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Adds the specified key and value to a mutable dictionary and returns the same mutable dictionary. If the key already exists in the dictionary, the dictionary is not modified.
+When working with a `Set`, the `Void()` function should be passed as the value.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict = MutDictInsert($dict,'foo',2);
+        return FromMutDict($dict);
+    }); -- {'foo':1}
+
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict = MutDictInsert($dict,'bar',2);
+        return FromMutDict($dict);
+    }); -- {'foo':1,'bar':2}
+
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo'}, $arg);
+        $dict = MutDictInsert($dict,'bar', Void());
+        return FromMutDict($dict);
+    }); -- {'foo','bar'}
+```
+
+## MutDictUpsert {#mutdictupsert}
+
+#### Signature
+
+```yql
+MutDictUpsert(Linear<mutDictType for Dict<K,V>>,K,V)->Linear<mutDictType for Dict<K,V>>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Adds or replaces the specified key and value in a mutable dictionary and returns the same mutable dictionary. If the key already exists in the dictionary, the value is updated.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict = MutDictUpsert($dict,'foo',2);
+        return FromMutDict($dict);
+    }); -- {'foo':2}
+
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict = MutDictUpsert($dict,'bar',2);
+        return FromMutDict($dict);
+    }); -- {'foo':1,'bar':2}
+```
+
+## MutDictUpdate {#mutdictupdate}
+
+#### Signature
+
+```yql
+MutDictUpdate(Linear<mutDictType for Dict<K,V>>,K,V)->Linear<mutDictType for Dict<K,V>>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Replaces the value in a mutable dictionary with the specified key and returns the same mutable dictionary. If the key does not exist in the dictionary, the dictionary is not modified.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict = MutDictUpdate($dict,'foo',2);
+        return FromMutDict($dict);
+    }); -- {'foo':2}
+
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict = MutDictUpdate($dict,'bar',2);
+        return FromMutDict($dict);
+    }); -- {'foo':1}
+```
+
+## MutDictRemove {#mutdictremove}
+
+#### Signature
+
+```yql
+MutDictRemove(Linear<mutDictType for Dict<K,V>>,K)->Linear<mutDictType for Dict<K,V>>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Removes the value from a mutable dictionary by the given key and returns the same mutable dictionary. If the key does not exist in the dictionary, the dictionary is not modified.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict = MutDictRemove($dict,'foo');
+        return FromMutDict($dict);
+    }); --{}
+
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict = MutDictRemove($dict,'bar');
+        return FromMutDict($dict);
+    }); -- {'foo':1}
+```
+
+## MutDictPop {#mutdictpop}
+
+#### Signature
+
+```yql
+MutDictPop(Linear<mutDictType for Dict<K,V>>,K)->Tuple<Linear<mutDictType for Dict<K,V>>,V?>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Removes the value from a mutable dictionary by the given key and returns the same mutable dictionary and the value by the removed key. If the key did not exist in the dictionary, the dictionary is not modified and an empty Optional is returned.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict, $val = MutDictPop($dict,'foo');
+        return (FromMutDict($dict), $val);
+    }); -- ({},1)
+
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict, $val = MutDictPop($dict,'bar');
+        return (FromMutDict($dict), $val);
+    }); -- ({'foo':1},null)
+```
+
+## MutDictContains {#mutdictcontains}
+
+#### Signature
+
+```yql
+MutDictContains(Linear<mutDictType for Dict<K,V>>,K)->Tuple<Linear<mutDictType for Dict<K,V>>,Bool>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Checks for the existence of a key in a mutable dictionary, returns the same mutable dictionary and the result.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict, $val = MutDictContains($dict,'foo');
+        return (FromMutDict($dict), $val);
+    }); -- ({'foo':1},True)
+
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict, $val = MutDictContains($dict,'bar');
+        return (FromMutDict($dict), $val);
+    }); -- ({'foo':1},False)
+```
+
+## MutDictLookup {#mutdictlookup}
+
+#### Signature
+
+```yql
+MutDictLookup(Linear<mutDictType for Dict<K,V>>,K)->Tuple<Linear<mutDictType for Dict<K,V>>,V?>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Gets a value by key in a mutable dictionary, returns the same mutable dictionary and an optional result.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict, $val = MutDictLookup($dict,'foo');
+        return (FromMutDict($dict), $val);
+    }); -- ({'foo':1},1)
+
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict, $val = MutDictLookup($dict,'bar');
+        return (FromMutDict($dict), $val);
+    }); -- ({'foo':1},null)
+```
+
+## MutDictHasItems {#mutdicthasitems}
+
+#### Signature
+
+```yql
+MutDictHasItems(Linear<mutDictType for Dict<K,V>>)->Tuple<Linear<mutDictType for Dict<K,V>>,Bool>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Checks whether a mutable dictionary is not empty and returns the same mutable dictionary and the result.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict, $val = MutDictHasItems($dict);
+        return (FromMutDict($dict), $val);
+    }); -- ({'foo':1},True)
+
+SELECT Block(
+    ($arg)->{
+        $dict = MutDictCreate(String, Int32, $arg);
+        $dict, $val = MutDictHasItems($dict);
+        return (FromMutDict($dict), $val);
+    }); -- ({},False)
+```
+
+## MutDictLength {#mutdictlength}
+
+#### Signature
+
+```yql
+MutDictLength(Linear<mutDictType for Dict<K,V>>)->Tuple<Linear<mutDictType for Dict<K,V>>,Uint64>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Gets the number of elements in a mutable dictionary and returns the same mutable dictionary and the result.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict, $val = MutDictLength($dict);
+        return (FromMutDict($dict), $val);
+    }); -- ({'foo':1},1)
+
+SELECT Block(
+    ($arg)->{
+        $dict = MutDictCreate(String, Int32, $arg);
+        $dict, $val = MutDictLength($dict);
+        return (FromMutDict($dict), $val);
+    }); -- ({},0)
+```
+
+## MutDictKeys {#mutdictkeys}
+
+#### Signature
+
+```yql
+MutDictKeys(Linear<mutDictType for Dict<K,V>>)->Tuple<Linear<mutDictType for Dict<K,V>>,List<K>>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Gets a list of keys in a mutable dictionary and returns the same mutable dictionary and the result.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict, $val = MutDictKeys($dict);
+        return (FromMutDict($dict), $val);
+    }); -- ({'foo':1},['foo'])
+
+SELECT Block(
+    ($arg)->{
+        $dict = MutDictCreate(String, Int32, $arg);
+        $dict, $val = MutDictKeys($dict);
+        return (FromMutDict($dict), $val);
+    }); -- ({},[])
+```
+
+## MutDictPayloads {#mutdictpayloads}
+
+#### Signature
+
+```yql
+MutDictPayloads(Linear<mutDictType for Dict<K,V>>)->Tuple<Linear<mutDictType for Dict<K,V>>,List<V>>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Gets a list of values ​​in a mutable dictionary and returns the same mutable dictionary and the result.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict, $val = MutDictPayloads($dict);
+        return (FromMutDict($dict), $val);
+    }); -- ({'foo':1},['1'])
+
+SELECT Block(
+    ($arg)->{
+        $dict = MutDictCreate(String, Int32, $arg);
+        $dict, $val = MutDictPayloads($dict);
+        return (FromMutDict($dict), $val);
+    }); -- ({},[])
+```
+
+## MutDictItems {#mutdictitems}
+
+#### Signature
+
+```yql
+MutDictItems(Linear<mutDictType for Dict<K,V>>)->Tuple<Linear<mutDictType for Dict<K,V>>,List<Tuple<K,V>>>
+```
+
+This function is available since version [2025.04](../changelog/2025.04.md).
+Gets a list of tuples with key-value pairs in a mutable dictionary, returns the same mutable dictionary and the result.
+
+#### Examples
+
+```yql
+SELECT Block(
+    ($arg)->{
+        $dict = ToMutDict({'foo':1}, $arg);
+        $dict, $val = MutDictItems($dict);
+        return (FromMutDict($dict), $val);
+    }); -- ({'foo':1},[('foo',1)])
+
+SELECT Block(
+    ($arg)->{
+        $dict = MutDictCreate(String, Int32, $arg);
+        $dict, $val = MutDictItems($dict);
+        return (FromMutDict($dict), $val);
+    }); -- ({},[])
+```
diff --git a/yql/essentials/docs/en/builtins/types.md b/yql/essentials/docs/en/builtins/types.md
index 566ee1de1f2..06105c785d3 100644
--- a/yql/essentials/docs/en/builtins/types.md
+++ b/yql/essentials/docs/en/builtins/types.md
@@ -165,6 +165,24 @@ Return the same-name [special data types](../types/special.md). They have no arg
 SELECT FormatType(VoidType()); -- Void
 ```
 
+## LinearType, DynamicLinearType {#lineartype}
+
+#### Signature
+
+```yql
+LinearType(Type) -> linear type parameterized by the given type
+```
+
+Functions available since version [2025.04](../changelog/2025.04.md).
+Returns the [linear](../types/linear.md) type.
+
+#### Examples
+
+```yql
+SELECT FormatType(LinearType(ResourceType("Foo"))); -- Linear<Resource<'Foo'>>
+SELECT FormatType(DynamicLinearType(ResourceType("Foo"))); -- DynamicLinear<Resource<'Foo'>>
+```
+
 ## OptionalItemType, ListItemType and StreamItemType {#optionalitemtype}
 
 If a type is passed to these functions, then they perform the action reverse to [OptionalType](#optionaltype), [ListType](#listtype), and [StreamType](#listtype): return the item type based on its container type.
@@ -185,6 +203,34 @@ SELECT FormatType(ListItemType(
 )); -- Int32
 ```
 
+## LinearItemType {#linearitemtype}
+
+#### Signature
+
+```yql
+LinearItemType(LinearType)->linear type parameter
+LinearItemType(DynamicLinearType)->linear type parameter
+```
+
+These functions are available starting with version [2025.04](../changelog/2025.04.md).
+If these functions are passed a type, they perform the inverse of [LinearType](#lineartype) or [DynamicLinearType](#lineartype) — they return the type of the linear type parameter.
+
+If these functions are passed a type handle, they perform the inverse of [LinearTypeHandle](#lineartypehandle) or [DynamicLinearTypeHandle](#lineartypehandle)—they return the handle of the parameter type based on the linear type handle.
+
+#### Examples
+
+```yql
+SELECT FormatType(LinearItemType(
+    ParseType("Linear<Int32>")
+)); -- Int32
+```
+
+```yql
+SELECT FormatType(LinearItemType(
+    ParseTypeHandle("Linear<Int32>")
+)); -- Int32
+```
+
 ## DictKeyType and DictPayloadType {#dictkeytype}
 
 Returns the type of the key or value based on the dictionary type.
@@ -635,3 +681,23 @@ Getting the number of arguments in a lambda function.
 SELECT LambdaArgumentsCount(($x, $y)->($x+$y))
 ; -- 2
 ```
+
+### LinearTypeHandle and DynamicLinearTypeHandle {#lineartypehandle}
+
+#### Signature
+
+```yql
+LinearTypeHandle(TypeHandle)->handle of a static linear type
+DynamicLinearTypeHandle(TypeHandle)->handle of a dynamic linear type
+```
+
+Functions available starting with version [2025.04](../changelog/2025.04.md).
+These functions construct a handle of a static or dynamic linear type based on the passed handle of the parameter type.
+
+#### Examples
+
+```yql
+SELECT FormatType(LinearTypeHandle(
+    TypeHandle(DataType("Bool"))
+)); -- Linear<Bool>
+```
diff --git a/yql/essentials/docs/en/changelog/2025.04.md b/yql/essentials/docs/en/changelog/2025.04.md
index fbffc9112cc..f6e20c7092d 100644
--- a/yql/essentials/docs/en/changelog/2025.04.md
+++ b/yql/essentials/docs/en/changelog/2025.04.md
@@ -1,6 +1,16 @@
+## Changes in types
+
+Added linear types.
+
 ## Changes in built-in functions
 
 * Added functions `WithSideEffects`/`WithSideEffectsMode` for working with side effects.
+* Added functions for creating new dictionaries based on existing ones with content modification: `DictInsert`/`DictUpsert`/`DictUpdate`/`DictRemove`.
+* Added functions for working with mutable dictionaries using linear types.
+* Added `Block` function for executing a block of code using anonymous dependent nodes.
+* Added `ToDynamicLinear`/`FromDynamicLinear` functions for converting between linear types.
+* Added `LinearType`/`DynamicLinearType` functions for constructing linear types. * Added the `LinearTypeHandle`/`DynamicLinearTypeHandle` functions for constructing linear types during code generation.
+* Added the `LinearItemType` function for retrieving the parameter type from a linear type.
 
 ## Changes in NOT NULL expression
 
diff --git a/yql/essentials/docs/en/types/index.md b/yql/essentials/docs/en/types/index.md
index 8933ad400b2..41405cd2699 100644
--- a/yql/essentials/docs/en/types/index.md
+++ b/yql/essentials/docs/en/types/index.md
@@ -6,6 +6,7 @@ This section contains articles on YQL data types:
 - [Optional types](optional.md)
 - [Containers](containers.md)
 - [Special types](special.md)
+- [Linear types](linear.md)
 - [Type casting](cast.md)
 - [Text representation of data types](type_string.md)
 - [Parameter transfer in JSON format](json.md)
diff --git a/yql/essentials/docs/en/types/linear.md b/yql/essentials/docs/en/types/linear.md
new file mode 100644
index 00000000000..ce17aab54b3
--- /dev/null
+++ b/yql/essentials/docs/en/types/linear.md
@@ -0,0 +1,37 @@
+## Linear Types
+
+Most types in YQL are immutable, meaning expressions return new values ​​rather than modify existing ones.
+This approach, common in functional programming languages, allows for more aggressive optimizations (such as removing common subexpressions or caching results).
+However, in some scenarios, this can lead to slower query execution. In particular, when attempting to modify a single value in a list/dictionary, it is necessary to either return a full copy or use persistent data structures, which also incurs additional overhead.
+
+Linear types offer a different approach: instead of reusing the immutable results of expression evaluation, reuse of a linear type value is prohibited. It is passed, as if in a relay race, from the point of creation to the point of consumption, where it is converted to a regular immutable value.
+
+Linear types are available starting with version [2025.04](../changelog/2025.04.md).
+
+Linear types are described by a single type parameter T and come in two varieties: statically verified Linear<T> and runtime-verified DynamicLinear<T>.
+Statically verified types are more efficient but have composition limitations.
+
+Typically, the Resource type is used in the T parameter of a linear type. In this case, user-defined functions (UDFs) can pass such data between each other with a guarantee of protection against reuse in the query, allowing for a more efficient implementation.
+
+Linear types are not serializable—they cannot be read or written to tables, meaning they can only be used in the middle of expressions.
+
+Functions that accept or return linear types are divided into three classes:
+* If the linear type is contained in the result but not in the arguments, it is a generating function;
+* If the linear type is contained in both the arguments and the result, it is a transforming function;
+* If a linear type is contained in the arguments but not in the result, it is an consuming function.
+
+A generating function must accept a dependent expression in at least one argument, since multiple independent values ​​of linear types can be constructed from the input arguments.
+It is recommended to create and consume linear types within the [`Block`](../builtins/basic.md#block) function, which allows an anonymous dependent expression to be passed as a `lambda` argument.
+
+### Rules for checking static linear types `Linear<T>`
+
+* `Linear` types are checked as the last stage of optimization, and if the optimizer eliminates expression reuse, no error is raised.
+* `Linear` cannot be an argument to `lambda`.
+* `Linear` cannot be returned from `lambda`.
+* `Linear` can be used either by itself or as a field in a `Struct/Tuple` (without nesting). Whenever possible, individual uses of `Struct/Tuple` fields are tracked using the field access operator (dot).
+
+If you need to use values ​​of linear types within other container types (for example, in lists), you should use the `DynamicLinear` type.
+
+### Rules for checking dynamic linear types `DynamicLinear<T>`
+
+* The `FromDynamicLinear` function or user-defined functions (UDFs) may retrieve a value of this type, but only once, otherwise a query execution error will occur.
diff --git a/yql/essentials/docs/en/types/toc_i.yaml b/yql/essentials/docs/en/types/toc_i.yaml
index cd0f40f6f02..0a04c673b91 100644
--- a/yql/essentials/docs/en/types/toc_i.yaml
+++ b/yql/essentials/docs/en/types/toc_i.yaml
@@ -9,6 +9,8 @@ items:
   href: containers.md
 - name: Special
   href: special.md
+- name: Linear
+  href: linear.md
 - name: Type casting
   href: cast.md
 - name: Text representation of data types