update 21.2

docs/API/DataClassClass.md

@@ -1219,7 +1219,7 @@ In this case, the *value* parameter must be a **comparison vector object** conta
 |Property|Type|Description|
 |---|---|---|
 |vector|[4D.Vector](../API/VectorClass.md)|Mandatory. The vector to be compared|
-|metric|Text|Optional. [Vector computation](../API/VectorClass.md#understanding-the-different-vector-computations) to use for the query. You can use one of the following (Text) constants:<li>`mk cosine` (default if omitted): calculates the cosine similarity between vectors.</li><li>`mk dot`: calculates the dot similarity of vectors.</li><li>`mk euclidean`: calculates the Euclidean distance between vectors.|
+|metric|Text|Optional. [Vector computation](../API/VectorClass.md#understanding-the-different-vector-computations) to use for the query. You can use one of the following (Text) constants:<li>`mk cosine` (default if omitted): calculates the [cosine similarity](./VectorClass.md#cosinesimilarity) between vectors.</li><li>`mk dot`: calculates the [dot similarity](VectorClass.md#dotsimilarity) of vectors.</li><li>`mk euclidean`: calculates the [Euclidean distance](./VectorClass.md#euclideandistance) between vectors.|
 |threshold|Real|Optional (default: 0.5). A threshold value used to filter vector comparisons based on their cosine, dot or euclidean similarity score according to the selected "metric". It is highly recommended to choose a similarity that best fits your specific use case for optimal results.|
 
 Only a subset of **comparator** symbols are supported. Note that they compare results to the threshold value: 
@@ -1236,29 +1236,32 @@ For example, you want to return entities of MyClass where the similarity with a
 ```4d
 var $myVector : 4D.Vector
 $myVector := getVector //method to get a vector, e.g. from 4D.AIKit
-var $comparisonVector := {vector: $myVector; metric: mk euclidean; threshold: 1.2}
+var $comparisonVector := {vector: $myVector; metric: mk cosine; threshold: 1.2}
 var $results := ds.MyClass.query("myVectorField <= :1"; $comparisonVector)
 ```
 
 The **order by** statement is supported in the query string so that entities in the resulting entity selection are sorted by similarity. For example:
 
 ```4d
 var $results := ds.MyClass.query("myVectorField > :1 order by myVectorField desc"; $comparisonVector)  
-  //the first entity is the most similar
+  //$results.first() entity is the most similar
 ```
 
 :::note
 
-The default order is ascending, although a descending order is usually the most useful for vector similarity queries. Thus, you will usually have to add the `desc` keyword in your vector similarity query strings.
+You will generally want vector similarity query results to be sorted from "most similar" to "least similar." By default, results returned with an **order by** clause are sorted in ascending order. Depending on the similarity metric used, you may need to adjust the sorting direction to obtain the correct ranking:
+- for [**cosine**](./VectorClass.md#cosinesimilarity) and [**dot**](./VectorClass.md#dotsimilarity) similarity, higher values indicate greater similarity. Therefore, you will typically need to include the `desc` keyword in the query string.
+- for [**euclidean distance**](./VectorClass.md#euclideandistance) similarity, lower values indicate greater similarity. In this case, the default ascending order (or explicitly using the `asc` keyword) is appropriate.
 
 :::
 
 
-If the same vector appears multiple times in the query string, the order by will be applied to the results of the first one, for example:
+You can only order on a single vector field. If the same vector appears multiple times in the query string, the order by will be applied to the results of the first one, for example:
 
 ```4d
 var $results := ds.MyClass.query("myVectorField > :1 and myVectorField > :2 order by myVectorField desc"; /
-    {vector : $myVector1 };{vector : $myVector2 })  //myVectorField > :1 is used for the order by
+    {vector : $myVector1 };{vector : $myVector2 })  
+    //myVectorField > :1 is used for the order by
 ```
 
 See [more examples below](#example-4-2) (examples 4 and 5). 
@@ -1267,6 +1270,7 @@ See [more examples below](#example-4-2) (examples 4 and 5).
 :::tip Related blog posts
 
 - [4D AI: Searching Entities by Vector Similarity in 4D](https://blog.4d.com/4d-ai-searching-entities-by-vector-similarity-in-4d)
+- [4D AI: Sorting Query Results by Vector Similarity](https://blog.4d.com/4d-ai-sorting-query-results-by-vector-similarity/)
 - [Why Your Search Stack Feels Broken — and How Vector Search Fixes It](https://blog.4d.com/why-your-search-stack-feels-broken-and-how-vector-search-fixes-it)
 
 :::
@@ -1635,12 +1639,16 @@ var $result:=$client.embeddings.create("my long text to search"; "text-embedding
 var $vector:=$result.vector
 
   //embedding attribute is based upon a 4D field storing 4D.Vector class objects
+
   //search with default metric (cosine)
-var $employees:=ds.Employee.query("embedding > :1"; {vector : $vector})
+var $employees:=ds.Employee.query("embedding > :1 order by embedding desc"; {vector : $vector})
+
   //search with euclidean metric 
-var $employees:=ds.Employee.query("embedding > :1"; {vector: $vector; metric: mk euclidean})
+var $employees:=ds.Employee.query("embedding < :1 order by embedding"; {vector: $vector; metric: mk euclidean})
+
   //search with explicit cosine metric and custom threshold
-var $employees:=ds.Employee.query("embedding > :1"; {vector: $vector; metric: mk cosine; threshold: 0.9})
+var $employees:=ds.Employee.query("embedding > :1 order by embedding desc"; {vector: $vector; metric: mk cosine; threshold: 0.9})
+
   //search with a formula
 var $employees:=ds.Employee.query(Formula(This.embdedding.cosineSimilarity($vector)>0.9))
 
@@ -1649,19 +1657,15 @@ var $employees:=ds.Employee.query(Formula(This.embdedding.cosineSimilarity($vect
 
 #### Example 5
 
-We want to execute a query by vector similarity using vectors with different metrics and order the results by cosine similarity:
+Vector-based semantic ordering can be combined with traditional ORDA filters in the same query.
 
-```4d
-  //Create the comparison vectors 
-var $vector1Comparison:={vector: $myvector; metric: mk cosine; threshold: 0.4}
-var $vector2Comparison:={vector: $myvector; metric: mk euclidean; threshold:1}
-
-  //embedding attribute is based upon a 4D field storing 4D.Vector class objects
-ds.VectorTable.query("embedding>:1 and embedding<:2";$vector1Comparison;$vector2Comparison)\
-    .orderByFormula(Formula(This.embedding.cosineSimilarity($vector1Comparison)))
 
+```4d
+var $comparisonVector := {vector: $myVector; metric: mk cosine; threshold: 0.4} 
+var $results := ds.MyTable.query("myVectorField <= :1 AND salary>100000 order by myVectorField, salary desc"; $comparisonVector)
 ```
 
+
 #### See also
 
 [`.query()`](EntitySelectionClass.md#query) for entity selections

docs/API/QuotaManagerClass.md

@@ -0,0 +1,148 @@
+---
+id: QuotaManagerClass
+title: QuotaManager
+---
+
+
+The `4D.QuotaManager` class provides you with an interface to configure and monitor some usage limits you apply to your 4D application. Thresholds are useful for example to protect the server from poorly optimized requests or excessive use of server resources. Typically, the quota manager allows you to provide thresholds to ORDA resources a REST server session can access. 
+
+
+`4D.QuotaManager` objects can be instantiated by the [`quotas` property of a session](./SessionClass.md#quotas) object.
+
+
+<details><summary>History</summary>
+
+|Release|Changes|
+|---|---|
+|21 R4|Class added|
+
+</details>
+
+
+
+### QuotaManager Object
+
+
+4D.QuotaManager objects provide the following properties:
+
+||
+|---|
+|[<!-- INCLUDE #QuotaManagerClass.currentValues.Syntax -->](#currentvalues)<br/><!-- INCLUDE #QuotaManagerClass.defaultcurrentValuesEntitySetTimeout.Summary -->|
+|[<!-- INCLUDE #QuotaManagerClass.defaultEntitySetTimeout.Syntax -->](#defaultentitysettimeout)<br/><!-- INCLUDE #QuotaManagerClass.defaultEntitySetTimeout.Summary -->|
+|[<!-- INCLUDE #QuotaManagerClass.maxEntitySetTimeout.Syntax -->](#maxentitysettimeout)<br/><!-- INCLUDE #QuotaManagerClass.maxEntitySetTimeout.Summary -->|
+|[<!-- INCLUDE #QuotaManagerClass.nbEntitySets.Syntax -->](#nbentitysets)<br/><!-- INCLUDE #QuotaManagerClass.nbEntitySets().Summary -->|
+
+
+
+<!-- REF QuotaManagerClass.currentValues.Desc -->
+## .currentValues
+
+<!-- REF #QuotaManagerClass.currentValues.Syntax -->**currentValues** : Object<!-- END REF -->
+
+#### Description
+
+The `.currentValues` property contains <!-- REF #QuotaManagerClass.currentValues.Summary -->the current values related to the defined quotas properties<!-- END REF -->. This object is automatically updated by the server. 
+
+
+<!-- END REF -->
+
+
+<!-- REF QuotaManagerClass.defaultEntitySetTimeout.Desc -->
+## .defaultEntitySetTimeout
+
+<!-- REF #QuotaManagerClass.defaultEntitySetTimeout.Syntax -->**defaultEntitySetTimeout** : Integer<!-- END REF -->
+
+#### Description
+
+The `.defaultEntitySetTimeout` property contains <!-- REF #QuotaManagerClass.defaultEntitySetTimeout.Summary -->the default inactivity timeout for REST entity sets stored in memory during the current session (in seconds)<!-- END REF -->.
+
+By default, this value is 2 hours (7200 seconds). It can also be defined at the entity set creation using the [`$timeout` REST API](../REST/$timeout.md). 
+
+You can change this value dynamically using the [`quotas.defaultEntitySetTimeout` property of the Session](./SessionClass.md#quotas), so that it will be used for any entity set created afterwards in the session (existing entity set default timeout values are not modified). 
+
+:::note
+
+If you define a value higher than the `maxEntitySetTimeout` property value, it will be aligned with the `maxEntitySetTimeout` value. 
+
+:::
+
+You cannot pass a value <=0 (an error is generated in this case). To reset the property value for the session, pass *undefined*. 
+
+
+#### Example
+
+In some 4D code in a REST process:
+
+```4d
+Session.quotas.defaultEntitySetTimeout:=1200
+```
+
+
+<!-- END REF -->
+
+
+<!-- REF QuotaManagerClass.maxEntitySetTimeout.Desc -->
+## .maxEntitySetTimeout
+
+<!-- REF #QuotaManagerClass.maxEntitySetTimeout.Syntax -->**maxEntitySetTimeout** : Integer<!-- END REF -->
+
+#### Description
+
+The `.maxEntitySetTimeout` property contains <!-- REF #QuotaManagerClass.maxEntitySetTimeout.Summary -->the maximum inactivity timeout value for REST entity sets stored in memory during the current session (in seconds)<!-- END REF -->.
+
+You can set this value using the [`quotas.maxEntitySetTimeout` property of the Session](./SessionClass.md#quotas), so that it will be used for any entity set created afterward in the session (existing entity set maximum timeout values are not modified). 
+
+Once the `.maxEntitySetTimeout` property is set, any entity set created afterward in the session could not have a timeout value longer than the `.maxEntitySetTimeout` value.
+
+For example, assuming the maximum inactivity timeout is set to 40 minutes (2400 seconds), if an entity set is created with a required timeout which exceeds the maximum value:
+
+```
+http://127.0.0.1/rest/People?$filter=ID>=4&$method=entityset&$timeout=3000
+```
+
+... then the timeout defined in the request is ignored and the entity set will be released after 40 minutes if not used during this period of time.
+
+You cannot pass a value <=0 (an error is generated in this case). To reset the property value for the session, pass *undefined*. 
+
+#### Example
+
+In some 4D code in a REST process:
+
+```4d
+Session.quotas.maxEntitySetTimeout:=2400
+```
+
+
+<!-- END REF -->
+
+
+<!-- REF QuotaManagerClass.nbEntitySets.Desc -->
+## .nbEntitySets
+
+<!-- REF #QuotaManagerClass.nbEntitySets.Syntax -->**nbEntitySets** : Integer<!-- END REF -->
+
+#### Description
+
+The `.nbEntitySets` property contains <!-- REF #QuotaManagerClass.nbEntitySets.Summary -->the maximum number of REST entity sets allowed in memory for the current session (in seconds)<!-- END REF -->.
+
+By default, there is no limit for entity sets [stored in memory by REST requests](../REST/$info.md) (the value is 0). You can set a limit to control the server payload for a specific session.
+
+When the maximum number of allowed entity sets is reached, a REST request that need to create an entity set will get a [**429** HTTP status code and an error response](../REST/REST_requests.md#rest-status-and-response), until at least one entity set is released. You can release an entity set from the cache using the [`$release` REST command](../REST/$entityset.md#entitysetrelease). 
+
+You cannot pass a value <=0 (an error is generated in this case). To reset the property value for the session, pass *undefined*. 
+
+
+#### Example
+
+In some 4D code in a REST process:
+
+```4d
+	//max 50 entity sets
+Session.quotas.nbEntitySets:=50
+```
+
+<!-- END REF -->
+
+
+
+

docs/API/SessionClass.md

@@ -53,6 +53,7 @@ All session types can handle privileges, but only the code executed in a **web c
 |[<!-- INCLUDE #SessionClass.info.Syntax -->](#info)<br/><!-- INCLUDE #SessionClass.info.Summary -->|
 |[<!-- INCLUDE #SessionClass.isGuest().Syntax -->](#isguest)<br/><!-- INCLUDE #SessionClass.isGuest().Summary -->|
 |[<!-- INCLUDE #SessionClass.promote().Syntax -->](#promote)<br/><!-- INCLUDE #SessionClass.promote().Summary -->|
+|[<!-- INCLUDE #SessionClass.quotas.Syntax -->](#quotas)<br/><!-- INCLUDE #SessionClass.quotas.Summary -->|
 |[<!-- INCLUDE #SessionClass.restore().Syntax -->](#restore)<br/><!-- INCLUDE #SessionClass.restore().Summary -->|
 |[<!-- INCLUDE #SessionClass.setPrivileges().Syntax -->](#setprivileges)<br/><!-- INCLUDE #SessionClass.setPrivileges().Summary -->|
 |[<!-- INCLUDE #SessionClass.storage.Syntax -->](#storage)<br/><!-- INCLUDE #SessionClass.storage.Summary -->|
@@ -571,6 +572,8 @@ Since `.info` is a computed property, it is recommended to call it once and then
 
 :::
 
+This property is **read only**.
+
 
 <!-- END REF -->
 
@@ -718,6 +721,61 @@ End if
 <!-- END REF -->
 
 
+<!-- REF SessionClass.quotas.Desc -->
+## .quotas
+
+<details><summary>History</summary>
+
+|Release|Changes|
+|---|---|
+|21 R4|Added|
+
+</details>
+
+<!-- REF #SessionClass.quotas.Syntax -->**.quotas** : 4D.QuotaManager<!-- END REF -->
+
+#### Description
+
+
+The `.quotas` property contains <!-- REF #SessionClass.quotas.Summary -->a `4D.QuotaManager` object with current values and set values for server thresholds in the current session<!-- END REF -->. Server thresholds are used to control the requests to the server and help preventing excessive use of resources (see [`4D.QuotaManager` class](./QuotaManagerClass.md)).
+
+This property is **read only**.
+
+The following properties of the `4D.QuotaManager` object are available for the session:
+
+|Property||Type|Writable|Description|
+|---|---|---|---|---|
+|[nbEntitySets](./QuotaManagerClass.md#nbentitysets)||Integer|yes|Maximum allowed number of entity sets in server's memory|
+|[defaultEntitySetTimeout](./QuotaManagerClass.md#defaultentitysettimeout) ||Integer|yes|Default inactivity timeout for entity sets in memory (seconds)|
+|[maxEntitySetTimeout](./QuotaManagerClass.md#maxentitysettimeout) ||Integer|yes|Maximum inactivity timeout for entity sets in memory (seconds)|
+|currentValues||Object|no||
+||nbEntitySets|Integer|no|Number of entity sets currently in memory|
+
+When you modify a value, it is immediately taken into account by the server (no need to restart) and will be applied to further REST requests. 
+
+:::tip Related blog post
+
+[Make your REST server at the top of its game ... Forget throttling or crashing and tune yourself the memory usage](https://blog.4d.com/make-your-rest-server-at-the-top-of-its-game-forget-throttling-or-crashing-and-tune-yourself-the-memory-usage).
+
+:::
+
+#### Example
+
+```4d
+   //set the maximum number of entity sets in memory
+   //for the session to 50
+Session.quotas.nbEntitySets:=50
+```
+
+<!-- END REF -->
+
+
+#### See also
+
+[QuotaManager class](./QuotaManagerClass.md)
+
+
+
 <!-- REF SessionClass.restore().Desc -->
 ## .restore()
 

docs/Concepts/classes.md

@@ -115,7 +115,7 @@ You want to list 4D built-in classes:
 
 ## Class object
 
-When a class is [defined](#class-definition) in the project, it is loaded in the 4D language environment. A class is an object itself, of ["Class" class](API/ClassClass.md). A class object has the following properties and function:
+When a class is [defined](../Project/code-overview.md#creating-classes) in the project, it is loaded in the 4D language environment. A class is an object itself, of ["Class" class](API/ClassClass.md). A class object has the following properties and function:
 
 - [`name`](API/ClassClass.md#name) string
 - [`superclass`](API/ClassClass.md#superclass) object (null if none)

docs/Concepts/flow-control.md

@@ -59,6 +59,14 @@ The expression is TRUE only if both methods are TRUE. However, even if _MethodA_
  End if
 ```
 
+However, the most elegant solution is then to use the [`&&` short-circuit operator](./operators.md#short-circuit-and-operator-) and to write:
+
+```4d
+If (MethodA && MethodB)
+   ...
+End if
+```
+
 The result is similar and _MethodB_ is evaluated only if necessary. 
 
 > **Note:** The [ternary operator](operators.md#ternary-operator) allows writing one-line conditional expressions and can replace a full sequence of If..Else statements.

docs/Notes/updates.md

@@ -9,8 +9,15 @@ Read [**What’s new in 4D 21 R4**](https://blog.4d.com/whats-new-in-4d-21-r4/),
 
 #### Highlights
 
-- New [`defer`](../commands/defer) command to declare some code to be always executed at method or function exit. 
+- Multi-level list style sheets are now [supported in 4D Write Pro Interface](../WritePro/writeprointerface.md#multi-level-style-sheets), allowing users to create and manage structured multi-level lists directly from the toolbar and sidebar.
+- New [`defer`](../commands/defer) command to declare some code to be always executed at method or function exit; new [`Deferred formulas`](../commands/deferred-formulas) command to get the list of deferred formulas. 
+- New session `.quotas` property to configure thresholds for sessions. 
+- New [`4D.QuotaManager`](../API/QuotaManagerClass.md) class to handle threshold objects for protecting the server.
+- New [`$entityset/$release`](../REST/$entityset.md#entitysetrelease) REST request to delete entity sets from server cache.
 
+#### Behavior changes
+
+- The **`GET /Employee/$entityset/<entitySetID>?$method=release`** REST syntax is **deprecated** and should no longer be used. To delete entity sets, you must now use [`/$entityset/$release` with a POST verb](./$entityset.md).
 
 
 ## 4D 21 R3
@@ -20,7 +27,7 @@ Read [**What’s new in 4D 21 R3**](https://blog.4d.com/whats-new-in-4d-21-r3/),
 #### Highlights
 
 - The [`JSON Validate`](../commands/json-validate) command now supports of JSON Schema draft 2020-12. 
-- 4D Write Pro now supports [hierarchical list style sheets](../WritePro/user-legacy/stylesheets.md#hierarchical-list-style-sheets), enabling the creation and management of structured [multi-level lists](../WritePro/user-legacy/using-a-4d-write-pro-area.md#multi-level-lists) with automatic numbering.
+- 4D Write Pro now supports [multi-level list style sheets](../WritePro/user-legacy/stylesheets.md#multi-level-list-style-sheets), enabling the creation and management of structured [multi-level lists](../WritePro/user-legacy/using-a-4d-write-pro-area.md#multi-level-lists) with automatic numbering.
 - Ability to use a custom certificate from the macOS keychain instead of a local certificates folder in [`HTTPRequest`](../API/HTTPRequestClass.md#4dhttprequestnew) and [`HTTPAgent`](../API/HTTPAgentClass.md#4dhttpagentnew) classes. 
 - New [`4D.Method` class](../API/MethodClass.md) to create and execute a 4D method code from text source. [`METHOD Get path`](../commands/method-get-path) and [`METHOD RESOLVE PATH`](../commands/method-resolve-path) commands support a new `path volatile method` constant (128).
 - IMAP transporter now supports mailbox event notifications using the IDLE protocol through a [notifier object](../API/IMAPTransporterClass.md#notifier) of the [4D.IMAPNotifier](../API/IMAPNotifierClass.md) class, configurable via the `listener` property of [IMAP New transporter](../commands/imap-new-transporter).