diff --git a/docs/API/CollectionClass.md b/docs/API/CollectionClass.md index d5a6020ca7fcef..025e2731f2298a 100644 --- a/docs/API/CollectionClass.md +++ b/docs/API/CollectionClass.md @@ -292,7 +292,7 @@ By default, *col2* elements are added at the end of the orginal collection. You var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` diff --git a/docs/API/DataStoreClass.md b/docs/API/DataStoreClass.md index f6661185ec8b85..d18510a4218056 100644 --- a/docs/API/DataStoreClass.md +++ b/docs/API/DataStoreClass.md @@ -315,7 +315,7 @@ ds.unlock() //Our copy is over, we can now unlock the datastore -**.generateFineGrainedToken**( *privilege* : Text ; *name* : Text ; *expiry* : Date {; *info* : Object} ) : Object
**.generateFineGrainedToken**( *privileges* : Collection ; *name* : Text ; *expiry* : Date {; *info* : Object} ) : Object
**.generateFineGrainedToken**( *settings* : Object ; *name* : Text ; *expiry* : Date {; *info* : Object} ) : Object +**.generateFineGrainedToken**( *privilege* : Text ; *name* : Text {; *expiry* : Date {; *info* : Object}} ) : Object
**.generateFineGrainedToken**( *privileges* : Collection ; *name* : Text {; *expiry* : Date {; *info* : Object}} ) : Object
**.generateFineGrainedToken**( *settings* : Object ; *name* : Text {; *expiry* : Date {; *info* : Object}} ) : Object @@ -347,7 +347,7 @@ Unlike `Session.setPrivileges()`, a name that is not declared in the [`roles.jso In *name*, pass a name that identifies the token, for example the user and the client that will use it. It is the user name of the MCP sessions opened with the token. -In *expiry*, pass the expiration date of the token. It is required, and it must be later than the current date and at most 366 days ahead. +In *expiry*, pass the expiration date of the token. It must be later than the current date and at most 366 days ahead. If *expiry* is omitted, an error is raised. In *info*, you can pass an object that 4D stores with the token as is, and passes to the [`ds.mcpAuthenticated()`](../ORDA/ordaClasses.md#function-mcpauthenticated) function when an MCP session is opened with the token. Since it cannot be modified later, store stable identifiers (such as a user ID) and read the current values in `ds.mcpAuthenticated()`. Build *info* from the authenticated session, never from values sent by the client. @@ -987,7 +987,7 @@ If no *curPassphrase* or *curDataKey* is given, `.provideDataKey()` returns **nu -**.revokeFineGrainedToken**( *id* : Text )
**.revokeFineGrainedToken**( *tokenObj* : Object ) +**.revokeFineGrainedToken**( *id* : Text ) : Boolean
**.revokeFineGrainedToken**( *tokenObj* : Object ) : Boolean @@ -997,6 +997,7 @@ If no *curPassphrase* or *curDataKey* is given, `.provideDataKey()` returns **nu |---|---|---|---| |id|Text|→|Identifier of the token to revoke| |tokenObj|Object|→|Object with a `token` property containing the token to revoke| +|Result|Boolean|←|True if the token was revoked| @@ -1009,6 +1010,8 @@ You designate the token: - in the *id* parameter, with its identifier (returned by [`.generateFineGrainedToken()`](#generatefinegrainedtoken) and [`.listFineGrainedTokens()`](#listfinegrainedtokens)), - or in the *tokenObj* parameter, with an object whose `token` property contains the token itself (`"4dfgt_..."`), for example to let the holder of a token revoke it. +The function returns **True** if the token was revoked, **False** otherwise (for example if the token does not exist or was already revoked). + The token stops working at the next request, and the MCP sessions opened with it are closed. [Binary URLs](../WebServer/mcp-server.md#binary-attributes) already returned to the client remain valid until they expire (10 minutes at most). When the function is called in a web context (code executed for a web or REST request), it can only revoke a token whose privileges are all held by the current session. @@ -1041,7 +1044,7 @@ End if -**.revokeOAuthGrant**( *id* : Text ) +**.revokeOAuthGrant**( *id* : Text ) : Boolean @@ -1050,6 +1053,7 @@ End if |Parameter|Type||Description| |---|---|---|---| |id|Text|→|Identifier of the grant to revoke| +|Result|Boolean|←|True if the grant was revoked| @@ -1057,6 +1061,8 @@ End if The `.revokeOAuthGrant()` function revokes a grant given to a user through the OAuth mode of the MCP server (see [`.listOAuthGrants()`](#listoauthgrants)). +The function returns **True** if the grant was revoked, **False** otherwise (for example if the grant does not exist or was already revoked). + The access tokens of the grant get an HTTP 401 status from the next request, its refresh token is refused, and its MCP sessions are closed. The user must log in again from the MCP client. When the function is called in a web context (code executed for a web or REST request), it can only revoke a grant whose privileges are all held by the current session. diff --git a/docs/API/MCPContextClass.md b/docs/API/MCPContextClass.md index e01bb140705d38..dfbae44cad948a 100644 --- a/docs/API/MCPContextClass.md +++ b/docs/API/MCPContextClass.md @@ -118,7 +118,7 @@ End if ## .error() -**.error**( *message* : Text ) +**.error**( { *message* : Text } )
@@ -131,7 +131,7 @@ End if #### Description -The `.error()` function makes the current tool call return an error result with *message*. The result has `isError: true`, and the value returned by the function is ignored. +The `.error()` function makes the current tool call return an error result with *message*. The result has `isError: true`, and the value returned by the function is ignored. If *message* is omitted, the error message is empty. `.error()` does not stop the execution of the function: call `return` after it if needed. @@ -156,7 +156,7 @@ exposed MCP Function refund($amount : Real) : Text ## .hasInput() -**.hasInput**( *name* : Text ) : Boolean +**.hasInput**( { *name* : Text } ) : Boolean
@@ -164,7 +164,7 @@ exposed MCP Function refund($amount : Real) : Text |Parameter|Type||Description| |---|---|---|---| |name|Text|→|Name of a field requested with `.requireInput()`| -|Result|Boolean|←|True if the user answered this field| +|Result|Boolean|←|True if the user answered this field (or any field if *name* is omitted)|
@@ -172,6 +172,8 @@ exposed MCP Function refund($amount : Real) : Text The `.hasInput()` function returns **True** if the current call contains a verified answer of the user for the *name* field. +If *name* is omitted or empty, `.hasInput()` returns **True** if the current call contains a verified answer of the user for at least one field. + The answer is verified when the client calls the tool again with the answers and a valid `requestState`: signed by 4D for the same token, tool, arguments, and fields, less than 10 minutes ago, and since the MCP server was last enabled. Otherwise, `.hasInput()` returns **False**. Outside an MCP tool call, `.hasInput()` returns **False**. diff --git a/docs/API/WebServerClass.md b/docs/API/WebServerClass.md index c93c3bd776680a..29e38e56c5dc76 100644 --- a/docs/API/WebServerClass.md +++ b/docs/API/WebServerClass.md @@ -776,7 +776,7 @@ The "SameSite" session |Constant|Value|Description| |---|---|---| |Web SameSite Strict|"Strict"|*Default value* - Cookies are only sent in a first-party context| -|Web SameSite Lax|"Lax"|Cookies are also sent on cross-site subrequests but only when a user is navigating to the origin site (i.e. when following a link).| +|Web SameSite Lax|"Lax"|Cookies are not sent with requests coming from other websites (images, frames, forms, scripts), except when the user navigates to the site from another website with a GET request (following a link, redirection).| |Web SameSite None|"None"|Cookies are sent in all contexts, i.e in responses to both first-party and cross-origin requests. See the [Session Cookie SameSite](WebServer/webServerConfig.md#session-cookie-samesite) description for detailed information. diff --git a/docs/Notes/updates.md b/docs/Notes/updates.md index 9774a24f2e1dd6..20d48d8925ce3e 100644 --- a/docs/Notes/updates.md +++ b/docs/Notes/updates.md @@ -157,11 +157,11 @@ Read [**What’s new in 4D 21 R2**](https://blog.4d.com/whats-new-in-4d-21-r2/), |ICU|77.1|21|This upgrade forces an automatic rebuild of alphanumeric, text and object indexes.| |libldap|2.6.10|21|| |libsasl|2.1.28|20|| -|Libuv |1.53.0|**21 R5**|Used for QUIC| +|Libuv |1.53.0|21 R5|Used for QUIC| |libZip|1.11.4|21|Used by zip class, 4D Write Pro, svg and serverNet components| |LZMA|5.8.1|21|| -|ngtcp2|1.24.0|21 R4|Used for QUIC| -|OpenSSL|4.0.3|**21 R5**|| +|ngtcp2|1.26.0|**21 R6**|Used for QUIC| +|OpenSSL|4.0.3|21 R5|| |PDFWriter|4.7.0|21|Used for [`WP Export document`](../WritePro/commands/wp-export-document.md) and [`WP Export variable`](../WritePro/commands/wp-export-variable.md) | |SpreadJS|18.2.0|21 R2|See [this blog post](https://blog.4d.com/4d-view-pro-whats-new-in-4d-21-r2/) for an overview of the new features| |webKit|WKWebView|19|| diff --git a/docs/ORDA/ordaClasses.md b/docs/ORDA/ordaClasses.md index 1a8358df8d89a7..20fc28c898c260 100644 --- a/docs/ORDA/ordaClasses.md +++ b/docs/ORDA/ordaClasses.md @@ -1065,7 +1065,7 @@ $status:=$remoteDS.Schools.registerNewStudent($student) // OK $id:=$remoteDS.Schools.computeIDNumber() // Error "Unknown member method" ``` -## onHTTPGet keyword +## `onHTTPGet` keyword Use the `onHTTPGet` keyword to declare functions that can be called through HTTP requests using the `GET` verb. Such functions can return any web contents, for example using the [`4D.OutgoingMessage`](../API/OutgoingMessageClass.md) class. @@ -1089,7 +1089,9 @@ The `exposed` keyword must also be added in this case, otherwise an error will b :::caution -As this type of call is an easy offered action, the developer must ensure no sensitive action is done in such functions. +`onHTTPGet` lets the function also be called with GET, for example by following a link. Depending on the session cookie's [`SameSite` value](../WebServer/webServerConfig.md#session-cookie-samesite), a link on another website can then send a request that runs in the session of the user logged in to your application. + +Use `onHTTPGet` only for functions that read and return content, such as a file to download, a picture or a report. Do not use `onHTTPGet` for a function that changes anything (i.e. that creates, modifies or deletes data, issues or revokes credentials, sends a message). ::: diff --git a/docs/REST/ClassFunctions.md b/docs/REST/ClassFunctions.md index b8176863d7ca0c..1f58c816d979ff 100644 --- a/docs/REST/ClassFunctions.md +++ b/docs/REST/ClassFunctions.md @@ -82,7 +82,11 @@ See [Exposed vs non-exposed functions](../ORDA/ordaClasses.md#exposed-vs-non-exp ### `onHTTPGet` -Functions allowed to be called from HTTP `GET` requests must also be specifically declared with the [`onHTTPGet` keyword](../ORDA/ordaClasses.md#onhttpget-keyword). For example: +Functions allowed to be called from HTTP `GET` requests must also be specifically declared with the [`onHTTPGet` keyword](../ORDA/ordaClasses.md#onhttpget-keyword). Functions declared with `exposed` alone can only be called with `POST`. + +Declare with `onHTTPGet` only functions that read and return content: depending on the session cookie's [`SameSite` value](../WebServer/webServerConfig.md#session-cookie-samesite), a link on another website can send a request that runs in the session of a logged-in user (see the caution in [`onHTTPGet` keyword section](../ORDA/ordaClasses.md#onhttpget-keyword)). + +For example: ```4d //allowing GET requests diff --git a/docs/ViewPro/configuring.md b/docs/ViewPro/configuring.md index e33a7d61cb9049..fc7601e2dd879f 100644 --- a/docs/ViewPro/configuring.md +++ b/docs/ViewPro/configuring.md @@ -403,7 +403,7 @@ Watermark attributes are used to superimpose text or an image onto the 4D View P \* If using text type, pass the filepath (absolute or relative) of the image. If you pass a relative path, the file should be located next to the database structure file. In Windows, the file extension must be indicated. No matter the type used to set an image, the image itself (not a reference) is stored in the 4D View Pro area and is returned by [VP Get print info](commands/vp-get-print-info.md). -## Style Objects {#style-objects} {#style-objects} +## Style Objects {#style-objects} 4D View Pro style objects and style sheets allow you to control the graphical aspects and the look of your 4D View Pro documents. diff --git a/docs/WebServer/webServer.md b/docs/WebServer/webServer.md index 4def5c935bcf20..90dee70f4ab113 100644 --- a/docs/WebServer/webServer.md +++ b/docs/WebServer/webServer.md @@ -6,11 +6,6 @@ title: Web Server 4D in local mode and 4D Server include a web server engine (aka http server) that enables you to design and publish powerful web applications that can make the most of your 4D databases. -:::warning Deprecated feature - - Using the web server on a remote 4D (4D client) is **deprecated** as of 4D 21. It is no longer recommended to use this feature. - -::: ## Easy Monitoring @@ -67,3 +62,9 @@ The 4D web server supports access to data stored in your 4D applications through `On Web Authentication`, `On Web Connection`, as well as `On REST Authentication` database methods are the entry points of requests in the web server; they can be used to evaluate and route any type of request. + +:::warning Deprecated feature + + Using the web server on a remote 4D (4D client) is **deprecated** as of 4D 21. It is no longer recommended to use this feature. + +::: diff --git a/docs/WebServer/webServerConfig.md b/docs/WebServer/webServerConfig.md index 80a10e74848074..5e463e809472ef 100644 --- a/docs/WebServer/webServerConfig.md +++ b/docs/WebServer/webServerConfig.md @@ -617,14 +617,31 @@ Value of the `SameSite` attribute value of the session cookie. This attribute al Three values are available: -- "Strict" (default `SameSite` attribute value for 4D session cookies): cookies will only be sent in the first-party context, i.e. context matching the domain of the current site, and never to third-party websites. -- "Lax": Cookies are not sent on cross-site subrequests (for example to load images or frames into a third-party site), but are sent when a user is navigating to the origin site (i.e. they follow a link). +- "Strict" (default `SameSite` attribute value for 4D session cookies): the session cookie is only sent with requests coming from pages of the same site, and never with requests coming from other websites. A "site" is a domain with all its subdomains, with the same scheme: `https://app.example.com` and `https://blog.example.com` are the same site, `http://app.example.com` is another one. +- "Lax": Cookies are not sent on cross-site subrequests (for example to load images or frames into a third-party site), but are sent when a user is navigating to the origin site with a GET request (i.e. they follow a link). - "None": Cookies are sent in all contexts, i.e in responses to both first-party and cross-origin requests. When "None" value is used, the cookie `Secure` attribute must also be set (or the cookie will be blocked). -The `Secure` attribute value of the session cookie is automatically set to "True" if the connection is HTTPS (whatever the `SameSite` attribute value). +#### Effect on exposed functions -> It is not recommended to set `SameSite=None` on a HTTP server since the `Secure` attribute will be missing (used in HTTPS only) and cookies will be blocked. +Any web page open in a user's browser can make that browser send requests to your application. If the user has opened a 4D web session in the same browser, the `SameSite` value determines whether these requests carry the 4D session cookie: +- with the cookie, the request runs in the user's session. This can be intended (from an intranet portal, for example), but a malicious website can use it to act on behalf of the user (cross-site request forgery, CSRF); +- without the cookie, the request runs as a guest. +In both cases, the function is executed only if the privileges of that session allow it. + +|Request from another website to|"Strict"|"Lax"|"None"| +|---|---|---|---| +|an [exposed](../ORDA/ordaClasses.md#exposed-vs-non-exposed-functions) function (POST only)|Runs as a guest|Runs as a guest|Runs in the user's session (form, script)| +|an exposed [onHTTPGet](../ORDA/ordaClasses.md#onhttpget-keyword) function (GET and POST)|Runs as a guest|Runs in the user's session through a link or a redirection; as a guest otherwise|Runs in the user's session (link, redirection, image, form, script)| + + +:::note Notes + +- Keep in mind that a site includes its subdomains. Whatever the `SameSite` value, requests sent by pages of another application on your site (for example https://blog.example.com for https://app.example.com) run in the user's session. +- Use "None" only if your application must be used inside another website (for example in a frame), and check that each exposed function can safely run in the user's session when another website requests it. +- The `Secure` attribute value of the session cookie is automatically set to "True" if the connection is HTTPS (whatever the `SameSite` attribute value). It is not recommended to set `SameSite=None` on a HTTP server since the `Secure` attribute will be missing (used in HTTPS only) and cookies will be blocked. + +::: ## Use preemptive processes diff --git a/docs/language-legacy/4D Environment/set-database-parameter.md b/docs/language-legacy/4D Environment/set-database-parameter.md index 7463aa1174347b..39f50b5f7f46c3 100644 --- a/docs/language-legacy/4D Environment/set-database-parameter.md +++ b/docs/language-legacy/4D Environment/set-database-parameter.md @@ -812,9 +812,9 @@ Refer to example 2. **Kept between two sessions**: No -**Possible values**: Positive integer. Default value = 15, minimum value = 1. +**Possible values**: Positive integer. Default value = 900, minimum value = 60. -**Description**: Timeout in minutes for client/server sessions in the event of an unexpected disconnection from the QUIC network layer. This timeout is the period of time allowed for a session during which the connection between the server and the client can be automatically reestablished following an unintended disconnection. If, at the end of this timeout, the connection has not been reestablished. +**Description**: Timeout in seconds for client/server sessions in the event of an unexpected disconnection from the QUIC network layer. This timeout is the period of time allowed for a session during which the connection between the server and the client can be automatically reestablished following an unintended disconnection. If, at the end of this timeout, the connection has not been reestablished, the client session is closed with a message. This setting can only be set on 4D Server and applies to all new 4D remote sessions (existing sessions timeout value is untouched). diff --git a/docs/language-legacy/Forms/form-get-current-page.md b/docs/language-legacy/Forms/form-get-current-page.md index be0a9ba1c72451..4b681171317d8e 100644 --- a/docs/language-legacy/Forms/form-get-current-page.md +++ b/docs/language-legacy/Forms/form-get-current-page.md @@ -32,7 +32,7 @@ displayed_sidebar: docs The **FORM Get current page** command returns the number of the currently displayed form page or of the current form loaded by the [FORM LOAD](../commands/form-load) command. -The *\** parameter is useful when the command is called in the context of a page type subform containing several pages. In this case, when you pass this parameter, the command changes the page of the current subform (the one that called the command). By default, when the *\** parameter is omitted, the command is always applied to the parent form. +The *\** parameter is useful when the command is called in the context of a page type subform containing several pages. In this case, when you pass this parameter, the command returns the page number of the current subform (the one that called the command). By default, when the *\** parameter is omitted, the command is always applied to the parent form. ## Example diff --git a/docs/language-legacy/Selection/create-entity-selection.md b/docs/language-legacy/Selection/create-entity-selection.md index 75d089df2c725a..16d4ad76c10dff 100644 --- a/docs/language-legacy/Selection/create-entity-selection.md +++ b/docs/language-legacy/Selection/create-entity-selection.md @@ -32,6 +32,7 @@ displayed_sidebar: docs The `Create entity selection` command builds and returns a new, [alterable](../../ORDA/entities.md#shareable-or-alterable-entity-selections) entity selection related to the dataclass matching the given *dsTable*, according to the current selection of this table. + If the current selection is sorted, an [ordered](../../ORDA/dsMapping.md#ordered-or-unordered-entity-selection) entity selection is created (the order of the current selection is kept). If the current selection is unsorted, an unordered entity selection is created. If the *dsTable* is not exposed in [`ds`](../commands/ds), an error is returned. This command cannot be used with a Remote datastore. @@ -43,6 +44,16 @@ In the optional *settings* parameter, you can pass an object containing the foll |context|Text|Label for the [optimization context](../../ORDA/client-server-optimization.md) applied to the entity selection.| +:::info + +For performance reasons, in 4D single-user and 4D Server, the returned entity selection is directly connected to the current selection of *dsTable* (it is not a copy). Until the current selection is replaced, changes made to one are reflected in the other. For example, [`REDUCE SELECTION`](../commands/reduce-selection) shortens the entity selection, and [`.add()`](../../API/EntitySelectionClass.md#add) on the entity selection adds the entity to the current selection. To get an independent entity selection, call [`.copy()`](../../API/EntitySelectionClass.md#copy) on the result: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Example ```4d diff --git a/docs/language-legacy/Web Server/web-get-body-part.md b/docs/language-legacy/Web Server/web-get-body-part.md index ac613bb721ec65..c83c16eeb7ac90 100644 --- a/docs/language-legacy/Web Server/web-get-body-part.md +++ b/docs/language-legacy/Web Server/web-get-body-part.md @@ -39,8 +39,8 @@ The *contents* parameter receives the contents of the part. When the parts to be The *name* parameter receives the variable name of the HTTP input field. -The *mimeType* and *name* parameters receive the Mime type and the name of the original file, if any. A *name* is only received when the file was submitted as ``. -*mimeType* and *name* are optional but must be passed together. +The *mimeType* and *fileName* parameters receive the Mime type and the name of the original file, if any. A *fileName* is only received when the file was submitted as ``. +*mimeType* and *fileName* are optional but must be passed together. **Note:** In the context of a multi-part request, the first array of the [WEB GET VARIABLES](../commands/web-get-variables) command returns all parts of the form, in the same order as the **WEB GET BODY PART** command. You can use it in order to get the position of the parts of the form directly. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/assets/en/Develop/index-add.png b/i18n/es/docusaurus-plugin-content-docs/current/assets/en/Develop/index-add.png new file mode 100644 index 00000000000000..05e72c5f179854 Binary files /dev/null and b/i18n/es/docusaurus-plugin-content-docs/current/assets/en/Develop/index-add.png differ diff --git a/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Settings.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Settings.md new file mode 100644 index 00000000000000..c7a4cef3f972f3 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Settings.md @@ -0,0 +1,184 @@ +--- +id: settings +title: Propiedades +--- + +# Propiedades + +The `Settings` class is the persisted configuration for the embedding pipeline. It loads and saves a JSON file (default: `Settings/embeddings.json`, overridable with the `EMBEDDINGS_SETTINGS_PATH` environment variable) containing a list of [Definition](Definition.md) entries, a batch size, and phrase-validation options. + +## Propiedades + +| Nombre de la propiedad | Tipo | Descripción | +| ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `definitions` | Collection of [Definition](Definition.md) | The configured definitions. | +| `batchSize` | Integer | Chunk size used by [Process.processEntitySelection](Process.md#processentityselection). Default: `50`. | +| `phrase` | Object | Phrase-validation options (see below). | +| `embedder` | Object | Optional embedder configuration (see below). | +| `file` | 4D.File *(read-only)* | The backing file the settings are loaded from and saved to. | + +### phrase options + +Passed verbatim to [Phrase.validate()](Phrase.md#validate) whenever the pipeline validates a definition. + +| Campo | Tipo | Por defecto | Descripción | +| ----------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------- | +| `allowRelations` | Boolean | `False` | Allow dot-notation through N:1 / 1:1 relations. | +| `allowCalculated` | Boolean | `False` | Allow calculated attributes in phrases. | +| `allowAlias` | Boolean | `False` | Allow alias attributes in phrases. | +| `allowObject` | Boolean | `False` | Allow object attributes in phrases. | + +> **Invalidation caveat.** Dirty-flag tracking only covers direct scalar fields on the entity. Fields that are only reachable through one of these options — a related entity's attribute, a calculated value, an alias, or a sub-property of an object — will **not** automatically mark the entity as dirty when they change. If such fields are part of a phrase and their source data changes, the vector will not be recomputed unless you call `invalidateVectors()` explicitly or use `force: true` when processing. + +### embedder options + +Controls how [Process](Process.md) builds its embedder. When absent, a default `Embedder` is created with its own defaults. + +| Campo | Tipo | Por defecto | Descripción | +| ------------ | ------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `className` | Text | — | Name of a project class to instantiate instead of the built-in `Embedder`. The class must expose `embed` and `embedBatch` functions. If instantiation fails or the interface is missing, a diagnostic error is logged and the default `Embedder` is used as fallback. | +| `maxRetries` | Integer | `3` | Number of retry attempts on rate-limit errors (forwarded to `Embedder`). | +| `backoffMs` | Integer | `500` | Base back-off delay in ms, doubled each retry (forwarded to `Embedder`). | + +Any additional keys are forwarded as-is to the constructor of the target class (built-in or custom). + +## Formato del archivo + +```json +{ + "batchSize": 50, + "phrase": { + "allowRelations": false, + "allowCalculated": false, + "allowAlias": false, + "allowObject": false + }, + "embedder": { + "maxRetries": 5, + "backoffMs": 200 + }, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding-3-small", + "phrase": "Student {firstName} {lastName}", + "autoInvalidate": true + } + ] +} +``` + +Each definition may include `autoInvalidate` (`true` by default) to control save-time automatic invalidation. + +The same file also carries the `scheduler` key (see [Scheduler](Scheduler.md#configuration)) and any other top-level key you add: `Settings` reads and rewrites only the keys listed above and leaves the rest untouched. + +With a custom embedder class: + +```json +{ + "embedder": { + "className": "MyCustomEmbedder" + }, + "definitions": [...] +} +``` + +## Class constructor + +Create a settings instance. The configuration file is loaded immediately. + +| Nombre del argumento | Tipo | Descripción | +| -------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| *file* | 4D.File | Opcional. A file to use instead of the default location. The override applies process-wide for subsequent settings access. **Not supported in 4D Remote mode** — pass it only when running locally or on the server. | + +When *file* is omitted, the default location is used: `Settings/embeddings.json`, or the path given by the `EMBEDDINGS_SETTINGS_PATH` environment variable. + +```4d +// Default location +var $settings:=cs.EmbeddingStudio.Settings.new() + +// Custom file (server / mono only) +var $settings:=cs.EmbeddingStudio.Settings.new(File("/some/path/custom.json")) +``` + +## Funciones + +### load() + +**load**() + +Reload the backing file into memory, overwriting in-memory state. A missing file resets to defaults without raising. + +A file that **exists but cannot be parsed** also leaves the instance on defaults, but it is remembered: an error is logged and [`save()`](#save) then refuses to write, so a malformed file is never silently replaced by defaults. + +### save() + +**save**() : Boolean + +Serialize the current in-memory state to the backing file. Only the keys this class owns (`batchSize`, `phrase`, `embedder`, `definitions`) are written — every other top-level key present in the file (the `scheduler` configuration, model aliases…) is preserved as-is. A key whose value is back to its default is *removed* from the file rather than written. + +Definitions are merged with what the file holds at that instant, using the snapshot taken at load time as the common ancestor: two editors open at the same time no longer drop each other's definitions. + +| Resultado | Tipo | Descripción | +| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| resultado | Boolean | `True` when written. `False` — nothing written — when the file could not be read at load time. | + +```4d +$settings.definitions.push(cs.EmbeddingStudio.Definition.new("Students"; "student_vector_1"; "text-embedding-3-small"; "{firstName}")) +$settings.batchSize:=100 +$settings.save() +``` + +### find() + +**find**(*dataclassName* : Text ; *vectorName* : Text) : [Definition](Definition.md) + +Look up the saved definition for the given dataclass/vector pair. + +| Argumento | Tipo | Descripción | +| --------------- | --------------------------- | ------------------------------------------------------------------- | +| *dataclassName* | Text | Nombre de la dataclass. | +| *vectorName* | Text | Name of the vector field on that dataclass. | +| Resultado | [Definition](Definition.md) | The matching definition, or `Null` if none matches. | + +```4d +var $def:=$settings.find("Students"; "student_vector_1") +``` + +### findAll() + +**findAll**(*dataclassName* : Text) : Collection of [Definition](Definition.md) + +Return every saved definition configured for the given dataclass. + +| Argumento | Tipo | Descripción | +| --------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------- | +| *dataclassName* | Text | Nombre de la dataclass. | +| Resultado | Collection of [Definition](Definition.md) | All matching definitions (empty collection if none match). | + +```4d +var $defs:=$settings.findAll("Students") +// → every Students definition; used by Process.process(ds.Students) +``` + +### invalidateVectors() + +**invalidateVectors**() : Object + +Calls [`invalidateVectors()`](Definition.md#invalidatevectors) on every definition in `definitions` and merges the results into a single status object. + +| Argumento | Tipo | Descripción | +| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | +| Resultado | Object | `{updated: Integer, skipped: Integer, errors: Collection of Text}` — accumulated across all definitions. | + +```4d +var $result:=cs.EmbeddingStudio.Settings.new().invalidateVectors() +// → { updated: 120; skipped: 0; errors: [] } +``` + +## Ver también + +- [Definition](Definition.md) +- [Process](Process.md) +- [Phrase](Phrase.md) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/StudioEmbedder.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/StudioEmbedder.md new file mode 100644 index 00000000000000..96e099d3e1461b --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/StudioEmbedder.md @@ -0,0 +1,125 @@ +--- +id: studioembedder +title: StudioEmbedder +--- + +# StudioEmbedder + +The `StudioEmbedder` class renders and embeds on demand, resolved against the Studio settings: a saved definition gives the phrase and the model, so the vector you compute matches the ones stored by [Process](Process.md). Nothing is persisted. Typical uses: building the vector of a search query, finding entities similar to a given one, or previewing the text sent for an entity. + +For the full batch pipeline that persists vectors on entities, see [Process](Process.md). + +## Propiedades + +| Nombre de la propiedad | Tipo | Descripción | +| ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------------- | +| `propiedades` | [Settings](Settings.md) | The settings (vectors, batch size, phrase validation options). | +| `embedder` | [Embedder](Embedder.md) | The API-calling engine. Stateless and swappable. | +| `opciones` | Object | Runtime options object. | + +## Class constructor + +| Nombre del argumento | Tipo | Descripción | +| -------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| *settings* | [Settings](Settings.md) | Opcional. If omitted, settings are loaded from the default `Settings/embeddings.json`. | +| *opciones* | Object | Optional runtime options. Supports `embedder` for injection. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings) +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings; {embedder: $mockEmbedder}) +``` + +## Funciones + +### render() + +**render**(*entity* : 4D.Entity ; *definitionOrPhrase* : Variant) : Text + +Return the text that [`embed()`](#embed) sends for an entity (the phrase rendered against it). No API call, no persistence. + +| Argumento | Tipo | Descripción | +| -------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *entity* | 4D.Entity | The entity to render against. | +| *definitionOrPhrase* | `Null`, [Phrase](Phrase.md), [Definition](Definition.md), Text, or plain object stub | `Null` → auto-resolve via settings (requires a unique match). Text → compiled as a throwaway `cs.EmbeddingStudio.Phrase`. Object stub → see [stub resolution](#stub-resolution). | +| Resultado | Text | The rendered text. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $text: Text +$text:=$studioEmbedder.render($student; $def) // use def's phrase +$text:=$studioEmbedder.render($student; cs.EmbeddingStudio.Phrase.new("Hi {firstName}")) +$text:=$studioEmbedder.render($student; "Student: {lastName}") // raw template +$text:=$studioEmbedder.render($student) // auto-resolve +$text:=$studioEmbedder.render($student; {vectorName: "student_vector_1"}) // stub → saved definition's phrase +$text:=$studioEmbedder.render($student; {phrase: "Hi {firstName}"}) // ad-hoc stub → inline template +``` + +### embed() + +**embed**(*input* : Variant ; *context* : Variant ; *model* : Text) : [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) + +Compute a vector for an arbitrary input, without persisting anywhere. + +| Argumento | Tipo | Descripción | +| --------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| *entrada* | Text or 4D.Entity | Text → embedded directly. Entity → phrase rendered then embedded. | +| *context* | Text, [Phrase](Phrase.md), [Definition](Definition.md), Text template, plain object stub, or `Null` | Provides phrase and/or model depending on *input*. Object stub → see [stub resolution](#stub-resolution). | +| *model* | Text | Optional explicit model name. Used when *context* does not carry one. | +| Resultado | [EmbedderResult](EmbedderResult.md) | The embedding result (use `.vector` to get the 4D.Vector). | + +Throws if no model can be determined. + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $vector: 4D.Vector + +// Text + model +$vector:=$studioEmbedder.embed("some text"; "text-embedding-3-small").vector + +// Text + definition (picks up def.modelAlias) +$vector:=$studioEmbedder.embed("some text"; $def).vector + +// Entity + definition (uses def.phrase + def.modelAlias) +$vector:=$studioEmbedder.embed($student; $def).vector + +// Entity + phrase + explicit model +$vector:=$studioEmbedder.embed($student; $phrase; "text-embedding-3-small").vector + +// Entity + ad-hoc template + model +$vector:=$studioEmbedder.embed($student; "Profile: {firstName} {lastName}"; "text-embedding-3-small").vector + +// Entity alone (auto-resolve, only when exactly one def matches the dataclass) +$vector:=$studioEmbedder.embed($student).vector + +// Entity + stub (deduces phrase + model from the matching saved definition) +$vector:=$studioEmbedder.embed($student; {vectorName: "student_vector_1"}).vector + +// Entity + ad-hoc stub (phrase compiled inline, model taken from the stub) +$vector:=$studioEmbedder.embed($student; {phrase: "Hi {firstName}"; modelAlias: "text-embedding-3-small"}).vector + +// Text + stub that only supplies the model +$vector:=$studioEmbedder.embed("some text"; {modelAlias: "text-embedding-3-small"}).vector +``` + +## Stub resolution + +Both `render()` and `embed()` accept a plain object in place of a `Phrase`/`Definition`. A stub is resolved the same way [`Process`](Process.md#definition-resolution-entity-context) resolves its `definition` argument, so the behavior matches. Two flavors are supported: + +| Stub | Resolves to | +| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `{vectorName: "..."}` (optionally `{dataclassName: "..."}`) | The matching **saved definition** for the entity's dataclass — deducing its phrase (and, for `embed`, its model). Resolves to nothing when there is no unique match. | +| `{phrase: "tpl {field}"}` or `{template: "tpl {field}"}` | An **ad-hoc** `Phrase` compiled inline; nothing is looked up. Pair with `{modelAlias: "..."}` to give `embed()` a model. | + +For `embed()`, the model is deduced in this order: an explicit `{modelAlias}` on the stub → the model of a stub-matched saved definition → the *model* argument → the entity's unique definition. An explicit `{modelAlias}` always wins. + +Unlike [`Process.process()`](Process.md#process-resolution), a stub is **not** turned into a brand-new `Definition` from its fields — `StudioEmbedder` persists nothing, so use `{phrase}`/`{template}` for one-off templates. + +## Ver también + +- [Process](Process.md) +- [Settings](Settings.md) +- [Definition](Definition.md) +- [Embedder](Embedder.md) +- [EmbedderResult](EmbedderResult.md) +- [Phrase](Phrase.md) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/license.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/license.md new file mode 100644 index 00000000000000..8f6fc0dd2b5ffc --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/license.md @@ -0,0 +1,167 @@ +--- +id: license +title: SOFTWARE LICENSE AGREEMENT +--- + +# SOFTWARE LICENSE AGREEMENT + +## Preamble + +The purpose of this Software license agreement is to grant users the right to modify and re-use the software governed by this license. + +The exercising of this right is conditional upon the obligation to make /available to the community the modifications made to the source code of the software so as to contribute to its evolution. + +In consideration of access to the source code and the rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software's author, the holder of the economic rights, and the successive licensors only have limited liability. + +## Article 1 – DEFINITIONS + +***Agreement***: means this license agreement, and its possible subsequent versions and annexes. + +***Software***: means the software in its Object Code and/or Source Code form and, where applicable, its documentation, "as is" when the Licensee accepts the Agreement. + +***Initial Software***: means the Software in its Source Code and possibly its Object Code form and, where applicable, its documentation, "as is" when it is first distributed under the terms and conditions of the Agreement. + +***Modified Software***: means the Software modified by at least one Integrated Contribution. + +***Source Code***: means all the Software's instructions and program lines to which access is required so as to modify the Software. + +***Object Code***: means the binary files originating from the compilation of the Source Code. + +***Holder***: means the holder(s) of the economic rights over the Initial Software, in this case it is 4D SAS. + +***Licensee***: means the Software user(s) having accepted the Agreement. + +***Contributor***: means a Licensee having made at least one Integrated Contribution. + +***Licensor***: means the Holder, or any other individual or legal entity, who distributes the Software under the Agreement. + +***Integrated Contribution***: means new functions integrated into the Source Code by any or all Contributors. + +***Parties***: mean both the Licensee and the Licensor. + +These expressions may be used both in singular and plural form. + +## Article 2 - PURPOSE + +The purpose of the Agreement is the grant by the Licensor to the Licensee of a non-exclusive, transferable and worldwide license for the Software as set forth in Article 5 hereinafter for the whole term of the protection granted by the rights over said Software. + +## Article 3 - ACCEPTANCE + +The Licensee shall be deemed as having accepted the terms and conditions of this Agreement upon the occurrence of the first of the following events: + +- loading the Software by any or all means, notably, by downloading from a remote server; +- the first time the Licensee exercises any of the rights granted hereunder. + +## Article 4 - EFFECTIVE DATE AND TERM + +### 4.1 EFFECTIVE DATE + +The Agreement shall become effective on the date when it is accepted by the Licensee as set forth in Article 3. + +### 4.2 TERM + +The Agreement shall remain in force for the entire legal term of protection of the economic rights over the Software. + +## Article 5 - SCOPE OF RIGHTS GRANTED + +The Licensor hereby grants to the Licensee, who accepts, the following rights over the Software for the term of the Agreement, on the basis of the terms and conditions set forth hereinafter. + +### 5.1 RIGHT OF USE + +The Licensee is authorized to use the Software, without any limitation as to its fields of application, with it being hereinafter specified that this comprises: + +- permanent or temporary reproduction of all or part of the Software by any or all means and in any or all form. +- loading, displaying, running, or storing the Software on any or all medium. +- entitlement to observe, study or test its operation. + +### 5.2 RIGHT OF MODIFICATION + +The right of modification means the right to adapt, arrange, or make any or all modifications to the Software; being understood that such modifications of the Software shall results in a change of its functionalities and/or in an addition of functionalities to the Initial Software. + +Consequently to distribute a Modified Software according to the provision of section 5.3.2, the Licensee shall make exclusively significant modification as described above to the Software provided that it includes an explicit notice that it is the author of said modification and indicates the date of the creation thereof. + +### 5.3 RIGHT OF DISTRIBUTION + +In particular, the right of distribution includes the right to publish, transmit and communicate the Modified Software to the general public on any or all medium, and by any or all means, and the right to market, either in consideration of a fee, or + +#### 5.3.1 DISTRIBUTION OF SOFTWARE WITHOUT MODIFICATION + +The Licensee is forbidden to distribute true copies of the Software in Source Code or Object Code form. + +#### 5.3.2 DISTRIBUTION OF MODIFIED SOFTWARE + +When the Licensee creates Modified Software, this Modified Software may be distributed provided that said distribution complies with all the provisions of the Agreement and subject to compliance with the requirement to include a notice concerning the rights over the Software as defined in Article 6.3. + +In the event the creation of the Modified Software, the Licensee undertakes that: + +- the resulting Modified Software will be governed by this Agreement, being understood that such Agreement shall be integrated in the Modified Software the Integrated Contributions in the resulting Modified Software will be clearly identified and documented, +- the Licensee will allow effective access to the source code of the Modified Software, at a minimum during the entire period of distribution of the Derivative Software, such that such modifications may be carried over in a subsequent version of the Software. +- the Modified Software must be renamed to exclude any reference to 4D. For example, it is expressly prohibited to distribute a Modified Software named “4D SVG”; Licensee shall rename the Modified Software such as “Name of the Licensee SVG”. Consequently, Licensee is expressly forbidden to use 4D’s product name in general to promote his modified work. + +## Article 6 - INTELLECTUAL PROPERTY + +### 6.1 OVER THE INITIAL SOFTWARE + +The Holder owns the intellectual property rights over the Initial Software. Any or all use of the Initial Software is subject to compliance with the terms and conditions under which the Holder has elected to distribute its work and no one shall be entitled to modify the terms and conditions for the distribution of said Initial Software. + +### 6.2 OVER THE INTEGRATED CONTRIBUTIONS + +The Licensee who develops an Integrated Contribution is the owner of the intellectual property rights over this Contribution as defined by applicable law. + +### 6.3 NOTICE OF RIGHTS + +The Licensee expressly undertakes: + +- not to remove, or modify, in any manner, the intellectual property notices attached to the Software; +- to reproduce said notices, in an identical manner, in the copies of the Software modified; +- to ensure that use of the Software, its intellectual property notices and the fact that it is governed by the Agreement is indicated in a text that is easily accessible, specifically from the interface of any Modified Software. + +The Licensee undertakes not to directly or indirectly infringe the intellectual property rights of the Holder on the Software and to take, where applicable, vis- à-vis its staff, any and all measures required to ensure respect of said intellectual property rights of the Holder. + +## Article 7 - RELATED SERVICES + +Under no circumstances shall the Agreement oblige the Licensor to provide technical assistance or maintenance services for the Software. + +However, the Licensor is entitled to offer this type of services. The terms and conditions of such technical assistance, and/or such maintenance, shall be set forth in a separate instrument. + +## Article 8 - DISCLAIMER OF WARRANTY. + +THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE HOLDER PROVIDES THE SOFTWARE “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH LICENSEE. SHOULD THE SOFTWARE PROVE DEFECTIVE, LICENSEE ASSUMES THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +## Article 9 - LIMITATION OF LIABILITY + +TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE TO LICENSEE ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS AGREEMENT OR USE OF THE SOFTWARE, EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR DAMAGES. + +## Article 10 – TERMINATION + +### 10.1 + +In the event of a breach by the Licensee of its obligations hereunder, the Licensor may automatically terminate this Agreement thirty (30) days after notice has been sent to the Licensee and has remained ineffective. + +### 10.2 + +A Licensee whose Agreement is terminated shall no longer be authorized to use, modify or distribute the Software. However, any licenses that it may have granted prior to termination of the Agreement shall remain valid subject to their having been granted in compliance with the terms and conditions hereof. + +## Article 11 – MISCELLANEOUS + +### 11.1 + +Neither Party shall be liable for any or all delay, or failure to perform the Agreement, that may be attributable to an event of force majeure, an act of God or an outside cause, such as defective functioning or interruptions of the electricity or telecommunications networks, network paralysis following a virus attack, intervention by government authorities, natural disasters, water damage, earthquakes, fire, explosions, strikes and labor unrest, war, etc. + +### 11.2 + +Any failure by either Party, on one or more occasions, to invoke one or more of the provisions hereof, shall under no circumstances be interpreted as being a waiver by the interested Party of its right to invoke said provision(s) subsequently. + +### 11.3 + +In the event that one or more of the provisions hereof were to conflict with a current or future applicable act or legislative text, said act or legislative text shall prevail, and the Parties shall make the necessary amendments so as to comply with said act or legislative text. All other provisions shall remain effective. Similarly, invalidity of a provision of the Agreement, for any reason whatsoever, shall not cause the Agreement as a whole to be invalid. + +## Article 12 - GOVERNING LAW AND JURISDICTION + +### 12.1 + +The Agreement is governed by French law. The Parties agree to endeavor to seek an amicable solution to any disagreements or disputes that may arise during the performance of the Agreement. + +### 12.2 + +Failing an amicable solution within two (2) months as from their occurrence, and unless emergency proceedings are necessary, the disagreements or disputes shall be referred to the Versailles Courts having jurisdiction, by the more diligent Party. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/overview.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/overview.md new file mode 100644 index 00000000000000..a45d58e4af31a5 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/overview.md @@ -0,0 +1,211 @@ +--- +id: overview +title: 4D-Embedding-Studio +--- + +# 4D-Embedding-Studio + +## Generalidades + +4D Embedding Studio is a component for defining, processing, and maintaining AI embedding vectors directly in your 4D dataclass entities. + +You can use the component without writing a single line of code: select attributes from your dataclasses to construct the sentences to be vectorized and specify the model to use. For each entity, the component calls the embedding API and stores the resulting `4D.Vector` values. Configure the embedding scheduler to (re)calculate the vectors for your data at fixed intervals or on demand. + +You can then use the ORDA [`query()` by vector feature](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity) to request your data using semantics. + +If you want to have more control over your embeddings, the component offers an extensive API that allows you to customize each step of the data vectorization process, manage the scheduler, and integrate high-performance RAG (*Retrieval Augmented Generation*) features into your 4D application. + +## Requisitos + +- [4D-AIKit](https://github.com/4d/4D-AIKit) (loaded automatically as a dependency). +- 4D project (21 R5 or later) with the following configuration: + - a valid model alias + - a dataclass with a `4D.Vector` attribute (object field at the database level). + +## Quick Start + +**1. Add a field of type Object to the table and associate it with the `4D.Vector` class.** +**2. Select **Embedding Studio...** in the **Design** menu to display the Embedding Studio window.** + +![menu](../assets/en/embedding-studio/menu.png) + +**3. For each listed `4D.Vector` attribute, write a descriptive phrase based upon attributes of the dataclass.** +Use the contextual menu to insert appropriate attributes. +This phrase will be vectorized for every entity. +**4. Select a model alias (or create a new one).** +**5. Select "Execute now" to launch the vectorization of your data or configure the scheduler.** + +## User Guide + +### Configuring the dataclass + +To use the 4D Embedding Studio interface, you need to create at least one object attribute associated to a `4D.Vector` class in your datastore. This must be done at the database level (only storage attributes can be embeddings). + +In the Structure editor, add an Object field to the dataclass (table) whose entities you want to query using AI and enter ["4D.Vector" as class](https://developer.4d.com/docs/Develop/structure-fields#class). + +#### Dirty-flag support + +In a production application, data is rarely static. If an embedding is based on an attribute value that has changed (e.g. a product description), it becomes obsolete and could no longer be relevant. By default, 4D automatically invalidates and flags for recalculation affected embeddings. + +If you do not use a dirty-flag field (see below), 4D simply replaces any invalidated vector by `Null`. It is therefore no longer used in searches until its next calculation. This option is suitable for applications that prioritize strict consistency: it is better to return no results than to rely on an embedding that no longer matches the current data. + +Or, you can add a Boolean field named `_dirty` (e.g. "myVector_dirty") to the structure. In this case, when an update is required, this field is set to `True`, and the associated vector is retained until it is recalculated. Your application can then choose to continue using this vector temporarily or exclude it using a filter on `dirty = False`. The flag is cleared automatically after a successful save. +This strategy promotes service continuity while allowing you to precisely identify vectors awaiting recalculation. If your business logic requires full control, you can also disable automatic invalidation and manage this lifecycle yourself. + +*Note: Certain modifications, such as a model changes, require vectors to be replaced immediately.* + +### Creating an embedding + +When you select **Embedding Studio...** in the **Design** menu, the Embedding Studio window is displayed. + +The list on the left side shows all `4D.Vector` class attributes defined in the datastore. You can add as many vector attributes as you want per dataclass. + +A check mark (✓) in the Dirty Flag column indicates that a [`_dirty` boolean field](#dirty-flag-support) is associated to the vector field. + +**Note:** Any change in the database structure will require that you restart the 4D application so that the 4D Embedding Studio lists up-to-date values. + +#### Writing a descriptive sentence + +To create or edit an embedding, select the attribute to configure in this list and write the embedding definition in the "Descriptive sentence" area on the right side. Use the associated menu to build the sentence and to add references to dataclass available attributes with the `{attribute_name}` syntax. + +The sentence must build a text that describes the entity just like a human would do it. The embedding could then capturate the semantics and not only attribute values. + +For example, for a `Product` dataclass with many attributes such as name and category, you could write: +"The {name} product is a {category} from the {brand} brand. Description: {description}. Key features: {features}." + +![menu](../assets/en/embedding-studio/studio-interface.png) + +### Selecting a model + +Once you have defined your vector attribute, choose the model to use for generating the embedding. The list of models includes the **model aliases** you defined in the [Project Settings](https://developer.4d.com/docs/settings/ai#model-aliases). + +The choice of model is important because it determines the relevance and quality of your embeddings. You’ll also need to provide this model with every query on the dataclass data so that the comparison is performed using the same model. + +### Auto-invalidate on save + +When this option is checked (default), embeddings are automatically invalidated when at least one of their definition attributes has been modified and the entity was successfully saved. + +However, you might want to handle invalidation in a custom way using the [4D Embedding Studio API](#api-guide). In this case, uncheck this option to disable the automatic mechanism. + +### Calculating embeddings + +Embeddings are calculated by sending a request to the AI model, which then returns the vectorization result, which is subsequently stored in the `4D.Vector` attribute in the dataclass. 4D automatically handles this operation and optimizes it by calculating only the necessary vectors. Each vector is processed independently. Thus, an error on one element does not interrupt the recalculation of the others. Elements that fail will be automatically retried during the next run. Recalculations are performed asynchronously, without blocking users. + +These calculations can be performed **on demand** or **scheduled at regular intervals** using the scheduler in the 4D Embedding Studio component. + +**Note:** You can also customize embedding calculations per dataclass or entity using the [4D Embedding Studio API](#api-guide). + +#### On demand + +To launch an embedding calculation, select **Run now** in the menu at the bottom of the 4D Embedding Studio window. This item is disabled if the datastore does not contain any embedding to calculate. When started, you can select **Cancel run** at any moment. + +#### Backups periódicos + +You can configure the 4D Embedding Studio component scheduler to adjust the calculation frequency to suit your application’s needs. + +**Important:** The scheduler needs a 4D worker process to run. You can start it manually for testing purposes (**Start now** button in the scheduler dialog box) but to make sure a worker is available every times the application opens, you need to configure it. Puede: + +- select the **Execute "On Host Database Event" method of the components** option in the [project Settings](https://developer.4d.com/docs/settings/security#options) +- or write the following code in your startup code: + +```4d + //at startup +cs.EmbeddingStudio.Scheduler.me.start() +``` + +The scheduler allows you can set the time interval between two calculations. Select the tab corresponding to your needs and click **Save**. + +- **Never**: the scheduler is off and never runs +- **At regular interval**: set the time interval between each calculation starting from a specified time. +- **Once a day**: the calculation takes place every day at a specific time + starting from a specific time. + +### Building queries with embeddings + +Once you have defined embeddings in your datastore, you can start [querying your dataclasses using AI-based features](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity). You just need to make sure that you use the same model for your embedding definition and in the query string. + +For example, assuming that: + +• you have defined a `4D.Vector` attribute named "product_vector" in the Products dataclass using a sentence: "The {name} is in the {category} category. It has these {features} features and can be used for {usage}." +• you want to find products that "can be used safely outside". + +Puede escribir: + +```4d +// Retrieve the model alias from the embedding definition, configured in 4D Embedding Studio +var $settings:=cs.EmbeddingStudio.Settings.new() +var $definition:=$settings.find("Products"; "product_vector") + +// Compute the vector of the query with the same model +var $result:=cs.EmbeddingStudio.StudioEmbedder.new().embed("products that can be used safely outside"; $definition) +var $vector:=$result.vector + + //search with default metric (cosine) +var $products:=ds.Products.query("product_vector > :1 order by product_vector desc"; {vector : $vector}) + +``` + +If you use a dirty field, simply add a criterion to exclude vectors waiting to be recalculated: + +```4d +var $products:=ds.Products.query("product_vector > :1 and product_vector_dirty = false order by product_vector desc"; {vector : $vector}) +``` + +## API Guide + +### Quick start + +**1. Configure your vectors** in `Settings/embeddings.json`: + +```json +{ + "batchSize": 50, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding", + "phrase": "Student {firstName} {lastName}, enrolled in {program}", + "autoInvalidate": true + } + ] +} +``` + +**2. Run the full pipeline** (all definitions, all records): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +var $r:=$p.process() + +If ($r.success) + ALERT("Updated "+String($r.entitiesUpdated)+" entities in "+String($r.duration)+" ms") +End if +``` + +**3. Process a single entity on save** (e.g. in a trigger or REST hook): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +$p.processEntity($entity) +``` + +### Class reference + +| Class | Descripción | +| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Process](Classes/Process.md) | Main orchestrator — entry point for all batch and entity operations. | +| [Scheduler](Classes/Scheduler.md) | Automated recalculation scheduler — background task, force/cancel, and runtime status. | +| [StudioEmbedder](Classes/StudioEmbedder.md) | Renders and embeds on demand using your saved definitions — e.g. to build a search query vector. Nothing is persisted. | +| [Settings](Classes/Settings.md) | Loads and saves the `embeddings.json` configuration file. | +| [Definition](Classes/Definition.md) | Describes one vector field: dataclass, field name, model alias, and phrase template. | +| [Embedder](Classes/Embedder.md) | Thin wrapper around the AIKit embeddings API with retry/backoff logic. | +| [EmbedderResult](Classes/EmbedderResult.md) | Typed wrapper normalizing API responses — vectors, usage metrics, rate-limit state. | +| [ProcessResult](Classes/ProcessResult.md) | Returned by every batch function — statistics and error breakdown. | +| [ProcessError](Classes/ProcessError.md) | Typed entry in `ProcessResult.errors` — scope, severity, code, ref, message, retryable. | +| [ProcessErrorCode](Classes/ProcessErrorCode.md) | Singleton catalogue of machine-readable error codes and their default severity/retryability. | +| [Phrase](Classes/Phrase.md) | Lightweight `{variable}` template engine used to build text from entity attributes. | + +### Ver también + +Blog post: [Vectorize your data effortlessly with 4D Embedding Studio](https://blog.4d.com/vectorize-your-data-effortlessly-with-4d-vector-studio) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/ratelimit.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/ratelimit.md new file mode 100644 index 00000000000000..ac90518d4805db --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/ratelimit.md @@ -0,0 +1,65 @@ +--- +id: ratelimit +title: Rate Limiting +--- + +# Rate Limiting + +The embedding pipeline includes built-in rate-limit awareness. When the API provider returns rate-limit headers (as OpenAI does), the system automatically throttles requests and adapts batch sizes to stay within budget. Providers that don't return rate-limit headers (e.g. Ollama) are unaffected — the pipeline runs at full speed. + +## Principios de funcionamiento + +Each call to [`Embedder.embed()`](Classes/Embedder.md) or [`Embedder.embedBatch()`](Classes/Embedder.md) returns an [`EmbedderResult`](Classes/EmbedderResult.md) that carries rate-limit state alongside the embedding vectors. The pipeline uses this data in a three-step loop: + +1. **Pre-flight throttle** — before sending a batch, the pipeline checks whether the remaining token budget is sufficient. If not, it waits for the reset window to elapse before proceeding. +2. **Adaptive batch sizing** — the pipeline computes the largest batch that fits within 80% of the remaining token budget. This avoids hitting the ceiling while still making efficient use of the quota. +3. **State update** — after each API response, the pipeline records the new remaining budget, computes an average tokens-per-entity estimate, and feeds both into the next iteration. + +## Rate-limit fields on EmbedderResult + +These fields are populated from the API response headers. When a provider doesn't return them, they keep their defaults and the pipeline skips throttling. + +| Campo | Por defecto | Significado | +| ------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `remainingTokens` | `-1` | Tokens left in the current window. `-1` = unknown. | +| `remainingRequests` | `-1` | Requests left in the current window. | +| `limitTokens` | `0` | TPM (tokens per minute) ceiling. | +| `limitRequests` | `0` | RPM (requests per minute) ceiling. | +| `resetTokens` | `""` | Time until the token bucket refills (e.g. `"6m0s"`, `"200ms"`). | +| `resetRequests` | `""` | Time until the request bucket refills. | + +## Batch size adaptation + +The pipeline starts with the configured `batchSize` (from [Settings](Classes/Settings.md), default 50). After the first API response provides rate-limit data, the batch size may shrink: + +``` +nextBatchSize = min( floor(remainingTokens × 0.8 / tokensPerEntity), configBatchSize ) +``` + +- `tokensPerEntity` is estimated from the last chunk (`totalTokens / chunkSize`). +- The result is clamped to a floor of 1 and a ceiling of `configBatchSize`. +- When `remainingTokens` is unknown (`-1`), the configured batch size is used as-is. + +## Pre-flight wait + +Before each batch, the pipeline checks: + +- **Token budget**: if `remainingTokens < estimatedTokens × 1.1`, it waits for the token reset window. +- **Request budget**: if `remainingRequests = 0`, it waits for the request reset window. + +The reset durations are parsed from the API's string format (`"6m0s"` → 360 seconds, `"200ms"` → 1 second). + +## Providers without rate limits + +Some providers (Ollama, local models) don't return rate-limit headers. En este caso: + +- `remainingTokens` stays at `-1` (unknown) +- No throttling occurs — batches run at `configBatchSize` without waits +- The pipeline works identically to how it did before rate-limit support was added + +## Ver también + +- [EmbedderResult](Classes/EmbedderResult.md) — carries rate-limit fields +- [Embedder](Classes/Embedder.md) — wraps the API calls +- [Process](Classes/Process.md) — orchestrates the batch loop +- [Settings](Classes/Settings.md) — `batchSize` configuration diff --git a/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md b/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md index c6067334c0f0f5..900114887825bc 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md @@ -822,7 +822,7 @@ Consulte el ejemplo 2. **Valores posibles**: entero positivo. Valor predeterminado = 900, valor mínimo = 60. -**Descripción**: tiempo de espera en segundos para las sesiones cliente/servidor en caso de desconexión inesperada al utilizar la capa de red QUIC. Este tiempo de espera es el período permitido para una sesión durante el cual la conexión entre el servidor y el cliente puede restablecerse automáticamente tras una desconexión involuntaria. Si, al final de este tiempo de espera, la conexión no se ha restablecido, la sesión se cierra. +**Descripción**: tiempo de espera en segundos para las sesiones cliente/servidor en caso de desconexión inesperada al utilizar la capa de red QUIC. Este tiempo de espera es el período permitido para una sesión durante el cual la conexión entre el servidor y el cliente puede restablecerse automáticamente tras una desconexión involuntaria. Si, al final de este tiempo de espera, la conexión no se ha restablecido, la sesión cliente se cierra con un mensaje. Este parámetro solo puede configurarse en 4D Server y se aplica a todas las nuevas sesiones remotas de 4D (el valor del tiempo de espera de las sesiones existentes no se modifica). diff --git a/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md b/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md index 9528b84eee6237..21bf395bf412c0 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md @@ -32,7 +32,7 @@ displayed_sidebar: docs El comando **FORM Get current page** devuelve el número de la página actual del formulario mostrada actualmente o del formulario actual cargado vía el comando [FORM LOAD](../commands/form-load). -El parámetro *\** es útil cuando el comando se llama en el contexto de un subformulario en página que contiene varias páginas. En este caso, cuando pase este parámetro, el comando cambia la página del subformulario actual (la que llamó al comando). Por defecto, cuando se omite el parámetro *\**, el comando se aplica siempre al formulario padre. +El parámetro *\** es útil cuando el comando se llama en el contexto de un subformulario en página que contiene varias páginas. En este caso, cuando pase este parámetro, el comando devuelve el número de página del subformulario actual (el que llamó al comando). Por defecto, cuando se omite el parámetro *\**, el comando se aplica siempre al formulario padre. ## Ejemplo diff --git a/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md b/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md index 1db113b0ca4fa3..b50965f4ee7173 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md @@ -45,6 +45,16 @@ En el parámetro opcional *settings*, puede pasar un objeto que contenga la sigu | --------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------- | | context | Text | Etiqueta para el [contexto de optimización](../../ORDA/client-server-optimization.md) aplicado a la selección de entidades. | +:::info + +Por razones de rendimiento, en 4D monopuesto y 4D Server, la selección de entidades devuelta está directamente conectada a la selección actual de *dsTable* (no es una copia). Mientras no se reemplace la selección actual, los cambios realizados en una se reflejan en la otra. Por ejemplo, [`REDUCE SELECTION`](../commands/reduce-selection) reduce la selección de entidades, y [`.add()`](../../API/EntitySelectionClass.md#add) aplicada a la selección de entidades añade la entidad a la selección actual. Para obtener una selección de entidades independiente, llame a [`.copy()`](../../API/EntitySelectionClass.md#copy) en el resultado: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Ejemplo ```4d diff --git a/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md b/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md index a2c50c144ca8cc..703167b16f1b66 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md @@ -39,7 +39,7 @@ El parámetro *contenido* recibe el contenido de la parte. Cuando las partes a r El parámetro *nombre* recupera el nombre de la variable del campo input HTTP. -Los parámetros *tipoMime* y *nomArchivo* reciben el tipo Mime y el nombre del archivo original, si lo hay. nomArchivo solo se recibe cuando el archivo se envio como ``. +Los parámetros *tipoMime* y *nomArchivo* reciben el tipo Mime y el nombre del archivo original, si lo hay. *nomArchivo* solo se recibe cuando el archivo se envió como ``. *tipoMime* y *nomArchivo* son opcionales pero deben pasarse juntos. **Nota**: en el contexto de una petición multi-part, el primer de array del comando [WEB GET VARIABLES](../commands/web-get-variables) devuelve todas las partes del formulario, en el mismo orden que el comando **WEB GET BODY PART**. Puede utilizarlo para obtener directamente la posición de una parte de un formulario. diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md index c6067334c0f0f5..900114887825bc 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md @@ -822,7 +822,7 @@ Consulte el ejemplo 2. **Valores posibles**: entero positivo. Valor predeterminado = 900, valor mínimo = 60. -**Descripción**: tiempo de espera en segundos para las sesiones cliente/servidor en caso de desconexión inesperada al utilizar la capa de red QUIC. Este tiempo de espera es el período permitido para una sesión durante el cual la conexión entre el servidor y el cliente puede restablecerse automáticamente tras una desconexión involuntaria. Si, al final de este tiempo de espera, la conexión no se ha restablecido, la sesión se cierra. +**Descripción**: tiempo de espera en segundos para las sesiones cliente/servidor en caso de desconexión inesperada al utilizar la capa de red QUIC. Este tiempo de espera es el período permitido para una sesión durante el cual la conexión entre el servidor y el cliente puede restablecerse automáticamente tras una desconexión involuntaria. Si, al final de este tiempo de espera, la conexión no se ha restablecido, la sesión cliente se cierra con un mensaje. Este parámetro solo puede configurarse en 4D Server y se aplica a todas las nuevas sesiones remotas de 4D (el valor del tiempo de espera de las sesiones existentes no se modifica). diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md index 9528b84eee6237..21bf395bf412c0 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md @@ -32,7 +32,7 @@ displayed_sidebar: docs El comando **FORM Get current page** devuelve el número de la página actual del formulario mostrada actualmente o del formulario actual cargado vía el comando [FORM LOAD](../commands/form-load). -El parámetro *\** es útil cuando el comando se llama en el contexto de un subformulario en página que contiene varias páginas. En este caso, cuando pase este parámetro, el comando cambia la página del subformulario actual (la que llamó al comando). Por defecto, cuando se omite el parámetro *\**, el comando se aplica siempre al formulario padre. +El parámetro *\** es útil cuando el comando se llama en el contexto de un subformulario en página que contiene varias páginas. En este caso, cuando pase este parámetro, el comando devuelve el número de página del subformulario actual (el que llamó al comando). Por defecto, cuando se omite el parámetro *\**, el comando se aplica siempre al formulario padre. ## Ejemplo diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md index 1db113b0ca4fa3..b50965f4ee7173 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md @@ -45,6 +45,16 @@ En el parámetro opcional *settings*, puede pasar un objeto que contenga la sigu | --------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------- | | context | Text | Etiqueta para el [contexto de optimización](../../ORDA/client-server-optimization.md) aplicado a la selección de entidades. | +:::info + +Por razones de rendimiento, en 4D monopuesto y 4D Server, la selección de entidades devuelta está directamente conectada a la selección actual de *dsTable* (no es una copia). Mientras no se reemplace la selección actual, los cambios realizados en una se reflejan en la otra. Por ejemplo, [`REDUCE SELECTION`](../commands/reduce-selection) reduce la selección de entidades, y [`.add()`](../../API/EntitySelectionClass.md#add) aplicada a la selección de entidades añade la entidad a la selección actual. Para obtener una selección de entidades independiente, llame a [`.copy()`](../../API/EntitySelectionClass.md#copy) en el resultado: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Ejemplo ```4d diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md index a2c50c144ca8cc..703167b16f1b66 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md @@ -39,7 +39,7 @@ El parámetro *contenido* recibe el contenido de la parte. Cuando las partes a r El parámetro *nombre* recupera el nombre de la variable del campo input HTTP. -Los parámetros *tipoMime* y *nomArchivo* reciben el tipo Mime y el nombre del archivo original, si lo hay. nomArchivo solo se recibe cuando el archivo se envio como ``. +Los parámetros *tipoMime* y *nomArchivo* reciben el tipo Mime y el nombre del archivo original, si lo hay. *nomArchivo* solo se recibe cuando el archivo se envió como ``. *tipoMime* y *nomArchivo* son opcionales pero deben pasarse juntos. **Nota**: en el contexto de una petición multi-part, el primer de array del comando [WEB GET VARIABLES](../commands/web-get-variables) devuelve todas las partes del formulario, en el mismo orden que el comando **WEB GET BODY PART**. Puede utilizarlo para obtener directamente la posición de una parte de un formulario. diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/menu.png b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/menu.png new file mode 100644 index 00000000000000..425fd0d7e65879 Binary files /dev/null and b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/menu.png differ diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/studio-interface.png b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/studio-interface.png new file mode 100644 index 00000000000000..75dae7c9303297 Binary files /dev/null and b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/studio-interface.png differ diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Definition.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Definition.md new file mode 100644 index 00000000000000..0c3a6c37dd4a37 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Definition.md @@ -0,0 +1,165 @@ +--- +id: definition +title: Definición +--- + +# Definición + +The `Definition` class describes how a single vector field on a dataclass should be computed: which dataclass, which vector field, which model alias, and which text template ([Phrase](Phrase.md)) to render from each entity. + +A collection of these is what [Settings](Settings.md) persists. + +## Propiedades + +| Nombre de la propiedad | Tipo | Descripción | +| ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| `dataclassName` | Text | Name of the target dataclass. | +| `vectorName` | Text | Name of the `4D.Vector` field on that dataclass. | +| `modelAlias` | Text | Embedding model alias (e.g. `"text-embedding-3-small"`). | +| `phrase` | [Phrase](Phrase.md) | Compiled template used to build the text that will be embedded. | +| `autoInvalidate` | Boolean | Controls automatic invalidation on entity save. Default: `True`. | + +## Class constructor + +Create a definition. + +| Nombre del argumento | Tipo | Descripción | +| -------------------- | ---- | -------------------------------------------------------------------------------------------------- | +| *dataclassName* | Text | Name of the target dataclass. | +| *vectorName* | Text | Name of the target vector field. | +| *modelAlias* | Text | Embedding model alias. | +| *phraseTemplate* | Text | Phrase template with `{field}` placeholders — compiled into a [Phrase](Phrase.md). | + +```4d +var $def:=cs.EmbeddingStudio.Definition.new(\ + "Students"; \ + "student_vector_1"; \ + "text-embedding-3-small"; \ + "Student {firstName} {lastName}") +``` + +## Propiedades calculadas + +### hasDefinition + +**hasDefinition** : Boolean *(read-only)* + +Returns `True` if at least a model or a phrase template has been set. A definition without either has no content to process. + +```4d +If ($def.hasDefinition) + // worth validating further +End if +``` + +## Funciones + +### validate() + +**validate**( *settings* : Settings ) : Object + +Validates the definition against the live datastore model and the known embedding models. All errors are collected before returning — the result always describes the full set of problems found. + +| Argumento | Tipo | Descripción | +| ---------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| *settings* | [Settings](Settings.md) \| Null | Used to pass phrase validation options. Pass `Null` to skip phrase options. | +| Resultado | Object | `{success: Boolean, errors: Collection}` where each error is `{field: Text, message: Text}`. | + +Checked in order: + +| Check | `field` value | +| ------------------------------------ | ----------------- | +| `dataclassName` is not empty | `"dataclassName"` | +| `vectorName` is not empty | `"vectorName"` | +| `modelAlias` is set and recognised | `"modelAlias"` | +| Dataclass exists in `ds` | `"dataclassName"` | +| Vector field exists | `"vectorName"` | +| Field type is `4D.Vector` | `"vectorName"` | +| Phrase template is not empty | `"phrase"` | +| Phrase keys resolve in the dataclass | `"phrase"` | + +The first two checks (identity) return immediately on failure; the remaining checks accumulate so all problems are reported in one pass. + +```4d +var $result:=$def.validate(cs.EmbeddingStudio.Settings.new()) + +If (Not($result.success)) + var $err : Object + For each ($err; $result.errors) + TRACE // $err.field, $err.message + End for each +End if +``` + +### invalidateVectors() + +**invalidateVectors**() : Object + +Marks all already-computed entities for re-embedding, forcing a full rebuild on the next run. Only entities that already have a vector value are processed — entities with a `Null` vector are skipped. + +Useful during development or after a model/phrase change to trigger a clean rebuild of all vectors. + +The strategy depends on whether a companion `_dirty` field exists on the dataclass: + +| Companion `_dirty` field | Action taken | +| ------------------------ | -------------------------------------------------------------- | +| Present | Sets `_dirty` to `True` — vector is left untouched | +| Absent | Nullifies the vector field | + +| Argumento | Tipo | Descripción | +| --------- | ------ | ------------------------------------------------------------------ | +| Resultado | Object | `{updated: Integer, skipped: Integer, errors: Collection of Text}` | + +- `updated` — number of entities successfully marked +- `skipped` — number of entities that could not be saved +- `errors` — one entry per save failure, formatted as `"DataclassName: statusText"` + +```4d +var $result:=$def.invalidateVectors() + +If ($result.skipped > 0) + var $e : Text + For each ($e; $result.errors) + // $e + End for each +End if +// → { updated: 42; skipped: 0; errors: [] } +``` + +### toObject() + +**toObject**() : Object + +Returns a plain object suitable for JSON persistence. The phrase is flattened to its template text. + +| Argumento | Tipo | Descripción | +| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | +| Resultado | Object | `{version, dataclassName, vectorName, modelAlias, phrase, autoInvalidate}` where `phrase` is the template string. | + +```4d +$def.toObject() +// → { version: 0; dataclassName: "Students"; vectorName: "student_vector_1"; +// modelAlias: "text-embedding-3-small"; phrase: "Student {firstName} {lastName}"; +// autoInvalidate: true } +``` + +## Automatic invalidation + +`autoInvalidate` controls whether save-time automatic invalidation is enabled for this definition. + +- `True` (default): when relevant attributes change on an entity save, vectors are automatically invalidated. +- `False`: save-time automatic invalidation is skipped for this definition. + +This setting does not affect manual invalidation via `invalidateVectors()`. + +## Dirty flag convention + +The pipeline in [Process](Process.md) will recompute an entity whenever the target vector is `Null`, or when a sibling field `_dirty` exists on the dataclass and is `True`. + +Declaring the dirty flag is optional — when absent, only the null-vector case triggers recomputation. When present, it is cleared automatically on successful save. + +## Ver también + +- [Settings](Settings.md) +- [Process](Process.md) +- [Phrase](Phrase.md) diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Embedder.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Embedder.md new file mode 100644 index 00000000000000..211a2476dbd758 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Embedder.md @@ -0,0 +1,96 @@ +--- +id: embedder +title: Embedder +--- + +# Embedder + +The `Embedder` class is a thin wrapper around [4D AIKit](https://developer.4d.com/docs/aikit/Classes/openai) focused on embeddings. It exposes two functions — one for a single text, one for a batch — and handles retries with exponential backoff (respecting the `Retry-After` header when present). + +It is stateless beyond configuration and safe to share between processes. + +## Propiedades + +| Nombre de la propiedad | Tipo | Descripción | +| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `client` | cs.AIKit.OpenAI | The underlying AIKit client used for HTTP requests. | +| `maxRetries` | Integer | Maximum number of retries on transient errors. Default: `3`. | +| `backoffMs` | Integer | Base delay (ms) between retries. Doubled each attempt. | + +## Class constructor + +Create a embedder. All options are optional. + +| Nombre del argumento | Tipo | Descripción | +| -------------------- | ------ | ----------------------------------------------------------------------------- | +| *opciones* | Object | `{client, maxRetries, backoffMs}` — any field may be omitted. | + +```4d +// Default — uses cs.AIKit.OpenAI.new() internally +var $proc:=cs.EmbeddingStudio.Embedder.new() + +// Provide a pre-configured AIKit client (custom API key, base URL, etc.) +var $client:=cs.AIKit.OpenAI.new({apiKey: "…"; baseURL: "https://server.ai"}) +var $proc:=cs.EmbeddingStudio.Embedder.new({client: $client; maxRetries: 5; backoffMs: 1000}) +``` + +> If the 4D AIKit component is not loaded (or is too old to provide `OpenAIProviders`), the constructor still succeeds with a `Null` client, and the first `embed()` / `embedBatch()` call throws an error whose `message` explains what is missing and whose `isAIKitMissing` property is `True`. + +## Funciones + +### embed() + +**embed**(*text* : Text ; *model* : Text) : [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) + +Embed a single text. Returns a typed result with the embedding vector, token usage, and rate-limit state. + +| Argumento | Tipo | Descripción | +| --------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| *text* | Text | The text to vectorize. | +| *model* | Text | The embedding model to use (e.g. `"text-embedding-3-small"`). | +| Resultado | [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) | Typed wrapper — `.vector` holds the embedding, `.promptTokens` / `.totalTokens` hold usage, rate-limit fields are flat camelCase. | + +Throws if retries are exhausted or the API returns a non-retryable error. + +```4d +var $result:=$proc.embed("it rains cats and dogs"; "text-embedding-3-small") +// $result.vector → 4D.Vector +// $result.promptTokens → Integer +// $result.totalTokens → Integer +// $result.remainingTokens → Integer (-1 if unknown) +``` + +### embedBatch() + +**embedBatch**(*texts* : Collection ; *model* : Text) : [cs.EmbedderResult](EmbedderResult.md) + +Embed a collection of texts in a single API call. Returns a typed result with vectors in the same order as inputs, token usage, and rate-limit state. + +| Argumento | Tipo | Descripción | +| --------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | +| *texts* | Collection | Collection of Text to vectorize. Empty or `Null` returns an empty result. | +| *model* | Text | The embedding model to use. | +| Resultado | [cs.EmbedderResult](EmbedderResult.md) | Typed wrapper — `.vectors` holds the embeddings collection, token and rate-limit fields are flat camelCase. | + +```4d +var $result:=$proc.embedBatch(["hello"; "world"]; "text-embedding-3-small") +// $result.vectors[0] → 4D.Vector for "hello" +// $result.vectors[1] → 4D.Vector for "world" +// $result.totalTokens → Integer (sum for the batch) +// $result.remainingTokens → Integer (after this call) +``` + +## Retry policy + +Transient errors (HTTP 408, 409, 429, 5xx) are retried up to `maxRetries` times. + +- If the response carries a `Retry-After` or `retry-after-ms` header, the embedder waits that long. +- Otherwise, it waits `backoffMs * 2^attempt`. + +Non-retryable errors are thrown immediately — see [OpenAIError](https://developer.4d.com/docs/aikit/Classes/openaierror) for the thrown shape. + +## Ver también + +- [EmbedderResult](EmbedderResult.md) +- [Process](Process.md) +- [OpenAIEmbeddingsAPI](https://developer.4d.com/docs/aikit/Classes/openaiembeddingsapi) (AIKit) diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/EmbedderResult.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/EmbedderResult.md new file mode 100644 index 00000000000000..b0da967bd3ba2f --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/EmbedderResult.md @@ -0,0 +1,80 @@ +--- +id: embedderresult +title: EmbedderResult +--- + +# EmbedderResult + +Typed wrapper for `Embedder.embed()` and `Embedder.embedBatch()` responses. Normalizes OpenAI's snake_case API keys (`prompt_tokens`, `total_tokens`) to camelCase properties, and flattens the nested rate-limit structure into direct properties. + +A single class handles both single and batch results — `embed()` populates `.vector`, `embedBatch()` populates `.vectors`. + +## Propiedades + +### Embedding results + +| Propiedad | Tipo | Por defecto | Descripción | +| --------- | ------------------------- | ----------- | ------------------------------------------------------------------------------ | +| `vector` | 4D.Vector | Null | Single embedding result. Null for batch calls. | +| `vectors` | Collection | `[]` | Batch embedding results. | + +### Token usage + +| Propiedad | Tipo | Por defecto | Descripción | +| -------------- | ------- | ----------- | -------------------------------------------------------------------- | +| `promptTokens` | Integer | `0` | Input tokens consumed. | +| `totalTokens` | Integer | `0` | Total tokens consumed (in + out). | + +### Rate-limit state + +| Propiedad | Tipo | Por defecto | Descripción | +| ------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------- | +| `remainingTokens` | Integer | `-1` | Tokens left in the current window. `-1` = unknown. | +| `remainingRequests` | Integer | `-1` | Requests left in the current window. `-1` = unknown. | +| `limitTokens` | Integer | `0` | TPM ceiling for the account. | +| `limitRequests` | Integer | `0` | RPM ceiling for the account. | +| `resetTokens` | Text | `""` | Time until token bucket refills (e.g. `"6m0s"`). | +| `resetRequests` | Text | `""` | Time until request bucket refills (e.g. `"1s"`). | + +## Class constructor + +```4d +// From a real API result (used by Embedder internally) +var $result:=cs.EmbedderResult.new($aikitResult; True) // batch +var $result:=cs.EmbedderResult.new($aikitResult; False) // single + +// Empty result (no API call — e.g. empty batch) +var $result:=cs.EmbedderResult.new() +``` + +| Argumento | Tipo | Descripción | +| ----------- | ------- | ------------------------------------------------------------------------------------------------------------ | +| *resultado* | Object | An object with `.vector`/`.vectors`, `.usage`, `.rateLimit` (duck-typed). | +| *isBatch* | Boolean | `True` to read `.vectors`, `False` to read `.vector`. | + +The constructor accepts any object that exposes the expected shape — it does not require a specific class. This makes it easy to construct in tests. + +## Utilización + +```4d +// Single embedding +var $r:=$embedder.embed("hello world"; "text-embedding-3-small") +$r.vector // → 4D.Vector +$r.promptTokens // → 6 +$r.totalTokens // → 6 + +// Batch embedding +var $r:=$embedder.embedBatch(["hello"; "world"]; "text-embedding-3-small") +$r.vectors.length // → 2 +$r.totalTokens // → 10 + +// Rate-limit awareness +$r.remainingTokens // → 148230 (or -1 if not yet known) +$r.resetTokens // → "6m0s" +``` + +## Ver también + +- [Embedder](Embedder.md) — creates EmbedderResult instances +- [ProcessResult](ProcessResult.md) — run-level report that accumulates EmbedderResult usage +- [Rate Limiting](../RateLimit.md) — how the pipeline uses rate-limit fields for throttling and batch sizing diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Phrase.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Phrase.md new file mode 100644 index 00000000000000..43155973191b05 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Phrase.md @@ -0,0 +1,117 @@ +--- +id: phrase +title: Phrase +--- + +# Phrase + +The `Phrase` class is a lightweight template engine: a template with `{variable}` placeholders is compiled once, then rendered efficiently against different data objects. + +## Propiedades + +| Nombre de la propiedad | Tipo | Descripción | +| ---------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- | +| `template` | Text | Computed — returns the original template string. | +| `keys` | Collection | Computed — returns the variable names found in the template, dot-notation keys joined back to strings. | + +## Class constructor + +Compile a template. Compilation walks the template once and extracts static parts and variable paths. + +| Nombre del argumento | Tipo | Descripción | +| -------------------- | ---- | ---------------------------------------------------------- | +| *template* | Text | Template string with `{variable}` markers. | + +```4d +var $tpl:=cs.EmbeddingStudio.Phrase.new("Hello {firstName}, you study at {schoolName}.") +$tpl.keys // → ["firstName"; "schoolName"] +``` + +## Funciones + +### render() + +**render**(*data* : Object) : Text + +Render the compiled template by replacing variables with values from *data*. Missing keys produce an empty string. + +| Argumento | Tipo | Descripción | +| --------- | ------ | ------------------------------------------------------------------------------------------------------ | +| *data* | Object | A plain object or a 4D.Entity whose fields supply the variable values. | +| Resultado | Text | The rendered text. | + +```4d +var $text:=$tpl.render({firstName: "Alice"; school: {name: "MIT"}}) +// → "Hello Alice, you study at MIT." + +// Works directly on entities +$text:=$tpl.render(ds.Students.first()) +``` + +### validate() + +**validate**(*dataclass* : 4D.DataClass ; *options* : Object) : Object + +Validate that all keys in the phrase can be resolved against the given dataclass. Walks dot-notation paths through N:1 / 1:1 relations. + +| Argumento | Tipo | Descripción | +| ----------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| *dataclass* | 4D.DataClass | The dataclass to validate against. | +| *opciones* | Object | Optional validation flags (see below). All default to `False` — storage kind only. | +| Resultado | Object | `{success: Boolean, errors: Collection of {key, message}}`. | + +#### Opciones + +| Campo | Tipo | Por defecto | Descripción | +| ----------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------- | +| `allowRelations` | Boolean | `False` | Allow dot-notation paths through N:1 / 1:1 relations. | +| `allowCalculated` | Boolean | `False` | Allow calculated attributes. | +| `allowAlias` | Boolean | `False` | Allow alias attributes. | + +```4d +var $tpl:=cs.EmbeddingStudio.Phrase.new("{firstName} at {school.name}") + +// Storage-only validation — fails because {school.name} uses a relation +var $v:=$tpl.validate(ds.Students) +// $v.success → False +// $v.errors → [{key: "school.name"; message: "..."}] + +// Allow relations +$v:=$tpl.validate(ds.Students; {allowRelations: True}) +// $v.success → True +``` + +#### Rejected shapes + +Regardless of options: + +- Attributes that do not exist on the dataclass. +- Attributes whose class ID is `4D.Vector`. +- 1:N relations (`relatedEntities`) as the final key. +- Intermediate segments that are not relations (when dot-notation is used). + +### atributos() + +**attributes**(*dataclass* : 4D.DataClass) : Collection + +Resolves each phrase key against *dataclass* and returns an ordered Collection of ORDA attribute descriptor objects, one per key in the same order as `.keys`. For dot-notation paths, traverses N:1 relations to reach the final attribute. Pushes `Null` for any key whose path cannot be resolved (unknown attribute or non-relation intermediate segment). + +| Argumento | Tipo | Descripción | +| ----------- | ---------------------------- | -------------------------------------------------------------------------------------------- | +| *dataclass* | 4D.DataClass | The dataclass to resolve attributes against. | +| Resultado | Collection | Ordered collection of ORDA attribute objects (or `Null`). | + +Each resolved entry is an ORDA attribute descriptor with `.name`, `.kind`, and more — see [DataClass.attributeName](https://developer.4d.com/docs/API/DataClassClass#attributename). + +```4d +var $tpl:=cs.EmbeddingStudio.Phrase.new("{firstName} graduated from {school.name}") +var $attrs:=$tpl.attributes(ds.Students) +// $attrs[0].name → "firstName" $attrs[0].type → "string" +// $attrs[1].name → "name" $attrs[1].type → "string" (from School dataclass) +// $attrs[1] is Null if school.name could not be resolved +``` + +## Ver también + +- [Definition](Definition.md) — holds a `Phrase`. +- [StudioEmbedder.render()](StudioEmbedder.md#render) — renders a phrase for an entity, non-persisting. diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Process.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Process.md new file mode 100644 index 00000000000000..f536f9b4f1209e --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Process.md @@ -0,0 +1,188 @@ +--- +id: process +title: Proceso +--- + +# Proceso + +The `Process` class orchestrates the full embedding pipeline: it browses 4D entities, renders text from their fields using a [Definition](Definition.md), calls the embeddings API through an [Embedder](Embedder.md), and stores the resulting `4D.Vector` on each entity. + +To render or embed on demand without persistence (search query vectors, phrase previews), see [StudioEmbedder](StudioEmbedder.md). + +## Propiedades + +| Nombre de la propiedad | Tipo | Descripción | +| ---------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- | +| `propiedades` | [Settings](Settings.md) | The settings (definitions, batch size, phrase validation options). | +| `embedder` | [Embedder](Embedder.md) | The API-calling engine. Stateless and swappable. | +| `opciones` | Object | Runtime options object (see [Options object](#options-object) below). | + +### Options object + +| Llave | Tipo | Descripción | +| ---------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `onProgress` | 4D.Function | Called after each processed chunk with `{definition, report}`. | +| `onSuccess` | 4D.Function | Called once at the end when `report.success = True`, with `{report, success, errors}`. | +| `onError` | 4D.Function | Called once at the end when `report.success = False`, with `{report, success, errors}`. | +| `onTerminate` | 4D.Function | Called once at the end in all cases (after `onSuccess`/`onError`), with `{report, success, errors}`. | +| `dryRun` | Boolean | If `True`, runs selection/filter logic but skips API calls and entity saves. | +| `force` | Boolean | If `True`, recomputes every entity ignoring null-vector / dirty-flag filter. | +| `debug` | Boolean | If `True`, emits additional diagnostic log entries. | +| `pauseIndexes` | Boolean | If `True`, index maintenance on the target table is paused for the duration of a `processEntitySelection` batch run, then resumed right after (or on early exit/critical error). Default `False` — indexes are left alone. See [Pausing indexes](#pausing-indexes) before enabling it. | +| `waitForIndexes` | Boolean | Only used with `pauseIndexes`. If `True`, resuming indexes blocks until they are rebuilt. Default `False` — resume is asynchronous (indexes rebuilt in the background). | +| `shouldCancel` | 4D.Function | Predicate called between chunks during selection processing. Returning `True` stops the run gracefully (cooperative cancel) — what [`Scheduler.cancel()`](Scheduler.md#cancel) uses. | +| `embedder` | [Embedder](Embedder.md) | Inject a custom embedder (otherwise a default one is created). | + +## Class constructor + +Create an instance of the orchestrator. + +| Nombre del argumento | Tipo | Descripción | +| -------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| *settings* | [Settings](Settings.md) | Opcional. If omitted, settings are loaded from the default `Settings/embeddings.json`. | +| *opciones* | Object | Optional runtime options (see table above). | + +```4d +// Simplest — uses defaults +var $p:=cs.EmbeddingStudio.Process.new() + +// With explicit settings +var $p:=cs.EmbeddingStudio.Process.new($settings) + +// With options +var $p:=cs.EmbeddingStudio.Process.new($settings; {\ + force: True; \ + onProgress: Formula(ALERT("chunk done: "+String($1.report.entitiesUpdated)))}) +``` + +## Batch processing functions + +### proceso() + +**process**(*definition* : Variant) : [ProcessResult](ProcessResult.md) + +Process one, many, or all [Definition](Definition.md) entries against the full content of their target dataclass. + +| Argumento | Tipo | Descripción | +| ------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| *definición* | `Null`, [Definition](Definition.md), `4D.DataClass`, plain object, or Collection | See [process() resolution](#process-resolution). `Null` → every definition in settings. | +| Resultado | [ProcessResult](ProcessResult.md) | Statistics and per-error breakdown. | + +```4d +// Every definition in settings +var $r:=$p.process() + +// One specific definition +var $r:=$p.process($def) + +// Multiple definitions +var $r:=$p.process([$def1; $def2]) + +// Every definition configured for a whole dataclass +var $r:=$p.process(ds.Students) + +// A plain descriptor — looked up in settings, or built on the fly +var $r:=$p.process({dataclassName: "Students"; vectorName: "student_vector_1"}) + +// Any mix — each item is resolved independently and flattened +var $r:=$p.process([ds.Students; $def; {dataclassName: "School"; vectorName: "school_vector_1"}]) +``` + +#### process() resolution + +`process()` has no entity context, so it resolves each input into concrete [Definition](Definition.md) objects directly from settings: + +| Entrada | Comportamiento | +| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Null` | Every definition in settings. | +| [Definition](Definition.md) | Used as-is. | +| `4D.DataClass` (e.g. `ds.Students`) | Every definition in settings whose `dataclassName` matches that dataclass. | +| `{dataclassName: "..."; vectorName: "..."}` | The matching saved definition, or — if none is found — a new `Definition` built from the object's fields (`modelAlias`, `phrase.template`). | +| Collection | Each item is resolved with the rules above and the results are **flattened** into one collection (a `4D.DataClass` item can expand to several definitions). Unsupported items are dropped. | +| Anything else | Empty result. | + +### processEntity() + +**processEntity**(*entity* : 4D.Entity ; *definition* : Variant) : [ProcessResult](ProcessResult.md) + +Process a single entity. Cheap path — no chunking, no server-side filter. + +| Argumento | Tipo | Descripción | +| ------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| *entity* | 4D.Entity | The entity to (re)compute vectors for. | +| *definición* | `Null`, [Definition](Definition.md), Collection, or `{vectorName: ...}` | See [resolution rules](#definition-resolution). `Null` infers from entity's dataclass. | +| Resultado | [ProcessResult](ProcessResult.md) | Statistics and per-error breakdown. | + +```4d +// Auto-resolve every definition matching this entity's dataclass +var $r:=$p.processEntity($entity) + +// Specific definition +var $r:=$p.processEntity($entity; $def) + +// By vector name only (looked up in settings against the entity's dataclass) +var $r:=$p.processEntity($entity; {vectorName: "student_vector_1"}) +``` + +### processEntitySelection() + +**processEntitySelection**(*selection* : 4D.EntitySelection ; *definition* : Variant) : [ProcessResult](ProcessResult.md) + +Workhorse path for large jobs. Chunks the selection by `settings.batchSize`, sends one API call per chunk, saves each entity individually. + +| Argumento | Tipo | Descripción | +| ------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| *selection* | 4D.EntitySelection | Entities to process. Pre-filtering by the caller is allowed; the pipeline still applies its null/dirty filter. | +| *definición* | `Null`, [Definition](Definition.md), Collection, or `{vectorName: ...}` | See [resolution rules](#definition-resolution). | +| Resultado | [ProcessResult](ProcessResult.md) | Statistics and per-error breakdown. | + +```4d +var $todo:=ds.Students.query("country = :1"; "FR") +var $r:=$p.processEntitySelection($todo; $def) +``` + +### Definition resolution (entity context) + +The polymorphic *definition* argument accepted by `processEntity` and `processEntitySelection`. Unlike [`process()`](#process-resolution), these have an entity/selection to infer the dataclass from, so a bare `{vectorName: "..."}` stub is enough: + +| Entrada | Comportamiento | +| --------------------------- | ----------------------------------------------------------------------------------------------- | +| `Null` | All definitions in settings whose `dataclassName` matches the entity/selection. | +| [Definition](Definition.md) | Used as-is; the `dataclassName` must match the entity/selection. | +| `{vectorName: "..."}` | Looked up in settings by `vectorName` against the entity/selection dataclass. | +| Collection | Each item resolved using the rules above; mismatches are silently dropped. | + +### Recompute rules + +An entity is (re)computed when **any** of these are true: + +- The target vector field is `Null`. +- A sibling field named `{vectorName}_dirty` exists and is `True`. +- The `force` option is `True`. + +The dirty field is optional per dataclass. If it doesn't exist, only the null-vector case triggers recomputation. Upon successful save, the pipeline clears the dirty flag (when present). + +For `processEntitySelection`, the filter is executed as a server-side ORDA query before any API call, so only the rows that actually need work are loaded into memory. For `processEntity`, the check is done in memory on the already-fetched entity. + +### Pausing indexes + +By default the indexes of the target table are maintained normally while vectors are saved. With the `pauseIndexes` option, a batch run calls [`PAUSE INDEXES`](https://developer.4d.com/docs/commands/pause-indexes) on the table before writing and [`RESUME INDEXES`](https://developer.4d.com/docs/commands/resume-indexes) once done (also on early exit or critical error). + +Be aware of what these commands do: + +- `PAUSE INDEXES` disables **all** the indexes of the table (except the primary key index), not only the vector ones: every index on every other field of the table is paused too. While paused, queries and sorts on that table, including those of other processes, run without any index. +- `RESUME INDEXES` then **rebuilds all these indexes**, for the whole table, not only for the records that were recomputed. On a table with several indexes, this rebuild can cost more than the time saved during the writes. +- With `waitForIndexes` set to `True`, the run blocks until the rebuild completes; otherwise the rebuild runs in the background. +- These commands cannot run on a 4D remote client: there the option is ignored (a warning is logged once) and the recalculation runs with indexes maintained normally. Run it on the server, for example through the [Scheduler](Scheduler.md), to use it. + +Enable it only for large recalculations, such as computing the vectors of a whole table for the first time. + +## Ver también + +- [StudioEmbedder](StudioEmbedder.md) +- [Settings](Settings.md) +- [Definition](Definition.md) +- [Embedder](Embedder.md) +- [ProcessResult](ProcessResult.md) +- [Phrase](Phrase.md) +- [Rate Limiting](../RateLimit.md) diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessError.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessError.md new file mode 100644 index 00000000000000..95a9debef40b85 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessError.md @@ -0,0 +1,87 @@ +--- +id: processerror +title: ProcessError +--- + +# ProcessError + +A `ProcessError` is one structured, typed entry in the `errors` collection of a [ProcessResult](ProcessResult.md). Its typed fields let callers react to a specific failure mode programmatically — retry transient failures, abort on a fatal model outage, count save failures — without parsing message strings. + +You read these instances from [ProcessResult](ProcessResult.md)`.errors`, directly or through its query helpers (`errorsByCode`, `errorsByScope`, `retryableErrors`). + +## Propiedades + +| Nombre de la propiedad | Tipo | Descripción | +| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `alcance` | Text | Where the error originated: `"pipeline"`, `"definition"`, `"chunk"`, or `"entity"`. | +| `severity` | Text | `"warning"`, `"error"`, or `"fatal"`. Determined by `code` (see [ProcessErrorCode](ProcessErrorCode.md)). | +| `code` | Integer | Machine-readable error code — compare against the constants on [ProcessErrorCode](ProcessErrorCode.md). | +| `ref` | Variant | Scope-dependent reference: `"Dataclass.vector"`, an entity primary key, a model alias, or `Null`. | +| `message` | Text | Human-readable, localized message. | +| `retryable` | Boolean | `True` when re-running the operation could plausibly succeed. Determined by `code`. | + +### scope values + +| Alcance | Significado | +| -------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `"pipeline"` | Top-level failure affecting the whole run (null selection, a model became unavailable). | +| `"definition"` | A [Definition](Definition.md) failed validation or was skipped. | +| `"chunk"` | A whole batch (chunk) of entities failed in a single API call. | +| `"entidad"` | A single entity failed to embed or save. | + +### severity values + +| Severity | Significado | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `"warning"` | Non-blocking — does **not** make [ProcessResult](ProcessResult.md)`.success` false. | +| `"error"` | A recoverable failure scoped to one entity, chunk, or definition. Makes `success` false. | +| `"fatal"` | Blocks the rest of the run (e.g. the model is unavailable). Also surfaces via `hasFatal`. | + +## Propiedades calculadas + +| Propiedad | Tipo | Descripción | +| --------- | ------- | ------------------------------------------------- | +| `isFatal` | Boolean | `True` when `severity = "fatal"`. | + +## Funciones + +### toObject() + +**toObject**() : Object + +Returns a plain object (`{scope, severity, code, ref, message, retryable}`) suitable for logging or JSON serialization. + +| Argumento | Tipo | Descripción | +| --------- | ------ | ------------------------------------------------------ | +| Resultado | Object | A JSON-friendly snapshot of the error. | + +## Ejemplo + +React to failures by type rather than by message text: + +```4d +var $r:=$p.process() + +If (Not($r.success)) + + If ($r.hasFatal) + ALERT("A model became unavailable — aborting until it recovers.") + End if + + var $codes:=cs.EmbeddingStudio.ProcessErrorCode.me + var $saveFailures:=$r.errorsByCode($codes.SAVE_FAILED) + If ($saveFailures.length>0) + ALERT(String($saveFailures.length)+" entities failed to save.") + End if + + // Collect entity keys worth retrying later + var $retry:=$r.retryableErrors().query("scope = :1"; "entity").extract("ref") + +End if +``` + +## Ver también + +- [ProcessErrorCode](ProcessErrorCode.md) — the catalogue of `code` values and their severity/retryability. +- [ProcessResult](ProcessResult.md) — owns the `errors` collection and the query helpers (`errorsByCode`, `errorsByScope`, `retryableErrors`). +- [Process](Process.md) — produces these errors. diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessErrorCode.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessErrorCode.md new file mode 100644 index 00000000000000..f5d1b0d6e065bb --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessErrorCode.md @@ -0,0 +1,55 @@ +--- +id: processerrorcode +title: ProcessErrorCode +--- + +# ProcessErrorCode + +A `singleton` exposing the stable, machine-readable error codes carried by [ProcessError](ProcessError.md) `.code`, plus a `meta()` lookup mapping each code to its default `severity` and `retryable` flag. Compare against these constants instead of parsing message strings. + +Access the shared instance via `.me`: + +```4d +var $codes:=cs.EmbeddingStudio.ProcessErrorCode.me +If ($error.code=$codes.SAVE_FAILED) + // … +End if +``` + +## Codes + +| Constante | Valor | Default severity | Retryable | Raised when… | +| ----------------------- | ----- | ---------------- | --------- | ------------------------------------------------------------------------------------------------- | +| `NULL_INPUT` | 100 | error | No | A required entity, selection, or definition was `Null`. | +| `INVALID_DEFINITION` | 101 | error | No | A value is not a usable [Definition](Definition.md) instance. | +| `VALIDATION_FAILED` | 102 | error | No | `Definition.validate()` reported a problem. | +| `MODEL_UNAVAILABLE` | 200 | fatal | Sí | A critical API error made the model unusable for the rest of the run. | +| `MODEL_SKIPPED` | 201 | error | Sí | A definition was skipped because its model already failed critically. | +| `EMBED_FAILED` | 202 | error | Sí | A non-critical embedding call failed (single entity or chunk). | +| `VECTOR_COUNT_MISMATCH` | 300 | error | No | The provider returned a different vector count than requested. | +| `SAVE_FAILED` | 400 | error | Sí | `entity.save()` failed (validation, lock, …). | + +Codes are grouped by hundreds: `1xx` input/configuration, `2xx` model/API, `3xx` data integrity, `4xx` persistence. Unknown codes resolve to `{severity: "error"; retryable: False; label: "UNKNOWN"}`. + +## Funciones + +### meta() + +**meta**( $code : Integer ) : Object + +Returns the `severity` and `retryable` flag associated with a code — the same values carried by a [ProcessError](ProcessError.md) with that `code`. + +| Argumento | Tipo | Descripción | +| --------- | ------- | ----------------------------------------------------------------------- | +| `$code` | Integer | One of the code constants above. | +| Resultado | Object | `{severity : Text; retryable : Boolean; label : Text}`. | + +```4d +var $m:=cs.EmbeddingStudio.ProcessErrorCode.me.meta(cs.EmbeddingStudio.ProcessErrorCode.me.MODEL_UNAVAILABLE) +// $m = {severity: "fatal"; retryable: True; label: "MODEL_UNAVAILABLE"} +``` + +## Ver también + +- [ProcessError](ProcessError.md) — carries a `.code` from this list. +- [ProcessResult](ProcessResult.md) — `errorsByCode()` filters errors by code. diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessResult.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessResult.md new file mode 100644 index 00000000000000..7263643f095e95 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessResult.md @@ -0,0 +1,91 @@ +--- +id: processresult +title: ProcessResult +--- + +# ProcessResult + +The `ProcessResult` class is the return value of every batch entry point of [Process](Process.md) (`process`, `processEntity`, `processEntitySelection`). It accumulates statistics, per-error breakdowns, and wall-clock duration. + +The orchestrator never throws out of its public batch API — failures are recorded here and the job continues. The caller decides what to do with them. + +## Propiedades + +| Nombre de la propiedad | Tipo | Descripción | +| ---------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `definitionsProcessed` | Integer | Number of [Definition](Definition.md) entries processed. | +| `entitiesConsidered` | Integer | Number of entities that passed the "needs recompute" filter. | +| `entitiesUpdated` | Integer | Number of entities whose vector was successfully written and saved. | +| `entitiesSkipped` | Integer | Number of entities that could not be processed: individual embed or save errors, or whole-chunk API failures (those entities are left unchanged for the next run). | +| `apiCalls` | Integer | Number of embeddings API calls made. | +| `promptTokens` | Integer | Total prompt tokens consumed across all API calls in this run. | +| `totalTokens` | Integer | Total tokens consumed across all API calls in this run. | +| `duración` | Integer | Total duration of the job in milliseconds. | +| `errors` | Collection | List of [ProcessError](ProcessError.md) entries recorded during the run. | + +### Propiedades calculadas + +| Propiedad | Tipo | Descripción | +| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `success` | Boolean | `True` when no `"error"` or `"fatal"` entry was recorded. `"warning"` entries do not fail the run. | +| `hasFatal` | Boolean | `True` when at least one `"fatal"` entry was recorded (e.g. a model became unavailable). | + +### Error entries + +Each item in `errors` is a [ProcessError](ProcessError.md) with `scope`, `severity`, `code`, `ref`, `message`, and `retryable`. See [ProcessError](ProcessError.md) for the field meanings and [ProcessErrorCode](ProcessErrorCode.md) for the `code` catalogue. + +## Funciones + +### errorsByScope() + +**errorsByScope**( $scope : Text ) : Collection + +Errors filtered by `scope` (`"pipeline"`, `"definition"`, `"chunk"`, `"entity"`). + +### errorsByCode() + +**errorsByCode**( $code : Integer ) : Collection + +Errors filtered by machine-readable code — see [ProcessErrorCode](ProcessErrorCode.md). + +### retryableErrors() + +**retryableErrors**() : Collection + +Errors flagged `retryable` — re-running the operation could plausibly succeed. + +### toObject() + +**toObject**() : Object + +Returns a plain object suitable for logging or JSON serialization. + +| Argumento | Tipo | Descripción | +| --------- | ------ | ------------------------------------------------------- | +| Resultado | Object | A JSON-friendly snapshot of the report. | + +```4d +var $r:=$p.process() +LOG EVENT(Into 4D log file; JSON Stringify($r.toObject())) +``` + +## Ejemplo + +```4d +var $r:=$p.processEntitySelection(ds.Students.all(); $def) + +If ($r.success) + ALERT("Updated "+String($r.entitiesUpdated)+" students in "+String($r.duration)+" ms") +Else + var $err : Object + For each ($err; $r.errors) + ALERT("[" + $err.scope + "] " + String($err.ref) + " — " + $err.message) + End for each +End if +``` + +## Ver también + +- [Process](Process.md) +- [ProcessError](ProcessError.md) — the typed shape of each `errors` entry. +- [ProcessErrorCode](ProcessErrorCode.md) — the `code` catalogue. diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Scheduler.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Scheduler.md new file mode 100644 index 00000000000000..d76f5fce408e54 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Scheduler.md @@ -0,0 +1,369 @@ +--- +id: scheduler +title: Backups periódicos +--- + +# Backups periódicos + +The `Scheduler` class is the public entry point for the **automated embedding recalculation** service. It maintains a background task that runs the embedding pipeline (see [Process](Process.md)) at a configured interval or a fixed daily time, guarantees that **at most one** recalculation batch runs at a time, and exposes runtime status for administration and monitoring interfaces. + +It is a **singleton**, accessed through `cs.EmbeddingStudio.Scheduler.me`. + +The scheduler runs two named workers: + +| Worker | Rol | +| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `EmbeddingStudioScheduler` | Background loop that re-reads the config each cycle, computes the next run and fires when due. | +| `EmbeddingStudio` | Execution worker that runs one recalculation batch (shared with the Studio UI, so scheduled and manual runs are serialized). | + +## Configuración + +The configuration lives under the `scheduler` key of `Settings/embeddings.json`: + +```json +{ + "scheduler": { + "mode": "interval", + "intervalHours": 3, + "startFrom": "reference", + "startReference": "2026-09-02T14:00:00", + "dailyTime": "00:00" + } +} +``` + +| Llave | Tipo | Values / range | Descripción | +| ---------------- | ------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `mode` | Text | `"never"` \| `"interval"` \| `"daily"` | Scheduling mode. Absent/unknown ⇒ `never` (no automatic run). | +| `intervalHours` | Integer | `1`..`24` | Interval mode only. Out-of-range ⇒ default `3`. | +| `startFrom` | Text | `"reference"` \| `"lastExecution"` | Interval mode only. Anchor of the interval (see below). Anything other than `"lastExecution"` — including the legacy `"now"` — is normalized to `reference`. Default `reference`. | +| `startReference` | Text | `"YYYY-MM-DDThh:mm:ss"` | Interval mode with `startFrom = "reference"`. Fixed instant the interval counts from. Absent ⇒ the moment the scheduler was armed, then the current instant. | +| `dailyTime` | Text | `"HH:MM"` | Daily mode only. Time of day for the recalculation. Default `"00:00"`. | + +**Interval anchoring (`startFrom`)** + +- `reference` — **fixed rate**: the interval is anchored on the fixed `startReference` instant, so the slots do not drift whatever a run's duration is. Slots are advanced by `intervalHours` until the first one strictly after now. When `startReference` is absent (a fresh or legacy config), the anchor falls back to the moment the scheduler was armed (`start()`), then to the current instant. +- `lastExecution` — **fixed delay**: the interval is anchored on the last completed recalculation. If the elapsed time since the last run already exceeds the interval (e.g. after a restart), the run is triggered immediately. If there is no prior run, it runs immediately. + +The effective configuration is read from the file on **every loop cycle**, so changes take effect without restarting the scheduler. + +## Starting the scheduler + +Configuring a `mode` is **not enough**: nothing runs until the scheduler is started. There are two ways to get there, and which one applies depends on a single option of your host database. + +### 1. Automatic — let the host database start it + +In the host database, open **Settings > Security** and check **"Execute 'On Host Database Event' method of the components"** (it is *unchecked* by default, for security reasons). + +With this option on, 4D Embedding Studio starts the scheduler by itself when the host database opens, and stops it when the host database closes. There is nothing else to write. + +Use [`autoStart()`](#autostart) to check whether the option is on: + +```4d +If (Not(cs.EmbeddingStudio.Scheduler.me.autoStart())) + // the option is off — I must start the scheduler myself + cs.EmbeddingStudio.Scheduler.me.start() +End if +``` + +### 2. Manual — start it from your own code + +If you prefer to leave the option off, the scheduler never starts on its own. Call [`start()`](#start) from wherever it suits you — typically the host `On Startup` or `On Server Startup` database method — and [`stop()`](#stop) when the database closes (`On Exit` / `On Server Shutdown`): + +```4d +// Host "On Server Startup" +cs.EmbeddingStudio.Scheduler.me.start() + +// Host "On Server Shutdown" +cs.EmbeddingStudio.Scheduler.me.stop() +``` + +> In client/server, arm the scheduler from `On Server Startup`, not from `On Startup`: +> `On Startup` runs on every remote client, and the scheduler state is per machine — each +> client would arm its own loop and run its own batches. If you do call [`start()`](#start) +> from `On Startup` (single-user setups), guard it with +> `If (Application type#4D Remote mode)`. + +`start()` is idempotent, so calling it from several places is harmless. + +### Checking that it really runs + +[`isStarted()`](#isstarted) tells you whether the background loop is alive right now — the answer to "is my schedule actually being watched?": + +```4d +var $s:=cs.EmbeddingStudio.Scheduler.me.status() +If ($s.enabled && Not($s.started)) + ALERT("A schedule is configured but the scheduler is not started.") +End if +``` + +## Funciones + +### start() + +**start**() : Boolean + +Arms the scheduler and starts the background loop worker if it is not already running. Idempotent — calling it again while already armed simply refreshes the "start from now" anchor. + +| Resultado | Tipo | Descripción | +| --------- | ------- | ------------------------------ | +| resultado | Boolean | Always `True`. | + +```4d +cs.EmbeddingStudio.Scheduler.me.start() +``` + +### stop() + +**stop**() + +Disarms the scheduler and stops the background loop worker. A recalculation batch already in progress is **not** interrupted — it finishes normally (use [`cancel()`](#cancel) to request an early stop). + +```4d +cs.EmbeddingStudio.Scheduler.me.stop() +``` + +### cancelado() + +**cancel**() + +Requests a **cooperative** cancel of the batch currently running. The running batch is never force-killed; it stops gracefully between two chunks. Has no effect if no batch is running. + +```4d +cs.EmbeddingStudio.Scheduler.me.cancel() +``` + +### force() + +**force**() : Object + +Forces a recalculation **now**, regardless of the schedule. It honors the single-batch rule: if a batch is already running, the forced trigger is skipped (and logged). Non-blocking — the run happens on the execution worker. + +| Resultado | Tipo | Descripción | +| --------- | ------ | ----------------------------------------------------- | +| resultado | Object | The current [status](#status) object. | + +```4d +var $status:=cs.EmbeddingStudio.Scheduler.me.force() +``` + +### status() + +**status**() : Object + +Returns the current scheduler status, without any input parameter — suitable for administration and monitoring displays. + +| Resultado | Tipo | Descripción | +| --------- | ------ | ---------------------------------------------------- | +| resultado | Object | See [Status object](#status-object). | + +```4d +var $s:=cs.EmbeddingStudio.Scheduler.me.status() +If ($s.running) + ALERT("A recalculation is running since "+$s.batchStart) +End if +``` + +#### Objeto estado + +| Llave | Tipo | Descripción | +| ---------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `enabled` | Boolean | `False` when `mode = "never"`. | +| `mode` | Text | Effective mode (`never` \| `interval` \| `daily`). | +| `armed` | Boolean | `True` when the background loop is armed (after `start()`, until `stop()`). | +| `running` | Boolean | `True` while a recalculation batch is in progress. | +| `batchStart` | Text \| Null | ISO timestamp of the running batch start (`Null` when idle). | +| `lastExecution` | Text \| Null | ISO timestamp of the last completed run (`Null` if none yet). Restored from the persisted history after a restart, so it survives the loss of in-memory state. | +| `lastRunBeforeRestart` | Boolean | `True` when `lastExecution` was recovered from the history after a restart rather than produced by a run in the current session. | +| `nextRun` | Text \| Null | ISO timestamp of the next scheduled run (`Null` in `never` mode). | +| `lastResult` | Text \| Null | Result of the last trigger: `started` \| `skipped` \| `completed` \| `failed`. | +| `error` | Text \| Null | Error summary when the last run failed (safe for admin display), else `Null`. | +| `started` | Boolean | `True` when the background loop is really alive (see [`isStarted()`](#isstarted)). | +| `autoStart` | Boolean | `True` when the host database starts the scheduler by itself (see [`autoStart()`](#autostart)). | + +### isStarted() + +**isStarted**() : Boolean + +Tells whether the scheduler is **effectively running**, i.e. whether its background loop is alive at this very moment. Unlike the `armed` flag of the [status](#status-object), it reflects reality: if the loop was never started, or was killed, the result is `False`. + +| Resultado | Tipo | Descripción | +| --------- | ------- | --------------------------------------------------------- | +| resultado | Boolean | `True` when the background loop is alive. | + +```4d +If (Not(cs.EmbeddingStudio.Scheduler.me.isStarted())) + cs.EmbeddingStudio.Scheduler.me.start() +End if +``` + +### autoStart() + +**autoStart**() : Boolean + +Tells whether the host database authorizes 4D Embedding Studio to start itself, i.e. whether the **"Execute 'On Host Database Event' method of the components"** option is checked in the host **Settings > Security** (see [Starting the scheduler](#starting-the-scheduler)). + +- `True` — the scheduler starts with the host database and stops with it. You have nothing to call. +- `False` — nothing starts automatically: your code must call [`start()`](#start) and [`stop()`](#stop). + +The answer is read from the host structure settings. When they cannot be read, the result is `False` — the safe answer, since starting an already-started scheduler is harmless. + +| Resultado | Tipo | Descripción | +| --------- | ------- | -------------------------------------------------------------------- | +| resultado | Boolean | `True` when the host starts the scheduler by itself. | + +```4d +var $auto:=cs.EmbeddingStudio.Scheduler.me.autoStart() +``` + +### config() + +**config**() : Object + +Returns the effective scheduler configuration with defaults applied (as resolved from `embeddings.json`). + +| Resultado | Tipo | Descripción | +| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | +| resultado | Object | `{mode; intervalHours; startFrom; startReference; dailyTime}` (see [Configuration](#configuration)). | + +```4d +var $cfg:=cs.EmbeddingStudio.Scheduler.me.config() +``` + +### saveConfig() + +**saveConfig**( *cfg* : Object ) : Object + +Validates, normalizes and **persists** a scheduler configuration to the `scheduler` key of `embeddings.json`, then returns the normalized value. This is the programmatic equivalent of the scheduler settings window: it lets you change the schedule entirely by code, without the GUI. Only the `scheduler` key is written — other keys of the settings file are preserved. + +The configuration is written **on the server**: in a 4D Server / 4D remote setup the file is always edited on the server machine, so a remote client can safely call this method. Because the loop re-reads the configuration on every cycle, the new schedule takes effect without restarting the scheduler. + +| Parámetros | Tipo | Descripción | +| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| cfg | Object | Raw configuration `{mode; intervalHours; startFrom; startReference; dailyTime}` (see [Configuration](#configuration)). Missing/out-of-range values are defaulted. | + +| Resultado | Tipo | Descripción | +| --------- | ------ | ---------------------------------------------------------------- | +| resultado | Object | The normalized configuration that was persisted. | + +```4d +// Switch to a 6-hour interval counting from the last execution +cs.EmbeddingStudio.Scheduler.me.saveConfig({mode: "interval"; intervalHours: 6; startFrom: "lastExecution"}) + +// Switch to a daily run at 02:30 +cs.EmbeddingStudio.Scheduler.me.saveConfig({mode: "daily"; dailyTime: "02:30"}) + +// Disable the automatic schedule +cs.EmbeddingStudio.Scheduler.me.saveConfig({mode: "never"}) +``` + +### nextRun() + +**nextRun**() : Object + +Computes the next scheduled run from the current configuration and state. + +| Resultado | Tipo | Descripción | +| --------- | -------------- | --------------------------------------------------------------------------------------------------------------- | +| resultado | Object \| Null | `{date : Date; time : Time; timestamp : Text; immediate : Boolean}`, or `Null` in `never` mode. | + +```4d +var $next:=cs.EmbeddingStudio.Scheduler.me.nextRun() +``` + +### reload() + +**reload**() : Object + +No-op convenience: the configuration is re-read automatically on each loop cycle, so this simply returns the current [status](#status). Provided for callers that want an explicit "config changed, give me the up-to-date status" call. + +| Resultado | Tipo | Descripción | +| --------- | ------ | ----------------------------------------------------- | +| resultado | Object | The current [status](#status) object. | + +## Concurrency & logging + +- **Single batch** — at any time, at most one recalculation batch runs. A trigger (scheduled or forced) fired while a batch is running is **skipped**, not queued. +- **Skip traceability** — skipped triggers are logged with their timestamp in the execution history (`Logs/embeddingHistory.json`). +- **Cooperative cancel** — `cancel()` stops a running batch gracefully between chunks; it is never force-killed. +- **History** — each run records start/end timestamps, status, token usage and the computed next run date in `Logs/embeddingHistory.json` (see [ProcessResult](ProcessResult.md) for per-run details). + +### Execution history file + +`Logs/embeddingHistory.json` is written by the pipeline itself (every full `process()` run, scheduled or manual), guarded by a semaphore so concurrent processes never interleave writes. It holds the **current** run at the top level, the one before it under `previous`, and the same pair per definition under `definitions`. + +```json +{ + "startTime": "2026-09-01T14:03:00", + "endTime": "2026-09-01T14:03:00", + "status": "completed", + "trigger": "completed", + "error": null, + "nextComputeDate": "2026-09-02T14:03:00", + "promptTokens": 0, + "totalTokens": 0, + "cumulativePromptTokens": 37802, + "cumulativeTotalTokens": 37802, + "previous": { "startTime": "…", "endTime": "…", "status": "completed", "error": null, + "nextComputeDate": "…", "promptTokens": 12764, "totalTokens": 12764, + "cumulativePromptTokens": 37802, "cumulativeTotalTokens": 37802 }, + "skipped": ["2026-09-01T12:00:00"], + "definitions": { + "Students.student_vector_1": { + "startTime": "…", "endTime": "…", "status": "completed", "error": null, + "promptTokens": 1054, "totalTokens": 1054, + "cumulativePromptTokens": 4210, "cumulativeTotalTokens": 4210, + "previous": { "…": "…" } + } + } +} +``` + +| Llave | Tipo | Descripción | +| -------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `startTime` / `endTime` | Text \| Null | ISO timestamps of the run, in the scheduler's local base. `endTime` is `null` while a run is in progress. | +| `status` | Text | `running` \| `completed` \| `failed`. | +| `trigger` | Text | Last event that touched the file: `started` \| `skipped` \| `completed` \| `failed`. | +| `error` | Text \| Null | Summary of the run's errors, or `null`. Never contains an API key. | +| `nextComputeDate` | Text \| Null | Next scheduled run computed at the end of the run (the `nextComputeDate` option of [Process](Process.md)). | +| `promptTokens` / `totalTokens` | Integer | Usage for this run alone. | +| `cumulativePromptTokens` / `cumulativeTotalTokens` | Integer | Running totals across all recorded runs. | +| `previous` | Object | Snapshot of the preceding run — the same keys, without `trigger`, `skipped` and `definitions`. Only one generation is kept. | +| `skipped` | Collection | ISO timestamps of triggers skipped because a batch was already running. Capped at the **last 50**. | +| `definitions` | Object | One entry per definition, keyed `"."`, each with its own `startTime`, `endTime`, `status` (`completed` \| `failed` \| `skipped`), `error`, token counters and `previous`. | + +[`status()`](#status) reads `startTime`, `endTime`, `status`, `trigger`, `error` and `nextComputeDate` back from this file, which is how `lastExecution` survives a server restart. + +## Lifecycle + +| Host setting | What happens | What you must do | +| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| **"Execute 'On Host Database Event' method of the components"** checked | The scheduler starts when the host database opens and stops when it closes. | Nothing. | +| Option unchecked (default) | The scheduler never starts by itself. | Call [`start()`](#start) at startup and [`stop()`](#stop) at shutdown. | + +Ask [`autoStart()`](#autostart) which case you are in, and [`isStarted()`](#isstarted) whether the loop is currently alive. Stopping the scheduler never interrupts a batch in progress — it finishes normally. + +## Ejemplo + +```4d +// --- Start at server startup, unless the host does it for us --- +If (Not(cs.EmbeddingStudio.Scheduler.me.autoStart())) + cs.EmbeddingStudio.Scheduler.me.start() +End if + +// --- Admin panel: force a recalculation and read status --- +var $status:=cs.EmbeddingStudio.Scheduler.me.force() + +// --- Monitoring: display last / next run and current state --- +$status:=cs.EmbeddingStudio.Scheduler.me.status() +var $info:="Mode: "+$status.mode\ + +" — Last: "+String($status.lastExecution)\ + +" — Next: "+String($status.nextRun)\ + +" — "+($status.running ? "running" : String($status.lastResult)) + +// --- Cancel a long-running batch --- +cs.EmbeddingStudio.Scheduler.me.cancel() + +// --- Disable automatic runs --- +cs.EmbeddingStudio.Scheduler.me.stop() +``` diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Settings.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Settings.md new file mode 100644 index 00000000000000..c7a4cef3f972f3 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Settings.md @@ -0,0 +1,184 @@ +--- +id: settings +title: Propiedades +--- + +# Propiedades + +The `Settings` class is the persisted configuration for the embedding pipeline. It loads and saves a JSON file (default: `Settings/embeddings.json`, overridable with the `EMBEDDINGS_SETTINGS_PATH` environment variable) containing a list of [Definition](Definition.md) entries, a batch size, and phrase-validation options. + +## Propiedades + +| Nombre de la propiedad | Tipo | Descripción | +| ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `definitions` | Collection of [Definition](Definition.md) | The configured definitions. | +| `batchSize` | Integer | Chunk size used by [Process.processEntitySelection](Process.md#processentityselection). Default: `50`. | +| `phrase` | Object | Phrase-validation options (see below). | +| `embedder` | Object | Optional embedder configuration (see below). | +| `file` | 4D.File *(read-only)* | The backing file the settings are loaded from and saved to. | + +### phrase options + +Passed verbatim to [Phrase.validate()](Phrase.md#validate) whenever the pipeline validates a definition. + +| Campo | Tipo | Por defecto | Descripción | +| ----------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------- | +| `allowRelations` | Boolean | `False` | Allow dot-notation through N:1 / 1:1 relations. | +| `allowCalculated` | Boolean | `False` | Allow calculated attributes in phrases. | +| `allowAlias` | Boolean | `False` | Allow alias attributes in phrases. | +| `allowObject` | Boolean | `False` | Allow object attributes in phrases. | + +> **Invalidation caveat.** Dirty-flag tracking only covers direct scalar fields on the entity. Fields that are only reachable through one of these options — a related entity's attribute, a calculated value, an alias, or a sub-property of an object — will **not** automatically mark the entity as dirty when they change. If such fields are part of a phrase and their source data changes, the vector will not be recomputed unless you call `invalidateVectors()` explicitly or use `force: true` when processing. + +### embedder options + +Controls how [Process](Process.md) builds its embedder. When absent, a default `Embedder` is created with its own defaults. + +| Campo | Tipo | Por defecto | Descripción | +| ------------ | ------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `className` | Text | — | Name of a project class to instantiate instead of the built-in `Embedder`. The class must expose `embed` and `embedBatch` functions. If instantiation fails or the interface is missing, a diagnostic error is logged and the default `Embedder` is used as fallback. | +| `maxRetries` | Integer | `3` | Number of retry attempts on rate-limit errors (forwarded to `Embedder`). | +| `backoffMs` | Integer | `500` | Base back-off delay in ms, doubled each retry (forwarded to `Embedder`). | + +Any additional keys are forwarded as-is to the constructor of the target class (built-in or custom). + +## Formato del archivo + +```json +{ + "batchSize": 50, + "phrase": { + "allowRelations": false, + "allowCalculated": false, + "allowAlias": false, + "allowObject": false + }, + "embedder": { + "maxRetries": 5, + "backoffMs": 200 + }, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding-3-small", + "phrase": "Student {firstName} {lastName}", + "autoInvalidate": true + } + ] +} +``` + +Each definition may include `autoInvalidate` (`true` by default) to control save-time automatic invalidation. + +The same file also carries the `scheduler` key (see [Scheduler](Scheduler.md#configuration)) and any other top-level key you add: `Settings` reads and rewrites only the keys listed above and leaves the rest untouched. + +With a custom embedder class: + +```json +{ + "embedder": { + "className": "MyCustomEmbedder" + }, + "definitions": [...] +} +``` + +## Class constructor + +Create a settings instance. The configuration file is loaded immediately. + +| Nombre del argumento | Tipo | Descripción | +| -------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| *file* | 4D.File | Opcional. A file to use instead of the default location. The override applies process-wide for subsequent settings access. **Not supported in 4D Remote mode** — pass it only when running locally or on the server. | + +When *file* is omitted, the default location is used: `Settings/embeddings.json`, or the path given by the `EMBEDDINGS_SETTINGS_PATH` environment variable. + +```4d +// Default location +var $settings:=cs.EmbeddingStudio.Settings.new() + +// Custom file (server / mono only) +var $settings:=cs.EmbeddingStudio.Settings.new(File("/some/path/custom.json")) +``` + +## Funciones + +### load() + +**load**() + +Reload the backing file into memory, overwriting in-memory state. A missing file resets to defaults without raising. + +A file that **exists but cannot be parsed** also leaves the instance on defaults, but it is remembered: an error is logged and [`save()`](#save) then refuses to write, so a malformed file is never silently replaced by defaults. + +### save() + +**save**() : Boolean + +Serialize the current in-memory state to the backing file. Only the keys this class owns (`batchSize`, `phrase`, `embedder`, `definitions`) are written — every other top-level key present in the file (the `scheduler` configuration, model aliases…) is preserved as-is. A key whose value is back to its default is *removed* from the file rather than written. + +Definitions are merged with what the file holds at that instant, using the snapshot taken at load time as the common ancestor: two editors open at the same time no longer drop each other's definitions. + +| Resultado | Tipo | Descripción | +| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| resultado | Boolean | `True` when written. `False` — nothing written — when the file could not be read at load time. | + +```4d +$settings.definitions.push(cs.EmbeddingStudio.Definition.new("Students"; "student_vector_1"; "text-embedding-3-small"; "{firstName}")) +$settings.batchSize:=100 +$settings.save() +``` + +### find() + +**find**(*dataclassName* : Text ; *vectorName* : Text) : [Definition](Definition.md) + +Look up the saved definition for the given dataclass/vector pair. + +| Argumento | Tipo | Descripción | +| --------------- | --------------------------- | ------------------------------------------------------------------- | +| *dataclassName* | Text | Nombre de la dataclass. | +| *vectorName* | Text | Name of the vector field on that dataclass. | +| Resultado | [Definition](Definition.md) | The matching definition, or `Null` if none matches. | + +```4d +var $def:=$settings.find("Students"; "student_vector_1") +``` + +### findAll() + +**findAll**(*dataclassName* : Text) : Collection of [Definition](Definition.md) + +Return every saved definition configured for the given dataclass. + +| Argumento | Tipo | Descripción | +| --------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------- | +| *dataclassName* | Text | Nombre de la dataclass. | +| Resultado | Collection of [Definition](Definition.md) | All matching definitions (empty collection if none match). | + +```4d +var $defs:=$settings.findAll("Students") +// → every Students definition; used by Process.process(ds.Students) +``` + +### invalidateVectors() + +**invalidateVectors**() : Object + +Calls [`invalidateVectors()`](Definition.md#invalidatevectors) on every definition in `definitions` and merges the results into a single status object. + +| Argumento | Tipo | Descripción | +| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | +| Resultado | Object | `{updated: Integer, skipped: Integer, errors: Collection of Text}` — accumulated across all definitions. | + +```4d +var $result:=cs.EmbeddingStudio.Settings.new().invalidateVectors() +// → { updated: 120; skipped: 0; errors: [] } +``` + +## Ver también + +- [Definition](Definition.md) +- [Process](Process.md) +- [Phrase](Phrase.md) diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/StudioEmbedder.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/StudioEmbedder.md new file mode 100644 index 00000000000000..96e099d3e1461b --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/StudioEmbedder.md @@ -0,0 +1,125 @@ +--- +id: studioembedder +title: StudioEmbedder +--- + +# StudioEmbedder + +The `StudioEmbedder` class renders and embeds on demand, resolved against the Studio settings: a saved definition gives the phrase and the model, so the vector you compute matches the ones stored by [Process](Process.md). Nothing is persisted. Typical uses: building the vector of a search query, finding entities similar to a given one, or previewing the text sent for an entity. + +For the full batch pipeline that persists vectors on entities, see [Process](Process.md). + +## Propiedades + +| Nombre de la propiedad | Tipo | Descripción | +| ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------------- | +| `propiedades` | [Settings](Settings.md) | The settings (vectors, batch size, phrase validation options). | +| `embedder` | [Embedder](Embedder.md) | The API-calling engine. Stateless and swappable. | +| `opciones` | Object | Runtime options object. | + +## Class constructor + +| Nombre del argumento | Tipo | Descripción | +| -------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| *settings* | [Settings](Settings.md) | Opcional. If omitted, settings are loaded from the default `Settings/embeddings.json`. | +| *opciones* | Object | Optional runtime options. Supports `embedder` for injection. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings) +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings; {embedder: $mockEmbedder}) +``` + +## Funciones + +### render() + +**render**(*entity* : 4D.Entity ; *definitionOrPhrase* : Variant) : Text + +Return the text that [`embed()`](#embed) sends for an entity (the phrase rendered against it). No API call, no persistence. + +| Argumento | Tipo | Descripción | +| -------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *entity* | 4D.Entity | The entity to render against. | +| *definitionOrPhrase* | `Null`, [Phrase](Phrase.md), [Definition](Definition.md), Text, or plain object stub | `Null` → auto-resolve via settings (requires a unique match). Text → compiled as a throwaway `cs.EmbeddingStudio.Phrase`. Object stub → see [stub resolution](#stub-resolution). | +| Resultado | Text | The rendered text. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $text: Text +$text:=$studioEmbedder.render($student; $def) // use def's phrase +$text:=$studioEmbedder.render($student; cs.EmbeddingStudio.Phrase.new("Hi {firstName}")) +$text:=$studioEmbedder.render($student; "Student: {lastName}") // raw template +$text:=$studioEmbedder.render($student) // auto-resolve +$text:=$studioEmbedder.render($student; {vectorName: "student_vector_1"}) // stub → saved definition's phrase +$text:=$studioEmbedder.render($student; {phrase: "Hi {firstName}"}) // ad-hoc stub → inline template +``` + +### embed() + +**embed**(*input* : Variant ; *context* : Variant ; *model* : Text) : [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) + +Compute a vector for an arbitrary input, without persisting anywhere. + +| Argumento | Tipo | Descripción | +| --------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| *entrada* | Text or 4D.Entity | Text → embedded directly. Entity → phrase rendered then embedded. | +| *context* | Text, [Phrase](Phrase.md), [Definition](Definition.md), Text template, plain object stub, or `Null` | Provides phrase and/or model depending on *input*. Object stub → see [stub resolution](#stub-resolution). | +| *model* | Text | Optional explicit model name. Used when *context* does not carry one. | +| Resultado | [EmbedderResult](EmbedderResult.md) | The embedding result (use `.vector` to get the 4D.Vector). | + +Throws if no model can be determined. + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $vector: 4D.Vector + +// Text + model +$vector:=$studioEmbedder.embed("some text"; "text-embedding-3-small").vector + +// Text + definition (picks up def.modelAlias) +$vector:=$studioEmbedder.embed("some text"; $def).vector + +// Entity + definition (uses def.phrase + def.modelAlias) +$vector:=$studioEmbedder.embed($student; $def).vector + +// Entity + phrase + explicit model +$vector:=$studioEmbedder.embed($student; $phrase; "text-embedding-3-small").vector + +// Entity + ad-hoc template + model +$vector:=$studioEmbedder.embed($student; "Profile: {firstName} {lastName}"; "text-embedding-3-small").vector + +// Entity alone (auto-resolve, only when exactly one def matches the dataclass) +$vector:=$studioEmbedder.embed($student).vector + +// Entity + stub (deduces phrase + model from the matching saved definition) +$vector:=$studioEmbedder.embed($student; {vectorName: "student_vector_1"}).vector + +// Entity + ad-hoc stub (phrase compiled inline, model taken from the stub) +$vector:=$studioEmbedder.embed($student; {phrase: "Hi {firstName}"; modelAlias: "text-embedding-3-small"}).vector + +// Text + stub that only supplies the model +$vector:=$studioEmbedder.embed("some text"; {modelAlias: "text-embedding-3-small"}).vector +``` + +## Stub resolution + +Both `render()` and `embed()` accept a plain object in place of a `Phrase`/`Definition`. A stub is resolved the same way [`Process`](Process.md#definition-resolution-entity-context) resolves its `definition` argument, so the behavior matches. Two flavors are supported: + +| Stub | Resolves to | +| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `{vectorName: "..."}` (optionally `{dataclassName: "..."}`) | The matching **saved definition** for the entity's dataclass — deducing its phrase (and, for `embed`, its model). Resolves to nothing when there is no unique match. | +| `{phrase: "tpl {field}"}` or `{template: "tpl {field}"}` | An **ad-hoc** `Phrase` compiled inline; nothing is looked up. Pair with `{modelAlias: "..."}` to give `embed()` a model. | + +For `embed()`, the model is deduced in this order: an explicit `{modelAlias}` on the stub → the model of a stub-matched saved definition → the *model* argument → the entity's unique definition. An explicit `{modelAlias}` always wins. + +Unlike [`Process.process()`](Process.md#process-resolution), a stub is **not** turned into a brand-new `Definition` from its fields — `StudioEmbedder` persists nothing, so use `{phrase}`/`{template}` for one-off templates. + +## Ver también + +- [Process](Process.md) +- [Settings](Settings.md) +- [Definition](Definition.md) +- [Embedder](Embedder.md) +- [EmbedderResult](EmbedderResult.md) +- [Phrase](Phrase.md) diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/license.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/license.md new file mode 100644 index 00000000000000..8f6fc0dd2b5ffc --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/license.md @@ -0,0 +1,167 @@ +--- +id: license +title: SOFTWARE LICENSE AGREEMENT +--- + +# SOFTWARE LICENSE AGREEMENT + +## Preamble + +The purpose of this Software license agreement is to grant users the right to modify and re-use the software governed by this license. + +The exercising of this right is conditional upon the obligation to make /available to the community the modifications made to the source code of the software so as to contribute to its evolution. + +In consideration of access to the source code and the rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software's author, the holder of the economic rights, and the successive licensors only have limited liability. + +## Article 1 – DEFINITIONS + +***Agreement***: means this license agreement, and its possible subsequent versions and annexes. + +***Software***: means the software in its Object Code and/or Source Code form and, where applicable, its documentation, "as is" when the Licensee accepts the Agreement. + +***Initial Software***: means the Software in its Source Code and possibly its Object Code form and, where applicable, its documentation, "as is" when it is first distributed under the terms and conditions of the Agreement. + +***Modified Software***: means the Software modified by at least one Integrated Contribution. + +***Source Code***: means all the Software's instructions and program lines to which access is required so as to modify the Software. + +***Object Code***: means the binary files originating from the compilation of the Source Code. + +***Holder***: means the holder(s) of the economic rights over the Initial Software, in this case it is 4D SAS. + +***Licensee***: means the Software user(s) having accepted the Agreement. + +***Contributor***: means a Licensee having made at least one Integrated Contribution. + +***Licensor***: means the Holder, or any other individual or legal entity, who distributes the Software under the Agreement. + +***Integrated Contribution***: means new functions integrated into the Source Code by any or all Contributors. + +***Parties***: mean both the Licensee and the Licensor. + +These expressions may be used both in singular and plural form. + +## Article 2 - PURPOSE + +The purpose of the Agreement is the grant by the Licensor to the Licensee of a non-exclusive, transferable and worldwide license for the Software as set forth in Article 5 hereinafter for the whole term of the protection granted by the rights over said Software. + +## Article 3 - ACCEPTANCE + +The Licensee shall be deemed as having accepted the terms and conditions of this Agreement upon the occurrence of the first of the following events: + +- loading the Software by any or all means, notably, by downloading from a remote server; +- the first time the Licensee exercises any of the rights granted hereunder. + +## Article 4 - EFFECTIVE DATE AND TERM + +### 4.1 EFFECTIVE DATE + +The Agreement shall become effective on the date when it is accepted by the Licensee as set forth in Article 3. + +### 4.2 TERM + +The Agreement shall remain in force for the entire legal term of protection of the economic rights over the Software. + +## Article 5 - SCOPE OF RIGHTS GRANTED + +The Licensor hereby grants to the Licensee, who accepts, the following rights over the Software for the term of the Agreement, on the basis of the terms and conditions set forth hereinafter. + +### 5.1 RIGHT OF USE + +The Licensee is authorized to use the Software, without any limitation as to its fields of application, with it being hereinafter specified that this comprises: + +- permanent or temporary reproduction of all or part of the Software by any or all means and in any or all form. +- loading, displaying, running, or storing the Software on any or all medium. +- entitlement to observe, study or test its operation. + +### 5.2 RIGHT OF MODIFICATION + +The right of modification means the right to adapt, arrange, or make any or all modifications to the Software; being understood that such modifications of the Software shall results in a change of its functionalities and/or in an addition of functionalities to the Initial Software. + +Consequently to distribute a Modified Software according to the provision of section 5.3.2, the Licensee shall make exclusively significant modification as described above to the Software provided that it includes an explicit notice that it is the author of said modification and indicates the date of the creation thereof. + +### 5.3 RIGHT OF DISTRIBUTION + +In particular, the right of distribution includes the right to publish, transmit and communicate the Modified Software to the general public on any or all medium, and by any or all means, and the right to market, either in consideration of a fee, or + +#### 5.3.1 DISTRIBUTION OF SOFTWARE WITHOUT MODIFICATION + +The Licensee is forbidden to distribute true copies of the Software in Source Code or Object Code form. + +#### 5.3.2 DISTRIBUTION OF MODIFIED SOFTWARE + +When the Licensee creates Modified Software, this Modified Software may be distributed provided that said distribution complies with all the provisions of the Agreement and subject to compliance with the requirement to include a notice concerning the rights over the Software as defined in Article 6.3. + +In the event the creation of the Modified Software, the Licensee undertakes that: + +- the resulting Modified Software will be governed by this Agreement, being understood that such Agreement shall be integrated in the Modified Software the Integrated Contributions in the resulting Modified Software will be clearly identified and documented, +- the Licensee will allow effective access to the source code of the Modified Software, at a minimum during the entire period of distribution of the Derivative Software, such that such modifications may be carried over in a subsequent version of the Software. +- the Modified Software must be renamed to exclude any reference to 4D. For example, it is expressly prohibited to distribute a Modified Software named “4D SVG”; Licensee shall rename the Modified Software such as “Name of the Licensee SVG”. Consequently, Licensee is expressly forbidden to use 4D’s product name in general to promote his modified work. + +## Article 6 - INTELLECTUAL PROPERTY + +### 6.1 OVER THE INITIAL SOFTWARE + +The Holder owns the intellectual property rights over the Initial Software. Any or all use of the Initial Software is subject to compliance with the terms and conditions under which the Holder has elected to distribute its work and no one shall be entitled to modify the terms and conditions for the distribution of said Initial Software. + +### 6.2 OVER THE INTEGRATED CONTRIBUTIONS + +The Licensee who develops an Integrated Contribution is the owner of the intellectual property rights over this Contribution as defined by applicable law. + +### 6.3 NOTICE OF RIGHTS + +The Licensee expressly undertakes: + +- not to remove, or modify, in any manner, the intellectual property notices attached to the Software; +- to reproduce said notices, in an identical manner, in the copies of the Software modified; +- to ensure that use of the Software, its intellectual property notices and the fact that it is governed by the Agreement is indicated in a text that is easily accessible, specifically from the interface of any Modified Software. + +The Licensee undertakes not to directly or indirectly infringe the intellectual property rights of the Holder on the Software and to take, where applicable, vis- à-vis its staff, any and all measures required to ensure respect of said intellectual property rights of the Holder. + +## Article 7 - RELATED SERVICES + +Under no circumstances shall the Agreement oblige the Licensor to provide technical assistance or maintenance services for the Software. + +However, the Licensor is entitled to offer this type of services. The terms and conditions of such technical assistance, and/or such maintenance, shall be set forth in a separate instrument. + +## Article 8 - DISCLAIMER OF WARRANTY. + +THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE HOLDER PROVIDES THE SOFTWARE “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH LICENSEE. SHOULD THE SOFTWARE PROVE DEFECTIVE, LICENSEE ASSUMES THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +## Article 9 - LIMITATION OF LIABILITY + +TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE TO LICENSEE ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS AGREEMENT OR USE OF THE SOFTWARE, EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR DAMAGES. + +## Article 10 – TERMINATION + +### 10.1 + +In the event of a breach by the Licensee of its obligations hereunder, the Licensor may automatically terminate this Agreement thirty (30) days after notice has been sent to the Licensee and has remained ineffective. + +### 10.2 + +A Licensee whose Agreement is terminated shall no longer be authorized to use, modify or distribute the Software. However, any licenses that it may have granted prior to termination of the Agreement shall remain valid subject to their having been granted in compliance with the terms and conditions hereof. + +## Article 11 – MISCELLANEOUS + +### 11.1 + +Neither Party shall be liable for any or all delay, or failure to perform the Agreement, that may be attributable to an event of force majeure, an act of God or an outside cause, such as defective functioning or interruptions of the electricity or telecommunications networks, network paralysis following a virus attack, intervention by government authorities, natural disasters, water damage, earthquakes, fire, explosions, strikes and labor unrest, war, etc. + +### 11.2 + +Any failure by either Party, on one or more occasions, to invoke one or more of the provisions hereof, shall under no circumstances be interpreted as being a waiver by the interested Party of its right to invoke said provision(s) subsequently. + +### 11.3 + +In the event that one or more of the provisions hereof were to conflict with a current or future applicable act or legislative text, said act or legislative text shall prevail, and the Parties shall make the necessary amendments so as to comply with said act or legislative text. All other provisions shall remain effective. Similarly, invalidity of a provision of the Agreement, for any reason whatsoever, shall not cause the Agreement as a whole to be invalid. + +## Article 12 - GOVERNING LAW AND JURISDICTION + +### 12.1 + +The Agreement is governed by French law. The Parties agree to endeavor to seek an amicable solution to any disagreements or disputes that may arise during the performance of the Agreement. + +### 12.2 + +Failing an amicable solution within two (2) months as from their occurrence, and unless emergency proceedings are necessary, the disagreements or disputes shall be referred to the Versailles Courts having jurisdiction, by the more diligent Party. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/overview.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/overview.md new file mode 100644 index 00000000000000..a45d58e4af31a5 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/overview.md @@ -0,0 +1,211 @@ +--- +id: overview +title: 4D-Embedding-Studio +--- + +# 4D-Embedding-Studio + +## Generalidades + +4D Embedding Studio is a component for defining, processing, and maintaining AI embedding vectors directly in your 4D dataclass entities. + +You can use the component without writing a single line of code: select attributes from your dataclasses to construct the sentences to be vectorized and specify the model to use. For each entity, the component calls the embedding API and stores the resulting `4D.Vector` values. Configure the embedding scheduler to (re)calculate the vectors for your data at fixed intervals or on demand. + +You can then use the ORDA [`query()` by vector feature](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity) to request your data using semantics. + +If you want to have more control over your embeddings, the component offers an extensive API that allows you to customize each step of the data vectorization process, manage the scheduler, and integrate high-performance RAG (*Retrieval Augmented Generation*) features into your 4D application. + +## Requisitos + +- [4D-AIKit](https://github.com/4d/4D-AIKit) (loaded automatically as a dependency). +- 4D project (21 R5 or later) with the following configuration: + - a valid model alias + - a dataclass with a `4D.Vector` attribute (object field at the database level). + +## Quick Start + +**1. Add a field of type Object to the table and associate it with the `4D.Vector` class.** +**2. Select **Embedding Studio...** in the **Design** menu to display the Embedding Studio window.** + +![menu](../assets/en/embedding-studio/menu.png) + +**3. For each listed `4D.Vector` attribute, write a descriptive phrase based upon attributes of the dataclass.** +Use the contextual menu to insert appropriate attributes. +This phrase will be vectorized for every entity. +**4. Select a model alias (or create a new one).** +**5. Select "Execute now" to launch the vectorization of your data or configure the scheduler.** + +## User Guide + +### Configuring the dataclass + +To use the 4D Embedding Studio interface, you need to create at least one object attribute associated to a `4D.Vector` class in your datastore. This must be done at the database level (only storage attributes can be embeddings). + +In the Structure editor, add an Object field to the dataclass (table) whose entities you want to query using AI and enter ["4D.Vector" as class](https://developer.4d.com/docs/Develop/structure-fields#class). + +#### Dirty-flag support + +In a production application, data is rarely static. If an embedding is based on an attribute value that has changed (e.g. a product description), it becomes obsolete and could no longer be relevant. By default, 4D automatically invalidates and flags for recalculation affected embeddings. + +If you do not use a dirty-flag field (see below), 4D simply replaces any invalidated vector by `Null`. It is therefore no longer used in searches until its next calculation. This option is suitable for applications that prioritize strict consistency: it is better to return no results than to rely on an embedding that no longer matches the current data. + +Or, you can add a Boolean field named `_dirty` (e.g. "myVector_dirty") to the structure. In this case, when an update is required, this field is set to `True`, and the associated vector is retained until it is recalculated. Your application can then choose to continue using this vector temporarily or exclude it using a filter on `dirty = False`. The flag is cleared automatically after a successful save. +This strategy promotes service continuity while allowing you to precisely identify vectors awaiting recalculation. If your business logic requires full control, you can also disable automatic invalidation and manage this lifecycle yourself. + +*Note: Certain modifications, such as a model changes, require vectors to be replaced immediately.* + +### Creating an embedding + +When you select **Embedding Studio...** in the **Design** menu, the Embedding Studio window is displayed. + +The list on the left side shows all `4D.Vector` class attributes defined in the datastore. You can add as many vector attributes as you want per dataclass. + +A check mark (✓) in the Dirty Flag column indicates that a [`_dirty` boolean field](#dirty-flag-support) is associated to the vector field. + +**Note:** Any change in the database structure will require that you restart the 4D application so that the 4D Embedding Studio lists up-to-date values. + +#### Writing a descriptive sentence + +To create or edit an embedding, select the attribute to configure in this list and write the embedding definition in the "Descriptive sentence" area on the right side. Use the associated menu to build the sentence and to add references to dataclass available attributes with the `{attribute_name}` syntax. + +The sentence must build a text that describes the entity just like a human would do it. The embedding could then capturate the semantics and not only attribute values. + +For example, for a `Product` dataclass with many attributes such as name and category, you could write: +"The {name} product is a {category} from the {brand} brand. Description: {description}. Key features: {features}." + +![menu](../assets/en/embedding-studio/studio-interface.png) + +### Selecting a model + +Once you have defined your vector attribute, choose the model to use for generating the embedding. The list of models includes the **model aliases** you defined in the [Project Settings](https://developer.4d.com/docs/settings/ai#model-aliases). + +The choice of model is important because it determines the relevance and quality of your embeddings. You’ll also need to provide this model with every query on the dataclass data so that the comparison is performed using the same model. + +### Auto-invalidate on save + +When this option is checked (default), embeddings are automatically invalidated when at least one of their definition attributes has been modified and the entity was successfully saved. + +However, you might want to handle invalidation in a custom way using the [4D Embedding Studio API](#api-guide). In this case, uncheck this option to disable the automatic mechanism. + +### Calculating embeddings + +Embeddings are calculated by sending a request to the AI model, which then returns the vectorization result, which is subsequently stored in the `4D.Vector` attribute in the dataclass. 4D automatically handles this operation and optimizes it by calculating only the necessary vectors. Each vector is processed independently. Thus, an error on one element does not interrupt the recalculation of the others. Elements that fail will be automatically retried during the next run. Recalculations are performed asynchronously, without blocking users. + +These calculations can be performed **on demand** or **scheduled at regular intervals** using the scheduler in the 4D Embedding Studio component. + +**Note:** You can also customize embedding calculations per dataclass or entity using the [4D Embedding Studio API](#api-guide). + +#### On demand + +To launch an embedding calculation, select **Run now** in the menu at the bottom of the 4D Embedding Studio window. This item is disabled if the datastore does not contain any embedding to calculate. When started, you can select **Cancel run** at any moment. + +#### Backups periódicos + +You can configure the 4D Embedding Studio component scheduler to adjust the calculation frequency to suit your application’s needs. + +**Important:** The scheduler needs a 4D worker process to run. You can start it manually for testing purposes (**Start now** button in the scheduler dialog box) but to make sure a worker is available every times the application opens, you need to configure it. Puede: + +- select the **Execute "On Host Database Event" method of the components** option in the [project Settings](https://developer.4d.com/docs/settings/security#options) +- or write the following code in your startup code: + +```4d + //at startup +cs.EmbeddingStudio.Scheduler.me.start() +``` + +The scheduler allows you can set the time interval between two calculations. Select the tab corresponding to your needs and click **Save**. + +- **Never**: the scheduler is off and never runs +- **At regular interval**: set the time interval between each calculation starting from a specified time. +- **Once a day**: the calculation takes place every day at a specific time + starting from a specific time. + +### Building queries with embeddings + +Once you have defined embeddings in your datastore, you can start [querying your dataclasses using AI-based features](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity). You just need to make sure that you use the same model for your embedding definition and in the query string. + +For example, assuming that: + +• you have defined a `4D.Vector` attribute named "product_vector" in the Products dataclass using a sentence: "The {name} is in the {category} category. It has these {features} features and can be used for {usage}." +• you want to find products that "can be used safely outside". + +Puede escribir: + +```4d +// Retrieve the model alias from the embedding definition, configured in 4D Embedding Studio +var $settings:=cs.EmbeddingStudio.Settings.new() +var $definition:=$settings.find("Products"; "product_vector") + +// Compute the vector of the query with the same model +var $result:=cs.EmbeddingStudio.StudioEmbedder.new().embed("products that can be used safely outside"; $definition) +var $vector:=$result.vector + + //search with default metric (cosine) +var $products:=ds.Products.query("product_vector > :1 order by product_vector desc"; {vector : $vector}) + +``` + +If you use a dirty field, simply add a criterion to exclude vectors waiting to be recalculated: + +```4d +var $products:=ds.Products.query("product_vector > :1 and product_vector_dirty = false order by product_vector desc"; {vector : $vector}) +``` + +## API Guide + +### Quick start + +**1. Configure your vectors** in `Settings/embeddings.json`: + +```json +{ + "batchSize": 50, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding", + "phrase": "Student {firstName} {lastName}, enrolled in {program}", + "autoInvalidate": true + } + ] +} +``` + +**2. Run the full pipeline** (all definitions, all records): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +var $r:=$p.process() + +If ($r.success) + ALERT("Updated "+String($r.entitiesUpdated)+" entities in "+String($r.duration)+" ms") +End if +``` + +**3. Process a single entity on save** (e.g. in a trigger or REST hook): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +$p.processEntity($entity) +``` + +### Class reference + +| Class | Descripción | +| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Process](Classes/Process.md) | Main orchestrator — entry point for all batch and entity operations. | +| [Scheduler](Classes/Scheduler.md) | Automated recalculation scheduler — background task, force/cancel, and runtime status. | +| [StudioEmbedder](Classes/StudioEmbedder.md) | Renders and embeds on demand using your saved definitions — e.g. to build a search query vector. Nothing is persisted. | +| [Settings](Classes/Settings.md) | Loads and saves the `embeddings.json` configuration file. | +| [Definition](Classes/Definition.md) | Describes one vector field: dataclass, field name, model alias, and phrase template. | +| [Embedder](Classes/Embedder.md) | Thin wrapper around the AIKit embeddings API with retry/backoff logic. | +| [EmbedderResult](Classes/EmbedderResult.md) | Typed wrapper normalizing API responses — vectors, usage metrics, rate-limit state. | +| [ProcessResult](Classes/ProcessResult.md) | Returned by every batch function — statistics and error breakdown. | +| [ProcessError](Classes/ProcessError.md) | Typed entry in `ProcessResult.errors` — scope, severity, code, ref, message, retryable. | +| [ProcessErrorCode](Classes/ProcessErrorCode.md) | Singleton catalogue of machine-readable error codes and their default severity/retryability. | +| [Phrase](Classes/Phrase.md) | Lightweight `{variable}` template engine used to build text from entity attributes. | + +### Ver también + +Blog post: [Vectorize your data effortlessly with 4D Embedding Studio](https://blog.4d.com/vectorize-your-data-effortlessly-with-4d-vector-studio) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/ratelimit.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/ratelimit.md new file mode 100644 index 00000000000000..ac90518d4805db --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/ratelimit.md @@ -0,0 +1,65 @@ +--- +id: ratelimit +title: Rate Limiting +--- + +# Rate Limiting + +The embedding pipeline includes built-in rate-limit awareness. When the API provider returns rate-limit headers (as OpenAI does), the system automatically throttles requests and adapts batch sizes to stay within budget. Providers that don't return rate-limit headers (e.g. Ollama) are unaffected — the pipeline runs at full speed. + +## Principios de funcionamiento + +Each call to [`Embedder.embed()`](Classes/Embedder.md) or [`Embedder.embedBatch()`](Classes/Embedder.md) returns an [`EmbedderResult`](Classes/EmbedderResult.md) that carries rate-limit state alongside the embedding vectors. The pipeline uses this data in a three-step loop: + +1. **Pre-flight throttle** — before sending a batch, the pipeline checks whether the remaining token budget is sufficient. If not, it waits for the reset window to elapse before proceeding. +2. **Adaptive batch sizing** — the pipeline computes the largest batch that fits within 80% of the remaining token budget. This avoids hitting the ceiling while still making efficient use of the quota. +3. **State update** — after each API response, the pipeline records the new remaining budget, computes an average tokens-per-entity estimate, and feeds both into the next iteration. + +## Rate-limit fields on EmbedderResult + +These fields are populated from the API response headers. When a provider doesn't return them, they keep their defaults and the pipeline skips throttling. + +| Campo | Por defecto | Significado | +| ------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `remainingTokens` | `-1` | Tokens left in the current window. `-1` = unknown. | +| `remainingRequests` | `-1` | Requests left in the current window. | +| `limitTokens` | `0` | TPM (tokens per minute) ceiling. | +| `limitRequests` | `0` | RPM (requests per minute) ceiling. | +| `resetTokens` | `""` | Time until the token bucket refills (e.g. `"6m0s"`, `"200ms"`). | +| `resetRequests` | `""` | Time until the request bucket refills. | + +## Batch size adaptation + +The pipeline starts with the configured `batchSize` (from [Settings](Classes/Settings.md), default 50). After the first API response provides rate-limit data, the batch size may shrink: + +``` +nextBatchSize = min( floor(remainingTokens × 0.8 / tokensPerEntity), configBatchSize ) +``` + +- `tokensPerEntity` is estimated from the last chunk (`totalTokens / chunkSize`). +- The result is clamped to a floor of 1 and a ceiling of `configBatchSize`. +- When `remainingTokens` is unknown (`-1`), the configured batch size is used as-is. + +## Pre-flight wait + +Before each batch, the pipeline checks: + +- **Token budget**: if `remainingTokens < estimatedTokens × 1.1`, it waits for the token reset window. +- **Request budget**: if `remainingRequests = 0`, it waits for the request reset window. + +The reset durations are parsed from the API's string format (`"6m0s"` → 360 seconds, `"200ms"` → 1 second). + +## Providers without rate limits + +Some providers (Ollama, local models) don't return rate-limit headers. En este caso: + +- `remainingTokens` stays at `-1` (unknown) +- No throttling occurs — batches run at `configBatchSize` without waits +- The pipeline works identically to how it did before rate-limit support was added + +## Ver también + +- [EmbedderResult](Classes/EmbedderResult.md) — carries rate-limit fields +- [Embedder](Classes/Embedder.md) — wraps the API calls +- [Process](Classes/Process.md) — orchestrates the batch loop +- [Settings](Classes/Settings.md) — `batchSize` configuration diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md index c6067334c0f0f5..900114887825bc 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md @@ -822,7 +822,7 @@ Consulte el ejemplo 2. **Valores posibles**: entero positivo. Valor predeterminado = 900, valor mínimo = 60. -**Descripción**: tiempo de espera en segundos para las sesiones cliente/servidor en caso de desconexión inesperada al utilizar la capa de red QUIC. Este tiempo de espera es el período permitido para una sesión durante el cual la conexión entre el servidor y el cliente puede restablecerse automáticamente tras una desconexión involuntaria. Si, al final de este tiempo de espera, la conexión no se ha restablecido, la sesión se cierra. +**Descripción**: tiempo de espera en segundos para las sesiones cliente/servidor en caso de desconexión inesperada al utilizar la capa de red QUIC. Este tiempo de espera es el período permitido para una sesión durante el cual la conexión entre el servidor y el cliente puede restablecerse automáticamente tras una desconexión involuntaria. Si, al final de este tiempo de espera, la conexión no se ha restablecido, la sesión cliente se cierra con un mensaje. Este parámetro solo puede configurarse en 4D Server y se aplica a todas las nuevas sesiones remotas de 4D (el valor del tiempo de espera de las sesiones existentes no se modifica). diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md index 9528b84eee6237..21bf395bf412c0 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md @@ -32,7 +32,7 @@ displayed_sidebar: docs El comando **FORM Get current page** devuelve el número de la página actual del formulario mostrada actualmente o del formulario actual cargado vía el comando [FORM LOAD](../commands/form-load). -El parámetro *\** es útil cuando el comando se llama en el contexto de un subformulario en página que contiene varias páginas. En este caso, cuando pase este parámetro, el comando cambia la página del subformulario actual (la que llamó al comando). Por defecto, cuando se omite el parámetro *\**, el comando se aplica siempre al formulario padre. +El parámetro *\** es útil cuando el comando se llama en el contexto de un subformulario en página que contiene varias páginas. En este caso, cuando pase este parámetro, el comando devuelve el número de página del subformulario actual (el que llamó al comando). Por defecto, cuando se omite el parámetro *\**, el comando se aplica siempre al formulario padre. ## Ejemplo diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md index 1db113b0ca4fa3..b50965f4ee7173 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md @@ -45,6 +45,16 @@ En el parámetro opcional *settings*, puede pasar un objeto que contenga la sigu | --------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------- | | context | Text | Etiqueta para el [contexto de optimización](../../ORDA/client-server-optimization.md) aplicado a la selección de entidades. | +:::info + +Por razones de rendimiento, en 4D monopuesto y 4D Server, la selección de entidades devuelta está directamente conectada a la selección actual de *dsTable* (no es una copia). Mientras no se reemplace la selección actual, los cambios realizados en una se reflejan en la otra. Por ejemplo, [`REDUCE SELECTION`](../commands/reduce-selection) reduce la selección de entidades, y [`.add()`](../../API/EntitySelectionClass.md#add) aplicada a la selección de entidades añade la entidad a la selección actual. Para obtener una selección de entidades independiente, llame a [`.copy()`](../../API/EntitySelectionClass.md#copy) en el resultado: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Ejemplo ```4d diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md index a2c50c144ca8cc..703167b16f1b66 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md @@ -39,7 +39,7 @@ El parámetro *contenido* recibe el contenido de la parte. Cuando las partes a r El parámetro *nombre* recupera el nombre de la variable del campo input HTTP. -Los parámetros *tipoMime* y *nomArchivo* reciben el tipo Mime y el nombre del archivo original, si lo hay. nomArchivo solo se recibe cuando el archivo se envio como ``. +Los parámetros *tipoMime* y *nomArchivo* reciben el tipo Mime y el nombre del archivo original, si lo hay. *nomArchivo* solo se recibe cuando el archivo se envió como ``. *tipoMime* y *nomArchivo* son opcionales pero deben pasarse juntos. **Nota**: en el contexto de una petición multi-part, el primer de array del comando [WEB GET VARIABLES](../commands/web-get-variables) devuelve todas las partes del formulario, en el mismo orden que el comando **WEB GET BODY PART**. Puede utilizarlo para obtener directamente la posición de una parte de un formulario. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/assets/en/Develop/index-add.png b/i18n/fr/docusaurus-plugin-content-docs/current/assets/en/Develop/index-add.png new file mode 100644 index 00000000000000..05e72c5f179854 Binary files /dev/null and b/i18n/fr/docusaurus-plugin-content-docs/current/assets/en/Develop/index-add.png differ diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Settings.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Settings.md new file mode 100644 index 00000000000000..45c3b4fc59db17 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Settings.md @@ -0,0 +1,184 @@ +--- +id: settings +title: Propriétés +--- + +# Propriétés + +The `Settings` class is the persisted configuration for the embedding pipeline. It loads and saves a JSON file (default: `Settings/embeddings.json`, overridable with the `EMBEDDINGS_SETTINGS_PATH` environment variable) containing a list of [Definition](Definition.md) entries, a batch size, and phrase-validation options. + +## Propriétés + +| Nom de propriété | Type | Description | +| ---------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `definitions` | Collection of [Definition](Definition.md) | The configured definitions. | +| `batchSize` | Integer | Chunk size used by [Process.processEntitySelection](Process.md#processentityselection). Default: `50`. | +| `phrase` | Object | Phrase-validation options (see below). | +| `embedder` | Object | Optional embedder configuration (see below). | +| `file` | 4D.File *(read-only)* | The backing file the settings are loaded from and saved to. | + +### phrase options + +Passed verbatim to [Phrase.validate()](Phrase.md#validate) whenever the pipeline validates a definition. + +| Champ | Type | Par défaut | Description | +| ----------------- | ------- | ---------- | ----------------------------------------------------------------------------------------------- | +| `allowRelations` | Boolean | `False` | Allow dot-notation through N:1 / 1:1 relations. | +| `allowCalculated` | Boolean | `False` | Allow calculated attributes in phrases. | +| `allowAlias` | Boolean | `False` | Allow alias attributes in phrases. | +| `allowObject` | Boolean | `False` | Allow object attributes in phrases. | + +> **Invalidation caveat.** Dirty-flag tracking only covers direct scalar fields on the entity. Fields that are only reachable through one of these options — a related entity's attribute, a calculated value, an alias, or a sub-property of an object — will **not** automatically mark the entity as dirty when they change. If such fields are part of a phrase and their source data changes, the vector will not be recomputed unless you call `invalidateVectors()` explicitly or use `force: true` when processing. + +### embedder options + +Controls how [Process](Process.md) builds its embedder. When absent, a default `Embedder` is created with its own defaults. + +| Champ | Type | Par défaut | Description | +| ------------ | ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `className` | Text | — | Name of a project class to instantiate instead of the built-in `Embedder`. The class must expose `embed` and `embedBatch` functions. If instantiation fails or the interface is missing, a diagnostic error is logged and the default `Embedder` is used as fallback. | +| `maxRetries` | Integer | `3` | Number of retry attempts on rate-limit errors (forwarded to `Embedder`). | +| `backoffMs` | Integer | `500` | Base back-off delay in ms, doubled each retry (forwarded to `Embedder`). | + +Any additional keys are forwarded as-is to the constructor of the target class (built-in or custom). + +## Format de fichier + +```json +{ + "batchSize": 50, + "phrase": { + "allowRelations": false, + "allowCalculated": false, + "allowAlias": false, + "allowObject": false + }, + "embedder": { + "maxRetries": 5, + "backoffMs": 200 + }, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding-3-small", + "phrase": "Student {firstName} {lastName}", + "autoInvalidate": true + } + ] +} +``` + +Each definition may include `autoInvalidate` (`true` by default) to control save-time automatic invalidation. + +The same file also carries the `scheduler` key (see [Scheduler](Scheduler.md#configuration)) and any other top-level key you add: `Settings` reads and rewrites only the keys listed above and leaves the rest untouched. + +With a custom embedder class: + +```json +{ + "embedder": { + "className": "MyCustomEmbedder" + }, + "definitions": [...] +} +``` + +## Class constructor + +Create a settings instance. The configuration file is loaded immediately. + +| Nom de l'argument | Type | Description | +| ----------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *file* | 4D.File | Optionnel. A file to use instead of the default location. The override applies process-wide for subsequent settings access. **Not supported in 4D Remote mode** — pass it only when running locally or on the server. | + +When *file* is omitted, the default location is used: `Settings/embeddings.json`, or the path given by the `EMBEDDINGS_SETTINGS_PATH` environment variable. + +```4d +// Default location +var $settings:=cs.EmbeddingStudio.Settings.new() + +// Custom file (server / mono only) +var $settings:=cs.EmbeddingStudio.Settings.new(File("/some/path/custom.json")) +``` + +## Fonctions + +### load() + +**load**() + +Reload the backing file into memory, overwriting in-memory state. A missing file resets to defaults without raising. + +A file that **exists but cannot be parsed** also leaves the instance on defaults, but it is remembered: an error is logged and [`save()`](#save) then refuses to write, so a malformed file is never silently replaced by defaults. + +### sauvegarde() + +**save**() : Boolean + +Serialize the current in-memory state to the backing file. Only the keys this class owns (`batchSize`, `phrase`, `embedder`, `definitions`) are written — every other top-level key present in the file (the `scheduler` configuration, model aliases…) is preserved as-is. A key whose value is back to its default is *removed* from the file rather than written. + +Definitions are merged with what the file holds at that instant, using the snapshot taken at load time as the common ancestor: two editors open at the same time no longer drop each other's definitions. + +| Résultat | Type | Description | +| -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| Résultat | Boolean | `True` when written. `False` — nothing written — when the file could not be read at load time. | + +```4d +$settings.definitions.push(cs.EmbeddingStudio.Definition.new("Students"; "student_vector_1"; "text-embedding-3-small"; "{firstName}")) +$settings.batchSize:=100 +$settings.save() +``` + +### chercher() + +**find**(*dataclassName* : Text ; *vectorName* : Text) : [Definition](Definition.md) + +Look up the saved definition for the given dataclass/vector pair. + +| Argument | Type | Description | +| ----------------------- | --------------------------- | ------------------------------------------------------------------- | +| *dataclassName* | Text | Nom de la dataclass. | +| *vectorName* | Text | Name of the vector field on that dataclass. | +| Résultat de la fonction | [Definition](Definition.md) | The matching definition, or `Null` if none matches. | + +```4d +var $def:=$settings.find("Students"; "student_vector_1") +``` + +### findAll() + +**findAll**(*dataclassName* : Text) : Collection of [Definition](Definition.md) + +Return every saved definition configured for the given dataclass. + +| Argument | Type | Description | +| ----------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------- | +| *dataclassName* | Text | Nom de la dataclass. | +| Résultat de la fonction | Collection of [Definition](Definition.md) | All matching definitions (empty collection if none match). | + +```4d +var $defs:=$settings.findAll("Students") +// → every Students definition; used by Process.process(ds.Students) +``` + +### invalidateVectors() + +**invalidateVectors**() : Object + +Calls [`invalidateVectors()`](Definition.md#invalidatevectors) on every definition in `definitions` and merges the results into a single status object. + +| Argument | Type | Description | +| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | +| Résultat de la fonction | Object | `{updated: Integer, skipped: Integer, errors: Collection of Text}` — accumulated across all definitions. | + +```4d +var $result:=cs.EmbeddingStudio.Settings.new().invalidateVectors() +// → { updated: 120; skipped: 0; errors: [] } +``` + +## Voir également + +- [Definition](Definition.md) +- [Process](Process.md) +- [Phrase](Phrase.md) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/StudioEmbedder.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/StudioEmbedder.md new file mode 100644 index 00000000000000..53ef4019d9b785 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/StudioEmbedder.md @@ -0,0 +1,125 @@ +--- +id: studioembedder +title: StudioEmbedder +--- + +# StudioEmbedder + +The `StudioEmbedder` class renders and embeds on demand, resolved against the Studio settings: a saved definition gives the phrase and the model, so the vector you compute matches the ones stored by [Process](Process.md). Nothing is persisted. Typical uses: building the vector of a search query, finding entities similar to a given one, or previewing the text sent for an entity. + +For the full batch pipeline that persists vectors on entities, see [Process](Process.md). + +## Propriétés + +| Nom de propriété | Type | Description | +| ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------- | +| `propriétés` | [Settings](Settings.md) | The settings (vectors, batch size, phrase validation options). | +| `embedder` | [Embedder](Embedder.md) | The API-calling engine. Stateless and swappable. | +| `options` | Object | Runtime options object. | + +## Class constructor + +| Nom de l'argument | Type | Description | +| ----------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| *settings* | [Settings](Settings.md) | Optionnel. If omitted, settings are loaded from the default `Settings/embeddings.json`. | +| *options* | Object | Optional runtime options. Supports `embedder` for injection. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings) +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings; {embedder: $mockEmbedder}) +``` + +## Fonctions + +### render() + +**render**(*entity* : 4D.Entity ; *definitionOrPhrase* : Variant) : Text + +Return the text that [`embed()`](#embed) sends for an entity (the phrase rendered against it). No API call, no persistence. + +| Argument | Type | Description | +| ----------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *entity* | 4D.Entity | The entity to render against. | +| *definitionOrPhrase* | `Null`, [Phrase](Phrase.md), [Definition](Definition.md), Text, or plain object stub | `Null` → auto-resolve via settings (requires a unique match). Text → compiled as a throwaway `cs.EmbeddingStudio.Phrase`. Object stub → see [stub resolution](#stub-resolution). | +| Résultat de la fonction | Text | The rendered text. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $text: Text +$text:=$studioEmbedder.render($student; $def) // use def's phrase +$text:=$studioEmbedder.render($student; cs.EmbeddingStudio.Phrase.new("Hi {firstName}")) +$text:=$studioEmbedder.render($student; "Student: {lastName}") // raw template +$text:=$studioEmbedder.render($student) // auto-resolve +$text:=$studioEmbedder.render($student; {vectorName: "student_vector_1"}) // stub → saved definition's phrase +$text:=$studioEmbedder.render($student; {phrase: "Hi {firstName}"}) // ad-hoc stub → inline template +``` + +### embed() + +**embed**(*input* : Variant ; *context* : Variant ; *model* : Text) : [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) + +Compute a vector for an arbitrary input, without persisting anywhere. + +| Argument | Type | Description | +| ----------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| *input* | Text or 4D.Entity | Text → embedded directly. Entity → phrase rendered then embedded. | +| *context* | Text, [Phrase](Phrase.md), [Definition](Definition.md), Text template, plain object stub, or `Null` | Provides phrase and/or model depending on *input*. Object stub → see [stub resolution](#stub-resolution). | +| *model* | Text | Optional explicit model name. Used when *context* does not carry one. | +| Résultat de la fonction | [EmbedderResult](EmbedderResult.md) | The embedding result (use `.vector` to get the 4D.Vector). | + +Throws if no model can be determined. + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $vector: 4D.Vector + +// Text + model +$vector:=$studioEmbedder.embed("some text"; "text-embedding-3-small").vector + +// Text + definition (picks up def.modelAlias) +$vector:=$studioEmbedder.embed("some text"; $def).vector + +// Entity + definition (uses def.phrase + def.modelAlias) +$vector:=$studioEmbedder.embed($student; $def).vector + +// Entity + phrase + explicit model +$vector:=$studioEmbedder.embed($student; $phrase; "text-embedding-3-small").vector + +// Entity + ad-hoc template + model +$vector:=$studioEmbedder.embed($student; "Profile: {firstName} {lastName}"; "text-embedding-3-small").vector + +// Entity alone (auto-resolve, only when exactly one def matches the dataclass) +$vector:=$studioEmbedder.embed($student).vector + +// Entity + stub (deduces phrase + model from the matching saved definition) +$vector:=$studioEmbedder.embed($student; {vectorName: "student_vector_1"}).vector + +// Entity + ad-hoc stub (phrase compiled inline, model taken from the stub) +$vector:=$studioEmbedder.embed($student; {phrase: "Hi {firstName}"; modelAlias: "text-embedding-3-small"}).vector + +// Text + stub that only supplies the model +$vector:=$studioEmbedder.embed("some text"; {modelAlias: "text-embedding-3-small"}).vector +``` + +## Stub resolution + +Both `render()` and `embed()` accept a plain object in place of a `Phrase`/`Definition`. A stub is resolved the same way [`Process`](Process.md#definition-resolution-entity-context) resolves its `definition` argument, so the behavior matches. Two flavors are supported: + +| Stub | Resolves to | +| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `{vectorName: "..."}` (optionally `{dataclassName: "..."}`) | The matching **saved definition** for the entity's dataclass — deducing its phrase (and, for `embed`, its model). Resolves to nothing when there is no unique match. | +| `{phrase: "tpl {field}"}` or `{template: "tpl {field}"}` | An **ad-hoc** `Phrase` compiled inline; nothing is looked up. Pair with `{modelAlias: "..."}` to give `embed()` a model. | + +For `embed()`, the model is deduced in this order: an explicit `{modelAlias}` on the stub → the model of a stub-matched saved definition → the *model* argument → the entity's unique definition. An explicit `{modelAlias}` always wins. + +Unlike [`Process.process()`](Process.md#process-resolution), a stub is **not** turned into a brand-new `Definition` from its fields — `StudioEmbedder` persists nothing, so use `{phrase}`/`{template}` for one-off templates. + +## Voir également + +- [Process](Process.md) +- [Settings](Settings.md) +- [Definition](Definition.md) +- [Embedder](Embedder.md) +- [EmbedderResult](EmbedderResult.md) +- [Phrase](Phrase.md) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/license.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/license.md new file mode 100644 index 00000000000000..8f6fc0dd2b5ffc --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/license.md @@ -0,0 +1,167 @@ +--- +id: license +title: SOFTWARE LICENSE AGREEMENT +--- + +# SOFTWARE LICENSE AGREEMENT + +## Preamble + +The purpose of this Software license agreement is to grant users the right to modify and re-use the software governed by this license. + +The exercising of this right is conditional upon the obligation to make /available to the community the modifications made to the source code of the software so as to contribute to its evolution. + +In consideration of access to the source code and the rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software's author, the holder of the economic rights, and the successive licensors only have limited liability. + +## Article 1 – DEFINITIONS + +***Agreement***: means this license agreement, and its possible subsequent versions and annexes. + +***Software***: means the software in its Object Code and/or Source Code form and, where applicable, its documentation, "as is" when the Licensee accepts the Agreement. + +***Initial Software***: means the Software in its Source Code and possibly its Object Code form and, where applicable, its documentation, "as is" when it is first distributed under the terms and conditions of the Agreement. + +***Modified Software***: means the Software modified by at least one Integrated Contribution. + +***Source Code***: means all the Software's instructions and program lines to which access is required so as to modify the Software. + +***Object Code***: means the binary files originating from the compilation of the Source Code. + +***Holder***: means the holder(s) of the economic rights over the Initial Software, in this case it is 4D SAS. + +***Licensee***: means the Software user(s) having accepted the Agreement. + +***Contributor***: means a Licensee having made at least one Integrated Contribution. + +***Licensor***: means the Holder, or any other individual or legal entity, who distributes the Software under the Agreement. + +***Integrated Contribution***: means new functions integrated into the Source Code by any or all Contributors. + +***Parties***: mean both the Licensee and the Licensor. + +These expressions may be used both in singular and plural form. + +## Article 2 - PURPOSE + +The purpose of the Agreement is the grant by the Licensor to the Licensee of a non-exclusive, transferable and worldwide license for the Software as set forth in Article 5 hereinafter for the whole term of the protection granted by the rights over said Software. + +## Article 3 - ACCEPTANCE + +The Licensee shall be deemed as having accepted the terms and conditions of this Agreement upon the occurrence of the first of the following events: + +- loading the Software by any or all means, notably, by downloading from a remote server; +- the first time the Licensee exercises any of the rights granted hereunder. + +## Article 4 - EFFECTIVE DATE AND TERM + +### 4.1 EFFECTIVE DATE + +The Agreement shall become effective on the date when it is accepted by the Licensee as set forth in Article 3. + +### 4.2 TERM + +The Agreement shall remain in force for the entire legal term of protection of the economic rights over the Software. + +## Article 5 - SCOPE OF RIGHTS GRANTED + +The Licensor hereby grants to the Licensee, who accepts, the following rights over the Software for the term of the Agreement, on the basis of the terms and conditions set forth hereinafter. + +### 5.1 RIGHT OF USE + +The Licensee is authorized to use the Software, without any limitation as to its fields of application, with it being hereinafter specified that this comprises: + +- permanent or temporary reproduction of all or part of the Software by any or all means and in any or all form. +- loading, displaying, running, or storing the Software on any or all medium. +- entitlement to observe, study or test its operation. + +### 5.2 RIGHT OF MODIFICATION + +The right of modification means the right to adapt, arrange, or make any or all modifications to the Software; being understood that such modifications of the Software shall results in a change of its functionalities and/or in an addition of functionalities to the Initial Software. + +Consequently to distribute a Modified Software according to the provision of section 5.3.2, the Licensee shall make exclusively significant modification as described above to the Software provided that it includes an explicit notice that it is the author of said modification and indicates the date of the creation thereof. + +### 5.3 RIGHT OF DISTRIBUTION + +In particular, the right of distribution includes the right to publish, transmit and communicate the Modified Software to the general public on any or all medium, and by any or all means, and the right to market, either in consideration of a fee, or + +#### 5.3.1 DISTRIBUTION OF SOFTWARE WITHOUT MODIFICATION + +The Licensee is forbidden to distribute true copies of the Software in Source Code or Object Code form. + +#### 5.3.2 DISTRIBUTION OF MODIFIED SOFTWARE + +When the Licensee creates Modified Software, this Modified Software may be distributed provided that said distribution complies with all the provisions of the Agreement and subject to compliance with the requirement to include a notice concerning the rights over the Software as defined in Article 6.3. + +In the event the creation of the Modified Software, the Licensee undertakes that: + +- the resulting Modified Software will be governed by this Agreement, being understood that such Agreement shall be integrated in the Modified Software the Integrated Contributions in the resulting Modified Software will be clearly identified and documented, +- the Licensee will allow effective access to the source code of the Modified Software, at a minimum during the entire period of distribution of the Derivative Software, such that such modifications may be carried over in a subsequent version of the Software. +- the Modified Software must be renamed to exclude any reference to 4D. For example, it is expressly prohibited to distribute a Modified Software named “4D SVG”; Licensee shall rename the Modified Software such as “Name of the Licensee SVG”. Consequently, Licensee is expressly forbidden to use 4D’s product name in general to promote his modified work. + +## Article 6 - INTELLECTUAL PROPERTY + +### 6.1 OVER THE INITIAL SOFTWARE + +The Holder owns the intellectual property rights over the Initial Software. Any or all use of the Initial Software is subject to compliance with the terms and conditions under which the Holder has elected to distribute its work and no one shall be entitled to modify the terms and conditions for the distribution of said Initial Software. + +### 6.2 OVER THE INTEGRATED CONTRIBUTIONS + +The Licensee who develops an Integrated Contribution is the owner of the intellectual property rights over this Contribution as defined by applicable law. + +### 6.3 NOTICE OF RIGHTS + +The Licensee expressly undertakes: + +- not to remove, or modify, in any manner, the intellectual property notices attached to the Software; +- to reproduce said notices, in an identical manner, in the copies of the Software modified; +- to ensure that use of the Software, its intellectual property notices and the fact that it is governed by the Agreement is indicated in a text that is easily accessible, specifically from the interface of any Modified Software. + +The Licensee undertakes not to directly or indirectly infringe the intellectual property rights of the Holder on the Software and to take, where applicable, vis- à-vis its staff, any and all measures required to ensure respect of said intellectual property rights of the Holder. + +## Article 7 - RELATED SERVICES + +Under no circumstances shall the Agreement oblige the Licensor to provide technical assistance or maintenance services for the Software. + +However, the Licensor is entitled to offer this type of services. The terms and conditions of such technical assistance, and/or such maintenance, shall be set forth in a separate instrument. + +## Article 8 - DISCLAIMER OF WARRANTY. + +THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE HOLDER PROVIDES THE SOFTWARE “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH LICENSEE. SHOULD THE SOFTWARE PROVE DEFECTIVE, LICENSEE ASSUMES THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +## Article 9 - LIMITATION OF LIABILITY + +TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE TO LICENSEE ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS AGREEMENT OR USE OF THE SOFTWARE, EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR DAMAGES. + +## Article 10 – TERMINATION + +### 10.1 + +In the event of a breach by the Licensee of its obligations hereunder, the Licensor may automatically terminate this Agreement thirty (30) days after notice has been sent to the Licensee and has remained ineffective. + +### 10.2 + +A Licensee whose Agreement is terminated shall no longer be authorized to use, modify or distribute the Software. However, any licenses that it may have granted prior to termination of the Agreement shall remain valid subject to their having been granted in compliance with the terms and conditions hereof. + +## Article 11 – MISCELLANEOUS + +### 11.1 + +Neither Party shall be liable for any or all delay, or failure to perform the Agreement, that may be attributable to an event of force majeure, an act of God or an outside cause, such as defective functioning or interruptions of the electricity or telecommunications networks, network paralysis following a virus attack, intervention by government authorities, natural disasters, water damage, earthquakes, fire, explosions, strikes and labor unrest, war, etc. + +### 11.2 + +Any failure by either Party, on one or more occasions, to invoke one or more of the provisions hereof, shall under no circumstances be interpreted as being a waiver by the interested Party of its right to invoke said provision(s) subsequently. + +### 11.3 + +In the event that one or more of the provisions hereof were to conflict with a current or future applicable act or legislative text, said act or legislative text shall prevail, and the Parties shall make the necessary amendments so as to comply with said act or legislative text. All other provisions shall remain effective. Similarly, invalidity of a provision of the Agreement, for any reason whatsoever, shall not cause the Agreement as a whole to be invalid. + +## Article 12 - GOVERNING LAW AND JURISDICTION + +### 12.1 + +The Agreement is governed by French law. The Parties agree to endeavor to seek an amicable solution to any disagreements or disputes that may arise during the performance of the Agreement. + +### 12.2 + +Failing an amicable solution within two (2) months as from their occurrence, and unless emergency proceedings are necessary, the disagreements or disputes shall be referred to the Versailles Courts having jurisdiction, by the more diligent Party. \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/overview.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/overview.md new file mode 100644 index 00000000000000..cf0a2bd93b1888 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/overview.md @@ -0,0 +1,211 @@ +--- +id: overview +title: 4D-Embedding-Studio +--- + +# 4D-Embedding-Studio + +## Vue d’ensemble + +4D Embedding Studio is a component for defining, processing, and maintaining AI embedding vectors directly in your 4D dataclass entities. + +You can use the component without writing a single line of code: select attributes from your dataclasses to construct the sentences to be vectorized and specify the model to use. For each entity, the component calls the embedding API and stores the resulting `4D.Vector` values. Configure the embedding scheduler to (re)calculate the vectors for your data at fixed intervals or on demand. + +You can then use the ORDA [`query()` by vector feature](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity) to request your data using semantics. + +If you want to have more control over your embeddings, the component offers an extensive API that allows you to customize each step of the data vectorization process, manage the scheduler, and integrate high-performance RAG (*Retrieval Augmented Generation*) features into your 4D application. + +## Conditions requises + +- [4D-AIKit](https://github.com/4d/4D-AIKit) (loaded automatically as a dependency). +- 4D project (21 R5 or later) with the following configuration: + - a valid model alias + - a dataclass with a `4D.Vector` attribute (object field at the database level). + +## Quick Start + +**1. Add a field of type Object to the table and associate it with the `4D.Vector` class.** +**2. Select **Embedding Studio...** in the **Design** menu to display the Embedding Studio window.** + +![menu](../assets/en/embedding-studio/menu.png) + +**3. For each listed `4D.Vector` attribute, write a descriptive phrase based upon attributes of the dataclass.** +Use the contextual menu to insert appropriate attributes. +This phrase will be vectorized for every entity. +**4. Select a model alias (or create a new one).** +**5. Select "Execute now" to launch the vectorization of your data or configure the scheduler.** + +## User Guide + +### Configuring the dataclass + +To use the 4D Embedding Studio interface, you need to create at least one object attribute associated to a `4D.Vector` class in your datastore. This must be done at the database level (only storage attributes can be embeddings). + +In the Structure editor, add an Object field to the dataclass (table) whose entities you want to query using AI and enter ["4D.Vector" as class](https://developer.4d.com/docs/Develop/structure-fields#class). + +#### Dirty-flag support + +In a production application, data is rarely static. If an embedding is based on an attribute value that has changed (e.g. a product description), it becomes obsolete and could no longer be relevant. By default, 4D automatically invalidates and flags for recalculation affected embeddings. + +If you do not use a dirty-flag field (see below), 4D simply replaces any invalidated vector by `Null`. It is therefore no longer used in searches until its next calculation. This option is suitable for applications that prioritize strict consistency: it is better to return no results than to rely on an embedding that no longer matches the current data. + +Or, you can add a Boolean field named `_dirty` (e.g. "myVector_dirty") to the structure. In this case, when an update is required, this field is set to `True`, and the associated vector is retained until it is recalculated. Your application can then choose to continue using this vector temporarily or exclude it using a filter on `dirty = False`. The flag is cleared automatically after a successful save. +This strategy promotes service continuity while allowing you to precisely identify vectors awaiting recalculation. If your business logic requires full control, you can also disable automatic invalidation and manage this lifecycle yourself. + +*Note: Certain modifications, such as a model changes, require vectors to be replaced immediately.* + +### Creating an embedding + +When you select **Embedding Studio...** in the **Design** menu, the Embedding Studio window is displayed. + +The list on the left side shows all `4D.Vector` class attributes defined in the datastore. You can add as many vector attributes as you want per dataclass. + +A check mark (✓) in the Dirty Flag column indicates that a [`_dirty` boolean field](#dirty-flag-support) is associated to the vector field. + +**Note:** Any change in the database structure will require that you restart the 4D application so that the 4D Embedding Studio lists up-to-date values. + +#### Writing a descriptive sentence + +To create or edit an embedding, select the attribute to configure in this list and write the embedding definition in the "Descriptive sentence" area on the right side. Use the associated menu to build the sentence and to add references to dataclass available attributes with the `{attribute_name}` syntax. + +The sentence must build a text that describes the entity just like a human would do it. The embedding could then capturate the semantics and not only attribute values. + +For example, for a `Product` dataclass with many attributes such as name and category, you could write: +"The {name} product is a {category} from the {brand} brand. Description: {description}. Key features: {features}." + +![menu](../assets/en/embedding-studio/studio-interface.png) + +### Selecting a model + +Once you have defined your vector attribute, choose the model to use for generating the embedding. The list of models includes the **model aliases** you defined in the [Project Settings](https://developer.4d.com/docs/settings/ai#model-aliases). + +The choice of model is important because it determines the relevance and quality of your embeddings. You’ll also need to provide this model with every query on the dataclass data so that the comparison is performed using the same model. + +### Auto-invalidate on save + +When this option is checked (default), embeddings are automatically invalidated when at least one of their definition attributes has been modified and the entity was successfully saved. + +However, you might want to handle invalidation in a custom way using the [4D Embedding Studio API](#api-guide). In this case, uncheck this option to disable the automatic mechanism. + +### Calculating embeddings + +Embeddings are calculated by sending a request to the AI model, which then returns the vectorization result, which is subsequently stored in the `4D.Vector` attribute in the dataclass. 4D automatically handles this operation and optimizes it by calculating only the necessary vectors. Each vector is processed independently. Thus, an error on one element does not interrupt the recalculation of the others. Elements that fail will be automatically retried during the next run. Recalculations are performed asynchronously, without blocking users. + +These calculations can be performed **on demand** or **scheduled at regular intervals** using the scheduler in the 4D Embedding Studio component. + +**Note:** You can also customize embedding calculations per dataclass or entity using the [4D Embedding Studio API](#api-guide). + +#### On demand + +To launch an embedding calculation, select **Run now** in the menu at the bottom of the 4D Embedding Studio window. This item is disabled if the datastore does not contain any embedding to calculate. When started, you can select **Cancel run** at any moment. + +#### Périodicité + +You can configure the 4D Embedding Studio component scheduler to adjust the calculation frequency to suit your application’s needs. + +**Important:** The scheduler needs a 4D worker process to run. You can start it manually for testing purposes (**Start now** button in the scheduler dialog box) but to make sure a worker is available every times the application opens, you need to configure it. Vous pouvez soit : + +- select the **Execute "On Host Database Event" method of the components** option in the [project Settings](https://developer.4d.com/docs/settings/security#options) +- or write the following code in your startup code: + +```4d + //at startup +cs.EmbeddingStudio.Scheduler.me.start() +``` + +The scheduler allows you can set the time interval between two calculations. Select the tab corresponding to your needs and click **Save**. + +- **Never**: the scheduler is off and never runs +- **At regular interval**: set the time interval between each calculation starting from a specified time. +- **Once a day**: the calculation takes place every day at a specific time + starting from a specific time. + +### Building queries with embeddings + +Once you have defined embeddings in your datastore, you can start [querying your dataclasses using AI-based features](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity). You just need to make sure that you use the same model for your embedding definition and in the query string. + +For example, assuming that: + +• you have defined a `4D.Vector` attribute named "product_vector" in the Products dataclass using a sentence: "The {name} is in the {category} category. It has these {features} features and can be used for {usage}." +• you want to find products that "can be used safely outside". + +Vous pouvez écrire : + +```4d +// Retrieve the model alias from the embedding definition, configured in 4D Embedding Studio +var $settings:=cs.EmbeddingStudio.Settings.new() +var $definition:=$settings.find("Products"; "product_vector") + +// Compute the vector of the query with the same model +var $result:=cs.EmbeddingStudio.StudioEmbedder.new().embed("products that can be used safely outside"; $definition) +var $vector:=$result.vector + + //search with default metric (cosine) +var $products:=ds.Products.query("product_vector > :1 order by product_vector desc"; {vector : $vector}) + +``` + +If you use a dirty field, simply add a criterion to exclude vectors waiting to be recalculated: + +```4d +var $products:=ds.Products.query("product_vector > :1 and product_vector_dirty = false order by product_vector desc"; {vector : $vector}) +``` + +## API Guide + +### Quick start + +**1. Configure your vectors** in `Settings/embeddings.json`: + +```json +{ + "batchSize": 50, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding", + "phrase": "Student {firstName} {lastName}, enrolled in {program}", + "autoInvalidate": true + } + ] +} +``` + +**2. Run the full pipeline** (all definitions, all records): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +var $r:=$p.process() + +If ($r.success) + ALERT("Updated "+String($r.entitiesUpdated)+" entities in "+String($r.duration)+" ms") +End if +``` + +**3. Process a single entity on save** (e.g. in a trigger or REST hook): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +$p.processEntity($entity) +``` + +### Class reference + +| Class | Description | +| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Process](Classes/Process.md) | Main orchestrator — entry point for all batch and entity operations. | +| [Scheduler](Classes/Scheduler.md) | Automated recalculation scheduler — background task, force/cancel, and runtime status. | +| [StudioEmbedder](Classes/StudioEmbedder.md) | Renders and embeds on demand using your saved definitions — e.g. to build a search query vector. Nothing is persisted. | +| [Settings](Classes/Settings.md) | Loads and saves the `embeddings.json` configuration file. | +| [Definition](Classes/Definition.md) | Describes one vector field: dataclass, field name, model alias, and phrase template. | +| [Embedder](Classes/Embedder.md) | Thin wrapper around the AIKit embeddings API with retry/backoff logic. | +| [EmbedderResult](Classes/EmbedderResult.md) | Typed wrapper normalizing API responses — vectors, usage metrics, rate-limit state. | +| [ProcessResult](Classes/ProcessResult.md) | Returned by every batch function — statistics and error breakdown. | +| [ProcessError](Classes/ProcessError.md) | Typed entry in `ProcessResult.errors` — scope, severity, code, ref, message, retryable. | +| [ProcessErrorCode](Classes/ProcessErrorCode.md) | Singleton catalogue of machine-readable error codes and their default severity/retryability. | +| [Phrase](Classes/Phrase.md) | Lightweight `{variable}` template engine used to build text from entity attributes. | + +### Voir également + +Blog post: [Vectorize your data effortlessly with 4D Embedding Studio](https://blog.4d.com/vectorize-your-data-effortlessly-with-4d-vector-studio) \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/ratelimit.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/ratelimit.md new file mode 100644 index 00000000000000..757cf6d3c79040 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/ratelimit.md @@ -0,0 +1,65 @@ +--- +id: ratelimit +title: Rate Limiting +--- + +# Rate Limiting + +The embedding pipeline includes built-in rate-limit awareness. When the API provider returns rate-limit headers (as OpenAI does), the system automatically throttles requests and adapts batch sizes to stay within budget. Providers that don't return rate-limit headers (e.g. Ollama) are unaffected — the pipeline runs at full speed. + +## Principes de fonctionnement + +Each call to [`Embedder.embed()`](Classes/Embedder.md) or [`Embedder.embedBatch()`](Classes/Embedder.md) returns an [`EmbedderResult`](Classes/EmbedderResult.md) that carries rate-limit state alongside the embedding vectors. The pipeline uses this data in a three-step loop: + +1. **Pre-flight throttle** — before sending a batch, the pipeline checks whether the remaining token budget is sufficient. If not, it waits for the reset window to elapse before proceeding. +2. **Adaptive batch sizing** — the pipeline computes the largest batch that fits within 80% of the remaining token budget. This avoids hitting the ceiling while still making efficient use of the quota. +3. **State update** — after each API response, the pipeline records the new remaining budget, computes an average tokens-per-entity estimate, and feeds both into the next iteration. + +## Rate-limit fields on EmbedderResult + +These fields are populated from the API response headers. When a provider doesn't return them, they keep their defaults and the pipeline skips throttling. + +| Champ | Par défaut | Description | +| ------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `remainingTokens` | `-1` | Tokens left in the current window. `-1` = unknown. | +| `remainingRequests` | `-1` | Requests left in the current window. | +| `limitTokens` | `0` | TPM (tokens per minute) ceiling. | +| `limitRequests` | `0` | RPM (requests per minute) ceiling. | +| `resetTokens` | `""` | Time until the token bucket refills (e.g. `"6m0s"`, `"200ms"`). | +| `resetRequests` | `""` | Time until the request bucket refills. | + +## Batch size adaptation + +The pipeline starts with the configured `batchSize` (from [Settings](Classes/Settings.md), default 50). After the first API response provides rate-limit data, the batch size may shrink: + +``` +nextBatchSize = min( floor(remainingTokens × 0.8 / tokensPerEntity), configBatchSize ) +``` + +- `tokensPerEntity` is estimated from the last chunk (`totalTokens / chunkSize`). +- The result is clamped to a floor of 1 and a ceiling of `configBatchSize`. +- When `remainingTokens` is unknown (`-1`), the configured batch size is used as-is. + +## Pre-flight wait + +Before each batch, the pipeline checks: + +- **Token budget**: if `remainingTokens < estimatedTokens × 1.1`, it waits for the token reset window. +- **Request budget**: if `remainingRequests = 0`, it waits for the request reset window. + +The reset durations are parsed from the API's string format (`"6m0s"` → 360 seconds, `"200ms"` → 1 second). + +## Providers without rate limits + +Some providers (Ollama, local models) don't return rate-limit headers. Dans ce cas : + +- `remainingTokens` stays at `-1` (unknown) +- No throttling occurs — batches run at `configBatchSize` without waits +- The pipeline works identically to how it did before rate-limit support was added + +## Voir également + +- [EmbedderResult](Classes/EmbedderResult.md) — carries rate-limit fields +- [Embedder](Classes/Embedder.md) — wraps the API calls +- [Process](Classes/Process.md) — orchestrates the batch loop +- [Settings](Classes/Settings.md) — `batchSize` configuration diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md b/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md index 1c468a6d38c898..d63a9565f5b3ad 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md @@ -790,7 +790,7 @@ Reportez-vous à l'exemple 2. **Valeurs possibles** : Entier positif. Valeur par défaut = 900, valeur minimale = 60. -**Description** : Délai en secondes pour les sessions client/serveur en cas de déconnexion inattendue lors de l'utilisation de la couche réseau QUIC. Ce délai est la période accordée à une session pendant laquelle la connexion entre le serveur et le client peut être rétablie automatiquement suite à une déconnexion involontaire. Si, à l'issue de ce délai, la connexion n'a pas été rétablie, la session est fermée. +**Description** : Délai en secondes pour les sessions client/serveur en cas de déconnexion inattendue lors de l'utilisation de la couche réseau QUIC. Ce délai est la période accordée à une session pendant laquelle la connexion entre le serveur et le client peut être rétablie automatiquement suite à une déconnexion involontaire. Si, à l'issue de ce délai, la connexion n'a pas été rétablie, la session client est fermée avec un message. Ce paramètre ne peut être défini que sur 4D Server et s'applique à toutes les nouvelles sessions distantes 4D (la valeur du délai des sessions existantes n'est pas modifiée). diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md b/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md index d58a8ab4195453..aa4748dfc5340b 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md @@ -45,6 +45,16 @@ Dans le paramètre optionnel *settings*, vous pouvez passer un objet contenant l | --------- | ---- | ---------------------------------------------------------------------------------------------------------------------- | | context | Text | Nom du [contexte d'optimisation](../../ORDA/client-server-optimization.md) appliqué à l'entity selection. | +:::info + +Pour des raisons de performance, en 4D monoposte et 4D Server, l'entity selection retournée est directement liée à la sélection courante de *dsTable* (il ne s'agit pas d'une copie). Tant que la sélection courante n'est pas remplacée, les modifications apportées à l'une sont répercutées dans l'autre. Par exemple, [`REDUCE SELECTION`](../commands/reduce-selection) réduit l'entity selection, et [`.add()`](../../API/EntitySelectionClass.md#add) appliquée à l'entity selection ajoute l'entité à la sélection courante. Pour obtenir une entity selection indépendante, appelez [`.copy()`](../../API/EntitySelectionClass.md#copy) sur le résultat : + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Exemple ```4d diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md b/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md index 857594055ae15f..ff7872f81a3f91 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md @@ -35,7 +35,7 @@ displayed_sidebar: docs Passez dans le paramètre *partie* le numéro de la partie à analyser. Vous pouvez obtenir le nombre total de parties à l’aide de la commande [WEB Get body part count](../commands/web-get-body-part-count). -Le paramètre *contenuParti*e récupère le contenu de la partie. Lorsque les parties à récupérer sont des fichiers, vous devez passer un paramètre de type BLOB. Dans le cas de variables TEXT postées dans un formulaire Web, vous pouvez passer un paramètre de type texte. +Le paramètre *contenuPartie* récupère le contenu de la partie. Lorsque les parties à récupérer sont des fichiers, vous devez passer un paramètre de type BLOB. Dans le cas de variables TEXT postées dans un formulaire Web, vous pouvez passer un paramètre de type texte. Le paramètre *nomPartie* récupère le nom de la variable du champ input HTTP. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md index 1c468a6d38c898..d63a9565f5b3ad 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md @@ -790,7 +790,7 @@ Reportez-vous à l'exemple 2. **Valeurs possibles** : Entier positif. Valeur par défaut = 900, valeur minimale = 60. -**Description** : Délai en secondes pour les sessions client/serveur en cas de déconnexion inattendue lors de l'utilisation de la couche réseau QUIC. Ce délai est la période accordée à une session pendant laquelle la connexion entre le serveur et le client peut être rétablie automatiquement suite à une déconnexion involontaire. Si, à l'issue de ce délai, la connexion n'a pas été rétablie, la session est fermée. +**Description** : Délai en secondes pour les sessions client/serveur en cas de déconnexion inattendue lors de l'utilisation de la couche réseau QUIC. Ce délai est la période accordée à une session pendant laquelle la connexion entre le serveur et le client peut être rétablie automatiquement suite à une déconnexion involontaire. Si, à l'issue de ce délai, la connexion n'a pas été rétablie, la session client est fermée avec un message. Ce paramètre ne peut être défini que sur 4D Server et s'applique à toutes les nouvelles sessions distantes 4D (la valeur du délai des sessions existantes n'est pas modifiée). diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md index d58a8ab4195453..aa4748dfc5340b 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md @@ -45,6 +45,16 @@ Dans le paramètre optionnel *settings*, vous pouvez passer un objet contenant l | --------- | ---- | ---------------------------------------------------------------------------------------------------------------------- | | context | Text | Nom du [contexte d'optimisation](../../ORDA/client-server-optimization.md) appliqué à l'entity selection. | +:::info + +Pour des raisons de performance, en 4D monoposte et 4D Server, l'entity selection retournée est directement liée à la sélection courante de *dsTable* (il ne s'agit pas d'une copie). Tant que la sélection courante n'est pas remplacée, les modifications apportées à l'une sont répercutées dans l'autre. Par exemple, [`REDUCE SELECTION`](../commands/reduce-selection) réduit l'entity selection, et [`.add()`](../../API/EntitySelectionClass.md#add) appliquée à l'entity selection ajoute l'entité à la sélection courante. Pour obtenir une entity selection indépendante, appelez [`.copy()`](../../API/EntitySelectionClass.md#copy) sur le résultat : + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Exemple ```4d diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md index 857594055ae15f..ff7872f81a3f91 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md @@ -35,7 +35,7 @@ displayed_sidebar: docs Passez dans le paramètre *partie* le numéro de la partie à analyser. Vous pouvez obtenir le nombre total de parties à l’aide de la commande [WEB Get body part count](../commands/web-get-body-part-count). -Le paramètre *contenuParti*e récupère le contenu de la partie. Lorsque les parties à récupérer sont des fichiers, vous devez passer un paramètre de type BLOB. Dans le cas de variables TEXT postées dans un formulaire Web, vous pouvez passer un paramètre de type texte. +Le paramètre *contenuPartie* récupère le contenu de la partie. Lorsque les parties à récupérer sont des fichiers, vous devez passer un paramètre de type BLOB. Dans le cas de variables TEXT postées dans un formulaire Web, vous pouvez passer un paramètre de type texte. Le paramètre *nomPartie* récupère le nom de la variable du champ input HTTP. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/menu.png b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/menu.png new file mode 100644 index 00000000000000..425fd0d7e65879 Binary files /dev/null and b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/menu.png differ diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/studio-interface.png b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/studio-interface.png new file mode 100644 index 00000000000000..75dae7c9303297 Binary files /dev/null and b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/studio-interface.png differ diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Definition.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Definition.md new file mode 100644 index 00000000000000..634252ac475d38 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Definition.md @@ -0,0 +1,165 @@ +--- +id: definition +title: Définition +--- + +# Définition + +The `Definition` class describes how a single vector field on a dataclass should be computed: which dataclass, which vector field, which model alias, and which text template ([Phrase](Phrase.md)) to render from each entity. + +A collection of these is what [Settings](Settings.md) persists. + +## Propriétés + +| Nom de propriété | Type | Description | +| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| `dataclassName` | Text | Name of the target dataclass. | +| `vectorName` | Text | Name of the `4D.Vector` field on that dataclass. | +| `modelAlias` | Text | Embedding model alias (e.g. `"text-embedding-3-small"`). | +| `phrase` | [Phrase](Phrase.md) | Compiled template used to build the text that will be embedded. | +| `autoInvalidate` | Boolean | Controls automatic invalidation on entity save. Default: `True`. | + +## Class constructor + +Create a definition. + +| Nom de l'argument | Type | Description | +| ----------------- | ---- | -------------------------------------------------------------------------------------------------- | +| *dataclassName* | Text | Name of the target dataclass. | +| *vectorName* | Text | Name of the target vector field. | +| *modelAlias* | Text | Embedding model alias. | +| *phraseTemplate* | Text | Phrase template with `{field}` placeholders — compiled into a [Phrase](Phrase.md). | + +```4d +var $def:=cs.EmbeddingStudio.Definition.new(\ + "Students"; \ + "student_vector_1"; \ + "text-embedding-3-small"; \ + "Student {firstName} {lastName}") +``` + +## Propriétés calculées + +### hasDefinition + +**hasDefinition** : Boolean *(read-only)* + +Returns `True` if at least a model or a phrase template has been set. A definition without either has no content to process. + +```4d +If ($def.hasDefinition) + // worth validating further +End if +``` + +## Fonctions + +### validate() + +**validate**( *settings* : Settings ) : Object + +Validates the definition against the live datastore model and the known embedding models. All errors are collected before returning — the result always describes the full set of problems found. + +| Argument | Type | Description | +| ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| *settings* | [Settings](Settings.md) \| Null | Used to pass phrase validation options. Pass `Null` to skip phrase options. | +| Résultat de la fonction | Object | `{success: Boolean, errors: Collection}` where each error is `{field: Text, message: Text}`. | + +Checked in order: + +| Check | `field` value | +| ------------------------------------ | ----------------- | +| `dataclassName` is not empty | `"dataclassName"` | +| `vectorName` is not empty | `"vectorName"` | +| `modelAlias` is set and recognised | `"modelAlias"` | +| Dataclass exists in `ds` | `"dataclassName"` | +| Vector field exists | `"vectorName"` | +| Field type is `4D.Vector` | `"vectorName"` | +| Phrase template is not empty | `"phrase"` | +| Phrase keys resolve in the dataclass | `"phrase"` | + +The first two checks (identity) return immediately on failure; the remaining checks accumulate so all problems are reported in one pass. + +```4d +var $result:=$def.validate(cs.EmbeddingStudio.Settings.new()) + +If (Not($result.success)) + var $err : Object + For each ($err; $result.errors) + TRACE // $err.field, $err.message + End for each +End if +``` + +### invalidateVectors() + +**invalidateVectors**() : Object + +Marks all already-computed entities for re-embedding, forcing a full rebuild on the next run. Only entities that already have a vector value are processed — entities with a `Null` vector are skipped. + +Useful during development or after a model/phrase change to trigger a clean rebuild of all vectors. + +The strategy depends on whether a companion `_dirty` field exists on the dataclass: + +| Companion `_dirty` field | Action taken | +| ------------------------ | -------------------------------------------------------------- | +| Present | Sets `_dirty` to `True` — vector is left untouched | +| Absent | Nullifies the vector field | + +| Argument | Type | Description | +| ----------------------- | ------ | ------------------------------------------------------------------ | +| Résultat de la fonction | Object | `{updated: Integer, skipped: Integer, errors: Collection of Text}` | + +- `updated` — number of entities successfully marked +- `skipped` — number of entities that could not be saved +- `errors` — one entry per save failure, formatted as `"DataclassName: statusText"` + +```4d +var $result:=$def.invalidateVectors() + +If ($result.skipped > 0) + var $e : Text + For each ($e; $result.errors) + // $e + End for each +End if +// → { updated: 42; skipped: 0; errors: [] } +``` + +### toObject() + +**toObject**() : Object + +Returns a plain object suitable for JSON persistence. The phrase is flattened to its template text. + +| Argument | Type | Description | +| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | +| Résultat de la fonction | Object | `{version, dataclassName, vectorName, modelAlias, phrase, autoInvalidate}` where `phrase` is the template string. | + +```4d +$def.toObject() +// → { version: 0; dataclassName: "Students"; vectorName: "student_vector_1"; +// modelAlias: "text-embedding-3-small"; phrase: "Student {firstName} {lastName}"; +// autoInvalidate: true } +``` + +## Automatic invalidation + +`autoInvalidate` controls whether save-time automatic invalidation is enabled for this definition. + +- `True` (default): when relevant attributes change on an entity save, vectors are automatically invalidated. +- `False`: save-time automatic invalidation is skipped for this definition. + +This setting does not affect manual invalidation via `invalidateVectors()`. + +## Dirty flag convention + +The pipeline in [Process](Process.md) will recompute an entity whenever the target vector is `Null`, or when a sibling field `_dirty` exists on the dataclass and is `True`. + +Declaring the dirty flag is optional — when absent, only the null-vector case triggers recomputation. When present, it is cleared automatically on successful save. + +## Voir également + +- [Settings](Settings.md) +- [Process](Process.md) +- [Phrase](Phrase.md) diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Embedder.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Embedder.md new file mode 100644 index 00000000000000..2d8e5d846103ad --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Embedder.md @@ -0,0 +1,96 @@ +--- +id: embedder +title: Embedder +--- + +# Embedder + +The `Embedder` class is a thin wrapper around [4D AIKit](https://developer.4d.com/docs/aikit/Classes/openai) focused on embeddings. It exposes two functions — one for a single text, one for a batch — and handles retries with exponential backoff (respecting the `Retry-After` header when present). + +It is stateless beyond configuration and safe to share between processes. + +## Propriétés + +| Nom de propriété | Type | Description | +| ---------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `client` | cs.AIKit.OpenAI | The underlying AIKit client used for HTTP requests. | +| `maxRetries` | Integer | Maximum number of retries on transient errors. Default: `3`. | +| `backoffMs` | Integer | Base delay (ms) between retries. Doubled each attempt. | + +## Class constructor + +Create a embedder. All options are optional. + +| Nom de l'argument | Type | Description | +| ----------------- | ------ | ----------------------------------------------------------------------------- | +| *options* | Object | `{client, maxRetries, backoffMs}` — any field may be omitted. | + +```4d +// Default — uses cs.AIKit.OpenAI.new() internally +var $proc:=cs.EmbeddingStudio.Embedder.new() + +// Provide a pre-configured AIKit client (custom API key, base URL, etc.) +var $client:=cs.AIKit.OpenAI.new({apiKey: "…"; baseURL: "https://server.ai"}) +var $proc:=cs.EmbeddingStudio.Embedder.new({client: $client; maxRetries: 5; backoffMs: 1000}) +``` + +> If the 4D AIKit component is not loaded (or is too old to provide `OpenAIProviders`), the constructor still succeeds with a `Null` client, and the first `embed()` / `embedBatch()` call throws an error whose `message` explains what is missing and whose `isAIKitMissing` property is `True`. + +## Fonctions + +### embed() + +**embed**(*text* : Text ; *model* : Text) : [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) + +Embed a single text. Returns a typed result with the embedding vector, token usage, and rate-limit state. + +| Argument | Type | Description | +| ----------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| *text* | Text | The text to vectorize. | +| *model* | Text | The embedding model to use (e.g. `"text-embedding-3-small"`). | +| Résultat de la fonction | [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) | Typed wrapper — `.vector` holds the embedding, `.promptTokens` / `.totalTokens` hold usage, rate-limit fields are flat camelCase. | + +Throws if retries are exhausted or the API returns a non-retryable error. + +```4d +var $result:=$proc.embed("it rains cats and dogs"; "text-embedding-3-small") +// $result.vector → 4D.Vector +// $result.promptTokens → Integer +// $result.totalTokens → Integer +// $result.remainingTokens → Integer (-1 if unknown) +``` + +### embedBatch() + +**embedBatch**(*texts* : Collection ; *model* : Text) : [cs.EmbedderResult](EmbedderResult.md) + +Embed a collection of texts in a single API call. Returns a typed result with vectors in the same order as inputs, token usage, and rate-limit state. + +| Argument | Type | Description | +| ----------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | +| *texts* | Collection | Collection of Text to vectorize. Empty or `Null` returns an empty result. | +| *model* | Text | The embedding model to use. | +| Résultat de la fonction | [cs.EmbedderResult](EmbedderResult.md) | Typed wrapper — `.vectors` holds the embeddings collection, token and rate-limit fields are flat camelCase. | + +```4d +var $result:=$proc.embedBatch(["hello"; "world"]; "text-embedding-3-small") +// $result.vectors[0] → 4D.Vector for "hello" +// $result.vectors[1] → 4D.Vector for "world" +// $result.totalTokens → Integer (sum for the batch) +// $result.remainingTokens → Integer (after this call) +``` + +## Retry policy + +Transient errors (HTTP 408, 409, 429, 5xx) are retried up to `maxRetries` times. + +- If the response carries a `Retry-After` or `retry-after-ms` header, the embedder waits that long. +- Otherwise, it waits `backoffMs * 2^attempt`. + +Non-retryable errors are thrown immediately — see [OpenAIError](https://developer.4d.com/docs/aikit/Classes/openaierror) for the thrown shape. + +## Voir également + +- [EmbedderResult](EmbedderResult.md) +- [Process](Process.md) +- [OpenAIEmbeddingsAPI](https://developer.4d.com/docs/aikit/Classes/openaiembeddingsapi) (AIKit) diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/EmbedderResult.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/EmbedderResult.md new file mode 100644 index 00000000000000..853bd158d5fd4d --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/EmbedderResult.md @@ -0,0 +1,80 @@ +--- +id: embedderresult +title: EmbedderResult +--- + +# EmbedderResult + +Typed wrapper for `Embedder.embed()` and `Embedder.embedBatch()` responses. Normalizes OpenAI's snake_case API keys (`prompt_tokens`, `total_tokens`) to camelCase properties, and flattens the nested rate-limit structure into direct properties. + +A single class handles both single and batch results — `embed()` populates `.vector`, `embedBatch()` populates `.vectors`. + +## Propriétés + +### Embedding results + +| Propriété | Type | Par défaut | Description | +| --------- | ------------------------- | ---------- | ------------------------------------------------------------------------------ | +| `vector` | 4D.Vector | Null | Single embedding result. Null for batch calls. | +| `vectors` | Collection | `[]` | Batch embedding results. | + +### Token usage + +| Propriété | Type | Par défaut | Description | +| -------------- | ------- | ---------- | -------------------------------------------------------------------- | +| `promptTokens` | Integer | `0` | Input tokens consumed. | +| `totalTokens` | Integer | `0` | Total tokens consumed (in + out). | + +### Rate-limit state + +| Propriété | Type | Par défaut | Description | +| ------------------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------- | +| `remainingTokens` | Integer | `-1` | Tokens left in the current window. `-1` = unknown. | +| `remainingRequests` | Integer | `-1` | Requests left in the current window. `-1` = unknown. | +| `limitTokens` | Integer | `0` | TPM ceiling for the account. | +| `limitRequests` | Integer | `0` | RPM ceiling for the account. | +| `resetTokens` | Text | `""` | Time until token bucket refills (e.g. `"6m0s"`). | +| `resetRequests` | Text | `""` | Time until request bucket refills (e.g. `"1s"`). | + +## Class constructor + +```4d +// From a real API result (used by Embedder internally) +var $result:=cs.EmbedderResult.new($aikitResult; True) // batch +var $result:=cs.EmbedderResult.new($aikitResult; False) // single + +// Empty result (no API call — e.g. empty batch) +var $result:=cs.EmbedderResult.new() +``` + +| Argument | Type | Description | +| --------- | ------- | ------------------------------------------------------------------------------------------------------------ | +| *result* | Object | An object with `.vector`/`.vectors`, `.usage`, `.rateLimit` (duck-typed). | +| *isBatch* | Boolean | `True` to read `.vectors`, `False` to read `.vector`. | + +The constructor accepts any object that exposes the expected shape — it does not require a specific class. This makes it easy to construct in tests. + +## Utilisation + +```4d +// Single embedding +var $r:=$embedder.embed("hello world"; "text-embedding-3-small") +$r.vector // → 4D.Vector +$r.promptTokens // → 6 +$r.totalTokens // → 6 + +// Batch embedding +var $r:=$embedder.embedBatch(["hello"; "world"]; "text-embedding-3-small") +$r.vectors.length // → 2 +$r.totalTokens // → 10 + +// Rate-limit awareness +$r.remainingTokens // → 148230 (or -1 if not yet known) +$r.resetTokens // → "6m0s" +``` + +## Voir également + +- [Embedder](Embedder.md) — creates EmbedderResult instances +- [ProcessResult](ProcessResult.md) — run-level report that accumulates EmbedderResult usage +- [Rate Limiting](../RateLimit.md) — how the pipeline uses rate-limit fields for throttling and batch sizing diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Phrase.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Phrase.md new file mode 100644 index 00000000000000..7f8a82daec5ef0 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Phrase.md @@ -0,0 +1,117 @@ +--- +id: phrase +title: Phrase +--- + +# Phrase + +The `Phrase` class is a lightweight template engine: a template with `{variable}` placeholders is compiled once, then rendered efficiently against different data objects. + +## Propriétés + +| Nom de propriété | Type | Description | +| ---------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- | +| `template` | Text | Computed — returns the original template string. | +| `keys` | Collection | Computed — returns the variable names found in the template, dot-notation keys joined back to strings. | + +## Class constructor + +Compile a template. Compilation walks the template once and extracts static parts and variable paths. + +| Nom de l'argument | Type | Description | +| ----------------- | ---- | ---------------------------------------------------------- | +| *template* | Text | Template string with `{variable}` markers. | + +```4d +var $tpl:=cs.EmbeddingStudio.Phrase.new("Hello {firstName}, you study at {schoolName}.") +$tpl.keys // → ["firstName"; "schoolName"] +``` + +## Fonctions + +### render() + +**render**(*data* : Object) : Text + +Render the compiled template by replacing variables with values from *data*. Missing keys produce an empty string. + +| Argument | Type | Description | +| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------ | +| *data* | Object | A plain object or a 4D.Entity whose fields supply the variable values. | +| Résultat de la fonction | Text | The rendered text. | + +```4d +var $text:=$tpl.render({firstName: "Alice"; school: {name: "MIT"}}) +// → "Hello Alice, you study at MIT." + +// Works directly on entities +$text:=$tpl.render(ds.Students.first()) +``` + +### validate() + +**validate**(*dataclass* : 4D.DataClass ; *options* : Object) : Object + +Validate that all keys in the phrase can be resolved against the given dataclass. Walks dot-notation paths through N:1 / 1:1 relations. + +| Argument | Type | Description | +| ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| *dataclass* | 4D.DataClass | The dataclass to validate against. | +| *options* | Object | Optional validation flags (see below). All default to `False` — storage kind only. | +| Résultat de la fonction | Object | `{success: Boolean, errors: Collection of {key, message}}`. | + +#### Options + +| Champ | Type | Par défaut | Description | +| ----------------- | ------- | ---------- | ----------------------------------------------------------------------------------------------------- | +| `allowRelations` | Boolean | `False` | Allow dot-notation paths through N:1 / 1:1 relations. | +| `allowCalculated` | Boolean | `False` | Allow calculated attributes. | +| `allowAlias` | Boolean | `False` | Allow alias attributes. | + +```4d +var $tpl:=cs.EmbeddingStudio.Phrase.new("{firstName} at {school.name}") + +// Storage-only validation — fails because {school.name} uses a relation +var $v:=$tpl.validate(ds.Students) +// $v.success → False +// $v.errors → [{key: "school.name"; message: "..."}] + +// Allow relations +$v:=$tpl.validate(ds.Students; {allowRelations: True}) +// $v.success → True +``` + +#### Rejected shapes + +Regardless of options: + +- Attributes that do not exist on the dataclass. +- Attributes whose class ID is `4D.Vector`. +- 1:N relations (`relatedEntities`) as the final key. +- Intermediate segments that are not relations (when dot-notation is used). + +### attributs() + +**attributes**(*dataclass* : 4D.DataClass) : Collection + +Resolves each phrase key against *dataclass* and returns an ordered Collection of ORDA attribute descriptor objects, one per key in the same order as `.keys`. For dot-notation paths, traverses N:1 relations to reach the final attribute. Pushes `Null` for any key whose path cannot be resolved (unknown attribute or non-relation intermediate segment). + +| Argument | Type | Description | +| ----------------------- | ---------------------------- | -------------------------------------------------------------------------------------------- | +| *dataclass* | 4D.DataClass | The dataclass to resolve attributes against. | +| Résultat de la fonction | Collection | Ordered collection of ORDA attribute objects (or `Null`). | + +Each resolved entry is an ORDA attribute descriptor with `.name`, `.kind`, and more — see [DataClass.attributeName](https://developer.4d.com/docs/API/DataClassClass#attributename). + +```4d +var $tpl:=cs.EmbeddingStudio.Phrase.new("{firstName} graduated from {school.name}") +var $attrs:=$tpl.attributes(ds.Students) +// $attrs[0].name → "firstName" $attrs[0].type → "string" +// $attrs[1].name → "name" $attrs[1].type → "string" (from School dataclass) +// $attrs[1] is Null if school.name could not be resolved +``` + +## Voir également + +- [Definition](Definition.md) — holds a `Phrase`. +- [StudioEmbedder.render()](StudioEmbedder.md#render) — renders a phrase for an entity, non-persisting. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Process.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Process.md new file mode 100644 index 00000000000000..e15505f9d524e5 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Process.md @@ -0,0 +1,188 @@ +--- +id: process +title: Process +--- + +# Process + +The `Process` class orchestrates the full embedding pipeline: it browses 4D entities, renders text from their fields using a [Definition](Definition.md), calls the embeddings API through an [Embedder](Embedder.md), and stores the resulting `4D.Vector` on each entity. + +To render or embed on demand without persistence (search query vectors, phrase previews), see [StudioEmbedder](StudioEmbedder.md). + +## Propriétés + +| Nom de propriété | Type | Description | +| ---------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- | +| `propriétés` | [Settings](Settings.md) | The settings (definitions, batch size, phrase validation options). | +| `embedder` | [Embedder](Embedder.md) | The API-calling engine. Stateless and swappable. | +| `options` | Object | Runtime options object (see [Options object](#options-object) below). | + +### Options object + +| Touche | Type | Description | +| ---------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `onProgress` | 4D.Function | Called after each processed chunk with `{definition, report}`. | +| `onSuccess` | 4D.Function | Called once at the end when `report.success = True`, with `{report, success, errors}`. | +| `onError` | 4D.Function | Called once at the end when `report.success = False`, with `{report, success, errors}`. | +| `onTerminate` | 4D.Function | Called once at the end in all cases (after `onSuccess`/`onError`), with `{report, success, errors}`. | +| `dryRun` | Boolean | If `True`, runs selection/filter logic but skips API calls and entity saves. | +| `force` | Boolean | If `True`, recomputes every entity ignoring null-vector / dirty-flag filter. | +| `debug` | Boolean | If `True`, emits additional diagnostic log entries. | +| `pauseIndexes` | Boolean | If `True`, index maintenance on the target table is paused for the duration of a `processEntitySelection` batch run, then resumed right after (or on early exit/critical error). Default `False` — indexes are left alone. See [Pausing indexes](#pausing-indexes) before enabling it. | +| `waitForIndexes` | Boolean | Only used with `pauseIndexes`. If `True`, resuming indexes blocks until they are rebuilt. Default `False` — resume is asynchronous (indexes rebuilt in the background). | +| `shouldCancel` | 4D.Function | Predicate called between chunks during selection processing. Returning `True` stops the run gracefully (cooperative cancel) — what [`Scheduler.cancel()`](Scheduler.md#cancel) uses. | +| `embedder` | [Embedder](Embedder.md) | Inject a custom embedder (otherwise a default one is created). | + +## Class constructor + +Create an instance of the orchestrator. + +| Nom de l'argument | Type | Description | +| ----------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| *settings* | [Settings](Settings.md) | Optionnel. If omitted, settings are loaded from the default `Settings/embeddings.json`. | +| *options* | Object | Optional runtime options (see table above). | + +```4d +// Simplest — uses defaults +var $p:=cs.EmbeddingStudio.Process.new() + +// With explicit settings +var $p:=cs.EmbeddingStudio.Process.new($settings) + +// With options +var $p:=cs.EmbeddingStudio.Process.new($settings; {\ + force: True; \ + onProgress: Formula(ALERT("chunk done: "+String($1.report.entitiesUpdated)))}) +``` + +## Batch processing functions + +### process() + +**process**(*definition* : Variant) : [ProcessResult](ProcessResult.md) + +Process one, many, or all [Definition](Definition.md) entries against the full content of their target dataclass. + +| Argument | Type | Description | +| ----------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| *définition* | `Null`, [Definition](Definition.md), `4D.DataClass`, plain object, or Collection | See [process() resolution](#process-resolution). `Null` → every definition in settings. | +| Résultat de la fonction | [ProcessResult](ProcessResult.md) | Statistics and per-error breakdown. | + +```4d +// Every definition in settings +var $r:=$p.process() + +// One specific definition +var $r:=$p.process($def) + +// Multiple definitions +var $r:=$p.process([$def1; $def2]) + +// Every definition configured for a whole dataclass +var $r:=$p.process(ds.Students) + +// A plain descriptor — looked up in settings, or built on the fly +var $r:=$p.process({dataclassName: "Students"; vectorName: "student_vector_1"}) + +// Any mix — each item is resolved independently and flattened +var $r:=$p.process([ds.Students; $def; {dataclassName: "School"; vectorName: "school_vector_1"}]) +``` + +#### process() resolution + +`process()` has no entity context, so it resolves each input into concrete [Definition](Definition.md) objects directly from settings: + +| Zone de saisie | Comportement | +| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Null` | Every definition in settings. | +| [Definition](Definition.md) | Used as-is. | +| `4D.DataClass` (e.g. `ds.Students`) | Every definition in settings whose `dataclassName` matches that dataclass. | +| `{dataclassName: "..."; vectorName: "..."}` | The matching saved definition, or — if none is found — a new `Definition` built from the object's fields (`modelAlias`, `phrase.template`). | +| Collection | Each item is resolved with the rules above and the results are **flattened** into one collection (a `4D.DataClass` item can expand to several definitions). Unsupported items are dropped. | +| Anything else | Empty result. | + +### processEntity() + +**processEntity**(*entity* : 4D.Entity ; *definition* : Variant) : [ProcessResult](ProcessResult.md) + +Process a single entity. Cheap path — no chunking, no server-side filter. + +| Argument | Type | Description | +| ----------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| *entity* | 4D.Entity | The entity to (re)compute vectors for. | +| *définition* | `Null`, [Definition](Definition.md), Collection, or `{vectorName: ...}` | See [resolution rules](#definition-resolution). `Null` infers from entity's dataclass. | +| Résultat de la fonction | [ProcessResult](ProcessResult.md) | Statistics and per-error breakdown. | + +```4d +// Auto-resolve every definition matching this entity's dataclass +var $r:=$p.processEntity($entity) + +// Specific definition +var $r:=$p.processEntity($entity; $def) + +// By vector name only (looked up in settings against the entity's dataclass) +var $r:=$p.processEntity($entity; {vectorName: "student_vector_1"}) +``` + +### processEntitySelection() + +**processEntitySelection**(*selection* : 4D.EntitySelection ; *definition* : Variant) : [ProcessResult](ProcessResult.md) + +Workhorse path for large jobs. Chunks the selection by `settings.batchSize`, sends one API call per chunk, saves each entity individually. + +| Argument | Type | Description | +| ----------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| *selection* | 4D.EntitySelection | Entities to process. Pre-filtering by the caller is allowed; the pipeline still applies its null/dirty filter. | +| *définition* | `Null`, [Definition](Definition.md), Collection, or `{vectorName: ...}` | See [resolution rules](#definition-resolution). | +| Résultat de la fonction | [ProcessResult](ProcessResult.md) | Statistics and per-error breakdown. | + +```4d +var $todo:=ds.Students.query("country = :1"; "FR") +var $r:=$p.processEntitySelection($todo; $def) +``` + +### Definition resolution (entity context) + +The polymorphic *definition* argument accepted by `processEntity` and `processEntitySelection`. Unlike [`process()`](#process-resolution), these have an entity/selection to infer the dataclass from, so a bare `{vectorName: "..."}` stub is enough: + +| Zone de saisie | Comportement | +| --------------------------- | ----------------------------------------------------------------------------------------------- | +| `Null` | All definitions in settings whose `dataclassName` matches the entity/selection. | +| [Definition](Definition.md) | Used as-is; the `dataclassName` must match the entity/selection. | +| `{vectorName: "..."}` | Looked up in settings by `vectorName` against the entity/selection dataclass. | +| Collection | Each item resolved using the rules above; mismatches are silently dropped. | + +### Recompute rules + +An entity is (re)computed when **any** of these are true: + +- The target vector field is `Null`. +- A sibling field named `{vectorName}_dirty` exists and is `True`. +- The `force` option is `True`. + +The dirty field is optional per dataclass. If it doesn't exist, only the null-vector case triggers recomputation. Upon successful save, the pipeline clears the dirty flag (when present). + +For `processEntitySelection`, the filter is executed as a server-side ORDA query before any API call, so only the rows that actually need work are loaded into memory. For `processEntity`, the check is done in memory on the already-fetched entity. + +### Pausing indexes + +By default the indexes of the target table are maintained normally while vectors are saved. With the `pauseIndexes` option, a batch run calls [`PAUSE INDEXES`](https://developer.4d.com/docs/commands/pause-indexes) on the table before writing and [`RESUME INDEXES`](https://developer.4d.com/docs/commands/resume-indexes) once done (also on early exit or critical error). + +Be aware of what these commands do: + +- `PAUSE INDEXES` disables **all** the indexes of the table (except the primary key index), not only the vector ones: every index on every other field of the table is paused too. While paused, queries and sorts on that table, including those of other processes, run without any index. +- `RESUME INDEXES` then **rebuilds all these indexes**, for the whole table, not only for the records that were recomputed. On a table with several indexes, this rebuild can cost more than the time saved during the writes. +- With `waitForIndexes` set to `True`, the run blocks until the rebuild completes; otherwise the rebuild runs in the background. +- These commands cannot run on a 4D remote client: there the option is ignored (a warning is logged once) and the recalculation runs with indexes maintained normally. Run it on the server, for example through the [Scheduler](Scheduler.md), to use it. + +Enable it only for large recalculations, such as computing the vectors of a whole table for the first time. + +## Voir également + +- [StudioEmbedder](StudioEmbedder.md) +- [Settings](Settings.md) +- [Definition](Definition.md) +- [Embedder](Embedder.md) +- [ProcessResult](ProcessResult.md) +- [Phrase](Phrase.md) +- [Rate Limiting](../RateLimit.md) diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessError.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessError.md new file mode 100644 index 00000000000000..3dfb9471b01545 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessError.md @@ -0,0 +1,87 @@ +--- +id: processerror +title: ProcessError +--- + +# ProcessError + +A `ProcessError` is one structured, typed entry in the `errors` collection of a [ProcessResult](ProcessResult.md). Its typed fields let callers react to a specific failure mode programmatically — retry transient failures, abort on a fatal model outage, count save failures — without parsing message strings. + +You read these instances from [ProcessResult](ProcessResult.md)`.errors`, directly or through its query helpers (`errorsByCode`, `errorsByScope`, `retryableErrors`). + +## Propriétés + +| Nom de propriété | Type | Description | +| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `portée` | Text | Where the error originated: `"pipeline"`, `"definition"`, `"chunk"`, or `"entity"`. | +| `severity` | Text | `"warning"`, `"error"`, or `"fatal"`. Determined by `code` (see [ProcessErrorCode](ProcessErrorCode.md)). | +| `code` | Integer | Machine-readable error code — compare against the constants on [ProcessErrorCode](ProcessErrorCode.md). | +| `ref` | Variant | Scope-dependent reference: `"Dataclass.vector"`, an entity primary key, a model alias, or `Null`. | +| `message` | Text | Human-readable, localized message. | +| `retryable` | Boolean | `True` when re-running the operation could plausibly succeed. Determined by `code`. | + +### scope values + +| Portée | Description | +| -------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `"pipeline"` | Top-level failure affecting the whole run (null selection, a model became unavailable). | +| `"definition"` | A [Definition](Definition.md) failed validation or was skipped. | +| `"chunk"` | A whole batch (chunk) of entities failed in a single API call. | +| `"entity"` | A single entity failed to embed or save. | + +### severity values + +| Severity | Description | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `"warning"` | Non-blocking — does **not** make [ProcessResult](ProcessResult.md)`.success` false. | +| `"error"` | A recoverable failure scoped to one entity, chunk, or definition. Makes `success` false. | +| `"fatal"` | Blocks the rest of the run (e.g. the model is unavailable). Also surfaces via `hasFatal`. | + +## Propriétés calculées + +| Propriété | Type | Description | +| --------- | ------- | ------------------------------------------------- | +| `isFatal` | Boolean | `True` when `severity = "fatal"`. | + +## Fonctions + +### toObject() + +**toObject**() : Object + +Returns a plain object (`{scope, severity, code, ref, message, retryable}`) suitable for logging or JSON serialization. + +| Argument | Type | Description | +| ----------------------- | ------ | ------------------------------------------------------ | +| Résultat de la fonction | Object | A JSON-friendly snapshot of the error. | + +## Exemple + +React to failures by type rather than by message text: + +```4d +var $r:=$p.process() + +If (Not($r.success)) + + If ($r.hasFatal) + ALERT("A model became unavailable — aborting until it recovers.") + End if + + var $codes:=cs.EmbeddingStudio.ProcessErrorCode.me + var $saveFailures:=$r.errorsByCode($codes.SAVE_FAILED) + If ($saveFailures.length>0) + ALERT(String($saveFailures.length)+" entities failed to save.") + End if + + // Collect entity keys worth retrying later + var $retry:=$r.retryableErrors().query("scope = :1"; "entity").extract("ref") + +End if +``` + +## Voir également + +- [ProcessErrorCode](ProcessErrorCode.md) — the catalogue of `code` values and their severity/retryability. +- [ProcessResult](ProcessResult.md) — owns the `errors` collection and the query helpers (`errorsByCode`, `errorsByScope`, `retryableErrors`). +- [Process](Process.md) — produces these errors. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessErrorCode.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessErrorCode.md new file mode 100644 index 00000000000000..44567dbacab051 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessErrorCode.md @@ -0,0 +1,55 @@ +--- +id: processerrorcode +title: ProcessErrorCode +--- + +# ProcessErrorCode + +A `singleton` exposing the stable, machine-readable error codes carried by [ProcessError](ProcessError.md) `.code`, plus a `meta()` lookup mapping each code to its default `severity` and `retryable` flag. Compare against these constants instead of parsing message strings. + +Access the shared instance via `.me`: + +```4d +var $codes:=cs.EmbeddingStudio.ProcessErrorCode.me +If ($error.code=$codes.SAVE_FAILED) + // … +End if +``` + +## Codes + +| Constante | Valeur | Default severity | Retryable | Raised when… | +| ----------------------- | ------ | ---------------- | --------- | ------------------------------------------------------------------------------------------------- | +| `NULL_INPUT` | 100 | error | Non | A required entity, selection, or definition was `Null`. | +| `INVALID_DEFINITION` | 101 | error | Non | A value is not a usable [Definition](Definition.md) instance. | +| `VALIDATION_FAILED` | 102 | error | Non | `Definition.validate()` reported a problem. | +| `MODEL_UNAVAILABLE` | 200 | fatal | Oui | A critical API error made the model unusable for the rest of the run. | +| `MODEL_SKIPPED` | 201 | error | Oui | A definition was skipped because its model already failed critically. | +| `EMBED_FAILED` | 202 | error | Oui | A non-critical embedding call failed (single entity or chunk). | +| `VECTOR_COUNT_MISMATCH` | 300 | error | Non | The provider returned a different vector count than requested. | +| `SAVE_FAILED` | 400 | error | Oui | `entity.save()` failed (validation, lock, …). | + +Codes are grouped by hundreds: `1xx` input/configuration, `2xx` model/API, `3xx` data integrity, `4xx` persistence. Unknown codes resolve to `{severity: "error"; retryable: False; label: "UNKNOWN"}`. + +## Fonctions + +### meta() + +**meta**( $code : Integer ) : Object + +Returns the `severity` and `retryable` flag associated with a code — the same values carried by a [ProcessError](ProcessError.md) with that `code`. + +| Argument | Type | Description | +| ----------------------- | ------- | ----------------------------------------------------------------------- | +| `$code` | Integer | One of the code constants above. | +| Résultat de la fonction | Object | `{severity : Text; retryable : Boolean; label : Text}`. | + +```4d +var $m:=cs.EmbeddingStudio.ProcessErrorCode.me.meta(cs.EmbeddingStudio.ProcessErrorCode.me.MODEL_UNAVAILABLE) +// $m = {severity: "fatal"; retryable: True; label: "MODEL_UNAVAILABLE"} +``` + +## Voir également + +- [ProcessError](ProcessError.md) — carries a `.code` from this list. +- [ProcessResult](ProcessResult.md) — `errorsByCode()` filters errors by code. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessResult.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessResult.md new file mode 100644 index 00000000000000..855a11dff50861 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessResult.md @@ -0,0 +1,91 @@ +--- +id: processresult +title: ProcessResult +--- + +# ProcessResult + +The `ProcessResult` class is the return value of every batch entry point of [Process](Process.md) (`process`, `processEntity`, `processEntitySelection`). It accumulates statistics, per-error breakdowns, and wall-clock duration. + +The orchestrator never throws out of its public batch API — failures are recorded here and the job continues. The caller decides what to do with them. + +## Propriétés + +| Nom de propriété | Type | Description | +| ---------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `definitionsProcessed` | Integer | Number of [Definition](Definition.md) entries processed. | +| `entitiesConsidered` | Integer | Number of entities that passed the "needs recompute" filter. | +| `entitiesUpdated` | Integer | Number of entities whose vector was successfully written and saved. | +| `entitiesSkipped` | Integer | Number of entities that could not be processed: individual embed or save errors, or whole-chunk API failures (those entities are left unchanged for the next run). | +| `apiCalls` | Integer | Number of embeddings API calls made. | +| `promptTokens` | Integer | Total prompt tokens consumed across all API calls in this run. | +| `totalTokens` | Integer | Total tokens consumed across all API calls in this run. | +| `durée` | Integer | Total duration of the job in milliseconds. | +| `errors` | Collection | List of [ProcessError](ProcessError.md) entries recorded during the run. | + +### Propriétés calculées + +| Propriété | Type | Description | +| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `success` | Boolean | `True` when no `"error"` or `"fatal"` entry was recorded. `"warning"` entries do not fail the run. | +| `hasFatal` | Boolean | `True` when at least one `"fatal"` entry was recorded (e.g. a model became unavailable). | + +### Error entries + +Each item in `errors` is a [ProcessError](ProcessError.md) with `scope`, `severity`, `code`, `ref`, `message`, and `retryable`. See [ProcessError](ProcessError.md) for the field meanings and [ProcessErrorCode](ProcessErrorCode.md) for the `code` catalogue. + +## Fonctions + +### errorsByScope() + +**errorsByScope**( $scope : Text ) : Collection + +Errors filtered by `scope` (`"pipeline"`, `"definition"`, `"chunk"`, `"entity"`). + +### errorsByCode() + +**errorsByCode**( $code : Integer ) : Collection + +Errors filtered by machine-readable code — see [ProcessErrorCode](ProcessErrorCode.md). + +### retryableErrors() + +**retryableErrors**() : Collection + +Errors flagged `retryable` — re-running the operation could plausibly succeed. + +### toObject() + +**toObject**() : Object + +Returns a plain object suitable for logging or JSON serialization. + +| Argument | Type | Description | +| ----------------------- | ------ | ------------------------------------------------------- | +| Résultat de la fonction | Object | A JSON-friendly snapshot of the report. | + +```4d +var $r:=$p.process() +LOG EVENT(Into 4D log file; JSON Stringify($r.toObject())) +``` + +## Exemple + +```4d +var $r:=$p.processEntitySelection(ds.Students.all(); $def) + +If ($r.success) + ALERT("Updated "+String($r.entitiesUpdated)+" students in "+String($r.duration)+" ms") +Else + var $err : Object + For each ($err; $r.errors) + ALERT("[" + $err.scope + "] " + String($err.ref) + " — " + $err.message) + End for each +End if +``` + +## Voir également + +- [Process](Process.md) +- [ProcessError](ProcessError.md) — the typed shape of each `errors` entry. +- [ProcessErrorCode](ProcessErrorCode.md) — the `code` catalogue. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Scheduler.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Scheduler.md new file mode 100644 index 00000000000000..152989726fb6b5 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Scheduler.md @@ -0,0 +1,369 @@ +--- +id: scheduler +title: Périodicité +--- + +# Périodicité + +The `Scheduler` class is the public entry point for the **automated embedding recalculation** service. It maintains a background task that runs the embedding pipeline (see [Process](Process.md)) at a configured interval or a fixed daily time, guarantees that **at most one** recalculation batch runs at a time, and exposes runtime status for administration and monitoring interfaces. + +It is a **singleton**, accessed through `cs.EmbeddingStudio.Scheduler.me`. + +The scheduler runs two named workers: + +| Worker | Rôle | +| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `EmbeddingStudioScheduler` | Background loop that re-reads the config each cycle, computes the next run and fires when due. | +| `EmbeddingStudio` | Execution worker that runs one recalculation batch (shared with the Studio UI, so scheduled and manual runs are serialized). | + +## Configuration + +The configuration lives under the `scheduler` key of `Settings/embeddings.json`: + +```json +{ + "scheduler": { + "mode": "interval", + "intervalHours": 3, + "startFrom": "reference", + "startReference": "2026-09-02T14:00:00", + "dailyTime": "00:00" + } +} +``` + +| Touche | Type | Values / range | Description | +| ---------------- | ------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `mode` | Text | `"never"` \| `"interval"` \| `"daily"` | Scheduling mode. Absent/unknown ⇒ `never` (no automatic run). | +| `intervalHours` | Integer | `1`..`24` | Interval mode only. Out-of-range ⇒ default `3`. | +| `startFrom` | Text | `"reference"` \| `"lastExecution"` | Interval mode only. Anchor of the interval (see below). Anything other than `"lastExecution"` — including the legacy `"now"` — is normalized to `reference`. Default `reference`. | +| `startReference` | Text | `"YYYY-MM-DDThh:mm:ss"` | Interval mode with `startFrom = "reference"`. Fixed instant the interval counts from. Absent ⇒ the moment the scheduler was armed, then the current instant. | +| `dailyTime` | Text | `"HH:MM"` | Daily mode only. Time of day for the recalculation. Default `"00:00"`. | + +**Interval anchoring (`startFrom`)** + +- `reference` — **fixed rate**: the interval is anchored on the fixed `startReference` instant, so the slots do not drift whatever a run's duration is. Slots are advanced by `intervalHours` until the first one strictly after now. When `startReference` is absent (a fresh or legacy config), the anchor falls back to the moment the scheduler was armed (`start()`), then to the current instant. +- `lastExecution` — **fixed delay**: the interval is anchored on the last completed recalculation. If the elapsed time since the last run already exceeds the interval (e.g. after a restart), the run is triggered immediately. If there is no prior run, it runs immediately. + +The effective configuration is read from the file on **every loop cycle**, so changes take effect without restarting the scheduler. + +## Starting the scheduler + +Configuring a `mode` is **not enough**: nothing runs until the scheduler is started. There are two ways to get there, and which one applies depends on a single option of your host database. + +### 1. Automatic — let the host database start it + +In the host database, open **Settings > Security** and check **"Execute 'On Host Database Event' method of the components"** (it is *unchecked* by default, for security reasons). + +With this option on, 4D Embedding Studio starts the scheduler by itself when the host database opens, and stops it when the host database closes. There is nothing else to write. + +Use [`autoStart()`](#autostart) to check whether the option is on: + +```4d +If (Not(cs.EmbeddingStudio.Scheduler.me.autoStart())) + // the option is off — I must start the scheduler myself + cs.EmbeddingStudio.Scheduler.me.start() +End if +``` + +### 2. Manual — start it from your own code + +If you prefer to leave the option off, the scheduler never starts on its own. Call [`start()`](#start) from wherever it suits you — typically the host `On Startup` or `On Server Startup` database method — and [`stop()`](#stop) when the database closes (`On Exit` / `On Server Shutdown`): + +```4d +// Host "On Server Startup" +cs.EmbeddingStudio.Scheduler.me.start() + +// Host "On Server Shutdown" +cs.EmbeddingStudio.Scheduler.me.stop() +``` + +> In client/server, arm the scheduler from `On Server Startup`, not from `On Startup`: +> `On Startup` runs on every remote client, and the scheduler state is per machine — each +> client would arm its own loop and run its own batches. If you do call [`start()`](#start) +> from `On Startup` (single-user setups), guard it with +> `If (Application type#4D Remote mode)`. + +`start()` is idempotent, so calling it from several places is harmless. + +### Checking that it really runs + +[`isStarted()`](#isstarted) tells you whether the background loop is alive right now — the answer to "is my schedule actually being watched?": + +```4d +var $s:=cs.EmbeddingStudio.Scheduler.me.status() +If ($s.enabled && Not($s.started)) + ALERT("A schedule is configured but the scheduler is not started.") +End if +``` + +## Fonctions + +### start() + +**start**() : Boolean + +Arms the scheduler and starts the background loop worker if it is not already running. Idempotent — calling it again while already armed simply refreshes the "start from now" anchor. + +| Résultat | Type | Description | +| -------- | ------- | ------------------------------ | +| Résultat | Boolean | Always `True`. | + +```4d +cs.EmbeddingStudio.Scheduler.me.start() +``` + +### stop() + +**stop**() + +Disarms the scheduler and stops the background loop worker. A recalculation batch already in progress is **not** interrupted — it finishes normally (use [`cancel()`](#cancel) to request an early stop). + +```4d +cs.EmbeddingStudio.Scheduler.me.stop() +``` + +### annuler() + +**cancel**() + +Requests a **cooperative** cancel of the batch currently running. The running batch is never force-killed; it stops gracefully between two chunks. Has no effect if no batch is running. + +```4d +cs.EmbeddingStudio.Scheduler.me.cancel() +``` + +### force() + +**force**() : Object + +Forces a recalculation **now**, regardless of the schedule. It honors the single-batch rule: if a batch is already running, the forced trigger is skipped (and logged). Non-blocking — the run happens on the execution worker. + +| Résultat | Type | Description | +| -------- | ------ | ----------------------------------------------------- | +| Résultat | Object | The current [status](#status) object. | + +```4d +var $status:=cs.EmbeddingStudio.Scheduler.me.force() +``` + +### status() + +**status**() : Object + +Returns the current scheduler status, without any input parameter — suitable for administration and monitoring displays. + +| Résultat | Type | Description | +| -------- | ------ | ---------------------------------------------------- | +| Résultat | Object | See [Status object](#status-object). | + +```4d +var $s:=cs.EmbeddingStudio.Scheduler.me.status() +If ($s.running) + ALERT("A recalculation is running since "+$s.batchStart) +End if +``` + +#### Objet statut + +| Touche | Type | Description | +| ---------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `enabled` | Boolean | `False` when `mode = "never"`. | +| `mode` | Text | Effective mode (`never` \| `interval` \| `daily`). | +| `armed` | Boolean | `True` when the background loop is armed (after `start()`, until `stop()`). | +| `running` | Boolean | `True` while a recalculation batch is in progress. | +| `batchStart` | Text \| Null | ISO timestamp of the running batch start (`Null` when idle). | +| `lastExecution` | Text \| Null | ISO timestamp of the last completed run (`Null` if none yet). Restored from the persisted history after a restart, so it survives the loss of in-memory state. | +| `lastRunBeforeRestart` | Boolean | `True` when `lastExecution` was recovered from the history after a restart rather than produced by a run in the current session. | +| `nextRun` | Text \| Null | ISO timestamp of the next scheduled run (`Null` in `never` mode). | +| `lastResult` | Text \| Null | Result of the last trigger: `started` \| `skipped` \| `completed` \| `failed`. | +| `error` | Text \| Null | Error summary when the last run failed (safe for admin display), else `Null`. | +| `started` | Boolean | `True` when the background loop is really alive (see [`isStarted()`](#isstarted)). | +| `autoStart` | Boolean | `True` when the host database starts the scheduler by itself (see [`autoStart()`](#autostart)). | + +### isStarted() + +**isStarted**() : Boolean + +Tells whether the scheduler is **effectively running**, i.e. whether its background loop is alive at this very moment. Unlike the `armed` flag of the [status](#status-object), it reflects reality: if the loop was never started, or was killed, the result is `False`. + +| Résultat | Type | Description | +| -------- | ------- | --------------------------------------------------------- | +| Résultat | Boolean | `True` when the background loop is alive. | + +```4d +If (Not(cs.EmbeddingStudio.Scheduler.me.isStarted())) + cs.EmbeddingStudio.Scheduler.me.start() +End if +``` + +### autoStart() + +**autoStart**() : Boolean + +Tells whether the host database authorizes 4D Embedding Studio to start itself, i.e. whether the **"Execute 'On Host Database Event' method of the components"** option is checked in the host **Settings > Security** (see [Starting the scheduler](#starting-the-scheduler)). + +- `True` — the scheduler starts with the host database and stops with it. You have nothing to call. +- `False` — nothing starts automatically: your code must call [`start()`](#start) and [`stop()`](#stop). + +The answer is read from the host structure settings. When they cannot be read, the result is `False` — the safe answer, since starting an already-started scheduler is harmless. + +| Résultat | Type | Description | +| -------- | ------- | -------------------------------------------------------------------- | +| Résultat | Boolean | `True` when the host starts the scheduler by itself. | + +```4d +var $auto:=cs.EmbeddingStudio.Scheduler.me.autoStart() +``` + +### config() + +**config**() : Object + +Returns the effective scheduler configuration with defaults applied (as resolved from `embeddings.json`). + +| Résultat | Type | Description | +| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | +| Résultat | Object | `{mode; intervalHours; startFrom; startReference; dailyTime}` (see [Configuration](#configuration)). | + +```4d +var $cfg:=cs.EmbeddingStudio.Scheduler.me.config() +``` + +### saveConfig() + +**saveConfig**( *cfg* : Object ) : Object + +Validates, normalizes and **persists** a scheduler configuration to the `scheduler` key of `embeddings.json`, then returns the normalized value. This is the programmatic equivalent of the scheduler settings window: it lets you change the schedule entirely by code, without the GUI. Only the `scheduler` key is written — other keys of the settings file are preserved. + +The configuration is written **on the server**: in a 4D Server / 4D remote setup the file is always edited on the server machine, so a remote client can safely call this method. Because the loop re-reads the configuration on every cycle, the new schedule takes effect without restarting the scheduler. + +| Paramètres | Type | Description | +| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| cfg | Object | Raw configuration `{mode; intervalHours; startFrom; startReference; dailyTime}` (see [Configuration](#configuration)). Missing/out-of-range values are defaulted. | + +| Résultat | Type | Description | +| -------- | ------ | ---------------------------------------------------------------- | +| Résultat | Object | The normalized configuration that was persisted. | + +```4d +// Switch to a 6-hour interval counting from the last execution +cs.EmbeddingStudio.Scheduler.me.saveConfig({mode: "interval"; intervalHours: 6; startFrom: "lastExecution"}) + +// Switch to a daily run at 02:30 +cs.EmbeddingStudio.Scheduler.me.saveConfig({mode: "daily"; dailyTime: "02:30"}) + +// Disable the automatic schedule +cs.EmbeddingStudio.Scheduler.me.saveConfig({mode: "never"}) +``` + +### nextRun() + +**nextRun**() : Object + +Computes the next scheduled run from the current configuration and state. + +| Résultat | Type | Description | +| -------- | -------------- | --------------------------------------------------------------------------------------------------------------- | +| Résultat | Object \| Null | `{date : Date; time : Time; timestamp : Text; immediate : Boolean}`, or `Null` in `never` mode. | + +```4d +var $next:=cs.EmbeddingStudio.Scheduler.me.nextRun() +``` + +### reload() + +**reload**() : Object + +No-op convenience: the configuration is re-read automatically on each loop cycle, so this simply returns the current [status](#status). Provided for callers that want an explicit "config changed, give me the up-to-date status" call. + +| Résultat | Type | Description | +| -------- | ------ | ----------------------------------------------------- | +| Résultat | Object | The current [status](#status) object. | + +## Concurrency & logging + +- **Single batch** — at any time, at most one recalculation batch runs. A trigger (scheduled or forced) fired while a batch is running is **skipped**, not queued. +- **Skip traceability** — skipped triggers are logged with their timestamp in the execution history (`Logs/embeddingHistory.json`). +- **Cooperative cancel** — `cancel()` stops a running batch gracefully between chunks; it is never force-killed. +- **History** — each run records start/end timestamps, status, token usage and the computed next run date in `Logs/embeddingHistory.json` (see [ProcessResult](ProcessResult.md) for per-run details). + +### Execution history file + +`Logs/embeddingHistory.json` is written by the pipeline itself (every full `process()` run, scheduled or manual), guarded by a semaphore so concurrent processes never interleave writes. It holds the **current** run at the top level, the one before it under `previous`, and the same pair per definition under `definitions`. + +```json +{ + "startTime": "2026-09-01T14:03:00", + "endTime": "2026-09-01T14:03:00", + "status": "completed", + "trigger": "completed", + "error": null, + "nextComputeDate": "2026-09-02T14:03:00", + "promptTokens": 0, + "totalTokens": 0, + "cumulativePromptTokens": 37802, + "cumulativeTotalTokens": 37802, + "previous": { "startTime": "…", "endTime": "…", "status": "completed", "error": null, + "nextComputeDate": "…", "promptTokens": 12764, "totalTokens": 12764, + "cumulativePromptTokens": 37802, "cumulativeTotalTokens": 37802 }, + "skipped": ["2026-09-01T12:00:00"], + "definitions": { + "Students.student_vector_1": { + "startTime": "…", "endTime": "…", "status": "completed", "error": null, + "promptTokens": 1054, "totalTokens": 1054, + "cumulativePromptTokens": 4210, "cumulativeTotalTokens": 4210, + "previous": { "…": "…" } + } + } +} +``` + +| Touche | Type | Description | +| -------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `startTime` / `endTime` | Text \| Null | ISO timestamps of the run, in the scheduler's local base. `endTime` is `null` while a run is in progress. | +| `status` | Text | `running` \| `completed` \| `failed`. | +| `trigger` | Text | Last event that touched the file: `started` \| `skipped` \| `completed` \| `failed`. | +| `error` | Text \| Null | Summary of the run's errors, or `null`. Never contains an API key. | +| `nextComputeDate` | Text \| Null | Next scheduled run computed at the end of the run (the `nextComputeDate` option of [Process](Process.md)). | +| `promptTokens` / `totalTokens` | Integer | Usage for this run alone. | +| `cumulativePromptTokens` / `cumulativeTotalTokens` | Integer | Running totals across all recorded runs. | +| `previous` | Object | Snapshot of the preceding run — the same keys, without `trigger`, `skipped` and `definitions`. Only one generation is kept. | +| `skipped` | Collection | ISO timestamps of triggers skipped because a batch was already running. Capped at the **last 50**. | +| `definitions` | Object | One entry per definition, keyed `"."`, each with its own `startTime`, `endTime`, `status` (`completed` \| `failed` \| `skipped`), `error`, token counters and `previous`. | + +[`status()`](#status) reads `startTime`, `endTime`, `status`, `trigger`, `error` and `nextComputeDate` back from this file, which is how `lastExecution` survives a server restart. + +## Lifecycle + +| Host setting | What happens | What you must do | +| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| **"Execute 'On Host Database Event' method of the components"** checked | The scheduler starts when the host database opens and stops when it closes. | Nothing. | +| Option unchecked (default) | The scheduler never starts by itself. | Call [`start()`](#start) at startup and [`stop()`](#stop) at shutdown. | + +Ask [`autoStart()`](#autostart) which case you are in, and [`isStarted()`](#isstarted) whether the loop is currently alive. Stopping the scheduler never interrupts a batch in progress — it finishes normally. + +## Exemple + +```4d +// --- Start at server startup, unless the host does it for us --- +If (Not(cs.EmbeddingStudio.Scheduler.me.autoStart())) + cs.EmbeddingStudio.Scheduler.me.start() +End if + +// --- Admin panel: force a recalculation and read status --- +var $status:=cs.EmbeddingStudio.Scheduler.me.force() + +// --- Monitoring: display last / next run and current state --- +$status:=cs.EmbeddingStudio.Scheduler.me.status() +var $info:="Mode: "+$status.mode\ + +" — Last: "+String($status.lastExecution)\ + +" — Next: "+String($status.nextRun)\ + +" — "+($status.running ? "running" : String($status.lastResult)) + +// --- Cancel a long-running batch --- +cs.EmbeddingStudio.Scheduler.me.cancel() + +// --- Disable automatic runs --- +cs.EmbeddingStudio.Scheduler.me.stop() +``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Settings.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Settings.md new file mode 100644 index 00000000000000..45c3b4fc59db17 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Settings.md @@ -0,0 +1,184 @@ +--- +id: settings +title: Propriétés +--- + +# Propriétés + +The `Settings` class is the persisted configuration for the embedding pipeline. It loads and saves a JSON file (default: `Settings/embeddings.json`, overridable with the `EMBEDDINGS_SETTINGS_PATH` environment variable) containing a list of [Definition](Definition.md) entries, a batch size, and phrase-validation options. + +## Propriétés + +| Nom de propriété | Type | Description | +| ---------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `definitions` | Collection of [Definition](Definition.md) | The configured definitions. | +| `batchSize` | Integer | Chunk size used by [Process.processEntitySelection](Process.md#processentityselection). Default: `50`. | +| `phrase` | Object | Phrase-validation options (see below). | +| `embedder` | Object | Optional embedder configuration (see below). | +| `file` | 4D.File *(read-only)* | The backing file the settings are loaded from and saved to. | + +### phrase options + +Passed verbatim to [Phrase.validate()](Phrase.md#validate) whenever the pipeline validates a definition. + +| Champ | Type | Par défaut | Description | +| ----------------- | ------- | ---------- | ----------------------------------------------------------------------------------------------- | +| `allowRelations` | Boolean | `False` | Allow dot-notation through N:1 / 1:1 relations. | +| `allowCalculated` | Boolean | `False` | Allow calculated attributes in phrases. | +| `allowAlias` | Boolean | `False` | Allow alias attributes in phrases. | +| `allowObject` | Boolean | `False` | Allow object attributes in phrases. | + +> **Invalidation caveat.** Dirty-flag tracking only covers direct scalar fields on the entity. Fields that are only reachable through one of these options — a related entity's attribute, a calculated value, an alias, or a sub-property of an object — will **not** automatically mark the entity as dirty when they change. If such fields are part of a phrase and their source data changes, the vector will not be recomputed unless you call `invalidateVectors()` explicitly or use `force: true` when processing. + +### embedder options + +Controls how [Process](Process.md) builds its embedder. When absent, a default `Embedder` is created with its own defaults. + +| Champ | Type | Par défaut | Description | +| ------------ | ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `className` | Text | — | Name of a project class to instantiate instead of the built-in `Embedder`. The class must expose `embed` and `embedBatch` functions. If instantiation fails or the interface is missing, a diagnostic error is logged and the default `Embedder` is used as fallback. | +| `maxRetries` | Integer | `3` | Number of retry attempts on rate-limit errors (forwarded to `Embedder`). | +| `backoffMs` | Integer | `500` | Base back-off delay in ms, doubled each retry (forwarded to `Embedder`). | + +Any additional keys are forwarded as-is to the constructor of the target class (built-in or custom). + +## Format de fichier + +```json +{ + "batchSize": 50, + "phrase": { + "allowRelations": false, + "allowCalculated": false, + "allowAlias": false, + "allowObject": false + }, + "embedder": { + "maxRetries": 5, + "backoffMs": 200 + }, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding-3-small", + "phrase": "Student {firstName} {lastName}", + "autoInvalidate": true + } + ] +} +``` + +Each definition may include `autoInvalidate` (`true` by default) to control save-time automatic invalidation. + +The same file also carries the `scheduler` key (see [Scheduler](Scheduler.md#configuration)) and any other top-level key you add: `Settings` reads and rewrites only the keys listed above and leaves the rest untouched. + +With a custom embedder class: + +```json +{ + "embedder": { + "className": "MyCustomEmbedder" + }, + "definitions": [...] +} +``` + +## Class constructor + +Create a settings instance. The configuration file is loaded immediately. + +| Nom de l'argument | Type | Description | +| ----------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *file* | 4D.File | Optionnel. A file to use instead of the default location. The override applies process-wide for subsequent settings access. **Not supported in 4D Remote mode** — pass it only when running locally or on the server. | + +When *file* is omitted, the default location is used: `Settings/embeddings.json`, or the path given by the `EMBEDDINGS_SETTINGS_PATH` environment variable. + +```4d +// Default location +var $settings:=cs.EmbeddingStudio.Settings.new() + +// Custom file (server / mono only) +var $settings:=cs.EmbeddingStudio.Settings.new(File("/some/path/custom.json")) +``` + +## Fonctions + +### load() + +**load**() + +Reload the backing file into memory, overwriting in-memory state. A missing file resets to defaults without raising. + +A file that **exists but cannot be parsed** also leaves the instance on defaults, but it is remembered: an error is logged and [`save()`](#save) then refuses to write, so a malformed file is never silently replaced by defaults. + +### sauvegarde() + +**save**() : Boolean + +Serialize the current in-memory state to the backing file. Only the keys this class owns (`batchSize`, `phrase`, `embedder`, `definitions`) are written — every other top-level key present in the file (the `scheduler` configuration, model aliases…) is preserved as-is. A key whose value is back to its default is *removed* from the file rather than written. + +Definitions are merged with what the file holds at that instant, using the snapshot taken at load time as the common ancestor: two editors open at the same time no longer drop each other's definitions. + +| Résultat | Type | Description | +| -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| Résultat | Boolean | `True` when written. `False` — nothing written — when the file could not be read at load time. | + +```4d +$settings.definitions.push(cs.EmbeddingStudio.Definition.new("Students"; "student_vector_1"; "text-embedding-3-small"; "{firstName}")) +$settings.batchSize:=100 +$settings.save() +``` + +### chercher() + +**find**(*dataclassName* : Text ; *vectorName* : Text) : [Definition](Definition.md) + +Look up the saved definition for the given dataclass/vector pair. + +| Argument | Type | Description | +| ----------------------- | --------------------------- | ------------------------------------------------------------------- | +| *dataclassName* | Text | Nom de la dataclass. | +| *vectorName* | Text | Name of the vector field on that dataclass. | +| Résultat de la fonction | [Definition](Definition.md) | The matching definition, or `Null` if none matches. | + +```4d +var $def:=$settings.find("Students"; "student_vector_1") +``` + +### findAll() + +**findAll**(*dataclassName* : Text) : Collection of [Definition](Definition.md) + +Return every saved definition configured for the given dataclass. + +| Argument | Type | Description | +| ----------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------- | +| *dataclassName* | Text | Nom de la dataclass. | +| Résultat de la fonction | Collection of [Definition](Definition.md) | All matching definitions (empty collection if none match). | + +```4d +var $defs:=$settings.findAll("Students") +// → every Students definition; used by Process.process(ds.Students) +``` + +### invalidateVectors() + +**invalidateVectors**() : Object + +Calls [`invalidateVectors()`](Definition.md#invalidatevectors) on every definition in `definitions` and merges the results into a single status object. + +| Argument | Type | Description | +| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | +| Résultat de la fonction | Object | `{updated: Integer, skipped: Integer, errors: Collection of Text}` — accumulated across all definitions. | + +```4d +var $result:=cs.EmbeddingStudio.Settings.new().invalidateVectors() +// → { updated: 120; skipped: 0; errors: [] } +``` + +## Voir également + +- [Definition](Definition.md) +- [Process](Process.md) +- [Phrase](Phrase.md) diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/StudioEmbedder.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/StudioEmbedder.md new file mode 100644 index 00000000000000..53ef4019d9b785 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/StudioEmbedder.md @@ -0,0 +1,125 @@ +--- +id: studioembedder +title: StudioEmbedder +--- + +# StudioEmbedder + +The `StudioEmbedder` class renders and embeds on demand, resolved against the Studio settings: a saved definition gives the phrase and the model, so the vector you compute matches the ones stored by [Process](Process.md). Nothing is persisted. Typical uses: building the vector of a search query, finding entities similar to a given one, or previewing the text sent for an entity. + +For the full batch pipeline that persists vectors on entities, see [Process](Process.md). + +## Propriétés + +| Nom de propriété | Type | Description | +| ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------- | +| `propriétés` | [Settings](Settings.md) | The settings (vectors, batch size, phrase validation options). | +| `embedder` | [Embedder](Embedder.md) | The API-calling engine. Stateless and swappable. | +| `options` | Object | Runtime options object. | + +## Class constructor + +| Nom de l'argument | Type | Description | +| ----------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| *settings* | [Settings](Settings.md) | Optionnel. If omitted, settings are loaded from the default `Settings/embeddings.json`. | +| *options* | Object | Optional runtime options. Supports `embedder` for injection. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings) +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings; {embedder: $mockEmbedder}) +``` + +## Fonctions + +### render() + +**render**(*entity* : 4D.Entity ; *definitionOrPhrase* : Variant) : Text + +Return the text that [`embed()`](#embed) sends for an entity (the phrase rendered against it). No API call, no persistence. + +| Argument | Type | Description | +| ----------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *entity* | 4D.Entity | The entity to render against. | +| *definitionOrPhrase* | `Null`, [Phrase](Phrase.md), [Definition](Definition.md), Text, or plain object stub | `Null` → auto-resolve via settings (requires a unique match). Text → compiled as a throwaway `cs.EmbeddingStudio.Phrase`. Object stub → see [stub resolution](#stub-resolution). | +| Résultat de la fonction | Text | The rendered text. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $text: Text +$text:=$studioEmbedder.render($student; $def) // use def's phrase +$text:=$studioEmbedder.render($student; cs.EmbeddingStudio.Phrase.new("Hi {firstName}")) +$text:=$studioEmbedder.render($student; "Student: {lastName}") // raw template +$text:=$studioEmbedder.render($student) // auto-resolve +$text:=$studioEmbedder.render($student; {vectorName: "student_vector_1"}) // stub → saved definition's phrase +$text:=$studioEmbedder.render($student; {phrase: "Hi {firstName}"}) // ad-hoc stub → inline template +``` + +### embed() + +**embed**(*input* : Variant ; *context* : Variant ; *model* : Text) : [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) + +Compute a vector for an arbitrary input, without persisting anywhere. + +| Argument | Type | Description | +| ----------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| *input* | Text or 4D.Entity | Text → embedded directly. Entity → phrase rendered then embedded. | +| *context* | Text, [Phrase](Phrase.md), [Definition](Definition.md), Text template, plain object stub, or `Null` | Provides phrase and/or model depending on *input*. Object stub → see [stub resolution](#stub-resolution). | +| *model* | Text | Optional explicit model name. Used when *context* does not carry one. | +| Résultat de la fonction | [EmbedderResult](EmbedderResult.md) | The embedding result (use `.vector` to get the 4D.Vector). | + +Throws if no model can be determined. + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $vector: 4D.Vector + +// Text + model +$vector:=$studioEmbedder.embed("some text"; "text-embedding-3-small").vector + +// Text + definition (picks up def.modelAlias) +$vector:=$studioEmbedder.embed("some text"; $def).vector + +// Entity + definition (uses def.phrase + def.modelAlias) +$vector:=$studioEmbedder.embed($student; $def).vector + +// Entity + phrase + explicit model +$vector:=$studioEmbedder.embed($student; $phrase; "text-embedding-3-small").vector + +// Entity + ad-hoc template + model +$vector:=$studioEmbedder.embed($student; "Profile: {firstName} {lastName}"; "text-embedding-3-small").vector + +// Entity alone (auto-resolve, only when exactly one def matches the dataclass) +$vector:=$studioEmbedder.embed($student).vector + +// Entity + stub (deduces phrase + model from the matching saved definition) +$vector:=$studioEmbedder.embed($student; {vectorName: "student_vector_1"}).vector + +// Entity + ad-hoc stub (phrase compiled inline, model taken from the stub) +$vector:=$studioEmbedder.embed($student; {phrase: "Hi {firstName}"; modelAlias: "text-embedding-3-small"}).vector + +// Text + stub that only supplies the model +$vector:=$studioEmbedder.embed("some text"; {modelAlias: "text-embedding-3-small"}).vector +``` + +## Stub resolution + +Both `render()` and `embed()` accept a plain object in place of a `Phrase`/`Definition`. A stub is resolved the same way [`Process`](Process.md#definition-resolution-entity-context) resolves its `definition` argument, so the behavior matches. Two flavors are supported: + +| Stub | Resolves to | +| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `{vectorName: "..."}` (optionally `{dataclassName: "..."}`) | The matching **saved definition** for the entity's dataclass — deducing its phrase (and, for `embed`, its model). Resolves to nothing when there is no unique match. | +| `{phrase: "tpl {field}"}` or `{template: "tpl {field}"}` | An **ad-hoc** `Phrase` compiled inline; nothing is looked up. Pair with `{modelAlias: "..."}` to give `embed()` a model. | + +For `embed()`, the model is deduced in this order: an explicit `{modelAlias}` on the stub → the model of a stub-matched saved definition → the *model* argument → the entity's unique definition. An explicit `{modelAlias}` always wins. + +Unlike [`Process.process()`](Process.md#process-resolution), a stub is **not** turned into a brand-new `Definition` from its fields — `StudioEmbedder` persists nothing, so use `{phrase}`/`{template}` for one-off templates. + +## Voir également + +- [Process](Process.md) +- [Settings](Settings.md) +- [Definition](Definition.md) +- [Embedder](Embedder.md) +- [EmbedderResult](EmbedderResult.md) +- [Phrase](Phrase.md) diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/license.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/license.md new file mode 100644 index 00000000000000..8f6fc0dd2b5ffc --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/license.md @@ -0,0 +1,167 @@ +--- +id: license +title: SOFTWARE LICENSE AGREEMENT +--- + +# SOFTWARE LICENSE AGREEMENT + +## Preamble + +The purpose of this Software license agreement is to grant users the right to modify and re-use the software governed by this license. + +The exercising of this right is conditional upon the obligation to make /available to the community the modifications made to the source code of the software so as to contribute to its evolution. + +In consideration of access to the source code and the rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software's author, the holder of the economic rights, and the successive licensors only have limited liability. + +## Article 1 – DEFINITIONS + +***Agreement***: means this license agreement, and its possible subsequent versions and annexes. + +***Software***: means the software in its Object Code and/or Source Code form and, where applicable, its documentation, "as is" when the Licensee accepts the Agreement. + +***Initial Software***: means the Software in its Source Code and possibly its Object Code form and, where applicable, its documentation, "as is" when it is first distributed under the terms and conditions of the Agreement. + +***Modified Software***: means the Software modified by at least one Integrated Contribution. + +***Source Code***: means all the Software's instructions and program lines to which access is required so as to modify the Software. + +***Object Code***: means the binary files originating from the compilation of the Source Code. + +***Holder***: means the holder(s) of the economic rights over the Initial Software, in this case it is 4D SAS. + +***Licensee***: means the Software user(s) having accepted the Agreement. + +***Contributor***: means a Licensee having made at least one Integrated Contribution. + +***Licensor***: means the Holder, or any other individual or legal entity, who distributes the Software under the Agreement. + +***Integrated Contribution***: means new functions integrated into the Source Code by any or all Contributors. + +***Parties***: mean both the Licensee and the Licensor. + +These expressions may be used both in singular and plural form. + +## Article 2 - PURPOSE + +The purpose of the Agreement is the grant by the Licensor to the Licensee of a non-exclusive, transferable and worldwide license for the Software as set forth in Article 5 hereinafter for the whole term of the protection granted by the rights over said Software. + +## Article 3 - ACCEPTANCE + +The Licensee shall be deemed as having accepted the terms and conditions of this Agreement upon the occurrence of the first of the following events: + +- loading the Software by any or all means, notably, by downloading from a remote server; +- the first time the Licensee exercises any of the rights granted hereunder. + +## Article 4 - EFFECTIVE DATE AND TERM + +### 4.1 EFFECTIVE DATE + +The Agreement shall become effective on the date when it is accepted by the Licensee as set forth in Article 3. + +### 4.2 TERM + +The Agreement shall remain in force for the entire legal term of protection of the economic rights over the Software. + +## Article 5 - SCOPE OF RIGHTS GRANTED + +The Licensor hereby grants to the Licensee, who accepts, the following rights over the Software for the term of the Agreement, on the basis of the terms and conditions set forth hereinafter. + +### 5.1 RIGHT OF USE + +The Licensee is authorized to use the Software, without any limitation as to its fields of application, with it being hereinafter specified that this comprises: + +- permanent or temporary reproduction of all or part of the Software by any or all means and in any or all form. +- loading, displaying, running, or storing the Software on any or all medium. +- entitlement to observe, study or test its operation. + +### 5.2 RIGHT OF MODIFICATION + +The right of modification means the right to adapt, arrange, or make any or all modifications to the Software; being understood that such modifications of the Software shall results in a change of its functionalities and/or in an addition of functionalities to the Initial Software. + +Consequently to distribute a Modified Software according to the provision of section 5.3.2, the Licensee shall make exclusively significant modification as described above to the Software provided that it includes an explicit notice that it is the author of said modification and indicates the date of the creation thereof. + +### 5.3 RIGHT OF DISTRIBUTION + +In particular, the right of distribution includes the right to publish, transmit and communicate the Modified Software to the general public on any or all medium, and by any or all means, and the right to market, either in consideration of a fee, or + +#### 5.3.1 DISTRIBUTION OF SOFTWARE WITHOUT MODIFICATION + +The Licensee is forbidden to distribute true copies of the Software in Source Code or Object Code form. + +#### 5.3.2 DISTRIBUTION OF MODIFIED SOFTWARE + +When the Licensee creates Modified Software, this Modified Software may be distributed provided that said distribution complies with all the provisions of the Agreement and subject to compliance with the requirement to include a notice concerning the rights over the Software as defined in Article 6.3. + +In the event the creation of the Modified Software, the Licensee undertakes that: + +- the resulting Modified Software will be governed by this Agreement, being understood that such Agreement shall be integrated in the Modified Software the Integrated Contributions in the resulting Modified Software will be clearly identified and documented, +- the Licensee will allow effective access to the source code of the Modified Software, at a minimum during the entire period of distribution of the Derivative Software, such that such modifications may be carried over in a subsequent version of the Software. +- the Modified Software must be renamed to exclude any reference to 4D. For example, it is expressly prohibited to distribute a Modified Software named “4D SVG”; Licensee shall rename the Modified Software such as “Name of the Licensee SVG”. Consequently, Licensee is expressly forbidden to use 4D’s product name in general to promote his modified work. + +## Article 6 - INTELLECTUAL PROPERTY + +### 6.1 OVER THE INITIAL SOFTWARE + +The Holder owns the intellectual property rights over the Initial Software. Any or all use of the Initial Software is subject to compliance with the terms and conditions under which the Holder has elected to distribute its work and no one shall be entitled to modify the terms and conditions for the distribution of said Initial Software. + +### 6.2 OVER THE INTEGRATED CONTRIBUTIONS + +The Licensee who develops an Integrated Contribution is the owner of the intellectual property rights over this Contribution as defined by applicable law. + +### 6.3 NOTICE OF RIGHTS + +The Licensee expressly undertakes: + +- not to remove, or modify, in any manner, the intellectual property notices attached to the Software; +- to reproduce said notices, in an identical manner, in the copies of the Software modified; +- to ensure that use of the Software, its intellectual property notices and the fact that it is governed by the Agreement is indicated in a text that is easily accessible, specifically from the interface of any Modified Software. + +The Licensee undertakes not to directly or indirectly infringe the intellectual property rights of the Holder on the Software and to take, where applicable, vis- à-vis its staff, any and all measures required to ensure respect of said intellectual property rights of the Holder. + +## Article 7 - RELATED SERVICES + +Under no circumstances shall the Agreement oblige the Licensor to provide technical assistance or maintenance services for the Software. + +However, the Licensor is entitled to offer this type of services. The terms and conditions of such technical assistance, and/or such maintenance, shall be set forth in a separate instrument. + +## Article 8 - DISCLAIMER OF WARRANTY. + +THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE HOLDER PROVIDES THE SOFTWARE “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH LICENSEE. SHOULD THE SOFTWARE PROVE DEFECTIVE, LICENSEE ASSUMES THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +## Article 9 - LIMITATION OF LIABILITY + +TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE TO LICENSEE ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS AGREEMENT OR USE OF THE SOFTWARE, EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR DAMAGES. + +## Article 10 – TERMINATION + +### 10.1 + +In the event of a breach by the Licensee of its obligations hereunder, the Licensor may automatically terminate this Agreement thirty (30) days after notice has been sent to the Licensee and has remained ineffective. + +### 10.2 + +A Licensee whose Agreement is terminated shall no longer be authorized to use, modify or distribute the Software. However, any licenses that it may have granted prior to termination of the Agreement shall remain valid subject to their having been granted in compliance with the terms and conditions hereof. + +## Article 11 – MISCELLANEOUS + +### 11.1 + +Neither Party shall be liable for any or all delay, or failure to perform the Agreement, that may be attributable to an event of force majeure, an act of God or an outside cause, such as defective functioning or interruptions of the electricity or telecommunications networks, network paralysis following a virus attack, intervention by government authorities, natural disasters, water damage, earthquakes, fire, explosions, strikes and labor unrest, war, etc. + +### 11.2 + +Any failure by either Party, on one or more occasions, to invoke one or more of the provisions hereof, shall under no circumstances be interpreted as being a waiver by the interested Party of its right to invoke said provision(s) subsequently. + +### 11.3 + +In the event that one or more of the provisions hereof were to conflict with a current or future applicable act or legislative text, said act or legislative text shall prevail, and the Parties shall make the necessary amendments so as to comply with said act or legislative text. All other provisions shall remain effective. Similarly, invalidity of a provision of the Agreement, for any reason whatsoever, shall not cause the Agreement as a whole to be invalid. + +## Article 12 - GOVERNING LAW AND JURISDICTION + +### 12.1 + +The Agreement is governed by French law. The Parties agree to endeavor to seek an amicable solution to any disagreements or disputes that may arise during the performance of the Agreement. + +### 12.2 + +Failing an amicable solution within two (2) months as from their occurrence, and unless emergency proceedings are necessary, the disagreements or disputes shall be referred to the Versailles Courts having jurisdiction, by the more diligent Party. \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/overview.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/overview.md new file mode 100644 index 00000000000000..cf0a2bd93b1888 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/overview.md @@ -0,0 +1,211 @@ +--- +id: overview +title: 4D-Embedding-Studio +--- + +# 4D-Embedding-Studio + +## Vue d’ensemble + +4D Embedding Studio is a component for defining, processing, and maintaining AI embedding vectors directly in your 4D dataclass entities. + +You can use the component without writing a single line of code: select attributes from your dataclasses to construct the sentences to be vectorized and specify the model to use. For each entity, the component calls the embedding API and stores the resulting `4D.Vector` values. Configure the embedding scheduler to (re)calculate the vectors for your data at fixed intervals or on demand. + +You can then use the ORDA [`query()` by vector feature](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity) to request your data using semantics. + +If you want to have more control over your embeddings, the component offers an extensive API that allows you to customize each step of the data vectorization process, manage the scheduler, and integrate high-performance RAG (*Retrieval Augmented Generation*) features into your 4D application. + +## Conditions requises + +- [4D-AIKit](https://github.com/4d/4D-AIKit) (loaded automatically as a dependency). +- 4D project (21 R5 or later) with the following configuration: + - a valid model alias + - a dataclass with a `4D.Vector` attribute (object field at the database level). + +## Quick Start + +**1. Add a field of type Object to the table and associate it with the `4D.Vector` class.** +**2. Select **Embedding Studio...** in the **Design** menu to display the Embedding Studio window.** + +![menu](../assets/en/embedding-studio/menu.png) + +**3. For each listed `4D.Vector` attribute, write a descriptive phrase based upon attributes of the dataclass.** +Use the contextual menu to insert appropriate attributes. +This phrase will be vectorized for every entity. +**4. Select a model alias (or create a new one).** +**5. Select "Execute now" to launch the vectorization of your data or configure the scheduler.** + +## User Guide + +### Configuring the dataclass + +To use the 4D Embedding Studio interface, you need to create at least one object attribute associated to a `4D.Vector` class in your datastore. This must be done at the database level (only storage attributes can be embeddings). + +In the Structure editor, add an Object field to the dataclass (table) whose entities you want to query using AI and enter ["4D.Vector" as class](https://developer.4d.com/docs/Develop/structure-fields#class). + +#### Dirty-flag support + +In a production application, data is rarely static. If an embedding is based on an attribute value that has changed (e.g. a product description), it becomes obsolete and could no longer be relevant. By default, 4D automatically invalidates and flags for recalculation affected embeddings. + +If you do not use a dirty-flag field (see below), 4D simply replaces any invalidated vector by `Null`. It is therefore no longer used in searches until its next calculation. This option is suitable for applications that prioritize strict consistency: it is better to return no results than to rely on an embedding that no longer matches the current data. + +Or, you can add a Boolean field named `_dirty` (e.g. "myVector_dirty") to the structure. In this case, when an update is required, this field is set to `True`, and the associated vector is retained until it is recalculated. Your application can then choose to continue using this vector temporarily or exclude it using a filter on `dirty = False`. The flag is cleared automatically after a successful save. +This strategy promotes service continuity while allowing you to precisely identify vectors awaiting recalculation. If your business logic requires full control, you can also disable automatic invalidation and manage this lifecycle yourself. + +*Note: Certain modifications, such as a model changes, require vectors to be replaced immediately.* + +### Creating an embedding + +When you select **Embedding Studio...** in the **Design** menu, the Embedding Studio window is displayed. + +The list on the left side shows all `4D.Vector` class attributes defined in the datastore. You can add as many vector attributes as you want per dataclass. + +A check mark (✓) in the Dirty Flag column indicates that a [`_dirty` boolean field](#dirty-flag-support) is associated to the vector field. + +**Note:** Any change in the database structure will require that you restart the 4D application so that the 4D Embedding Studio lists up-to-date values. + +#### Writing a descriptive sentence + +To create or edit an embedding, select the attribute to configure in this list and write the embedding definition in the "Descriptive sentence" area on the right side. Use the associated menu to build the sentence and to add references to dataclass available attributes with the `{attribute_name}` syntax. + +The sentence must build a text that describes the entity just like a human would do it. The embedding could then capturate the semantics and not only attribute values. + +For example, for a `Product` dataclass with many attributes such as name and category, you could write: +"The {name} product is a {category} from the {brand} brand. Description: {description}. Key features: {features}." + +![menu](../assets/en/embedding-studio/studio-interface.png) + +### Selecting a model + +Once you have defined your vector attribute, choose the model to use for generating the embedding. The list of models includes the **model aliases** you defined in the [Project Settings](https://developer.4d.com/docs/settings/ai#model-aliases). + +The choice of model is important because it determines the relevance and quality of your embeddings. You’ll also need to provide this model with every query on the dataclass data so that the comparison is performed using the same model. + +### Auto-invalidate on save + +When this option is checked (default), embeddings are automatically invalidated when at least one of their definition attributes has been modified and the entity was successfully saved. + +However, you might want to handle invalidation in a custom way using the [4D Embedding Studio API](#api-guide). In this case, uncheck this option to disable the automatic mechanism. + +### Calculating embeddings + +Embeddings are calculated by sending a request to the AI model, which then returns the vectorization result, which is subsequently stored in the `4D.Vector` attribute in the dataclass. 4D automatically handles this operation and optimizes it by calculating only the necessary vectors. Each vector is processed independently. Thus, an error on one element does not interrupt the recalculation of the others. Elements that fail will be automatically retried during the next run. Recalculations are performed asynchronously, without blocking users. + +These calculations can be performed **on demand** or **scheduled at regular intervals** using the scheduler in the 4D Embedding Studio component. + +**Note:** You can also customize embedding calculations per dataclass or entity using the [4D Embedding Studio API](#api-guide). + +#### On demand + +To launch an embedding calculation, select **Run now** in the menu at the bottom of the 4D Embedding Studio window. This item is disabled if the datastore does not contain any embedding to calculate. When started, you can select **Cancel run** at any moment. + +#### Périodicité + +You can configure the 4D Embedding Studio component scheduler to adjust the calculation frequency to suit your application’s needs. + +**Important:** The scheduler needs a 4D worker process to run. You can start it manually for testing purposes (**Start now** button in the scheduler dialog box) but to make sure a worker is available every times the application opens, you need to configure it. Vous pouvez soit : + +- select the **Execute "On Host Database Event" method of the components** option in the [project Settings](https://developer.4d.com/docs/settings/security#options) +- or write the following code in your startup code: + +```4d + //at startup +cs.EmbeddingStudio.Scheduler.me.start() +``` + +The scheduler allows you can set the time interval between two calculations. Select the tab corresponding to your needs and click **Save**. + +- **Never**: the scheduler is off and never runs +- **At regular interval**: set the time interval between each calculation starting from a specified time. +- **Once a day**: the calculation takes place every day at a specific time + starting from a specific time. + +### Building queries with embeddings + +Once you have defined embeddings in your datastore, you can start [querying your dataclasses using AI-based features](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity). You just need to make sure that you use the same model for your embedding definition and in the query string. + +For example, assuming that: + +• you have defined a `4D.Vector` attribute named "product_vector" in the Products dataclass using a sentence: "The {name} is in the {category} category. It has these {features} features and can be used for {usage}." +• you want to find products that "can be used safely outside". + +Vous pouvez écrire : + +```4d +// Retrieve the model alias from the embedding definition, configured in 4D Embedding Studio +var $settings:=cs.EmbeddingStudio.Settings.new() +var $definition:=$settings.find("Products"; "product_vector") + +// Compute the vector of the query with the same model +var $result:=cs.EmbeddingStudio.StudioEmbedder.new().embed("products that can be used safely outside"; $definition) +var $vector:=$result.vector + + //search with default metric (cosine) +var $products:=ds.Products.query("product_vector > :1 order by product_vector desc"; {vector : $vector}) + +``` + +If you use a dirty field, simply add a criterion to exclude vectors waiting to be recalculated: + +```4d +var $products:=ds.Products.query("product_vector > :1 and product_vector_dirty = false order by product_vector desc"; {vector : $vector}) +``` + +## API Guide + +### Quick start + +**1. Configure your vectors** in `Settings/embeddings.json`: + +```json +{ + "batchSize": 50, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding", + "phrase": "Student {firstName} {lastName}, enrolled in {program}", + "autoInvalidate": true + } + ] +} +``` + +**2. Run the full pipeline** (all definitions, all records): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +var $r:=$p.process() + +If ($r.success) + ALERT("Updated "+String($r.entitiesUpdated)+" entities in "+String($r.duration)+" ms") +End if +``` + +**3. Process a single entity on save** (e.g. in a trigger or REST hook): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +$p.processEntity($entity) +``` + +### Class reference + +| Class | Description | +| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Process](Classes/Process.md) | Main orchestrator — entry point for all batch and entity operations. | +| [Scheduler](Classes/Scheduler.md) | Automated recalculation scheduler — background task, force/cancel, and runtime status. | +| [StudioEmbedder](Classes/StudioEmbedder.md) | Renders and embeds on demand using your saved definitions — e.g. to build a search query vector. Nothing is persisted. | +| [Settings](Classes/Settings.md) | Loads and saves the `embeddings.json` configuration file. | +| [Definition](Classes/Definition.md) | Describes one vector field: dataclass, field name, model alias, and phrase template. | +| [Embedder](Classes/Embedder.md) | Thin wrapper around the AIKit embeddings API with retry/backoff logic. | +| [EmbedderResult](Classes/EmbedderResult.md) | Typed wrapper normalizing API responses — vectors, usage metrics, rate-limit state. | +| [ProcessResult](Classes/ProcessResult.md) | Returned by every batch function — statistics and error breakdown. | +| [ProcessError](Classes/ProcessError.md) | Typed entry in `ProcessResult.errors` — scope, severity, code, ref, message, retryable. | +| [ProcessErrorCode](Classes/ProcessErrorCode.md) | Singleton catalogue of machine-readable error codes and their default severity/retryability. | +| [Phrase](Classes/Phrase.md) | Lightweight `{variable}` template engine used to build text from entity attributes. | + +### Voir également + +Blog post: [Vectorize your data effortlessly with 4D Embedding Studio](https://blog.4d.com/vectorize-your-data-effortlessly-with-4d-vector-studio) \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/ratelimit.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/ratelimit.md new file mode 100644 index 00000000000000..757cf6d3c79040 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/ratelimit.md @@ -0,0 +1,65 @@ +--- +id: ratelimit +title: Rate Limiting +--- + +# Rate Limiting + +The embedding pipeline includes built-in rate-limit awareness. When the API provider returns rate-limit headers (as OpenAI does), the system automatically throttles requests and adapts batch sizes to stay within budget. Providers that don't return rate-limit headers (e.g. Ollama) are unaffected — the pipeline runs at full speed. + +## Principes de fonctionnement + +Each call to [`Embedder.embed()`](Classes/Embedder.md) or [`Embedder.embedBatch()`](Classes/Embedder.md) returns an [`EmbedderResult`](Classes/EmbedderResult.md) that carries rate-limit state alongside the embedding vectors. The pipeline uses this data in a three-step loop: + +1. **Pre-flight throttle** — before sending a batch, the pipeline checks whether the remaining token budget is sufficient. If not, it waits for the reset window to elapse before proceeding. +2. **Adaptive batch sizing** — the pipeline computes the largest batch that fits within 80% of the remaining token budget. This avoids hitting the ceiling while still making efficient use of the quota. +3. **State update** — after each API response, the pipeline records the new remaining budget, computes an average tokens-per-entity estimate, and feeds both into the next iteration. + +## Rate-limit fields on EmbedderResult + +These fields are populated from the API response headers. When a provider doesn't return them, they keep their defaults and the pipeline skips throttling. + +| Champ | Par défaut | Description | +| ------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `remainingTokens` | `-1` | Tokens left in the current window. `-1` = unknown. | +| `remainingRequests` | `-1` | Requests left in the current window. | +| `limitTokens` | `0` | TPM (tokens per minute) ceiling. | +| `limitRequests` | `0` | RPM (requests per minute) ceiling. | +| `resetTokens` | `""` | Time until the token bucket refills (e.g. `"6m0s"`, `"200ms"`). | +| `resetRequests` | `""` | Time until the request bucket refills. | + +## Batch size adaptation + +The pipeline starts with the configured `batchSize` (from [Settings](Classes/Settings.md), default 50). After the first API response provides rate-limit data, the batch size may shrink: + +``` +nextBatchSize = min( floor(remainingTokens × 0.8 / tokensPerEntity), configBatchSize ) +``` + +- `tokensPerEntity` is estimated from the last chunk (`totalTokens / chunkSize`). +- The result is clamped to a floor of 1 and a ceiling of `configBatchSize`. +- When `remainingTokens` is unknown (`-1`), the configured batch size is used as-is. + +## Pre-flight wait + +Before each batch, the pipeline checks: + +- **Token budget**: if `remainingTokens < estimatedTokens × 1.1`, it waits for the token reset window. +- **Request budget**: if `remainingRequests = 0`, it waits for the request reset window. + +The reset durations are parsed from the API's string format (`"6m0s"` → 360 seconds, `"200ms"` → 1 second). + +## Providers without rate limits + +Some providers (Ollama, local models) don't return rate-limit headers. Dans ce cas : + +- `remainingTokens` stays at `-1` (unknown) +- No throttling occurs — batches run at `configBatchSize` without waits +- The pipeline works identically to how it did before rate-limit support was added + +## Voir également + +- [EmbedderResult](Classes/EmbedderResult.md) — carries rate-limit fields +- [Embedder](Classes/Embedder.md) — wraps the API calls +- [Process](Classes/Process.md) — orchestrates the batch loop +- [Settings](Classes/Settings.md) — `batchSize` configuration diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md index 1c468a6d38c898..d63a9565f5b3ad 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md @@ -790,7 +790,7 @@ Reportez-vous à l'exemple 2. **Valeurs possibles** : Entier positif. Valeur par défaut = 900, valeur minimale = 60. -**Description** : Délai en secondes pour les sessions client/serveur en cas de déconnexion inattendue lors de l'utilisation de la couche réseau QUIC. Ce délai est la période accordée à une session pendant laquelle la connexion entre le serveur et le client peut être rétablie automatiquement suite à une déconnexion involontaire. Si, à l'issue de ce délai, la connexion n'a pas été rétablie, la session est fermée. +**Description** : Délai en secondes pour les sessions client/serveur en cas de déconnexion inattendue lors de l'utilisation de la couche réseau QUIC. Ce délai est la période accordée à une session pendant laquelle la connexion entre le serveur et le client peut être rétablie automatiquement suite à une déconnexion involontaire. Si, à l'issue de ce délai, la connexion n'a pas été rétablie, la session client est fermée avec un message. Ce paramètre ne peut être défini que sur 4D Server et s'applique à toutes les nouvelles sessions distantes 4D (la valeur du délai des sessions existantes n'est pas modifiée). diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md index d58a8ab4195453..aa4748dfc5340b 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md @@ -45,6 +45,16 @@ Dans le paramètre optionnel *settings*, vous pouvez passer un objet contenant l | --------- | ---- | ---------------------------------------------------------------------------------------------------------------------- | | context | Text | Nom du [contexte d'optimisation](../../ORDA/client-server-optimization.md) appliqué à l'entity selection. | +:::info + +Pour des raisons de performance, en 4D monoposte et 4D Server, l'entity selection retournée est directement liée à la sélection courante de *dsTable* (il ne s'agit pas d'une copie). Tant que la sélection courante n'est pas remplacée, les modifications apportées à l'une sont répercutées dans l'autre. Par exemple, [`REDUCE SELECTION`](../commands/reduce-selection) réduit l'entity selection, et [`.add()`](../../API/EntitySelectionClass.md#add) appliquée à l'entity selection ajoute l'entité à la sélection courante. Pour obtenir une entity selection indépendante, appelez [`.copy()`](../../API/EntitySelectionClass.md#copy) sur le résultat : + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Exemple ```4d diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md index 857594055ae15f..ff7872f81a3f91 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md @@ -35,7 +35,7 @@ displayed_sidebar: docs Passez dans le paramètre *partie* le numéro de la partie à analyser. Vous pouvez obtenir le nombre total de parties à l’aide de la commande [WEB Get body part count](../commands/web-get-body-part-count). -Le paramètre *contenuParti*e récupère le contenu de la partie. Lorsque les parties à récupérer sont des fichiers, vous devez passer un paramètre de type BLOB. Dans le cas de variables TEXT postées dans un formulaire Web, vous pouvez passer un paramètre de type texte. +Le paramètre *contenuPartie* récupère le contenu de la partie. Lorsque les parties à récupérer sont des fichiers, vous devez passer un paramètre de type BLOB. Dans le cas de variables TEXT postées dans un formulaire Web, vous pouvez passer un paramètre de type texte. Le paramètre *nomPartie* récupère le nom de la variable du champ input HTTP. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/assets/en/Develop/index-add.png b/i18n/ja/docusaurus-plugin-content-docs/current/assets/en/Develop/index-add.png new file mode 100644 index 00000000000000..05e72c5f179854 Binary files /dev/null and b/i18n/ja/docusaurus-plugin-content-docs/current/assets/en/Develop/index-add.png differ diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Settings.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Settings.md new file mode 100644 index 00000000000000..cb8643648e3d68 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Settings.md @@ -0,0 +1,184 @@ +--- +id: settings +title: 設定 +--- + +# 設定 + +The `Settings` class is the persisted configuration for the embedding pipeline. It loads and saves a JSON file (default: `Settings/embeddings.json`, overridable with the `EMBEDDINGS_SETTINGS_PATH` environment variable) containing a list of [Definition](Definition.md) entries, a batch size, and phrase-validation options. + +## プロパティ + +| プロパティ名 | 型 | 説明 | +| ------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `definitions` | Collection of [Definition](Definition.md) | The configured definitions. | +| `batchSize` | Integer | Chunk size used by [Process.processEntitySelection](Process.md#processentityselection). Default: `50`. | +| `phrase` | Object | Phrase-validation options (see below). | +| `embedder` | Object | Optional embedder configuration (see below). | +| `file` | 4D.File *(read-only)* | The backing file the settings are loaded from and saved to. | + +### phrase options + +Passed verbatim to [Phrase.validate()](Phrase.md#validate) whenever the pipeline validates a definition. + +| フィールド | 型 | デフォルト | 説明 | +| ----------------- | ------- | ------- | ----------------------------------------------------------------------------------------------- | +| `allowRelations` | Boolean | `false` | Allow dot-notation through N:1 / 1:1 relations. | +| `allowCalculated` | Boolean | `false` | Allow calculated attributes in phrases. | +| `allowAlias` | Boolean | `false` | Allow alias attributes in phrases. | +| `allowObject` | Boolean | `false` | Allow object attributes in phrases. | + +> **Invalidation caveat.** Dirty-flag tracking only covers direct scalar fields on the entity. Fields that are only reachable through one of these options — a related entity's attribute, a calculated value, an alias, or a sub-property of an object — will **not** automatically mark the entity as dirty when they change. If such fields are part of a phrase and their source data changes, the vector will not be recomputed unless you call `invalidateVectors()` explicitly or use `force: true` when processing. + +### embedder options + +Controls how [Process](Process.md) builds its embedder. When absent, a default `Embedder` is created with its own defaults. + +| フィールド | 型 | デフォルト | 説明 | +| ------------ | ------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `className` | Text | — | Name of a project class to instantiate instead of the built-in `Embedder`. The class must expose `embed` and `embedBatch` functions. If instantiation fails or the interface is missing, a diagnostic error is logged and the default `Embedder` is used as fallback. | +| `maxRetries` | Integer | `3` | Number of retry attempts on rate-limit errors (forwarded to `Embedder`). | +| `backoffMs` | Integer | `500` | Base back-off delay in ms, doubled each retry (forwarded to `Embedder`). | + +Any additional keys are forwarded as-is to the constructor of the target class (built-in or custom). + +## ファイル形式 + +```json +{ + "batchSize": 50, + "phrase": { + "allowRelations": false, + "allowCalculated": false, + "allowAlias": false, + "allowObject": false + }, + "embedder": { + "maxRetries": 5, + "backoffMs": 200 + }, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding-3-small", + "phrase": "Student {firstName} {lastName}", + "autoInvalidate": true + } + ] +} +``` + +Each definition may include `autoInvalidate` (`true` by default) to control save-time automatic invalidation. + +The same file also carries the `scheduler` key (see [Scheduler](Scheduler.md#configuration)) and any other top-level key you add: `Settings` reads and rewrites only the keys listed above and leaves the rest untouched. + +With a custom embedder class: + +```json +{ + "embedder": { + "className": "MyCustomEmbedder" + }, + "definitions": [...] +} +``` + +## Class constructor + +Create a settings instance. The configuration file is loaded immediately. + +| 引数名 | 型 | 説明 | +| ------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *ファイル* | 4D.File | 任意。 A file to use instead of the default location. The override applies process-wide for subsequent settings access. **Not supported in 4D Remote mode** — pass it only when running locally or on the server. | + +When *file* is omitted, the default location is used: `Settings/embeddings.json`, or the path given by the `EMBEDDINGS_SETTINGS_PATH` environment variable. + +```4d +// Default location +var $settings:=cs.EmbeddingStudio.Settings.new() + +// Custom file (server / mono only) +var $settings:=cs.EmbeddingStudio.Settings.new(File("/some/path/custom.json")) +``` + +## 関数 + +### load() + +**load**() + +Reload the backing file into memory, overwriting in-memory state. A missing file resets to defaults without raising. + +A file that **exists but cannot be parsed** also leaves the instance on defaults, but it is remembered: an error is logged and [`save()`](#save) then refuses to write, so a malformed file is never silently replaced by defaults. + +### save() + +**save**() : Boolean + +Serialize the current in-memory state to the backing file. Only the keys this class owns (`batchSize`, `phrase`, `embedder`, `definitions`) are written — every other top-level key present in the file (the `scheduler` configuration, model aliases…) is preserved as-is. A key whose value is back to its default is *removed* from the file rather than written. + +Definitions are merged with what the file holds at that instant, using the snapshot taken at load time as the common ancestor: two editors open at the same time no longer drop each other's definitions. + +| 戻り値 | 型 | 説明 | +| --- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| 戻り値 | Boolean | `True` when written. `False` — nothing written — when the file could not be read at load time. | + +```4d +$settings.definitions.push(cs.EmbeddingStudio.Definition.new("Students"; "student_vector_1"; "text-embedding-3-small"; "{firstName}")) +$settings.batchSize:=100 +$settings.save() +``` + +### find() + +**find**(*dataclassName* : Text ; *vectorName* : Text) : [Definition](Definition.md) + +Look up the saved definition for the given dataclass/vector pair. + +| 引数 | 型 | 説明 | +| --------------- | --------------------------- | ------------------------------------------------------------------- | +| *dataclassName* | Text | データクラスの名称。 | +| *vectorName* | Text | Name of the vector field on that dataclass. | +| 戻り値 | [Definition](Definition.md) | The matching definition, or `Null` if none matches. | + +```4d +var $def:=$settings.find("Students"; "student_vector_1") +``` + +### findAll() + +**findAll**(*dataclassName* : Text) : Collection of [Definition](Definition.md) + +Return every saved definition configured for the given dataclass. + +| 引数 | 型 | 説明 | +| --------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------- | +| *dataclassName* | Text | データクラスの名称。 | +| 戻り値 | Collection of [Definition](Definition.md) | All matching definitions (empty collection if none match). | + +```4d +var $defs:=$settings.findAll("Students") +// → every Students definition; used by Process.process(ds.Students) +``` + +### invalidateVectors() + +**invalidateVectors**() : Object + +Calls [`invalidateVectors()`](Definition.md#invalidatevectors) on every definition in `definitions` and merges the results into a single status object. + +| 引数 | 型 | 説明 | +| --- | ------ | ------------------------------------------------------------------------------------------------------------------------ | +| 戻り値 | Object | `{updated: Integer, skipped: Integer, errors: Collection of Text}` — accumulated across all definitions. | + +```4d +var $result:=cs.EmbeddingStudio.Settings.new().invalidateVectors() +// → { updated: 120; skipped: 0; errors: [] } +``` + +## 参照 + +- [Definition](Definition.md) +- [Process](Process.md) +- [Phrase](Phrase.md) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/StudioEmbedder.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/StudioEmbedder.md new file mode 100644 index 00000000000000..02cd8721b57487 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/StudioEmbedder.md @@ -0,0 +1,125 @@ +--- +id: studioembedder +title: StudioEmbedder +--- + +# StudioEmbedder + +The `StudioEmbedder` class renders and embeds on demand, resolved against the Studio settings: a saved definition gives the phrase and the model, so the vector you compute matches the ones stored by [Process](Process.md). Nothing is persisted. Typical uses: building the vector of a search query, finding entities similar to a given one, or previewing the text sent for an entity. + +For the full batch pipeline that persists vectors on entities, see [Process](Process.md). + +## プロパティ + +| プロパティ名 | 型 | 説明 | +| ---------- | ----------------------- | ------------------------------------------------------------------------------------------------- | +| `設定` | [Settings](Settings.md) | The settings (vectors, batch size, phrase validation options). | +| `embedder` | [Embedder](Embedder.md) | The API-calling engine. Stateless and swappable. | +| `options` | Object | Runtime options object. | + +## Class constructor + +| 引数名 | 型 | 説明 | +| --------- | ----------------------- | ------------------------------------------------------------------------------------------------ | +| *設定* | [Settings](Settings.md) | 任意。 If omitted, settings are loaded from the default `Settings/embeddings.json`. | +| *options* | Object | Optional runtime options. Supports `embedder` for injection. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings) +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings; {embedder: $mockEmbedder}) +``` + +## 関数 + +### render() + +**render**(*entity* : 4D.Entity ; *definitionOrPhrase* : Variant) : Text + +Return the text that [`embed()`](#embed) sends for an entity (the phrase rendered against it). No API call, no persistence. + +| 引数 | 型 | 説明 | +| -------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *entity* | 4D.Entity | The entity to render against. | +| *definitionOrPhrase* | `Null`, [Phrase](Phrase.md), [Definition](Definition.md), Text, or plain object stub | `Null` → auto-resolve via settings (requires a unique match). Text → compiled as a throwaway `cs.EmbeddingStudio.Phrase`. Object stub → see [stub resolution](#stub-resolution). | +| 戻り値 | Text | The rendered text. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $text: Text +$text:=$studioEmbedder.render($student; $def) // use def's phrase +$text:=$studioEmbedder.render($student; cs.EmbeddingStudio.Phrase.new("Hi {firstName}")) +$text:=$studioEmbedder.render($student; "Student: {lastName}") // raw template +$text:=$studioEmbedder.render($student) // auto-resolve +$text:=$studioEmbedder.render($student; {vectorName: "student_vector_1"}) // stub → saved definition's phrase +$text:=$studioEmbedder.render($student; {phrase: "Hi {firstName}"}) // ad-hoc stub → inline template +``` + +### embed() + +**embed**(*input* : Variant ; *context* : Variant ; *model* : Text) : [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) + +Compute a vector for an arbitrary input, without persisting anywhere. + +| 引数 | 型 | 説明 | +| --------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| *input* | Text or 4D.Entity | Text → embedded directly. Entity → phrase rendered then embedded. | +| *context* | Text, [Phrase](Phrase.md), [Definition](Definition.md), Text template, plain object stub, or `Null` | Provides phrase and/or model depending on *input*. Object stub → see [stub resolution](#stub-resolution). | +| *model* | Text | Optional explicit model name. Used when *context* does not carry one. | +| 戻り値 | [EmbedderResult](EmbedderResult.md) | The embedding result (use `.vector` to get the 4D.Vector). | + +Throws if no model can be determined. + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $vector: 4D.Vector + +// Text + model +$vector:=$studioEmbedder.embed("some text"; "text-embedding-3-small").vector + +// Text + definition (picks up def.modelAlias) +$vector:=$studioEmbedder.embed("some text"; $def).vector + +// Entity + definition (uses def.phrase + def.modelAlias) +$vector:=$studioEmbedder.embed($student; $def).vector + +// Entity + phrase + explicit model +$vector:=$studioEmbedder.embed($student; $phrase; "text-embedding-3-small").vector + +// Entity + ad-hoc template + model +$vector:=$studioEmbedder.embed($student; "Profile: {firstName} {lastName}"; "text-embedding-3-small").vector + +// Entity alone (auto-resolve, only when exactly one def matches the dataclass) +$vector:=$studioEmbedder.embed($student).vector + +// Entity + stub (deduces phrase + model from the matching saved definition) +$vector:=$studioEmbedder.embed($student; {vectorName: "student_vector_1"}).vector + +// Entity + ad-hoc stub (phrase compiled inline, model taken from the stub) +$vector:=$studioEmbedder.embed($student; {phrase: "Hi {firstName}"; modelAlias: "text-embedding-3-small"}).vector + +// Text + stub that only supplies the model +$vector:=$studioEmbedder.embed("some text"; {modelAlias: "text-embedding-3-small"}).vector +``` + +## Stub resolution + +Both `render()` and `embed()` accept a plain object in place of a `Phrase`/`Definition`. A stub is resolved the same way [`Process`](Process.md#definition-resolution-entity-context) resolves its `definition` argument, so the behavior matches. Two flavors are supported: + +| Stub | Resolves to | +| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `{vectorName: "..."}` (optionally `{dataclassName: "..."}`) | The matching **saved definition** for the entity's dataclass — deducing its phrase (and, for `embed`, its model). Resolves to nothing when there is no unique match. | +| `{phrase: "tpl {field}"}` or `{template: "tpl {field}"}` | An **ad-hoc** `Phrase` compiled inline; nothing is looked up. Pair with `{modelAlias: "..."}` to give `embed()` a model. | + +For `embed()`, the model is deduced in this order: an explicit `{modelAlias}` on the stub → the model of a stub-matched saved definition → the *model* argument → the entity's unique definition. An explicit `{modelAlias}` always wins. + +Unlike [`Process.process()`](Process.md#process-resolution), a stub is **not** turned into a brand-new `Definition` from its fields — `StudioEmbedder` persists nothing, so use `{phrase}`/`{template}` for one-off templates. + +## 参照 + +- [Process](Process.md) +- [Settings](Settings.md) +- [Definition](Definition.md) +- [Embedder](Embedder.md) +- [EmbedderResult](EmbedderResult.md) +- [Phrase](Phrase.md) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/license.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/license.md new file mode 100644 index 00000000000000..8f6fc0dd2b5ffc --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/license.md @@ -0,0 +1,167 @@ +--- +id: license +title: SOFTWARE LICENSE AGREEMENT +--- + +# SOFTWARE LICENSE AGREEMENT + +## Preamble + +The purpose of this Software license agreement is to grant users the right to modify and re-use the software governed by this license. + +The exercising of this right is conditional upon the obligation to make /available to the community the modifications made to the source code of the software so as to contribute to its evolution. + +In consideration of access to the source code and the rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software's author, the holder of the economic rights, and the successive licensors only have limited liability. + +## Article 1 – DEFINITIONS + +***Agreement***: means this license agreement, and its possible subsequent versions and annexes. + +***Software***: means the software in its Object Code and/or Source Code form and, where applicable, its documentation, "as is" when the Licensee accepts the Agreement. + +***Initial Software***: means the Software in its Source Code and possibly its Object Code form and, where applicable, its documentation, "as is" when it is first distributed under the terms and conditions of the Agreement. + +***Modified Software***: means the Software modified by at least one Integrated Contribution. + +***Source Code***: means all the Software's instructions and program lines to which access is required so as to modify the Software. + +***Object Code***: means the binary files originating from the compilation of the Source Code. + +***Holder***: means the holder(s) of the economic rights over the Initial Software, in this case it is 4D SAS. + +***Licensee***: means the Software user(s) having accepted the Agreement. + +***Contributor***: means a Licensee having made at least one Integrated Contribution. + +***Licensor***: means the Holder, or any other individual or legal entity, who distributes the Software under the Agreement. + +***Integrated Contribution***: means new functions integrated into the Source Code by any or all Contributors. + +***Parties***: mean both the Licensee and the Licensor. + +These expressions may be used both in singular and plural form. + +## Article 2 - PURPOSE + +The purpose of the Agreement is the grant by the Licensor to the Licensee of a non-exclusive, transferable and worldwide license for the Software as set forth in Article 5 hereinafter for the whole term of the protection granted by the rights over said Software. + +## Article 3 - ACCEPTANCE + +The Licensee shall be deemed as having accepted the terms and conditions of this Agreement upon the occurrence of the first of the following events: + +- loading the Software by any or all means, notably, by downloading from a remote server; +- the first time the Licensee exercises any of the rights granted hereunder. + +## Article 4 - EFFECTIVE DATE AND TERM + +### 4.1 EFFECTIVE DATE + +The Agreement shall become effective on the date when it is accepted by the Licensee as set forth in Article 3. + +### 4.2 TERM + +The Agreement shall remain in force for the entire legal term of protection of the economic rights over the Software. + +## Article 5 - SCOPE OF RIGHTS GRANTED + +The Licensor hereby grants to the Licensee, who accepts, the following rights over the Software for the term of the Agreement, on the basis of the terms and conditions set forth hereinafter. + +### 5.1 RIGHT OF USE + +The Licensee is authorized to use the Software, without any limitation as to its fields of application, with it being hereinafter specified that this comprises: + +- permanent or temporary reproduction of all or part of the Software by any or all means and in any or all form. +- loading, displaying, running, or storing the Software on any or all medium. +- entitlement to observe, study or test its operation. + +### 5.2 RIGHT OF MODIFICATION + +The right of modification means the right to adapt, arrange, or make any or all modifications to the Software; being understood that such modifications of the Software shall results in a change of its functionalities and/or in an addition of functionalities to the Initial Software. + +Consequently to distribute a Modified Software according to the provision of section 5.3.2, the Licensee shall make exclusively significant modification as described above to the Software provided that it includes an explicit notice that it is the author of said modification and indicates the date of the creation thereof. + +### 5.3 RIGHT OF DISTRIBUTION + +In particular, the right of distribution includes the right to publish, transmit and communicate the Modified Software to the general public on any or all medium, and by any or all means, and the right to market, either in consideration of a fee, or + +#### 5.3.1 DISTRIBUTION OF SOFTWARE WITHOUT MODIFICATION + +The Licensee is forbidden to distribute true copies of the Software in Source Code or Object Code form. + +#### 5.3.2 DISTRIBUTION OF MODIFIED SOFTWARE + +When the Licensee creates Modified Software, this Modified Software may be distributed provided that said distribution complies with all the provisions of the Agreement and subject to compliance with the requirement to include a notice concerning the rights over the Software as defined in Article 6.3. + +In the event the creation of the Modified Software, the Licensee undertakes that: + +- the resulting Modified Software will be governed by this Agreement, being understood that such Agreement shall be integrated in the Modified Software the Integrated Contributions in the resulting Modified Software will be clearly identified and documented, +- the Licensee will allow effective access to the source code of the Modified Software, at a minimum during the entire period of distribution of the Derivative Software, such that such modifications may be carried over in a subsequent version of the Software. +- the Modified Software must be renamed to exclude any reference to 4D. For example, it is expressly prohibited to distribute a Modified Software named “4D SVG”; Licensee shall rename the Modified Software such as “Name of the Licensee SVG”. Consequently, Licensee is expressly forbidden to use 4D’s product name in general to promote his modified work. + +## Article 6 - INTELLECTUAL PROPERTY + +### 6.1 OVER THE INITIAL SOFTWARE + +The Holder owns the intellectual property rights over the Initial Software. Any or all use of the Initial Software is subject to compliance with the terms and conditions under which the Holder has elected to distribute its work and no one shall be entitled to modify the terms and conditions for the distribution of said Initial Software. + +### 6.2 OVER THE INTEGRATED CONTRIBUTIONS + +The Licensee who develops an Integrated Contribution is the owner of the intellectual property rights over this Contribution as defined by applicable law. + +### 6.3 NOTICE OF RIGHTS + +The Licensee expressly undertakes: + +- not to remove, or modify, in any manner, the intellectual property notices attached to the Software; +- to reproduce said notices, in an identical manner, in the copies of the Software modified; +- to ensure that use of the Software, its intellectual property notices and the fact that it is governed by the Agreement is indicated in a text that is easily accessible, specifically from the interface of any Modified Software. + +The Licensee undertakes not to directly or indirectly infringe the intellectual property rights of the Holder on the Software and to take, where applicable, vis- à-vis its staff, any and all measures required to ensure respect of said intellectual property rights of the Holder. + +## Article 7 - RELATED SERVICES + +Under no circumstances shall the Agreement oblige the Licensor to provide technical assistance or maintenance services for the Software. + +However, the Licensor is entitled to offer this type of services. The terms and conditions of such technical assistance, and/or such maintenance, shall be set forth in a separate instrument. + +## Article 8 - DISCLAIMER OF WARRANTY. + +THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE HOLDER PROVIDES THE SOFTWARE “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH LICENSEE. SHOULD THE SOFTWARE PROVE DEFECTIVE, LICENSEE ASSUMES THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +## Article 9 - LIMITATION OF LIABILITY + +TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE TO LICENSEE ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS AGREEMENT OR USE OF THE SOFTWARE, EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR DAMAGES. + +## Article 10 – TERMINATION + +### 10.1 + +In the event of a breach by the Licensee of its obligations hereunder, the Licensor may automatically terminate this Agreement thirty (30) days after notice has been sent to the Licensee and has remained ineffective. + +### 10.2 + +A Licensee whose Agreement is terminated shall no longer be authorized to use, modify or distribute the Software. However, any licenses that it may have granted prior to termination of the Agreement shall remain valid subject to their having been granted in compliance with the terms and conditions hereof. + +## Article 11 – MISCELLANEOUS + +### 11.1 + +Neither Party shall be liable for any or all delay, or failure to perform the Agreement, that may be attributable to an event of force majeure, an act of God or an outside cause, such as defective functioning or interruptions of the electricity or telecommunications networks, network paralysis following a virus attack, intervention by government authorities, natural disasters, water damage, earthquakes, fire, explosions, strikes and labor unrest, war, etc. + +### 11.2 + +Any failure by either Party, on one or more occasions, to invoke one or more of the provisions hereof, shall under no circumstances be interpreted as being a waiver by the interested Party of its right to invoke said provision(s) subsequently. + +### 11.3 + +In the event that one or more of the provisions hereof were to conflict with a current or future applicable act or legislative text, said act or legislative text shall prevail, and the Parties shall make the necessary amendments so as to comply with said act or legislative text. All other provisions shall remain effective. Similarly, invalidity of a provision of the Agreement, for any reason whatsoever, shall not cause the Agreement as a whole to be invalid. + +## Article 12 - GOVERNING LAW AND JURISDICTION + +### 12.1 + +The Agreement is governed by French law. The Parties agree to endeavor to seek an amicable solution to any disagreements or disputes that may arise during the performance of the Agreement. + +### 12.2 + +Failing an amicable solution within two (2) months as from their occurrence, and unless emergency proceedings are necessary, the disagreements or disputes shall be referred to the Versailles Courts having jurisdiction, by the more diligent Party. \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/overview.md new file mode 100644 index 00000000000000..9053d57312e94a --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/overview.md @@ -0,0 +1,211 @@ +--- +id: overview +title: 4D-Embedding-Studio +--- + +# 4D-Embedding-Studio + +## 概要 + +4D Embedding Studio is a component for defining, processing, and maintaining AI embedding vectors directly in your 4D dataclass entities. + +You can use the component without writing a single line of code: select attributes from your dataclasses to construct the sentences to be vectorized and specify the model to use. For each entity, the component calls the embedding API and stores the resulting `4D.Vector` values. Configure the embedding scheduler to (re)calculate the vectors for your data at fixed intervals or on demand. + +You can then use the ORDA [`query()` by vector feature](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity) to request your data using semantics. + +If you want to have more control over your embeddings, the component offers an extensive API that allows you to customize each step of the data vectorization process, manage the scheduler, and integrate high-performance RAG (*Retrieval Augmented Generation*) features into your 4D application. + +## 要件 + +- [4D-AIKit](https://github.com/4d/4D-AIKit) (loaded automatically as a dependency). +- 4D project (21 R5 or later) with the following configuration: + - a valid model alias + - a dataclass with a `4D.Vector` attribute (object field at the database level). + +## Quick Start + +**1. Add a field of type Object to the table and associate it with the `4D.Vector` class.** +**2. Select **Embedding Studio...** in the **Design** menu to display the Embedding Studio window.** + +![menu](../assets/en/embedding-studio/menu.png) + +**3. For each listed `4D.Vector` attribute, write a descriptive phrase based upon attributes of the dataclass.** +Use the contextual menu to insert appropriate attributes. +This phrase will be vectorized for every entity. +**4. Select a model alias (or create a new one).** +**5. Select "Execute now" to launch the vectorization of your data or configure the scheduler.** + +## User Guide + +### Configuring the dataclass + +To use the 4D Embedding Studio interface, you need to create at least one object attribute associated to a `4D.Vector` class in your datastore. This must be done at the database level (only storage attributes can be embeddings). + +In the Structure editor, add an Object field to the dataclass (table) whose entities you want to query using AI and enter ["4D.Vector" as class](https://developer.4d.com/docs/Develop/structure-fields#class). + +#### Dirty-flag support + +In a production application, data is rarely static. If an embedding is based on an attribute value that has changed (e.g. a product description), it becomes obsolete and could no longer be relevant. By default, 4D automatically invalidates and flags for recalculation affected embeddings. + +If you do not use a dirty-flag field (see below), 4D simply replaces any invalidated vector by `Null`. It is therefore no longer used in searches until its next calculation. This option is suitable for applications that prioritize strict consistency: it is better to return no results than to rely on an embedding that no longer matches the current data. + +Or, you can add a Boolean field named `_dirty` (e.g. "myVector_dirty") to the structure. In this case, when an update is required, this field is set to `True`, and the associated vector is retained until it is recalculated. Your application can then choose to continue using this vector temporarily or exclude it using a filter on `dirty = False`. The flag is cleared automatically after a successful save. +This strategy promotes service continuity while allowing you to precisely identify vectors awaiting recalculation. If your business logic requires full control, you can also disable automatic invalidation and manage this lifecycle yourself. + +*Note: Certain modifications, such as a model changes, require vectors to be replaced immediately.* + +### Creating an embedding + +When you select **Embedding Studio...** in the **Design** menu, the Embedding Studio window is displayed. + +The list on the left side shows all `4D.Vector` class attributes defined in the datastore. You can add as many vector attributes as you want per dataclass. + +A check mark (✓) in the Dirty Flag column indicates that a [`_dirty` boolean field](#dirty-flag-support) is associated to the vector field. + +**Note:** Any change in the database structure will require that you restart the 4D application so that the 4D Embedding Studio lists up-to-date values. + +#### Writing a descriptive sentence + +To create or edit an embedding, select the attribute to configure in this list and write the embedding definition in the "Descriptive sentence" area on the right side. Use the associated menu to build the sentence and to add references to dataclass available attributes with the `{attribute_name}` syntax. + +The sentence must build a text that describes the entity just like a human would do it. The embedding could then capturate the semantics and not only attribute values. + +For example, for a `Product` dataclass with many attributes such as name and category, you could write: +"The {name} product is a {category} from the {brand} brand. Description: {description}. Key features: {features}." + +![menu](../assets/en/embedding-studio/studio-interface.png) + +### Selecting a model + +Once you have defined your vector attribute, choose the model to use for generating the embedding. The list of models includes the **model aliases** you defined in the [Project Settings](https://developer.4d.com/docs/settings/ai#model-aliases). + +The choice of model is important because it determines the relevance and quality of your embeddings. You’ll also need to provide this model with every query on the dataclass data so that the comparison is performed using the same model. + +### Auto-invalidate on save + +When this option is checked (default), embeddings are automatically invalidated when at least one of their definition attributes has been modified and the entity was successfully saved. + +However, you might want to handle invalidation in a custom way using the [4D Embedding Studio API](#api-guide). In this case, uncheck this option to disable the automatic mechanism. + +### Calculating embeddings + +Embeddings are calculated by sending a request to the AI model, which then returns the vectorization result, which is subsequently stored in the `4D.Vector` attribute in the dataclass. 4D automatically handles this operation and optimizes it by calculating only the necessary vectors. Each vector is processed independently. Thus, an error on one element does not interrupt the recalculation of the others. Elements that fail will be automatically retried during the next run. Recalculations are performed asynchronously, without blocking users. + +These calculations can be performed **on demand** or **scheduled at regular intervals** using the scheduler in the 4D Embedding Studio component. + +**Note:** You can also customize embedding calculations per dataclass or entity using the [4D Embedding Studio API](#api-guide). + +#### On demand + +To launch an embedding calculation, select **Run now** in the menu at the bottom of the 4D Embedding Studio window. This item is disabled if the datastore does not contain any embedding to calculate. When started, you can select **Cancel run** at any moment. + +#### スケジューラー + +You can configure the 4D Embedding Studio component scheduler to adjust the calculation frequency to suit your application’s needs. + +**Important:** The scheduler needs a 4D worker process to run. You can start it manually for testing purposes (**Start now** button in the scheduler dialog box) but to make sure a worker is available every times the application opens, you need to configure it. これには、次の二つの方法があります: + +- select the **Execute "On Host Database Event" method of the components** option in the [project Settings](https://developer.4d.com/docs/settings/security#options) +- or write the following code in your startup code: + +```4d + //at startup +cs.EmbeddingStudio.Scheduler.me.start() +``` + +The scheduler allows you can set the time interval between two calculations. Select the tab corresponding to your needs and click **Save**. + +- **Never**: the scheduler is off and never runs +- **At regular interval**: set the time interval between each calculation starting from a specified time. +- **Once a day**: the calculation takes place every day at a specific time + starting from a specific time. + +### Building queries with embeddings + +Once you have defined embeddings in your datastore, you can start [querying your dataclasses using AI-based features](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity). You just need to make sure that you use the same model for your embedding definition and in the query string. + +For example, assuming that: + +• you have defined a `4D.Vector` attribute named "product_vector" in the Products dataclass using a sentence: "The {name} is in the {category} category. It has these {features} features and can be used for {usage}." +• you want to find products that "can be used safely outside". + +以下のように書くことができます: + +```4d +// Retrieve the model alias from the embedding definition, configured in 4D Embedding Studio +var $settings:=cs.EmbeddingStudio.Settings.new() +var $definition:=$settings.find("Products"; "product_vector") + +// Compute the vector of the query with the same model +var $result:=cs.EmbeddingStudio.StudioEmbedder.new().embed("products that can be used safely outside"; $definition) +var $vector:=$result.vector + + //search with default metric (cosine) +var $products:=ds.Products.query("product_vector > :1 order by product_vector desc"; {vector : $vector}) + +``` + +If you use a dirty field, simply add a criterion to exclude vectors waiting to be recalculated: + +```4d +var $products:=ds.Products.query("product_vector > :1 and product_vector_dirty = false order by product_vector desc"; {vector : $vector}) +``` + +## API Guide + +### Quick start + +**1. Configure your vectors** in `Settings/embeddings.json`: + +```json +{ + "batchSize": 50, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding", + "phrase": "Student {firstName} {lastName}, enrolled in {program}", + "autoInvalidate": true + } + ] +} +``` + +**2. Run the full pipeline** (all definitions, all records): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +var $r:=$p.process() + +If ($r.success) + ALERT("Updated "+String($r.entitiesUpdated)+" entities in "+String($r.duration)+" ms") +End if +``` + +**3. Process a single entity on save** (e.g. in a trigger or REST hook): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +$p.processEntity($entity) +``` + +### Class reference + +| Class | 説明 | +| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Process](Classes/Process.md) | Main orchestrator — entry point for all batch and entity operations. | +| [Scheduler](Classes/Scheduler.md) | Automated recalculation scheduler — background task, force/cancel, and runtime status. | +| [StudioEmbedder](Classes/StudioEmbedder.md) | Renders and embeds on demand using your saved definitions — e.g. to build a search query vector. Nothing is persisted. | +| [Settings](Classes/Settings.md) | Loads and saves the `embeddings.json` configuration file. | +| [Definition](Classes/Definition.md) | Describes one vector field: dataclass, field name, model alias, and phrase template. | +| [Embedder](Classes/Embedder.md) | Thin wrapper around the AIKit embeddings API with retry/backoff logic. | +| [EmbedderResult](Classes/EmbedderResult.md) | Typed wrapper normalizing API responses — vectors, usage metrics, rate-limit state. | +| [ProcessResult](Classes/ProcessResult.md) | Returned by every batch function — statistics and error breakdown. | +| [ProcessError](Classes/ProcessError.md) | Typed entry in `ProcessResult.errors` — scope, severity, code, ref, message, retryable. | +| [ProcessErrorCode](Classes/ProcessErrorCode.md) | Singleton catalogue of machine-readable error codes and their default severity/retryability. | +| [Phrase](Classes/Phrase.md) | Lightweight `{variable}` template engine used to build text from entity attributes. | + +### 参照 + +Blog post: [Vectorize your data effortlessly with 4D Embedding Studio](https://blog.4d.com/vectorize-your-data-effortlessly-with-4d-vector-studio) \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/ratelimit.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/ratelimit.md new file mode 100644 index 00000000000000..00f50ec3d2bb7d --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/ratelimit.md @@ -0,0 +1,65 @@ +--- +id: ratelimit +title: Rate Limiting +--- + +# Rate Limiting + +The embedding pipeline includes built-in rate-limit awareness. When the API provider returns rate-limit headers (as OpenAI does), the system automatically throttles requests and adapts batch sizes to stay within budget. Providers that don't return rate-limit headers (e.g. Ollama) are unaffected — the pipeline runs at full speed. + +## 動作 + +Each call to [`Embedder.embed()`](Classes/Embedder.md) or [`Embedder.embedBatch()`](Classes/Embedder.md) returns an [`EmbedderResult`](Classes/EmbedderResult.md) that carries rate-limit state alongside the embedding vectors. The pipeline uses this data in a three-step loop: + +1. **Pre-flight throttle** — before sending a batch, the pipeline checks whether the remaining token budget is sufficient. If not, it waits for the reset window to elapse before proceeding. +2. **Adaptive batch sizing** — the pipeline computes the largest batch that fits within 80% of the remaining token budget. This avoids hitting the ceiling while still making efficient use of the quota. +3. **State update** — after each API response, the pipeline records the new remaining budget, computes an average tokens-per-entity estimate, and feeds both into the next iteration. + +## Rate-limit fields on EmbedderResult + +These fields are populated from the API response headers. When a provider doesn't return them, they keep their defaults and the pipeline skips throttling. + +| フィールド | デフォルト | 意味 | +| ------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `remainingTokens` | `-1` | Tokens left in the current window. `-1` = unknown. | +| `remainingRequests` | `-1` | Requests left in the current window. | +| `limitTokens` | `0` | TPM (tokens per minute) ceiling. | +| `limitRequests` | `0` | RPM (requests per minute) ceiling. | +| `resetTokens` | `""` | Time until the token bucket refills (e.g. `"6m0s"`, `"200ms"`). | +| `resetRequests` | `""` | Time until the request bucket refills. | + +## Batch size adaptation + +The pipeline starts with the configured `batchSize` (from [Settings](Classes/Settings.md), default 50). After the first API response provides rate-limit data, the batch size may shrink: + +``` +nextBatchSize = min( floor(remainingTokens × 0.8 / tokensPerEntity), configBatchSize ) +``` + +- `tokensPerEntity` is estimated from the last chunk (`totalTokens / chunkSize`). +- The result is clamped to a floor of 1 and a ceiling of `configBatchSize`. +- When `remainingTokens` is unknown (`-1`), the configured batch size is used as-is. + +## Pre-flight wait + +Before each batch, the pipeline checks: + +- **Token budget**: if `remainingTokens < estimatedTokens × 1.1`, it waits for the token reset window. +- **Request budget**: if `remainingRequests = 0`, it waits for the request reset window. + +The reset durations are parsed from the API's string format (`"6m0s"` → 360 seconds, `"200ms"` → 1 second). + +## Providers without rate limits + +Some providers (Ollama, local models) don't return rate-limit headers. この場合において: + +- `remainingTokens` stays at `-1` (unknown) +- No throttling occurs — batches run at `configBatchSize` without waits +- The pipeline works identically to how it did before rate-limit support was added + +## 参照 + +- [EmbedderResult](Classes/EmbedderResult.md) — carries rate-limit fields +- [Embedder](Classes/Embedder.md) — wraps the API calls +- [Process](Classes/Process.md) — orchestrates the batch loop +- [Settings](Classes/Settings.md) — `batchSize` configuration diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md b/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md index f10aa51e0cb74d..70b24c93bea689 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md @@ -791,7 +791,7 @@ QUERY BY FORMULA Joinsセレクタで、カレントプロセスの、フォー **取り得る値**: 正の整数。デフォルト値 = 900、最小値 = 60。 -**説明**: QUICネットワーク層を使用した場合に、予期しない切断が発生した際のクライアント/サーバーセッションのタイムアウト秒数。このタイムアウトは、意図しない切断の後にサーバーとクライアント間の接続が自動的に再確立できるセッションの許容期間です。このタイムアウト終了時に接続が再確立されていない場合、セッションは閉じられます。 +**説明**: QUICネットワーク層を使用した場合に、予期しない切断が発生した際のクライアント/サーバーセッションのタイムアウト秒数。このタイムアウトは、意図しない切断の後にサーバーとクライアント間の接続が自動的に再確立できるセッションの許容期間です。このタイムアウト終了時に接続が再確立されていない場合、クライアントセッションはメッセージとともに閉じられます。 この設定は4D Server上でのみ設定可能であり、すべての新しい4Dリモートセッションに適用されます(既存のセッションのタイムアウト値は変更されません)。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md b/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md index ea690f520386d0..0a98160da94d8e 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md @@ -32,7 +32,7 @@ displayed_sidebar: docs **FORM Get current page**コマンドは、現在表示されているフォームページ、または[FORM LOAD](../commands/form-load) コマンドによってロードされたカレントフォームの番号を返します。 -*\** 引数は、複数のページを含むサブフォームタイプのページのコンテキストでコマンドが呼び出される場合に使用します。この場合、この引数を渡すと、コマンドは (コマンドを呼び出した) カレントサブフォームのページを変更します。*\** が省略された場合、デフォルトでコマンドは常に親フォームに適用されます。 +*\** 引数は、複数のページを含むサブフォームタイプのページのコンテキストでコマンドが呼び出される場合に使用します。この場合、この引数を渡すと、コマンドは (コマンドを呼び出した) カレントサブフォームのページ番号を返します。*\** が省略された場合、デフォルトでコマンドは常に親フォームに適用されます。 ## 例題 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md b/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md index bd03ee2ebd814e..48b333bdbca799 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md @@ -45,6 +45,16 @@ displayed_sidebar: docs | ------- | ---- | ----------------------------------------------------------------------------- | | context | Text | エンティティセレクションに適用されている [最適化コンテキスト](../../ORDA/client-server-optimization.md) のラベル。 | +:::info + +パフォーマンス上の理由から、4D シングルユーザーおよび 4D Server では、返されるエンティティセレクションは *dsTable* のカレントセレクションに直接接続されています (コピーではありません)。 カレントセレクションが置き換えられるまでは、一方に加えた変更がもう一方にも反映されます。 たとえば、[`REDUCE SELECTION`](../commands/reduce-selection) はエンティティセレクションを縮小し、エンティティセレクションに対する [`.add()`](../../API/EntitySelectionClass.md#add) はカレントセレクションにエンティティを追加します。 独立したエンティティセレクションを取得するには、戻り値に対して [`.copy()`](../../API/EntitySelectionClass.md#copy) を呼び出します: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## 例題 ```4d diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md index 9ec35e99dda62c..f4efeb2fc70d53 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md @@ -789,7 +789,7 @@ QUERY BY FORMULA Joinsセレクタで、カレントプロセスの、フォー **取り得る値**: 正の整数。デフォルト値 = 900、最小値 = 60。 -**説明**: QUICネットワーク層を使用した場合に、予期しない切断が発生した際のクライアント/サーバーセッションのタイムアウト秒数。このタイムアウトは、意図しない切断の後にサーバーとクライアント間の接続が自動的に再確立できるセッションの許容期間です。このタイムアウト終了時に接続が再確立されていない場合、セッションは閉じられます。 +**説明**: QUICネットワーク層を使用した場合に、予期しない切断が発生した際のクライアント/サーバーセッションのタイムアウト秒数。このタイムアウトは、意図しない切断の後にサーバーとクライアント間の接続が自動的に再確立できるセッションの許容期間です。このタイムアウト終了時に接続が再確立されていない場合、クライアントセッションはメッセージとともに閉じられます。 この設定は4D Server上でのみ設定可能であり、すべての新しい4Dリモートセッションに適用されます(既存のセッションのタイムアウト値は変更されません)。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md index ea690f520386d0..0a98160da94d8e 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md @@ -32,7 +32,7 @@ displayed_sidebar: docs **FORM Get current page**コマンドは、現在表示されているフォームページ、または[FORM LOAD](../commands/form-load) コマンドによってロードされたカレントフォームの番号を返します。 -*\** 引数は、複数のページを含むサブフォームタイプのページのコンテキストでコマンドが呼び出される場合に使用します。この場合、この引数を渡すと、コマンドは (コマンドを呼び出した) カレントサブフォームのページを変更します。*\** が省略された場合、デフォルトでコマンドは常に親フォームに適用されます。 +*\** 引数は、複数のページを含むサブフォームタイプのページのコンテキストでコマンドが呼び出される場合に使用します。この場合、この引数を渡すと、コマンドは (コマンドを呼び出した) カレントサブフォームのページ番号を返します。*\** が省略された場合、デフォルトでコマンドは常に親フォームに適用されます。 ## 例題 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md index bd03ee2ebd814e..48b333bdbca799 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md @@ -45,6 +45,16 @@ displayed_sidebar: docs | ------- | ---- | ----------------------------------------------------------------------------- | | context | Text | エンティティセレクションに適用されている [最適化コンテキスト](../../ORDA/client-server-optimization.md) のラベル。 | +:::info + +パフォーマンス上の理由から、4D シングルユーザーおよび 4D Server では、返されるエンティティセレクションは *dsTable* のカレントセレクションに直接接続されています (コピーではありません)。 カレントセレクションが置き換えられるまでは、一方に加えた変更がもう一方にも反映されます。 たとえば、[`REDUCE SELECTION`](../commands/reduce-selection) はエンティティセレクションを縮小し、エンティティセレクションに対する [`.add()`](../../API/EntitySelectionClass.md#add) はカレントセレクションにエンティティを追加します。 独立したエンティティセレクションを取得するには、戻り値に対して [`.copy()`](../../API/EntitySelectionClass.md#copy) を呼び出します: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## 例題 ```4d diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/menu.png b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/menu.png new file mode 100644 index 00000000000000..425fd0d7e65879 Binary files /dev/null and b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/menu.png differ diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/studio-interface.png b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/studio-interface.png new file mode 100644 index 00000000000000..75dae7c9303297 Binary files /dev/null and b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/assets/en/embedding-studio/studio-interface.png differ diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Definition.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Definition.md new file mode 100644 index 00000000000000..6b29b5b7376cff --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Definition.md @@ -0,0 +1,165 @@ +--- +id: definition +title: 定義 +--- + +# 定義 + +The `Definition` class describes how a single vector field on a dataclass should be computed: which dataclass, which vector field, which model alias, and which text template ([Phrase](Phrase.md)) to render from each entity. + +A collection of these is what [Settings](Settings.md) persists. + +## プロパティ + +| プロパティ名 | 型 | 説明 | +| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| `dataclassName` | Text | Name of the target dataclass. | +| `vectorName` | Text | Name of the `4D.Vector` field on that dataclass. | +| `modelAlias` | Text | Embedding model alias (e.g. `"text-embedding-3-small"`). | +| `phrase` | [Phrase](Phrase.md) | Compiled template used to build the text that will be embedded. | +| `autoInvalidate` | Boolean | Controls automatic invalidation on entity save. Default: `True`. | + +## Class constructor + +Create a definition. + +| 引数名 | 型 | 説明 | +| ---------------- | ---- | -------------------------------------------------------------------------------------------------- | +| *dataclassName* | Text | Name of the target dataclass. | +| *vectorName* | Text | Name of the target vector field. | +| *modelAlias* | Text | Embedding model alias. | +| *phraseTemplate* | Text | Phrase template with `{field}` placeholders — compiled into a [Phrase](Phrase.md). | + +```4d +var $def:=cs.EmbeddingStudio.Definition.new(\ + "Students"; \ + "student_vector_1"; \ + "text-embedding-3-small"; \ + "Student {firstName} {lastName}") +``` + +## 計算プロパティ + +### hasDefinition + +**hasDefinition** : Boolean *(read-only)* + +Returns `True` if at least a model or a phrase template has been set. A definition without either has no content to process. + +```4d +If ($def.hasDefinition) + // worth validating further +End if +``` + +## 関数 + +### validate() + +**validate**( *settings* : Settings ) : Object + +Validates the definition against the live datastore model and the known embedding models. All errors are collected before returning — the result always describes the full set of problems found. + +| 引数 | 型 | 説明 | +| ---- | ------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| *設定* | [Settings](Settings.md) \| Null | Used to pass phrase validation options. Pass `Null` to skip phrase options. | +| 戻り値 | Object | `{success: Boolean, errors: Collection}` where each error is `{field: Text, message: Text}`. | + +Checked in order: + +| Check | `field` value | +| ------------------------------------ | ----------------- | +| `dataclassName` is not empty | `"dataclassName"` | +| `vectorName` is not empty | `"vectorName"` | +| `modelAlias` is set and recognised | `"modelAlias"` | +| Dataclass exists in `ds` | `"dataclassName"` | +| Vector field exists | `"vectorName"` | +| Field type is `4D.Vector` | `"vectorName"` | +| Phrase template is not empty | `"phrase"` | +| Phrase keys resolve in the dataclass | `"phrase"` | + +The first two checks (identity) return immediately on failure; the remaining checks accumulate so all problems are reported in one pass. + +```4d +var $result:=$def.validate(cs.EmbeddingStudio.Settings.new()) + +If (Not($result.success)) + var $err : Object + For each ($err; $result.errors) + TRACE // $err.field, $err.message + End for each +End if +``` + +### invalidateVectors() + +**invalidateVectors**() : Object + +Marks all already-computed entities for re-embedding, forcing a full rebuild on the next run. Only entities that already have a vector value are processed — entities with a `Null` vector are skipped. + +Useful during development or after a model/phrase change to trigger a clean rebuild of all vectors. + +The strategy depends on whether a companion `_dirty` field exists on the dataclass: + +| Companion `_dirty` field | Action taken | +| ------------------------ | -------------------------------------------------------------- | +| Present | Sets `_dirty` to `True` — vector is left untouched | +| Absent | Nullifies the vector field | + +| 引数 | 型 | 説明 | +| --- | ------ | ------------------------------------------------------------------ | +| 戻り値 | Object | `{updated: Integer, skipped: Integer, errors: Collection of Text}` | + +- `updated` — number of entities successfully marked +- `skipped` — number of entities that could not be saved +- `errors` — one entry per save failure, formatted as `"DataclassName: statusText"` + +```4d +var $result:=$def.invalidateVectors() + +If ($result.skipped > 0) + var $e : Text + For each ($e; $result.errors) + // $e + End for each +End if +// → { updated: 42; skipped: 0; errors: [] } +``` + +### toObject() + +**toObject**() : Object + +Returns a plain object suitable for JSON persistence. The phrase is flattened to its template text. + +| 引数 | 型 | 説明 | +| --- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | +| 戻り値 | Object | `{version, dataclassName, vectorName, modelAlias, phrase, autoInvalidate}` where `phrase` is the template string. | + +```4d +$def.toObject() +// → { version: 0; dataclassName: "Students"; vectorName: "student_vector_1"; +// modelAlias: "text-embedding-3-small"; phrase: "Student {firstName} {lastName}"; +// autoInvalidate: true } +``` + +## Automatic invalidation + +`autoInvalidate` controls whether save-time automatic invalidation is enabled for this definition. + +- `True` (default): when relevant attributes change on an entity save, vectors are automatically invalidated. +- `False`: save-time automatic invalidation is skipped for this definition. + +This setting does not affect manual invalidation via `invalidateVectors()`. + +## Dirty flag convention + +The pipeline in [Process](Process.md) will recompute an entity whenever the target vector is `Null`, or when a sibling field `_dirty` exists on the dataclass and is `True`. + +Declaring the dirty flag is optional — when absent, only the null-vector case triggers recomputation. When present, it is cleared automatically on successful save. + +## 参照 + +- [Settings](Settings.md) +- [Process](Process.md) +- [Phrase](Phrase.md) diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Embedder.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Embedder.md new file mode 100644 index 00000000000000..1d0f1ae886f748 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Embedder.md @@ -0,0 +1,96 @@ +--- +id: embedder +title: Embedder +--- + +# Embedder + +The `Embedder` class is a thin wrapper around [4D AIKit](https://developer.4d.com/docs/aikit/Classes/openai) focused on embeddings. It exposes two functions — one for a single text, one for a batch — and handles retries with exponential backoff (respecting the `Retry-After` header when present). + +It is stateless beyond configuration and safe to share between processes. + +## プロパティ + +| プロパティ名 | 型 | 説明 | +| ------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `client` | cs.AIKit.OpenAI | The underlying AIKit client used for HTTP requests. | +| `maxRetries` | Integer | Maximum number of retries on transient errors. Default: `3`. | +| `backoffMs` | Integer | Base delay (ms) between retries. Doubled each attempt. | + +## Class constructor + +Create a embedder. All options are optional. + +| 引数名 | 型 | 説明 | +| --------- | ------ | ----------------------------------------------------------------------------- | +| *options* | Object | `{client, maxRetries, backoffMs}` — any field may be omitted. | + +```4d +// Default — uses cs.AIKit.OpenAI.new() internally +var $proc:=cs.EmbeddingStudio.Embedder.new() + +// Provide a pre-configured AIKit client (custom API key, base URL, etc.) +var $client:=cs.AIKit.OpenAI.new({apiKey: "…"; baseURL: "https://server.ai"}) +var $proc:=cs.EmbeddingStudio.Embedder.new({client: $client; maxRetries: 5; backoffMs: 1000}) +``` + +> If the 4D AIKit component is not loaded (or is too old to provide `OpenAIProviders`), the constructor still succeeds with a `Null` client, and the first `embed()` / `embedBatch()` call throws an error whose `message` explains what is missing and whose `isAIKitMissing` property is `True`. + +## 関数 + +### embed() + +**embed**(*text* : Text ; *model* : Text) : [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) + +Embed a single text. Returns a typed result with the embedding vector, token usage, and rate-limit state. + +| 引数 | 型 | 説明 | +| ------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| *テキスト* | Text | The text to vectorize. | +| *model* | Text | The embedding model to use (e.g. `"text-embedding-3-small"`). | +| 戻り値 | [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) | Typed wrapper — `.vector` holds the embedding, `.promptTokens` / `.totalTokens` hold usage, rate-limit fields are flat camelCase. | + +Throws if retries are exhausted or the API returns a non-retryable error. + +```4d +var $result:=$proc.embed("it rains cats and dogs"; "text-embedding-3-small") +// $result.vector → 4D.Vector +// $result.promptTokens → Integer +// $result.totalTokens → Integer +// $result.remainingTokens → Integer (-1 if unknown) +``` + +### embedBatch() + +**embedBatch**(*texts* : Collection ; *model* : Text) : [cs.EmbedderResult](EmbedderResult.md) + +Embed a collection of texts in a single API call. Returns a typed result with vectors in the same order as inputs, token usage, and rate-limit state. + +| 引数 | 型 | 説明 | +| ------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | +| *texts* | Collection | Collection of Text to vectorize. Empty or `Null` returns an empty result. | +| *model* | Text | The embedding model to use. | +| 戻り値 | [cs.EmbedderResult](EmbedderResult.md) | Typed wrapper — `.vectors` holds the embeddings collection, token and rate-limit fields are flat camelCase. | + +```4d +var $result:=$proc.embedBatch(["hello"; "world"]; "text-embedding-3-small") +// $result.vectors[0] → 4D.Vector for "hello" +// $result.vectors[1] → 4D.Vector for "world" +// $result.totalTokens → Integer (sum for the batch) +// $result.remainingTokens → Integer (after this call) +``` + +## Retry policy + +Transient errors (HTTP 408, 409, 429, 5xx) are retried up to `maxRetries` times. + +- If the response carries a `Retry-After` or `retry-after-ms` header, the embedder waits that long. +- Otherwise, it waits `backoffMs * 2^attempt`. + +Non-retryable errors are thrown immediately — see [OpenAIError](https://developer.4d.com/docs/aikit/Classes/openaierror) for the thrown shape. + +## 参照 + +- [EmbedderResult](EmbedderResult.md) +- [Process](Process.md) +- [OpenAIEmbeddingsAPI](https://developer.4d.com/docs/aikit/Classes/openaiembeddingsapi) (AIKit) diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/EmbedderResult.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/EmbedderResult.md new file mode 100644 index 00000000000000..c2c44f170ee6e7 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/EmbedderResult.md @@ -0,0 +1,80 @@ +--- +id: embedderresult +title: EmbedderResult +--- + +# EmbedderResult + +Typed wrapper for `Embedder.embed()` and `Embedder.embedBatch()` responses. Normalizes OpenAI's snake_case API keys (`prompt_tokens`, `total_tokens`) to camelCase properties, and flattens the nested rate-limit structure into direct properties. + +A single class handles both single and batch results — `embed()` populates `.vector`, `embedBatch()` populates `.vectors`. + +## プロパティ + +### Embedding results + +| プロパティ | 型 | デフォルト | 説明 | +| --------- | ------------------------- | ----- | ------------------------------------------------------------------------------ | +| `vector` | 4D.Vector | Null | Single embedding result. Null for batch calls. | +| `vectors` | Collection | `[]` | Batch embedding results. | + +### Token usage + +| プロパティ | 型 | デフォルト | 説明 | +| -------------- | ------- | ----- | -------------------------------------------------------------------- | +| `promptTokens` | Integer | `0` | Input tokens consumed. | +| `totalTokens` | Integer | `0` | Total tokens consumed (in + out). | + +### Rate-limit state + +| プロパティ | 型 | デフォルト | 説明 | +| ------------------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------- | +| `remainingTokens` | Integer | `-1` | Tokens left in the current window. `-1` = unknown. | +| `remainingRequests` | Integer | `-1` | Requests left in the current window. `-1` = unknown. | +| `limitTokens` | Integer | `0` | TPM ceiling for the account. | +| `limitRequests` | Integer | `0` | RPM ceiling for the account. | +| `resetTokens` | Text | `""` | Time until token bucket refills (e.g. `"6m0s"`). | +| `resetRequests` | Text | `""` | Time until request bucket refills (e.g. `"1s"`). | + +## Class constructor + +```4d +// From a real API result (used by Embedder internally) +var $result:=cs.EmbedderResult.new($aikitResult; True) // batch +var $result:=cs.EmbedderResult.new($aikitResult; False) // single + +// Empty result (no API call — e.g. empty batch) +var $result:=cs.EmbedderResult.new() +``` + +| 引数 | 型 | 説明 | +| --------- | ------- | ------------------------------------------------------------------------------------------------------------ | +| *実行結果* | Object | An object with `.vector`/`.vectors`, `.usage`, `.rateLimit` (duck-typed). | +| *isBatch* | Boolean | `True` to read `.vectors`, `False` to read `.vector`. | + +The constructor accepts any object that exposes the expected shape — it does not require a specific class. This makes it easy to construct in tests. + +## 効果 + +```4d +// Single embedding +var $r:=$embedder.embed("hello world"; "text-embedding-3-small") +$r.vector // → 4D.Vector +$r.promptTokens // → 6 +$r.totalTokens // → 6 + +// Batch embedding +var $r:=$embedder.embedBatch(["hello"; "world"]; "text-embedding-3-small") +$r.vectors.length // → 2 +$r.totalTokens // → 10 + +// Rate-limit awareness +$r.remainingTokens // → 148230 (or -1 if not yet known) +$r.resetTokens // → "6m0s" +``` + +## 参照 + +- [Embedder](Embedder.md) — creates EmbedderResult instances +- [ProcessResult](ProcessResult.md) — run-level report that accumulates EmbedderResult usage +- [Rate Limiting](../RateLimit.md) — how the pipeline uses rate-limit fields for throttling and batch sizing diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Phrase.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Phrase.md new file mode 100644 index 00000000000000..151bec7cb2c351 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Phrase.md @@ -0,0 +1,117 @@ +--- +id: phrase +title: Phrase +--- + +# Phrase + +The `Phrase` class is a lightweight template engine: a template with `{variable}` placeholders is compiled once, then rendered efficiently against different data objects. + +## プロパティ + +| プロパティ名 | 型 | 説明 | +| ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- | +| `template` | Text | Computed — returns the original template string. | +| `keys` | Collection | Computed — returns the variable names found in the template, dot-notation keys joined back to strings. | + +## Class constructor + +Compile a template. Compilation walks the template once and extracts static parts and variable paths. + +| 引数名 | 型 | 説明 | +| ---------- | ---- | ---------------------------------------------------------- | +| *template* | Text | Template string with `{variable}` markers. | + +```4d +var $tpl:=cs.EmbeddingStudio.Phrase.new("Hello {firstName}, you study at {schoolName}.") +$tpl.keys // → ["firstName"; "schoolName"] +``` + +## 関数 + +### render() + +**render**(*data* : Object) : Text + +Render the compiled template by replacing variables with values from *data*. Missing keys produce an empty string. + +| 引数 | 型 | 説明 | +| ------ | ------ | ------------------------------------------------------------------------------------------------------ | +| *data* | Object | A plain object or a 4D.Entity whose fields supply the variable values. | +| 戻り値 | Text | The rendered text. | + +```4d +var $text:=$tpl.render({firstName: "Alice"; school: {name: "MIT"}}) +// → "Hello Alice, you study at MIT." + +// Works directly on entities +$text:=$tpl.render(ds.Students.first()) +``` + +### validate() + +**validate**(*dataclass* : 4D.DataClass ; *options* : Object) : Object + +Validate that all keys in the phrase can be resolved against the given dataclass. Walks dot-notation paths through N:1 / 1:1 relations. + +| 引数 | 型 | 説明 | +| --------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| *データクラス* | 4D.DataClass | The dataclass to validate against. | +| *options* | Object | Optional validation flags (see below). All default to `False` — storage kind only. | +| 戻り値 | Object | `{success: Boolean, errors: Collection of {key, message}}`. | + +#### オプション + +| フィールド | 型 | デフォルト | 説明 | +| ----------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------- | +| `allowRelations` | Boolean | `false` | Allow dot-notation paths through N:1 / 1:1 relations. | +| `allowCalculated` | Boolean | `false` | Allow calculated attributes. | +| `allowAlias` | Boolean | `false` | Allow alias attributes. | + +```4d +var $tpl:=cs.EmbeddingStudio.Phrase.new("{firstName} at {school.name}") + +// Storage-only validation — fails because {school.name} uses a relation +var $v:=$tpl.validate(ds.Students) +// $v.success → False +// $v.errors → [{key: "school.name"; message: "..."}] + +// Allow relations +$v:=$tpl.validate(ds.Students; {allowRelations: True}) +// $v.success → True +``` + +#### Rejected shapes + +Regardless of options: + +- Attributes that do not exist on the dataclass. +- Attributes whose class ID is `4D.Vector`. +- 1:N relations (`relatedEntities`) as the final key. +- Intermediate segments that are not relations (when dot-notation is used). + +### 属性() + +**attributes**(*dataclass* : 4D.DataClass) : Collection + +Resolves each phrase key against *dataclass* and returns an ordered Collection of ORDA attribute descriptor objects, one per key in the same order as `.keys`. For dot-notation paths, traverses N:1 relations to reach the final attribute. Pushes `Null` for any key whose path cannot be resolved (unknown attribute or non-relation intermediate segment). + +| 引数 | 型 | 説明 | +| -------- | ---------------------------- | -------------------------------------------------------------------------------------------- | +| *データクラス* | 4D.DataClass | The dataclass to resolve attributes against. | +| 戻り値 | Collection | Ordered collection of ORDA attribute objects (or `Null`). | + +Each resolved entry is an ORDA attribute descriptor with `.name`, `.kind`, and more — see [DataClass.attributeName](https://developer.4d.com/docs/API/DataClassClass#attributename). + +```4d +var $tpl:=cs.EmbeddingStudio.Phrase.new("{firstName} graduated from {school.name}") +var $attrs:=$tpl.attributes(ds.Students) +// $attrs[0].name → "firstName" $attrs[0].type → "string" +// $attrs[1].name → "name" $attrs[1].type → "string" (from School dataclass) +// $attrs[1] is Null if school.name could not be resolved +``` + +## 参照 + +- [Definition](Definition.md) — holds a `Phrase`. +- [StudioEmbedder.render()](StudioEmbedder.md#render) — renders a phrase for an entity, non-persisting. diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Process.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Process.md new file mode 100644 index 00000000000000..542bb920aa2b57 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Process.md @@ -0,0 +1,188 @@ +--- +id: process +title: プロセス +--- + +# プロセス + +The `Process` class orchestrates the full embedding pipeline: it browses 4D entities, renders text from their fields using a [Definition](Definition.md), calls the embeddings API through an [Embedder](Embedder.md), and stores the resulting `4D.Vector` on each entity. + +To render or embed on demand without persistence (search query vectors, phrase previews), see [StudioEmbedder](StudioEmbedder.md). + +## プロパティ + +| プロパティ名 | 型 | 説明 | +| ---------- | ----------------------- | -------------------------------------------------------------------------------------------------------- | +| `設定` | [Settings](Settings.md) | The settings (definitions, batch size, phrase validation options). | +| `embedder` | [Embedder](Embedder.md) | The API-calling engine. Stateless and swappable. | +| `options` | Object | Runtime options object (see [Options object](#options-object) below). | + +### Options object + +| キー | 型 | 説明 | +| ---------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `onProgress` | 4D.Function | Called after each processed chunk with `{definition, report}`. | +| `onSuccess` | 4D.Function | Called once at the end when `report.success = True`, with `{report, success, errors}`. | +| `onError` | 4D.Function | Called once at the end when `report.success = False`, with `{report, success, errors}`. | +| `onTerminate` | 4D.Function | Called once at the end in all cases (after `onSuccess`/`onError`), with `{report, success, errors}`. | +| `dryRun` | Boolean | If `True`, runs selection/filter logic but skips API calls and entity saves. | +| `force` | Boolean | If `True`, recomputes every entity ignoring null-vector / dirty-flag filter. | +| `debug` | Boolean | If `True`, emits additional diagnostic log entries. | +| `pauseIndexes` | Boolean | If `True`, index maintenance on the target table is paused for the duration of a `processEntitySelection` batch run, then resumed right after (or on early exit/critical error). Default `False` — indexes are left alone. See [Pausing indexes](#pausing-indexes) before enabling it. | +| `waitForIndexes` | Boolean | Only used with `pauseIndexes`. If `True`, resuming indexes blocks until they are rebuilt. Default `False` — resume is asynchronous (indexes rebuilt in the background). | +| `shouldCancel` | 4D.Function | Predicate called between chunks during selection processing. Returning `True` stops the run gracefully (cooperative cancel) — what [`Scheduler.cancel()`](Scheduler.md#cancel) uses. | +| `embedder` | [Embedder](Embedder.md) | Inject a custom embedder (otherwise a default one is created). | + +## Class constructor + +Create an instance of the orchestrator. + +| 引数名 | 型 | 説明 | +| --------- | ----------------------- | ------------------------------------------------------------------------------------------------ | +| *設定* | [Settings](Settings.md) | 任意。 If omitted, settings are loaded from the default `Settings/embeddings.json`. | +| *options* | Object | Optional runtime options (see table above). | + +```4d +// Simplest — uses defaults +var $p:=cs.EmbeddingStudio.Process.new() + +// With explicit settings +var $p:=cs.EmbeddingStudio.Process.new($settings) + +// With options +var $p:=cs.EmbeddingStudio.Process.new($settings; {\ + force: True; \ + onProgress: Formula(ALERT("chunk done: "+String($1.report.entitiesUpdated)))}) +``` + +## Batch processing functions + +### プロセス() + +**process**(*definition* : Variant) : [ProcessResult](ProcessResult.md) + +Process one, many, or all [Definition](Definition.md) entries against the full content of their target dataclass. + +| 引数 | 型 | 説明 | +| ---- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| *定義* | `Null`, [Definition](Definition.md), `4D.DataClass`, plain object, or Collection | See [process() resolution](#process-resolution). `Null` → every definition in settings. | +| 戻り値 | [ProcessResult](ProcessResult.md) | Statistics and per-error breakdown. | + +```4d +// Every definition in settings +var $r:=$p.process() + +// One specific definition +var $r:=$p.process($def) + +// Multiple definitions +var $r:=$p.process([$def1; $def2]) + +// Every definition configured for a whole dataclass +var $r:=$p.process(ds.Students) + +// A plain descriptor — looked up in settings, or built on the fly +var $r:=$p.process({dataclassName: "Students"; vectorName: "student_vector_1"}) + +// Any mix — each item is resolved independently and flattened +var $r:=$p.process([ds.Students; $def; {dataclassName: "School"; vectorName: "school_vector_1"}]) +``` + +#### process() resolution + +`process()` has no entity context, so it resolves each input into concrete [Definition](Definition.md) objects directly from settings: + +| 入力 | 動作 | +| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Null` | Every definition in settings. | +| [Definition](Definition.md) | Used as-is. | +| `4D.DataClass` (e.g. `ds.Students`) | Every definition in settings whose `dataclassName` matches that dataclass. | +| `{dataclassName: "..."; vectorName: "..."}` | The matching saved definition, or — if none is found — a new `Definition` built from the object's fields (`modelAlias`, `phrase.template`). | +| Collection | Each item is resolved with the rules above and the results are **flattened** into one collection (a `4D.DataClass` item can expand to several definitions). Unsupported items are dropped. | +| Anything else | Empty result. | + +### processEntity() + +**processEntity**(*entity* : 4D.Entity ; *definition* : Variant) : [ProcessResult](ProcessResult.md) + +Process a single entity. Cheap path — no chunking, no server-side filter. + +| 引数 | 型 | 説明 | +| -------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| *entity* | 4D.Entity | The entity to (re)compute vectors for. | +| *定義* | `Null`, [Definition](Definition.md), Collection, or `{vectorName: ...}` | See [resolution rules](#definition-resolution). `Null` infers from entity's dataclass. | +| 戻り値 | [ProcessResult](ProcessResult.md) | Statistics and per-error breakdown. | + +```4d +// Auto-resolve every definition matching this entity's dataclass +var $r:=$p.processEntity($entity) + +// Specific definition +var $r:=$p.processEntity($entity; $def) + +// By vector name only (looked up in settings against the entity's dataclass) +var $r:=$p.processEntity($entity; {vectorName: "student_vector_1"}) +``` + +### processEntitySelection() + +**processEntitySelection**(*selection* : 4D.EntitySelection ; *definition* : Variant) : [ProcessResult](ProcessResult.md) + +Workhorse path for large jobs. Chunks the selection by `settings.batchSize`, sends one API call per chunk, saves each entity individually. + +| 引数 | 型 | 説明 | +| ----------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| *selection* | 4D.EntitySelection | Entities to process. Pre-filtering by the caller is allowed; the pipeline still applies its null/dirty filter. | +| *定義* | `Null`, [Definition](Definition.md), Collection, or `{vectorName: ...}` | See [resolution rules](#definition-resolution). | +| 戻り値 | [ProcessResult](ProcessResult.md) | Statistics and per-error breakdown. | + +```4d +var $todo:=ds.Students.query("country = :1"; "FR") +var $r:=$p.processEntitySelection($todo; $def) +``` + +### Definition resolution (entity context) + +The polymorphic *definition* argument accepted by `processEntity` and `processEntitySelection`. Unlike [`process()`](#process-resolution), these have an entity/selection to infer the dataclass from, so a bare `{vectorName: "..."}` stub is enough: + +| 入力 | 動作 | +| --------------------------- | ----------------------------------------------------------------------------------------------- | +| `Null` | All definitions in settings whose `dataclassName` matches the entity/selection. | +| [Definition](Definition.md) | Used as-is; the `dataclassName` must match the entity/selection. | +| `{vectorName: "..."}` | Looked up in settings by `vectorName` against the entity/selection dataclass. | +| Collection | Each item resolved using the rules above; mismatches are silently dropped. | + +### Recompute rules + +An entity is (re)computed when **any** of these are true: + +- The target vector field is `Null`. +- A sibling field named `{vectorName}_dirty` exists and is `True`. +- The `force` option is `True`. + +The dirty field is optional per dataclass. If it doesn't exist, only the null-vector case triggers recomputation. Upon successful save, the pipeline clears the dirty flag (when present). + +For `processEntitySelection`, the filter is executed as a server-side ORDA query before any API call, so only the rows that actually need work are loaded into memory. For `processEntity`, the check is done in memory on the already-fetched entity. + +### Pausing indexes + +By default the indexes of the target table are maintained normally while vectors are saved. With the `pauseIndexes` option, a batch run calls [`PAUSE INDEXES`](https://developer.4d.com/docs/commands/pause-indexes) on the table before writing and [`RESUME INDEXES`](https://developer.4d.com/docs/commands/resume-indexes) once done (also on early exit or critical error). + +Be aware of what these commands do: + +- `PAUSE INDEXES` disables **all** the indexes of the table (except the primary key index), not only the vector ones: every index on every other field of the table is paused too. While paused, queries and sorts on that table, including those of other processes, run without any index. +- `RESUME INDEXES` then **rebuilds all these indexes**, for the whole table, not only for the records that were recomputed. On a table with several indexes, this rebuild can cost more than the time saved during the writes. +- With `waitForIndexes` set to `True`, the run blocks until the rebuild completes; otherwise the rebuild runs in the background. +- These commands cannot run on a 4D remote client: there the option is ignored (a warning is logged once) and the recalculation runs with indexes maintained normally. Run it on the server, for example through the [Scheduler](Scheduler.md), to use it. + +Enable it only for large recalculations, such as computing the vectors of a whole table for the first time. + +## 参照 + +- [StudioEmbedder](StudioEmbedder.md) +- [Settings](Settings.md) +- [Definition](Definition.md) +- [Embedder](Embedder.md) +- [ProcessResult](ProcessResult.md) +- [Phrase](Phrase.md) +- [Rate Limiting](../RateLimit.md) diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessError.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessError.md new file mode 100644 index 00000000000000..fa8a4e0316d6d6 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessError.md @@ -0,0 +1,87 @@ +--- +id: processerror +title: ProcessError +--- + +# ProcessError + +A `ProcessError` is one structured, typed entry in the `errors` collection of a [ProcessResult](ProcessResult.md). Its typed fields let callers react to a specific failure mode programmatically — retry transient failures, abort on a fatal model outage, count save failures — without parsing message strings. + +You read these instances from [ProcessResult](ProcessResult.md)`.errors`, directly or through its query helpers (`errorsByCode`, `errorsByScope`, `retryableErrors`). + +## プロパティ + +| プロパティ名 | 型 | 説明 | +| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `スコープ` | Text | Where the error originated: `"pipeline"`, `"definition"`, `"chunk"`, or `"entity"`. | +| `severity` | Text | `"warning"`, `"error"`, or `"fatal"`. Determined by `code` (see [ProcessErrorCode](ProcessErrorCode.md)). | +| `code` | Integer | Machine-readable error code — compare against the constants on [ProcessErrorCode](ProcessErrorCode.md). | +| `ref` | Variant | Scope-dependent reference: `"Dataclass.vector"`, an entity primary key, a model alias, or `Null`. | +| `message` | Text | Human-readable, localized message. | +| `retryable` | Boolean | `True` when re-running the operation could plausibly succeed. Determined by `code`. | + +### scope values + +| スコープ | 意味 | +| -------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `"pipeline"` | Top-level failure affecting the whole run (null selection, a model became unavailable). | +| `"definition"` | A [Definition](Definition.md) failed validation or was skipped. | +| `"chunk"` | A whole batch (chunk) of entities failed in a single API call. | +| `"entity"` | A single entity failed to embed or save. | + +### severity values + +| Severity | 意味 | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `"警告"` | Non-blocking — does **not** make [ProcessResult](ProcessResult.md)`.success` false. | +| `"error"` | A recoverable failure scoped to one entity, chunk, or definition. Makes `success` false. | +| `"fatal"` | Blocks the rest of the run (e.g. the model is unavailable). Also surfaces via `hasFatal`. | + +## 計算プロパティ + +| プロパティ | 型 | 説明 | +| --------- | ------- | ------------------------------------------------- | +| `isFatal` | Boolean | `True` when `severity = "fatal"`. | + +## 関数 + +### toObject() + +**toObject**() : Object + +Returns a plain object (`{scope, severity, code, ref, message, retryable}`) suitable for logging or JSON serialization. + +| 引数 | 型 | 説明 | +| --- | ------ | ------------------------------------------------------ | +| 戻り値 | Object | A JSON-friendly snapshot of the error. | + +## 例題 + +React to failures by type rather than by message text: + +```4d +var $r:=$p.process() + +If (Not($r.success)) + + If ($r.hasFatal) + ALERT("A model became unavailable — aborting until it recovers.") + End if + + var $codes:=cs.EmbeddingStudio.ProcessErrorCode.me + var $saveFailures:=$r.errorsByCode($codes.SAVE_FAILED) + If ($saveFailures.length>0) + ALERT(String($saveFailures.length)+" entities failed to save.") + End if + + // Collect entity keys worth retrying later + var $retry:=$r.retryableErrors().query("scope = :1"; "entity").extract("ref") + +End if +``` + +## 参照 + +- [ProcessErrorCode](ProcessErrorCode.md) — the catalogue of `code` values and their severity/retryability. +- [ProcessResult](ProcessResult.md) — owns the `errors` collection and the query helpers (`errorsByCode`, `errorsByScope`, `retryableErrors`). +- [Process](Process.md) — produces these errors. diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessErrorCode.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessErrorCode.md new file mode 100644 index 00000000000000..dafd474bde19ec --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessErrorCode.md @@ -0,0 +1,55 @@ +--- +id: processerrorcode +title: ProcessErrorCode +--- + +# ProcessErrorCode + +A `singleton` exposing the stable, machine-readable error codes carried by [ProcessError](ProcessError.md) `.code`, plus a `meta()` lookup mapping each code to its default `severity` and `retryable` flag. Compare against these constants instead of parsing message strings. + +Access the shared instance via `.me`: + +```4d +var $codes:=cs.EmbeddingStudio.ProcessErrorCode.me +If ($error.code=$codes.SAVE_FAILED) + // … +End if +``` + +## Codes + +| 定数 | 値 | Default severity | Retryable | Raised when… | +| ----------------------- | --- | ---------------- | --------- | ------------------------------------------------------------------------------------------------- | +| `NULL_INPUT` | 100 | error | × | A required entity, selection, or definition was `Null`. | +| `INVALID_DEFINITION` | 101 | error | × | A value is not a usable [Definition](Definition.md) instance. | +| `VALIDATION_FAILED` | 102 | error | × | `Definition.validate()` reported a problem. | +| `MODEL_UNAVAILABLE` | 200 | fatal | ◯ | A critical API error made the model unusable for the rest of the run. | +| `MODEL_SKIPPED` | 201 | error | ◯ | A definition was skipped because its model already failed critically. | +| `EMBED_FAILED` | 202 | error | ◯ | A non-critical embedding call failed (single entity or chunk). | +| `VECTOR_COUNT_MISMATCH` | 300 | error | × | The provider returned a different vector count than requested. | +| `SAVE_FAILED` | 400 | error | ◯ | `entity.save()` failed (validation, lock, …). | + +Codes are grouped by hundreds: `1xx` input/configuration, `2xx` model/API, `3xx` data integrity, `4xx` persistence. Unknown codes resolve to `{severity: "error"; retryable: False; label: "UNKNOWN"}`. + +## 関数 + +### meta() + +**meta**( $code : Integer ) : Object + +Returns the `severity` and `retryable` flag associated with a code — the same values carried by a [ProcessError](ProcessError.md) with that `code`. + +| 引数 | 型 | 説明 | +| ------- | ------- | ----------------------------------------------------------------------- | +| `$code` | Integer | One of the code constants above. | +| 戻り値 | Object | `{severity : Text; retryable : Boolean; label : Text}`. | + +```4d +var $m:=cs.EmbeddingStudio.ProcessErrorCode.me.meta(cs.EmbeddingStudio.ProcessErrorCode.me.MODEL_UNAVAILABLE) +// $m = {severity: "fatal"; retryable: True; label: "MODEL_UNAVAILABLE"} +``` + +## 参照 + +- [ProcessError](ProcessError.md) — carries a `.code` from this list. +- [ProcessResult](ProcessResult.md) — `errorsByCode()` filters errors by code. diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessResult.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessResult.md new file mode 100644 index 00000000000000..7c690d7eeda9f1 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/ProcessResult.md @@ -0,0 +1,91 @@ +--- +id: processresult +title: ProcessResult +--- + +# ProcessResult + +The `ProcessResult` class is the return value of every batch entry point of [Process](Process.md) (`process`, `processEntity`, `processEntitySelection`). It accumulates statistics, per-error breakdowns, and wall-clock duration. + +The orchestrator never throws out of its public batch API — failures are recorded here and the job continues. The caller decides what to do with them. + +## プロパティ + +| プロパティ名 | 型 | 説明 | +| ---------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `definitionsProcessed` | Integer | Number of [Definition](Definition.md) entries processed. | +| `entitiesConsidered` | Integer | Number of entities that passed the "needs recompute" filter. | +| `entitiesUpdated` | Integer | Number of entities whose vector was successfully written and saved. | +| `entitiesSkipped` | Integer | Number of entities that could not be processed: individual embed or save errors, or whole-chunk API failures (those entities are left unchanged for the next run). | +| `apiCalls` | Integer | Number of embeddings API calls made. | +| `promptTokens` | Integer | Total prompt tokens consumed across all API calls in this run. | +| `totalTokens` | Integer | Total tokens consumed across all API calls in this run. | +| `経過時間` | Integer | Total duration of the job in milliseconds. | +| `errors` | Collection | List of [ProcessError](ProcessError.md) entries recorded during the run. | + +### 計算プロパティ + +| プロパティ | 型 | 説明 | +| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `success` | Boolean | `True` when no `"error"` or `"fatal"` entry was recorded. `"warning"` entries do not fail the run. | +| `hasFatal` | Boolean | `True` when at least one `"fatal"` entry was recorded (e.g. a model became unavailable). | + +### Error entries + +Each item in `errors` is a [ProcessError](ProcessError.md) with `scope`, `severity`, `code`, `ref`, `message`, and `retryable`. See [ProcessError](ProcessError.md) for the field meanings and [ProcessErrorCode](ProcessErrorCode.md) for the `code` catalogue. + +## 関数 + +### errorsByScope() + +**errorsByScope**( $scope : Text ) : Collection + +Errors filtered by `scope` (`"pipeline"`, `"definition"`, `"chunk"`, `"entity"`). + +### errorsByCode() + +**errorsByCode**( $code : Integer ) : Collection + +Errors filtered by machine-readable code — see [ProcessErrorCode](ProcessErrorCode.md). + +### retryableErrors() + +**retryableErrors**() : Collection + +Errors flagged `retryable` — re-running the operation could plausibly succeed. + +### toObject() + +**toObject**() : Object + +Returns a plain object suitable for logging or JSON serialization. + +| 引数 | 型 | 説明 | +| --- | ------ | ------------------------------------------------------- | +| 戻り値 | Object | A JSON-friendly snapshot of the report. | + +```4d +var $r:=$p.process() +LOG EVENT(Into 4D log file; JSON Stringify($r.toObject())) +``` + +## 例題 + +```4d +var $r:=$p.processEntitySelection(ds.Students.all(); $def) + +If ($r.success) + ALERT("Updated "+String($r.entitiesUpdated)+" students in "+String($r.duration)+" ms") +Else + var $err : Object + For each ($err; $r.errors) + ALERT("[" + $err.scope + "] " + String($err.ref) + " — " + $err.message) + End for each +End if +``` + +## 参照 + +- [Process](Process.md) +- [ProcessError](ProcessError.md) — the typed shape of each `errors` entry. +- [ProcessErrorCode](ProcessErrorCode.md) — the `code` catalogue. diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Scheduler.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Scheduler.md new file mode 100644 index 00000000000000..8b61a1089b1b15 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Scheduler.md @@ -0,0 +1,369 @@ +--- +id: scheduler +title: スケジューラー +--- + +# スケジューラー + +The `Scheduler` class is the public entry point for the **automated embedding recalculation** service. It maintains a background task that runs the embedding pipeline (see [Process](Process.md)) at a configured interval or a fixed daily time, guarantees that **at most one** recalculation batch runs at a time, and exposes runtime status for administration and monitoring interfaces. + +It is a **singleton**, accessed through `cs.EmbeddingStudio.Scheduler.me`. + +The scheduler runs two named workers: + +| Worker | ロール | +| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `EmbeddingStudioScheduler` | Background loop that re-reads the config each cycle, computes the next run and fires when due. | +| `EmbeddingStudio` | Execution worker that runs one recalculation batch (shared with the Studio UI, so scheduled and manual runs are serialized). | + +## 設定 + +The configuration lives under the `scheduler` key of `Settings/embeddings.json`: + +```json +{ + "scheduler": { + "mode": "interval", + "intervalHours": 3, + "startFrom": "reference", + "startReference": "2026-09-02T14:00:00", + "dailyTime": "00:00" + } +} +``` + +| キー | 型 | Values / range | 説明 | +| ---------------- | ------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `mode` | Text | `"never"` \| `"interval"` \| `"daily"` | Scheduling mode. Absent/unknown ⇒ `never` (no automatic run). | +| `intervalHours` | Integer | `1`..`24` | Interval mode only. Out-of-range ⇒ default `3`. | +| `startFrom` | Text | `"reference"` \| `"lastExecution"` | Interval mode only. Anchor of the interval (see below). Anything other than `"lastExecution"` — including the legacy `"now"` — is normalized to `reference`. Default `reference`. | +| `startReference` | Text | `"YYYY-MM-DDThh:mm:ss"` | Interval mode with `startFrom = "reference"`. Fixed instant the interval counts from. Absent ⇒ the moment the scheduler was armed, then the current instant. | +| `dailyTime` | Text | `"HH:MM"` | Daily mode only. Time of day for the recalculation. Default `"00:00"`. | + +**Interval anchoring (`startFrom`)** + +- `reference` — **fixed rate**: the interval is anchored on the fixed `startReference` instant, so the slots do not drift whatever a run's duration is. Slots are advanced by `intervalHours` until the first one strictly after now. When `startReference` is absent (a fresh or legacy config), the anchor falls back to the moment the scheduler was armed (`start()`), then to the current instant. +- `lastExecution` — **fixed delay**: the interval is anchored on the last completed recalculation. If the elapsed time since the last run already exceeds the interval (e.g. after a restart), the run is triggered immediately. If there is no prior run, it runs immediately. + +The effective configuration is read from the file on **every loop cycle**, so changes take effect without restarting the scheduler. + +## Starting the scheduler + +Configuring a `mode` is **not enough**: nothing runs until the scheduler is started. There are two ways to get there, and which one applies depends on a single option of your host database. + +### 1. Automatic — let the host database start it + +In the host database, open **Settings > Security** and check **"Execute 'On Host Database Event' method of the components"** (it is *unchecked* by default, for security reasons). + +With this option on, 4D Embedding Studio starts the scheduler by itself when the host database opens, and stops it when the host database closes. There is nothing else to write. + +Use [`autoStart()`](#autostart) to check whether the option is on: + +```4d +If (Not(cs.EmbeddingStudio.Scheduler.me.autoStart())) + // the option is off — I must start the scheduler myself + cs.EmbeddingStudio.Scheduler.me.start() +End if +``` + +### 2. Manual — start it from your own code + +If you prefer to leave the option off, the scheduler never starts on its own. Call [`start()`](#start) from wherever it suits you — typically the host `On Startup` or `On Server Startup` database method — and [`stop()`](#stop) when the database closes (`On Exit` / `On Server Shutdown`): + +```4d +// Host "On Server Startup" +cs.EmbeddingStudio.Scheduler.me.start() + +// Host "On Server Shutdown" +cs.EmbeddingStudio.Scheduler.me.stop() +``` + +> In client/server, arm the scheduler from `On Server Startup`, not from `On Startup`: +> `On Startup` runs on every remote client, and the scheduler state is per machine — each +> client would arm its own loop and run its own batches. If you do call [`start()`](#start) +> from `On Startup` (single-user setups), guard it with +> `If (Application type#4D Remote mode)`. + +`start()` is idempotent, so calling it from several places is harmless. + +### Checking that it really runs + +[`isStarted()`](#isstarted) tells you whether the background loop is alive right now — the answer to "is my schedule actually being watched?": + +```4d +var $s:=cs.EmbeddingStudio.Scheduler.me.status() +If ($s.enabled && Not($s.started)) + ALERT("A schedule is configured but the scheduler is not started.") +End if +``` + +## 関数 + +### start() + +**start**() : Boolean + +Arms the scheduler and starts the background loop worker if it is not already running. Idempotent — calling it again while already armed simply refreshes the "start from now" anchor. + +| 戻り値 | 型 | 説明 | +| --- | ------- | ------------------------------ | +| 戻り値 | Boolean | Always `True`. | + +```4d +cs.EmbeddingStudio.Scheduler.me.start() +``` + +### stop() + +**stop**() + +Disarms the scheduler and stops the background loop worker. A recalculation batch already in progress is **not** interrupted — it finishes normally (use [`cancel()`](#cancel) to request an early stop). + +```4d +cs.EmbeddingStudio.Scheduler.me.stop() +``` + +### キャンセル() + +**cancel**() + +Requests a **cooperative** cancel of the batch currently running. The running batch is never force-killed; it stops gracefully between two chunks. Has no effect if no batch is running. + +```4d +cs.EmbeddingStudio.Scheduler.me.cancel() +``` + +### force() + +**force**() : Object + +Forces a recalculation **now**, regardless of the schedule. It honors the single-batch rule: if a batch is already running, the forced trigger is skipped (and logged). Non-blocking — the run happens on the execution worker. + +| 戻り値 | 型 | 説明 | +| --- | ------ | ----------------------------------------------------- | +| 戻り値 | Object | The current [status](#status) object. | + +```4d +var $status:=cs.EmbeddingStudio.Scheduler.me.force() +``` + +### status() + +**status**() : Object + +Returns the current scheduler status, without any input parameter — suitable for administration and monitoring displays. + +| 戻り値 | 型 | 説明 | +| --- | ------ | ---------------------------------------------------- | +| 戻り値 | Object | See [Status object](#status-object). | + +```4d +var $s:=cs.EmbeddingStudio.Scheduler.me.status() +If ($s.running) + ALERT("A recalculation is running since "+$s.batchStart) +End if +``` + +#### ステータスオブジェクト + +| キー | 型 | 説明 | +| ---------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `enabled` | Boolean | `False` when `mode = "never"`. | +| `mode` | Text | Effective mode (`never` \| `interval` \| `daily`). | +| `armed` | Boolean | `True` when the background loop is armed (after `start()`, until `stop()`). | +| `running` | Boolean | `True` while a recalculation batch is in progress. | +| `batchStart` | Text \| Null | ISO timestamp of the running batch start (`Null` when idle). | +| `lastExecution` | Text \| Null | ISO timestamp of the last completed run (`Null` if none yet). Restored from the persisted history after a restart, so it survives the loss of in-memory state. | +| `lastRunBeforeRestart` | Boolean | `True` when `lastExecution` was recovered from the history after a restart rather than produced by a run in the current session. | +| `nextRun` | Text \| Null | ISO timestamp of the next scheduled run (`Null` in `never` mode). | +| `lastResult` | Text \| Null | Result of the last trigger: `started` \| `skipped` \| `completed` \| `failed`. | +| `エラー発生` | Text \| Null | Error summary when the last run failed (safe for admin display), else `Null`. | +| `started` | Boolean | `True` when the background loop is really alive (see [`isStarted()`](#isstarted)). | +| `autoStart` | Boolean | `True` when the host database starts the scheduler by itself (see [`autoStart()`](#autostart)). | + +### isStarted() + +**isStarted**() : Boolean + +Tells whether the scheduler is **effectively running**, i.e. whether its background loop is alive at this very moment. Unlike the `armed` flag of the [status](#status-object), it reflects reality: if the loop was never started, or was killed, the result is `False`. + +| 戻り値 | 型 | 説明 | +| --- | ------- | --------------------------------------------------------- | +| 戻り値 | Boolean | `True` when the background loop is alive. | + +```4d +If (Not(cs.EmbeddingStudio.Scheduler.me.isStarted())) + cs.EmbeddingStudio.Scheduler.me.start() +End if +``` + +### autoStart() + +**autoStart**() : Boolean + +Tells whether the host database authorizes 4D Embedding Studio to start itself, i.e. whether the **"Execute 'On Host Database Event' method of the components"** option is checked in the host **Settings > Security** (see [Starting the scheduler](#starting-the-scheduler)). + +- `True` — the scheduler starts with the host database and stops with it. You have nothing to call. +- `False` — nothing starts automatically: your code must call [`start()`](#start) and [`stop()`](#stop). + +The answer is read from the host structure settings. When they cannot be read, the result is `False` — the safe answer, since starting an already-started scheduler is harmless. + +| 戻り値 | 型 | 説明 | +| --- | ------- | -------------------------------------------------------------------- | +| 戻り値 | Boolean | `True` when the host starts the scheduler by itself. | + +```4d +var $auto:=cs.EmbeddingStudio.Scheduler.me.autoStart() +``` + +### config() + +**config**() : Object + +Returns the effective scheduler configuration with defaults applied (as resolved from `embeddings.json`). + +| 戻り値 | 型 | 説明 | +| --- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | +| 戻り値 | Object | `{mode; intervalHours; startFrom; startReference; dailyTime}` (see [Configuration](#configuration)). | + +```4d +var $cfg:=cs.EmbeddingStudio.Scheduler.me.config() +``` + +### saveConfig() + +**saveConfig**( *cfg* : Object ) : Object + +Validates, normalizes and **persists** a scheduler configuration to the `scheduler` key of `embeddings.json`, then returns the normalized value. This is the programmatic equivalent of the scheduler settings window: it lets you change the schedule entirely by code, without the GUI. Only the `scheduler` key is written — other keys of the settings file are preserved. + +The configuration is written **on the server**: in a 4D Server / 4D remote setup the file is always edited on the server machine, so a remote client can safely call this method. Because the loop re-reads the configuration on every cycle, the new schedule takes effect without restarting the scheduler. + +| 引数 | 型 | 説明 | +| --- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| cfg | Object | Raw configuration `{mode; intervalHours; startFrom; startReference; dailyTime}` (see [Configuration](#configuration)). Missing/out-of-range values are defaulted. | + +| 戻り値 | 型 | 説明 | +| --- | ------ | ---------------------------------------------------------------- | +| 戻り値 | Object | The normalized configuration that was persisted. | + +```4d +// Switch to a 6-hour interval counting from the last execution +cs.EmbeddingStudio.Scheduler.me.saveConfig({mode: "interval"; intervalHours: 6; startFrom: "lastExecution"}) + +// Switch to a daily run at 02:30 +cs.EmbeddingStudio.Scheduler.me.saveConfig({mode: "daily"; dailyTime: "02:30"}) + +// Disable the automatic schedule +cs.EmbeddingStudio.Scheduler.me.saveConfig({mode: "never"}) +``` + +### nextRun() + +**nextRun**() : Object + +Computes the next scheduled run from the current configuration and state. + +| 戻り値 | 型 | 説明 | +| --- | -------------- | --------------------------------------------------------------------------------------------------------------- | +| 戻り値 | Object \| Null | `{date : Date; time : Time; timestamp : Text; immediate : Boolean}`, or `Null` in `never` mode. | + +```4d +var $next:=cs.EmbeddingStudio.Scheduler.me.nextRun() +``` + +### reload() + +**reload**() : Object + +No-op convenience: the configuration is re-read automatically on each loop cycle, so this simply returns the current [status](#status). Provided for callers that want an explicit "config changed, give me the up-to-date status" call. + +| 戻り値 | 型 | 説明 | +| --- | ------ | ----------------------------------------------------- | +| 戻り値 | Object | The current [status](#status) object. | + +## Concurrency & logging + +- **Single batch** — at any time, at most one recalculation batch runs. A trigger (scheduled or forced) fired while a batch is running is **skipped**, not queued. +- **Skip traceability** — skipped triggers are logged with their timestamp in the execution history (`Logs/embeddingHistory.json`). +- **Cooperative cancel** — `cancel()` stops a running batch gracefully between chunks; it is never force-killed. +- **History** — each run records start/end timestamps, status, token usage and the computed next run date in `Logs/embeddingHistory.json` (see [ProcessResult](ProcessResult.md) for per-run details). + +### Execution history file + +`Logs/embeddingHistory.json` is written by the pipeline itself (every full `process()` run, scheduled or manual), guarded by a semaphore so concurrent processes never interleave writes. It holds the **current** run at the top level, the one before it under `previous`, and the same pair per definition under `definitions`. + +```json +{ + "startTime": "2026-09-01T14:03:00", + "endTime": "2026-09-01T14:03:00", + "status": "completed", + "trigger": "completed", + "error": null, + "nextComputeDate": "2026-09-02T14:03:00", + "promptTokens": 0, + "totalTokens": 0, + "cumulativePromptTokens": 37802, + "cumulativeTotalTokens": 37802, + "previous": { "startTime": "…", "endTime": "…", "status": "completed", "error": null, + "nextComputeDate": "…", "promptTokens": 12764, "totalTokens": 12764, + "cumulativePromptTokens": 37802, "cumulativeTotalTokens": 37802 }, + "skipped": ["2026-09-01T12:00:00"], + "definitions": { + "Students.student_vector_1": { + "startTime": "…", "endTime": "…", "status": "completed", "error": null, + "promptTokens": 1054, "totalTokens": 1054, + "cumulativePromptTokens": 4210, "cumulativeTotalTokens": 4210, + "previous": { "…": "…" } + } + } +} +``` + +| キー | 型 | 説明 | +| -------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `startTime` / `endTime` | Text \| Null | ISO timestamps of the run, in the scheduler's local base. `endTime` is `null` while a run is in progress. | +| `status` | Text | `running` \| `completed` \| `failed`. | +| `trigger` | Text | Last event that touched the file: `started` \| `skipped` \| `completed` \| `failed`. | +| `エラー発生` | Text \| Null | Summary of the run's errors, or `null`. Never contains an API key. | +| `nextComputeDate` | Text \| Null | Next scheduled run computed at the end of the run (the `nextComputeDate` option of [Process](Process.md)). | +| `promptTokens` / `totalTokens` | Integer | Usage for this run alone. | +| `cumulativePromptTokens` / `cumulativeTotalTokens` | Integer | Running totals across all recorded runs. | +| `previous` | Object | Snapshot of the preceding run — the same keys, without `trigger`, `skipped` and `definitions`. Only one generation is kept. | +| `skipped` | Collection | ISO timestamps of triggers skipped because a batch was already running. Capped at the **last 50**. | +| `definitions` | Object | One entry per definition, keyed `"."`, each with its own `startTime`, `endTime`, `status` (`completed` \| `failed` \| `skipped`), `error`, token counters and `previous`. | + +[`status()`](#status) reads `startTime`, `endTime`, `status`, `trigger`, `error` and `nextComputeDate` back from this file, which is how `lastExecution` survives a server restart. + +## Lifecycle + +| Host setting | What happens | What you must do | +| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| **"Execute 'On Host Database Event' method of the components"** checked | The scheduler starts when the host database opens and stops when it closes. | Nothing. | +| Option unchecked (default) | The scheduler never starts by itself. | Call [`start()`](#start) at startup and [`stop()`](#stop) at shutdown. | + +Ask [`autoStart()`](#autostart) which case you are in, and [`isStarted()`](#isstarted) whether the loop is currently alive. Stopping the scheduler never interrupts a batch in progress — it finishes normally. + +## 例題 + +```4d +// --- Start at server startup, unless the host does it for us --- +If (Not(cs.EmbeddingStudio.Scheduler.me.autoStart())) + cs.EmbeddingStudio.Scheduler.me.start() +End if + +// --- Admin panel: force a recalculation and read status --- +var $status:=cs.EmbeddingStudio.Scheduler.me.force() + +// --- Monitoring: display last / next run and current state --- +$status:=cs.EmbeddingStudio.Scheduler.me.status() +var $info:="Mode: "+$status.mode\ + +" — Last: "+String($status.lastExecution)\ + +" — Next: "+String($status.nextRun)\ + +" — "+($status.running ? "running" : String($status.lastResult)) + +// --- Cancel a long-running batch --- +cs.EmbeddingStudio.Scheduler.me.cancel() + +// --- Disable automatic runs --- +cs.EmbeddingStudio.Scheduler.me.stop() +``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Settings.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Settings.md new file mode 100644 index 00000000000000..cb8643648e3d68 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Settings.md @@ -0,0 +1,184 @@ +--- +id: settings +title: 設定 +--- + +# 設定 + +The `Settings` class is the persisted configuration for the embedding pipeline. It loads and saves a JSON file (default: `Settings/embeddings.json`, overridable with the `EMBEDDINGS_SETTINGS_PATH` environment variable) containing a list of [Definition](Definition.md) entries, a batch size, and phrase-validation options. + +## プロパティ + +| プロパティ名 | 型 | 説明 | +| ------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `definitions` | Collection of [Definition](Definition.md) | The configured definitions. | +| `batchSize` | Integer | Chunk size used by [Process.processEntitySelection](Process.md#processentityselection). Default: `50`. | +| `phrase` | Object | Phrase-validation options (see below). | +| `embedder` | Object | Optional embedder configuration (see below). | +| `file` | 4D.File *(read-only)* | The backing file the settings are loaded from and saved to. | + +### phrase options + +Passed verbatim to [Phrase.validate()](Phrase.md#validate) whenever the pipeline validates a definition. + +| フィールド | 型 | デフォルト | 説明 | +| ----------------- | ------- | ------- | ----------------------------------------------------------------------------------------------- | +| `allowRelations` | Boolean | `false` | Allow dot-notation through N:1 / 1:1 relations. | +| `allowCalculated` | Boolean | `false` | Allow calculated attributes in phrases. | +| `allowAlias` | Boolean | `false` | Allow alias attributes in phrases. | +| `allowObject` | Boolean | `false` | Allow object attributes in phrases. | + +> **Invalidation caveat.** Dirty-flag tracking only covers direct scalar fields on the entity. Fields that are only reachable through one of these options — a related entity's attribute, a calculated value, an alias, or a sub-property of an object — will **not** automatically mark the entity as dirty when they change. If such fields are part of a phrase and their source data changes, the vector will not be recomputed unless you call `invalidateVectors()` explicitly or use `force: true` when processing. + +### embedder options + +Controls how [Process](Process.md) builds its embedder. When absent, a default `Embedder` is created with its own defaults. + +| フィールド | 型 | デフォルト | 説明 | +| ------------ | ------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `className` | Text | — | Name of a project class to instantiate instead of the built-in `Embedder`. The class must expose `embed` and `embedBatch` functions. If instantiation fails or the interface is missing, a diagnostic error is logged and the default `Embedder` is used as fallback. | +| `maxRetries` | Integer | `3` | Number of retry attempts on rate-limit errors (forwarded to `Embedder`). | +| `backoffMs` | Integer | `500` | Base back-off delay in ms, doubled each retry (forwarded to `Embedder`). | + +Any additional keys are forwarded as-is to the constructor of the target class (built-in or custom). + +## ファイル形式 + +```json +{ + "batchSize": 50, + "phrase": { + "allowRelations": false, + "allowCalculated": false, + "allowAlias": false, + "allowObject": false + }, + "embedder": { + "maxRetries": 5, + "backoffMs": 200 + }, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding-3-small", + "phrase": "Student {firstName} {lastName}", + "autoInvalidate": true + } + ] +} +``` + +Each definition may include `autoInvalidate` (`true` by default) to control save-time automatic invalidation. + +The same file also carries the `scheduler` key (see [Scheduler](Scheduler.md#configuration)) and any other top-level key you add: `Settings` reads and rewrites only the keys listed above and leaves the rest untouched. + +With a custom embedder class: + +```json +{ + "embedder": { + "className": "MyCustomEmbedder" + }, + "definitions": [...] +} +``` + +## Class constructor + +Create a settings instance. The configuration file is loaded immediately. + +| 引数名 | 型 | 説明 | +| ------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *ファイル* | 4D.File | 任意。 A file to use instead of the default location. The override applies process-wide for subsequent settings access. **Not supported in 4D Remote mode** — pass it only when running locally or on the server. | + +When *file* is omitted, the default location is used: `Settings/embeddings.json`, or the path given by the `EMBEDDINGS_SETTINGS_PATH` environment variable. + +```4d +// Default location +var $settings:=cs.EmbeddingStudio.Settings.new() + +// Custom file (server / mono only) +var $settings:=cs.EmbeddingStudio.Settings.new(File("/some/path/custom.json")) +``` + +## 関数 + +### load() + +**load**() + +Reload the backing file into memory, overwriting in-memory state. A missing file resets to defaults without raising. + +A file that **exists but cannot be parsed** also leaves the instance on defaults, but it is remembered: an error is logged and [`save()`](#save) then refuses to write, so a malformed file is never silently replaced by defaults. + +### save() + +**save**() : Boolean + +Serialize the current in-memory state to the backing file. Only the keys this class owns (`batchSize`, `phrase`, `embedder`, `definitions`) are written — every other top-level key present in the file (the `scheduler` configuration, model aliases…) is preserved as-is. A key whose value is back to its default is *removed* from the file rather than written. + +Definitions are merged with what the file holds at that instant, using the snapshot taken at load time as the common ancestor: two editors open at the same time no longer drop each other's definitions. + +| 戻り値 | 型 | 説明 | +| --- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| 戻り値 | Boolean | `True` when written. `False` — nothing written — when the file could not be read at load time. | + +```4d +$settings.definitions.push(cs.EmbeddingStudio.Definition.new("Students"; "student_vector_1"; "text-embedding-3-small"; "{firstName}")) +$settings.batchSize:=100 +$settings.save() +``` + +### find() + +**find**(*dataclassName* : Text ; *vectorName* : Text) : [Definition](Definition.md) + +Look up the saved definition for the given dataclass/vector pair. + +| 引数 | 型 | 説明 | +| --------------- | --------------------------- | ------------------------------------------------------------------- | +| *dataclassName* | Text | データクラスの名称。 | +| *vectorName* | Text | Name of the vector field on that dataclass. | +| 戻り値 | [Definition](Definition.md) | The matching definition, or `Null` if none matches. | + +```4d +var $def:=$settings.find("Students"; "student_vector_1") +``` + +### findAll() + +**findAll**(*dataclassName* : Text) : Collection of [Definition](Definition.md) + +Return every saved definition configured for the given dataclass. + +| 引数 | 型 | 説明 | +| --------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------- | +| *dataclassName* | Text | データクラスの名称。 | +| 戻り値 | Collection of [Definition](Definition.md) | All matching definitions (empty collection if none match). | + +```4d +var $defs:=$settings.findAll("Students") +// → every Students definition; used by Process.process(ds.Students) +``` + +### invalidateVectors() + +**invalidateVectors**() : Object + +Calls [`invalidateVectors()`](Definition.md#invalidatevectors) on every definition in `definitions` and merges the results into a single status object. + +| 引数 | 型 | 説明 | +| --- | ------ | ------------------------------------------------------------------------------------------------------------------------ | +| 戻り値 | Object | `{updated: Integer, skipped: Integer, errors: Collection of Text}` — accumulated across all definitions. | + +```4d +var $result:=cs.EmbeddingStudio.Settings.new().invalidateVectors() +// → { updated: 120; skipped: 0; errors: [] } +``` + +## 参照 + +- [Definition](Definition.md) +- [Process](Process.md) +- [Phrase](Phrase.md) diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/StudioEmbedder.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/StudioEmbedder.md new file mode 100644 index 00000000000000..02cd8721b57487 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/StudioEmbedder.md @@ -0,0 +1,125 @@ +--- +id: studioembedder +title: StudioEmbedder +--- + +# StudioEmbedder + +The `StudioEmbedder` class renders and embeds on demand, resolved against the Studio settings: a saved definition gives the phrase and the model, so the vector you compute matches the ones stored by [Process](Process.md). Nothing is persisted. Typical uses: building the vector of a search query, finding entities similar to a given one, or previewing the text sent for an entity. + +For the full batch pipeline that persists vectors on entities, see [Process](Process.md). + +## プロパティ + +| プロパティ名 | 型 | 説明 | +| ---------- | ----------------------- | ------------------------------------------------------------------------------------------------- | +| `設定` | [Settings](Settings.md) | The settings (vectors, batch size, phrase validation options). | +| `embedder` | [Embedder](Embedder.md) | The API-calling engine. Stateless and swappable. | +| `options` | Object | Runtime options object. | + +## Class constructor + +| 引数名 | 型 | 説明 | +| --------- | ----------------------- | ------------------------------------------------------------------------------------------------ | +| *設定* | [Settings](Settings.md) | 任意。 If omitted, settings are loaded from the default `Settings/embeddings.json`. | +| *options* | Object | Optional runtime options. Supports `embedder` for injection. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings) +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new($settings; {embedder: $mockEmbedder}) +``` + +## 関数 + +### render() + +**render**(*entity* : 4D.Entity ; *definitionOrPhrase* : Variant) : Text + +Return the text that [`embed()`](#embed) sends for an entity (the phrase rendered against it). No API call, no persistence. + +| 引数 | 型 | 説明 | +| -------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *entity* | 4D.Entity | The entity to render against. | +| *definitionOrPhrase* | `Null`, [Phrase](Phrase.md), [Definition](Definition.md), Text, or plain object stub | `Null` → auto-resolve via settings (requires a unique match). Text → compiled as a throwaway `cs.EmbeddingStudio.Phrase`. Object stub → see [stub resolution](#stub-resolution). | +| 戻り値 | Text | The rendered text. | + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $text: Text +$text:=$studioEmbedder.render($student; $def) // use def's phrase +$text:=$studioEmbedder.render($student; cs.EmbeddingStudio.Phrase.new("Hi {firstName}")) +$text:=$studioEmbedder.render($student; "Student: {lastName}") // raw template +$text:=$studioEmbedder.render($student) // auto-resolve +$text:=$studioEmbedder.render($student; {vectorName: "student_vector_1"}) // stub → saved definition's phrase +$text:=$studioEmbedder.render($student; {phrase: "Hi {firstName}"}) // ad-hoc stub → inline template +``` + +### embed() + +**embed**(*input* : Variant ; *context* : Variant ; *model* : Text) : [cs.EmbeddingStudio.EmbedderResult](EmbedderResult.md) + +Compute a vector for an arbitrary input, without persisting anywhere. + +| 引数 | 型 | 説明 | +| --------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| *input* | Text or 4D.Entity | Text → embedded directly. Entity → phrase rendered then embedded. | +| *context* | Text, [Phrase](Phrase.md), [Definition](Definition.md), Text template, plain object stub, or `Null` | Provides phrase and/or model depending on *input*. Object stub → see [stub resolution](#stub-resolution). | +| *model* | Text | Optional explicit model name. Used when *context* does not carry one. | +| 戻り値 | [EmbedderResult](EmbedderResult.md) | The embedding result (use `.vector` to get the 4D.Vector). | + +Throws if no model can be determined. + +```4d +var $studioEmbedder:=cs.EmbeddingStudio.StudioEmbedder.new() +var $vector: 4D.Vector + +// Text + model +$vector:=$studioEmbedder.embed("some text"; "text-embedding-3-small").vector + +// Text + definition (picks up def.modelAlias) +$vector:=$studioEmbedder.embed("some text"; $def).vector + +// Entity + definition (uses def.phrase + def.modelAlias) +$vector:=$studioEmbedder.embed($student; $def).vector + +// Entity + phrase + explicit model +$vector:=$studioEmbedder.embed($student; $phrase; "text-embedding-3-small").vector + +// Entity + ad-hoc template + model +$vector:=$studioEmbedder.embed($student; "Profile: {firstName} {lastName}"; "text-embedding-3-small").vector + +// Entity alone (auto-resolve, only when exactly one def matches the dataclass) +$vector:=$studioEmbedder.embed($student).vector + +// Entity + stub (deduces phrase + model from the matching saved definition) +$vector:=$studioEmbedder.embed($student; {vectorName: "student_vector_1"}).vector + +// Entity + ad-hoc stub (phrase compiled inline, model taken from the stub) +$vector:=$studioEmbedder.embed($student; {phrase: "Hi {firstName}"; modelAlias: "text-embedding-3-small"}).vector + +// Text + stub that only supplies the model +$vector:=$studioEmbedder.embed("some text"; {modelAlias: "text-embedding-3-small"}).vector +``` + +## Stub resolution + +Both `render()` and `embed()` accept a plain object in place of a `Phrase`/`Definition`. A stub is resolved the same way [`Process`](Process.md#definition-resolution-entity-context) resolves its `definition` argument, so the behavior matches. Two flavors are supported: + +| Stub | Resolves to | +| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `{vectorName: "..."}` (optionally `{dataclassName: "..."}`) | The matching **saved definition** for the entity's dataclass — deducing its phrase (and, for `embed`, its model). Resolves to nothing when there is no unique match. | +| `{phrase: "tpl {field}"}` or `{template: "tpl {field}"}` | An **ad-hoc** `Phrase` compiled inline; nothing is looked up. Pair with `{modelAlias: "..."}` to give `embed()` a model. | + +For `embed()`, the model is deduced in this order: an explicit `{modelAlias}` on the stub → the model of a stub-matched saved definition → the *model* argument → the entity's unique definition. An explicit `{modelAlias}` always wins. + +Unlike [`Process.process()`](Process.md#process-resolution), a stub is **not** turned into a brand-new `Definition` from its fields — `StudioEmbedder` persists nothing, so use `{phrase}`/`{template}` for one-off templates. + +## 参照 + +- [Process](Process.md) +- [Settings](Settings.md) +- [Definition](Definition.md) +- [Embedder](Embedder.md) +- [EmbedderResult](EmbedderResult.md) +- [Phrase](Phrase.md) diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/license.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/license.md new file mode 100644 index 00000000000000..8f6fc0dd2b5ffc --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/license.md @@ -0,0 +1,167 @@ +--- +id: license +title: SOFTWARE LICENSE AGREEMENT +--- + +# SOFTWARE LICENSE AGREEMENT + +## Preamble + +The purpose of this Software license agreement is to grant users the right to modify and re-use the software governed by this license. + +The exercising of this right is conditional upon the obligation to make /available to the community the modifications made to the source code of the software so as to contribute to its evolution. + +In consideration of access to the source code and the rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software's author, the holder of the economic rights, and the successive licensors only have limited liability. + +## Article 1 – DEFINITIONS + +***Agreement***: means this license agreement, and its possible subsequent versions and annexes. + +***Software***: means the software in its Object Code and/or Source Code form and, where applicable, its documentation, "as is" when the Licensee accepts the Agreement. + +***Initial Software***: means the Software in its Source Code and possibly its Object Code form and, where applicable, its documentation, "as is" when it is first distributed under the terms and conditions of the Agreement. + +***Modified Software***: means the Software modified by at least one Integrated Contribution. + +***Source Code***: means all the Software's instructions and program lines to which access is required so as to modify the Software. + +***Object Code***: means the binary files originating from the compilation of the Source Code. + +***Holder***: means the holder(s) of the economic rights over the Initial Software, in this case it is 4D SAS. + +***Licensee***: means the Software user(s) having accepted the Agreement. + +***Contributor***: means a Licensee having made at least one Integrated Contribution. + +***Licensor***: means the Holder, or any other individual or legal entity, who distributes the Software under the Agreement. + +***Integrated Contribution***: means new functions integrated into the Source Code by any or all Contributors. + +***Parties***: mean both the Licensee and the Licensor. + +These expressions may be used both in singular and plural form. + +## Article 2 - PURPOSE + +The purpose of the Agreement is the grant by the Licensor to the Licensee of a non-exclusive, transferable and worldwide license for the Software as set forth in Article 5 hereinafter for the whole term of the protection granted by the rights over said Software. + +## Article 3 - ACCEPTANCE + +The Licensee shall be deemed as having accepted the terms and conditions of this Agreement upon the occurrence of the first of the following events: + +- loading the Software by any or all means, notably, by downloading from a remote server; +- the first time the Licensee exercises any of the rights granted hereunder. + +## Article 4 - EFFECTIVE DATE AND TERM + +### 4.1 EFFECTIVE DATE + +The Agreement shall become effective on the date when it is accepted by the Licensee as set forth in Article 3. + +### 4.2 TERM + +The Agreement shall remain in force for the entire legal term of protection of the economic rights over the Software. + +## Article 5 - SCOPE OF RIGHTS GRANTED + +The Licensor hereby grants to the Licensee, who accepts, the following rights over the Software for the term of the Agreement, on the basis of the terms and conditions set forth hereinafter. + +### 5.1 RIGHT OF USE + +The Licensee is authorized to use the Software, without any limitation as to its fields of application, with it being hereinafter specified that this comprises: + +- permanent or temporary reproduction of all or part of the Software by any or all means and in any or all form. +- loading, displaying, running, or storing the Software on any or all medium. +- entitlement to observe, study or test its operation. + +### 5.2 RIGHT OF MODIFICATION + +The right of modification means the right to adapt, arrange, or make any or all modifications to the Software; being understood that such modifications of the Software shall results in a change of its functionalities and/or in an addition of functionalities to the Initial Software. + +Consequently to distribute a Modified Software according to the provision of section 5.3.2, the Licensee shall make exclusively significant modification as described above to the Software provided that it includes an explicit notice that it is the author of said modification and indicates the date of the creation thereof. + +### 5.3 RIGHT OF DISTRIBUTION + +In particular, the right of distribution includes the right to publish, transmit and communicate the Modified Software to the general public on any or all medium, and by any or all means, and the right to market, either in consideration of a fee, or + +#### 5.3.1 DISTRIBUTION OF SOFTWARE WITHOUT MODIFICATION + +The Licensee is forbidden to distribute true copies of the Software in Source Code or Object Code form. + +#### 5.3.2 DISTRIBUTION OF MODIFIED SOFTWARE + +When the Licensee creates Modified Software, this Modified Software may be distributed provided that said distribution complies with all the provisions of the Agreement and subject to compliance with the requirement to include a notice concerning the rights over the Software as defined in Article 6.3. + +In the event the creation of the Modified Software, the Licensee undertakes that: + +- the resulting Modified Software will be governed by this Agreement, being understood that such Agreement shall be integrated in the Modified Software the Integrated Contributions in the resulting Modified Software will be clearly identified and documented, +- the Licensee will allow effective access to the source code of the Modified Software, at a minimum during the entire period of distribution of the Derivative Software, such that such modifications may be carried over in a subsequent version of the Software. +- the Modified Software must be renamed to exclude any reference to 4D. For example, it is expressly prohibited to distribute a Modified Software named “4D SVG”; Licensee shall rename the Modified Software such as “Name of the Licensee SVG”. Consequently, Licensee is expressly forbidden to use 4D’s product name in general to promote his modified work. + +## Article 6 - INTELLECTUAL PROPERTY + +### 6.1 OVER THE INITIAL SOFTWARE + +The Holder owns the intellectual property rights over the Initial Software. Any or all use of the Initial Software is subject to compliance with the terms and conditions under which the Holder has elected to distribute its work and no one shall be entitled to modify the terms and conditions for the distribution of said Initial Software. + +### 6.2 OVER THE INTEGRATED CONTRIBUTIONS + +The Licensee who develops an Integrated Contribution is the owner of the intellectual property rights over this Contribution as defined by applicable law. + +### 6.3 NOTICE OF RIGHTS + +The Licensee expressly undertakes: + +- not to remove, or modify, in any manner, the intellectual property notices attached to the Software; +- to reproduce said notices, in an identical manner, in the copies of the Software modified; +- to ensure that use of the Software, its intellectual property notices and the fact that it is governed by the Agreement is indicated in a text that is easily accessible, specifically from the interface of any Modified Software. + +The Licensee undertakes not to directly or indirectly infringe the intellectual property rights of the Holder on the Software and to take, where applicable, vis- à-vis its staff, any and all measures required to ensure respect of said intellectual property rights of the Holder. + +## Article 7 - RELATED SERVICES + +Under no circumstances shall the Agreement oblige the Licensor to provide technical assistance or maintenance services for the Software. + +However, the Licensor is entitled to offer this type of services. The terms and conditions of such technical assistance, and/or such maintenance, shall be set forth in a separate instrument. + +## Article 8 - DISCLAIMER OF WARRANTY. + +THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE HOLDER PROVIDES THE SOFTWARE “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH LICENSEE. SHOULD THE SOFTWARE PROVE DEFECTIVE, LICENSEE ASSUMES THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +## Article 9 - LIMITATION OF LIABILITY + +TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE TO LICENSEE ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS AGREEMENT OR USE OF THE SOFTWARE, EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR DAMAGES. + +## Article 10 – TERMINATION + +### 10.1 + +In the event of a breach by the Licensee of its obligations hereunder, the Licensor may automatically terminate this Agreement thirty (30) days after notice has been sent to the Licensee and has remained ineffective. + +### 10.2 + +A Licensee whose Agreement is terminated shall no longer be authorized to use, modify or distribute the Software. However, any licenses that it may have granted prior to termination of the Agreement shall remain valid subject to their having been granted in compliance with the terms and conditions hereof. + +## Article 11 – MISCELLANEOUS + +### 11.1 + +Neither Party shall be liable for any or all delay, or failure to perform the Agreement, that may be attributable to an event of force majeure, an act of God or an outside cause, such as defective functioning or interruptions of the electricity or telecommunications networks, network paralysis following a virus attack, intervention by government authorities, natural disasters, water damage, earthquakes, fire, explosions, strikes and labor unrest, war, etc. + +### 11.2 + +Any failure by either Party, on one or more occasions, to invoke one or more of the provisions hereof, shall under no circumstances be interpreted as being a waiver by the interested Party of its right to invoke said provision(s) subsequently. + +### 11.3 + +In the event that one or more of the provisions hereof were to conflict with a current or future applicable act or legislative text, said act or legislative text shall prevail, and the Parties shall make the necessary amendments so as to comply with said act or legislative text. All other provisions shall remain effective. Similarly, invalidity of a provision of the Agreement, for any reason whatsoever, shall not cause the Agreement as a whole to be invalid. + +## Article 12 - GOVERNING LAW AND JURISDICTION + +### 12.1 + +The Agreement is governed by French law. The Parties agree to endeavor to seek an amicable solution to any disagreements or disputes that may arise during the performance of the Agreement. + +### 12.2 + +Failing an amicable solution within two (2) months as from their occurrence, and unless emergency proceedings are necessary, the disagreements or disputes shall be referred to the Versailles Courts having jurisdiction, by the more diligent Party. \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/overview.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/overview.md new file mode 100644 index 00000000000000..9053d57312e94a --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/overview.md @@ -0,0 +1,211 @@ +--- +id: overview +title: 4D-Embedding-Studio +--- + +# 4D-Embedding-Studio + +## 概要 + +4D Embedding Studio is a component for defining, processing, and maintaining AI embedding vectors directly in your 4D dataclass entities. + +You can use the component without writing a single line of code: select attributes from your dataclasses to construct the sentences to be vectorized and specify the model to use. For each entity, the component calls the embedding API and stores the resulting `4D.Vector` values. Configure the embedding scheduler to (re)calculate the vectors for your data at fixed intervals or on demand. + +You can then use the ORDA [`query()` by vector feature](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity) to request your data using semantics. + +If you want to have more control over your embeddings, the component offers an extensive API that allows you to customize each step of the data vectorization process, manage the scheduler, and integrate high-performance RAG (*Retrieval Augmented Generation*) features into your 4D application. + +## 要件 + +- [4D-AIKit](https://github.com/4d/4D-AIKit) (loaded automatically as a dependency). +- 4D project (21 R5 or later) with the following configuration: + - a valid model alias + - a dataclass with a `4D.Vector` attribute (object field at the database level). + +## Quick Start + +**1. Add a field of type Object to the table and associate it with the `4D.Vector` class.** +**2. Select **Embedding Studio...** in the **Design** menu to display the Embedding Studio window.** + +![menu](../assets/en/embedding-studio/menu.png) + +**3. For each listed `4D.Vector` attribute, write a descriptive phrase based upon attributes of the dataclass.** +Use the contextual menu to insert appropriate attributes. +This phrase will be vectorized for every entity. +**4. Select a model alias (or create a new one).** +**5. Select "Execute now" to launch the vectorization of your data or configure the scheduler.** + +## User Guide + +### Configuring the dataclass + +To use the 4D Embedding Studio interface, you need to create at least one object attribute associated to a `4D.Vector` class in your datastore. This must be done at the database level (only storage attributes can be embeddings). + +In the Structure editor, add an Object field to the dataclass (table) whose entities you want to query using AI and enter ["4D.Vector" as class](https://developer.4d.com/docs/Develop/structure-fields#class). + +#### Dirty-flag support + +In a production application, data is rarely static. If an embedding is based on an attribute value that has changed (e.g. a product description), it becomes obsolete and could no longer be relevant. By default, 4D automatically invalidates and flags for recalculation affected embeddings. + +If you do not use a dirty-flag field (see below), 4D simply replaces any invalidated vector by `Null`. It is therefore no longer used in searches until its next calculation. This option is suitable for applications that prioritize strict consistency: it is better to return no results than to rely on an embedding that no longer matches the current data. + +Or, you can add a Boolean field named `_dirty` (e.g. "myVector_dirty") to the structure. In this case, when an update is required, this field is set to `True`, and the associated vector is retained until it is recalculated. Your application can then choose to continue using this vector temporarily or exclude it using a filter on `dirty = False`. The flag is cleared automatically after a successful save. +This strategy promotes service continuity while allowing you to precisely identify vectors awaiting recalculation. If your business logic requires full control, you can also disable automatic invalidation and manage this lifecycle yourself. + +*Note: Certain modifications, such as a model changes, require vectors to be replaced immediately.* + +### Creating an embedding + +When you select **Embedding Studio...** in the **Design** menu, the Embedding Studio window is displayed. + +The list on the left side shows all `4D.Vector` class attributes defined in the datastore. You can add as many vector attributes as you want per dataclass. + +A check mark (✓) in the Dirty Flag column indicates that a [`_dirty` boolean field](#dirty-flag-support) is associated to the vector field. + +**Note:** Any change in the database structure will require that you restart the 4D application so that the 4D Embedding Studio lists up-to-date values. + +#### Writing a descriptive sentence + +To create or edit an embedding, select the attribute to configure in this list and write the embedding definition in the "Descriptive sentence" area on the right side. Use the associated menu to build the sentence and to add references to dataclass available attributes with the `{attribute_name}` syntax. + +The sentence must build a text that describes the entity just like a human would do it. The embedding could then capturate the semantics and not only attribute values. + +For example, for a `Product` dataclass with many attributes such as name and category, you could write: +"The {name} product is a {category} from the {brand} brand. Description: {description}. Key features: {features}." + +![menu](../assets/en/embedding-studio/studio-interface.png) + +### Selecting a model + +Once you have defined your vector attribute, choose the model to use for generating the embedding. The list of models includes the **model aliases** you defined in the [Project Settings](https://developer.4d.com/docs/settings/ai#model-aliases). + +The choice of model is important because it determines the relevance and quality of your embeddings. You’ll also need to provide this model with every query on the dataclass data so that the comparison is performed using the same model. + +### Auto-invalidate on save + +When this option is checked (default), embeddings are automatically invalidated when at least one of their definition attributes has been modified and the entity was successfully saved. + +However, you might want to handle invalidation in a custom way using the [4D Embedding Studio API](#api-guide). In this case, uncheck this option to disable the automatic mechanism. + +### Calculating embeddings + +Embeddings are calculated by sending a request to the AI model, which then returns the vectorization result, which is subsequently stored in the `4D.Vector` attribute in the dataclass. 4D automatically handles this operation and optimizes it by calculating only the necessary vectors. Each vector is processed independently. Thus, an error on one element does not interrupt the recalculation of the others. Elements that fail will be automatically retried during the next run. Recalculations are performed asynchronously, without blocking users. + +These calculations can be performed **on demand** or **scheduled at regular intervals** using the scheduler in the 4D Embedding Studio component. + +**Note:** You can also customize embedding calculations per dataclass or entity using the [4D Embedding Studio API](#api-guide). + +#### On demand + +To launch an embedding calculation, select **Run now** in the menu at the bottom of the 4D Embedding Studio window. This item is disabled if the datastore does not contain any embedding to calculate. When started, you can select **Cancel run** at any moment. + +#### スケジューラー + +You can configure the 4D Embedding Studio component scheduler to adjust the calculation frequency to suit your application’s needs. + +**Important:** The scheduler needs a 4D worker process to run. You can start it manually for testing purposes (**Start now** button in the scheduler dialog box) but to make sure a worker is available every times the application opens, you need to configure it. これには、次の二つの方法があります: + +- select the **Execute "On Host Database Event" method of the components** option in the [project Settings](https://developer.4d.com/docs/settings/security#options) +- or write the following code in your startup code: + +```4d + //at startup +cs.EmbeddingStudio.Scheduler.me.start() +``` + +The scheduler allows you can set the time interval between two calculations. Select the tab corresponding to your needs and click **Save**. + +- **Never**: the scheduler is off and never runs +- **At regular interval**: set the time interval between each calculation starting from a specified time. +- **Once a day**: the calculation takes place every day at a specific time + starting from a specific time. + +### Building queries with embeddings + +Once you have defined embeddings in your datastore, you can start [querying your dataclasses using AI-based features](https://developer.4d.com/docs/API/DataClassClass#query-by-vector-similarity). You just need to make sure that you use the same model for your embedding definition and in the query string. + +For example, assuming that: + +• you have defined a `4D.Vector` attribute named "product_vector" in the Products dataclass using a sentence: "The {name} is in the {category} category. It has these {features} features and can be used for {usage}." +• you want to find products that "can be used safely outside". + +以下のように書くことができます: + +```4d +// Retrieve the model alias from the embedding definition, configured in 4D Embedding Studio +var $settings:=cs.EmbeddingStudio.Settings.new() +var $definition:=$settings.find("Products"; "product_vector") + +// Compute the vector of the query with the same model +var $result:=cs.EmbeddingStudio.StudioEmbedder.new().embed("products that can be used safely outside"; $definition) +var $vector:=$result.vector + + //search with default metric (cosine) +var $products:=ds.Products.query("product_vector > :1 order by product_vector desc"; {vector : $vector}) + +``` + +If you use a dirty field, simply add a criterion to exclude vectors waiting to be recalculated: + +```4d +var $products:=ds.Products.query("product_vector > :1 and product_vector_dirty = false order by product_vector desc"; {vector : $vector}) +``` + +## API Guide + +### Quick start + +**1. Configure your vectors** in `Settings/embeddings.json`: + +```json +{ + "batchSize": 50, + "definitions": [ + { + "dataclassName": "Students", + "vectorName": "student_vector_1", + "modelAlias": "text-embedding", + "phrase": "Student {firstName} {lastName}, enrolled in {program}", + "autoInvalidate": true + } + ] +} +``` + +**2. Run the full pipeline** (all definitions, all records): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +var $r:=$p.process() + +If ($r.success) + ALERT("Updated "+String($r.entitiesUpdated)+" entities in "+String($r.duration)+" ms") +End if +``` + +**3. Process a single entity on save** (e.g. in a trigger or REST hook): + +```4d +var $p:=cs.EmbeddingStudio.Process.new() +$p.processEntity($entity) +``` + +### Class reference + +| Class | 説明 | +| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Process](Classes/Process.md) | Main orchestrator — entry point for all batch and entity operations. | +| [Scheduler](Classes/Scheduler.md) | Automated recalculation scheduler — background task, force/cancel, and runtime status. | +| [StudioEmbedder](Classes/StudioEmbedder.md) | Renders and embeds on demand using your saved definitions — e.g. to build a search query vector. Nothing is persisted. | +| [Settings](Classes/Settings.md) | Loads and saves the `embeddings.json` configuration file. | +| [Definition](Classes/Definition.md) | Describes one vector field: dataclass, field name, model alias, and phrase template. | +| [Embedder](Classes/Embedder.md) | Thin wrapper around the AIKit embeddings API with retry/backoff logic. | +| [EmbedderResult](Classes/EmbedderResult.md) | Typed wrapper normalizing API responses — vectors, usage metrics, rate-limit state. | +| [ProcessResult](Classes/ProcessResult.md) | Returned by every batch function — statistics and error breakdown. | +| [ProcessError](Classes/ProcessError.md) | Typed entry in `ProcessResult.errors` — scope, severity, code, ref, message, retryable. | +| [ProcessErrorCode](Classes/ProcessErrorCode.md) | Singleton catalogue of machine-readable error codes and their default severity/retryability. | +| [Phrase](Classes/Phrase.md) | Lightweight `{variable}` template engine used to build text from entity attributes. | + +### 参照 + +Blog post: [Vectorize your data effortlessly with 4D Embedding Studio](https://blog.4d.com/vectorize-your-data-effortlessly-with-4d-vector-studio) \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/ratelimit.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/ratelimit.md new file mode 100644 index 00000000000000..00f50ec3d2bb7d --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/ratelimit.md @@ -0,0 +1,65 @@ +--- +id: ratelimit +title: Rate Limiting +--- + +# Rate Limiting + +The embedding pipeline includes built-in rate-limit awareness. When the API provider returns rate-limit headers (as OpenAI does), the system automatically throttles requests and adapts batch sizes to stay within budget. Providers that don't return rate-limit headers (e.g. Ollama) are unaffected — the pipeline runs at full speed. + +## 動作 + +Each call to [`Embedder.embed()`](Classes/Embedder.md) or [`Embedder.embedBatch()`](Classes/Embedder.md) returns an [`EmbedderResult`](Classes/EmbedderResult.md) that carries rate-limit state alongside the embedding vectors. The pipeline uses this data in a three-step loop: + +1. **Pre-flight throttle** — before sending a batch, the pipeline checks whether the remaining token budget is sufficient. If not, it waits for the reset window to elapse before proceeding. +2. **Adaptive batch sizing** — the pipeline computes the largest batch that fits within 80% of the remaining token budget. This avoids hitting the ceiling while still making efficient use of the quota. +3. **State update** — after each API response, the pipeline records the new remaining budget, computes an average tokens-per-entity estimate, and feeds both into the next iteration. + +## Rate-limit fields on EmbedderResult + +These fields are populated from the API response headers. When a provider doesn't return them, they keep their defaults and the pipeline skips throttling. + +| フィールド | デフォルト | 意味 | +| ------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `remainingTokens` | `-1` | Tokens left in the current window. `-1` = unknown. | +| `remainingRequests` | `-1` | Requests left in the current window. | +| `limitTokens` | `0` | TPM (tokens per minute) ceiling. | +| `limitRequests` | `0` | RPM (requests per minute) ceiling. | +| `resetTokens` | `""` | Time until the token bucket refills (e.g. `"6m0s"`, `"200ms"`). | +| `resetRequests` | `""` | Time until the request bucket refills. | + +## Batch size adaptation + +The pipeline starts with the configured `batchSize` (from [Settings](Classes/Settings.md), default 50). After the first API response provides rate-limit data, the batch size may shrink: + +``` +nextBatchSize = min( floor(remainingTokens × 0.8 / tokensPerEntity), configBatchSize ) +``` + +- `tokensPerEntity` is estimated from the last chunk (`totalTokens / chunkSize`). +- The result is clamped to a floor of 1 and a ceiling of `configBatchSize`. +- When `remainingTokens` is unknown (`-1`), the configured batch size is used as-is. + +## Pre-flight wait + +Before each batch, the pipeline checks: + +- **Token budget**: if `remainingTokens < estimatedTokens × 1.1`, it waits for the token reset window. +- **Request budget**: if `remainingRequests = 0`, it waits for the request reset window. + +The reset durations are parsed from the API's string format (`"6m0s"` → 360 seconds, `"200ms"` → 1 second). + +## Providers without rate limits + +Some providers (Ollama, local models) don't return rate-limit headers. この場合において: + +- `remainingTokens` stays at `-1` (unknown) +- No throttling occurs — batches run at `configBatchSize` without waits +- The pipeline works identically to how it did before rate-limit support was added + +## 参照 + +- [EmbedderResult](Classes/EmbedderResult.md) — carries rate-limit fields +- [Embedder](Classes/Embedder.md) — wraps the API calls +- [Process](Classes/Process.md) — orchestrates the batch loop +- [Settings](Classes/Settings.md) — `batchSize` configuration diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md index f10aa51e0cb74d..70b24c93bea689 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md @@ -791,7 +791,7 @@ QUERY BY FORMULA Joinsセレクタで、カレントプロセスの、フォー **取り得る値**: 正の整数。デフォルト値 = 900、最小値 = 60。 -**説明**: QUICネットワーク層を使用した場合に、予期しない切断が発生した際のクライアント/サーバーセッションのタイムアウト秒数。このタイムアウトは、意図しない切断の後にサーバーとクライアント間の接続が自動的に再確立できるセッションの許容期間です。このタイムアウト終了時に接続が再確立されていない場合、セッションは閉じられます。 +**説明**: QUICネットワーク層を使用した場合に、予期しない切断が発生した際のクライアント/サーバーセッションのタイムアウト秒数。このタイムアウトは、意図しない切断の後にサーバーとクライアント間の接続が自動的に再確立できるセッションの許容期間です。このタイムアウト終了時に接続が再確立されていない場合、クライアントセッションはメッセージとともに閉じられます。 この設定は4D Server上でのみ設定可能であり、すべての新しい4Dリモートセッションに適用されます(既存のセッションのタイムアウト値は変更されません)。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md index ea690f520386d0..0a98160da94d8e 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md @@ -32,7 +32,7 @@ displayed_sidebar: docs **FORM Get current page**コマンドは、現在表示されているフォームページ、または[FORM LOAD](../commands/form-load) コマンドによってロードされたカレントフォームの番号を返します。 -*\** 引数は、複数のページを含むサブフォームタイプのページのコンテキストでコマンドが呼び出される場合に使用します。この場合、この引数を渡すと、コマンドは (コマンドを呼び出した) カレントサブフォームのページを変更します。*\** が省略された場合、デフォルトでコマンドは常に親フォームに適用されます。 +*\** 引数は、複数のページを含むサブフォームタイプのページのコンテキストでコマンドが呼び出される場合に使用します。この場合、この引数を渡すと、コマンドは (コマンドを呼び出した) カレントサブフォームのページ番号を返します。*\** が省略された場合、デフォルトでコマンドは常に親フォームに適用されます。 ## 例題 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md index bd03ee2ebd814e..48b333bdbca799 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md @@ -45,6 +45,16 @@ displayed_sidebar: docs | ------- | ---- | ----------------------------------------------------------------------------- | | context | Text | エンティティセレクションに適用されている [最適化コンテキスト](../../ORDA/client-server-optimization.md) のラベル。 | +:::info + +パフォーマンス上の理由から、4D シングルユーザーおよび 4D Server では、返されるエンティティセレクションは *dsTable* のカレントセレクションに直接接続されています (コピーではありません)。 カレントセレクションが置き換えられるまでは、一方に加えた変更がもう一方にも反映されます。 たとえば、[`REDUCE SELECTION`](../commands/reduce-selection) はエンティティセレクションを縮小し、エンティティセレクションに対する [`.add()`](../../API/EntitySelectionClass.md#add) はカレントセレクションにエンティティを追加します。 独立したエンティティセレクションを取得するには、戻り値に対して [`.copy()`](../../API/EntitySelectionClass.md#copy) を呼び出します: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## 例題 ```4d diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/API/CollectionClass.md b/i18n/pt/docusaurus-plugin-content-docs/current/API/CollectionClass.md index 2d4ab49d54ec33..a26d4aac064572 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/API/CollectionClass.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/API/CollectionClass.md @@ -272,13 +272,12 @@ Por padrão, os elementos *col2* são adicionados ao final da coleção original var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` - ## .concat()
História diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/API/DataStoreClass.md b/i18n/pt/docusaurus-plugin-content-docs/current/API/DataStoreClass.md index 45fe7ccb6c9d7b..10608d7174a5d2 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/API/DataStoreClass.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/API/DataStoreClass.md @@ -17,14 +17,19 @@ Um [Datastore](ORDA/dsMapping.md#datastore) é o objeto de interface fornecido p | [](#dataclassname)
| | [](#encryptionstatus)
| | [](#flushandlock)
| +| [](#generatefinegrainedtoken)
| | [](#getallremotecontexts)
| | [](#getglobalstamp)
| | [](#getinfo)
| | [](#getremotecontextinfo)
| | [](#getrequestlog)
| +| [](#listfinegrainedtokens)
| +| [](#listoauthgrants)
| | [](#locked)
| | [](#makeselectionsalterable)
| | [](#providedatakey)
| +| [](#revokefinegrainedtoken)
| +| [](#revokeoauthgrant)
| | [](#setadminprotection)
| | [](#setglobalstamp)
| | [](#setremotecontextinfo)
| @@ -292,6 +297,80 @@ ds.unlock() //Nossa cópia terminou, podemos desbloquear a datastore [.locked()](#locked)
[.unlock()](#unlock) + +## .generateFineGrainedToken() + +
História + +| Release | Mudanças | +| ------- | ---------- | +| 21 R6 | Adicionado | + +
+ +**.generateFineGrainedToken**( *privilege* : Text ; *name* : Text {; *expiry* : Date {; *info* : Object}} ) : Object
**.generateFineGrainedToken**( *privileges* : Collection ; *name* : Text {; *expiry* : Date {; *info* : Object}} ) : Object
**.generateFineGrainedToken**( *settings* : Object ; *name* : Text {; *expiry* : Date {; *info* : Object}} ) : Object + + +
+ +|Parâmetro|Tipo||Descrição| +|---|---|---|---| +|privilege|Text|→|Nome do privilégio, ou nomes de privilégios separados por vírgula| +|privileges|Collection|→|Coleção de nomes de privilégios| +|settings|Object|→|Objeto com uma propriedade "privileges" e/ou "roles"| +|name|Text|→|Nome do token| +|expiry|Date|→|Data de expiração do token| +|info|Object|→|Informações armazenadas com o token e passadas para `ds.mcpAuthenticated()`| +|Result|Object|←|`{id; token}`| +
+ + +#### Descrição + +A função `.generateFineGrainedToken()` gera um Fine-Grained Token que dá acesso ao servidor MCP com os privilégios que você passar. Para mais informações, veja [Fine-Grained Tokens](../WebServer/mcp-server.md#fine-grained-tokens). + +Você passa os privilégios e/ou roles do token nas mesmas formas que para [`Session.setPrivileges()`](SessionClass.md#setprivileges): + +- No parâmetro *privilege*, passe uma string contendo um nome de privilégio (ou vários nomes de privilégios separados por vírgula). +- No parâmetro *privileges*, passe uma coleção de strings contendo nomes de privilégios. +- No parâmetro *settings*, passe um objeto com uma propriedade `privileges` e/ou `roles` (string ou coleção de strings). + +Diferente de `Session.setPrivileges()`, um nome que não está declarado no arquivo [`roles.json`](../ORDA/privileges.md#rolesjson-file) gera um erro. + +Em *name*, passe um nome que identifica o token, por exemplo o usuário e o cliente que irá utilizá-lo. É o nome de usuário das sessões MCP abertas com o token. + +Em *expiry*, passe a data de expiração do token. Deve ser posterior à data atual e no máximo 366 dias à frente. Se *expiry* for omitido, um erro será gerado. + +Em *info*, você pode passar um objeto que o 4D armazena com o token como está, e passa para a função [`ds.mcpAuthenticated()`](../ORDA/ordaClasses.md#function-mcpauthenticated) quando uma sessão MCP é aberta com o token. Como não pode ser modificado depois, armazene identificadores estáveis (como um ID de usuário) e leia os valores atuais em `ds.mcpAuthenticated()`. Construa *info* a partir da sessão autenticada, nunca de valores enviados pelo cliente. + +A função só pode ser chamada em contexto web, ou seja, a partir de código executado para uma requisição web ou REST (por exemplo, uma função exposta chamada após o usuário ser autenticado). Todo privilégio do token deve ser detido pela sessão atual ([`Session.getPrivileges()`](SessionClass.md#getprivileges), incluindo roles, excluindo privilégios promovidos). Caso contrário, um erro é gerado. + +Se um erro for gerado, nenhum token é criado. + +**Objeto retornado** + +|Propriedade|Tipo|Descrição| +|---|---|---| +|id|Text|Identificador do token. Não é secreto: use para [revogar](#revokefinegrainedtoken) o token| +|token|Text|O token, começando com "4dfgt_". Ele é retornado apenas uma vez: o 4D armazena apenas seu hash, no arquivo `fgt.json` da pasta de dados| + +#### Exemplo + +Em uma função exposta da classe DataStore, chamada por um usuário autenticado, você gera um token válido por 3 meses: + +```4d +exposed Function getMCPToken() : Text + var $expiry:=Add to date(Current date; 0; 3; 0) + var $result:=ds.generateFineGrainedToken({roles: "salesperson"}; "Claude Desktop - "+Session.userName; $expiry; {userName: Session.userName}) + return $result.token // "4dfgt_..." +``` + +#### Veja também + +[.listFineGrainedTokens()](#listfinegrainedtokens)
[.revokeFineGrainedToken()](#revokefinegrainedtoken) + + + ## .getAllRemoteContexts()
História @@ -625,6 +704,110 @@ Por padrão, o acesso ao Data Explorer é concedido para sessões `webAdmin`, ma + +## .listFineGrainedTokens() + +
História + +| Release | Mudanças | +| ------- | ---------- | +| 21 R6 | Adicionado | + +
+ +**.listFineGrainedTokens**() : Collection + + +
+ +|Parâmetro|Tipo||Descrição| +|---|---|---|---| +|Result|Collection|←|Coleção de objetos de descrição de token| +
+ + +#### Descrição + +A função `.listFineGrainedTokens()` retorna a descrição dos Fine-Grained Tokens gerados para o servidor MCP (veja [`.generateFineGrainedToken()`](#generatefinegrainedtoken)). + +Quando a função é chamada em contexto web (código executado para uma requisição web ou REST), a coleção contém apenas os tokens cujos privilégios são todos detidos pela sessão atual. Em outros lugares (por exemplo, em um método ou procedimento armazenado), contém todos os tokens. + +Cada objeto da coleção retornada contém as seguintes propriedades. O token em si e seu hash nunca são retornados. + +|Propriedade|Tipo|Descrição| +|---|---|---| +|id|Text|Identificador do token| +|name|Text|Nome do token| +|privileges|Text, Collection ou Object|Privilégios e roles do token, conforme passado na geração| +|expiry|Text|Data de expiração do token| +|info|Object|Informações armazenadas com o token| +|createdAt|Text|Data e hora da geração do token| + +#### Exemplo + +Você revoga todos os tokens gerados para um usuário: + +```4d +var $tokens:=ds.listFineGrainedTokens().query("info.userName = :1"; "jsmith") +var $token : Object +For each ($token; $tokens) + ds.revokeFineGrainedToken($token.id) +End for each +``` + + + + +## .listOAuthGrants() + +
História + +| Release | Mudanças | +| ------- | ---------- | +| 21 R6 | Adicionado | + +
+ +**.listOAuthGrants**() : Collection + + +
+ +|Parâmetro|Tipo||Descrição| +|---|---|---|---| +|Result|Collection|←|Coleção de objetos de descrição de grant| +
+ + +#### Descrição + +A função `.listOAuthGrants()` retorna a descrição dos grants dados a usuários através do modo OAuth do servidor MCP. Um grant é criado cada vez que um usuário faz login a partir de um cliente MCP (veja [OAuth 2.1 mode](../WebServer/mcp-server.md#oauth-21-mode)). + +Quando a função é chamada em contexto web (código executado para uma requisição web ou REST), a coleção contém apenas os grants cujos privilégios são todos detidos pela sessão atual. Em outros lugares, contém todos os grants. + +Cada objeto da coleção retornada contém as seguintes propriedades: + +|Propriedade|Tipo|Descrição| +|---|---|---| +|id|Text|Identificador do grant| +|userName|Text|Nome de usuário do grant (`userName` retornado por [`ds.mcpGrant()`](../ORDA/ordaClasses.md#function-mcpgrant), ou o nome de login)| +|clientId|Text|Identificador do cliente MCP| +|clientName|Text|Nome do cliente MCP| +|privileges|Text, Collection ou Object|Privilégios e roles retornados por `ds.mcpGrant()`| +|createdAt|Text|Data e hora do login| +|lastUsedAt|Text|Data e hora do último uso do grant| +|expiresAt|Text|Data e hora de expiração do grant| + +#### Exemplo + +Você lista os clientes MCP nos quais um usuário está logado: + +```4d +var $clients:=ds.listOAuthGrants().query("userName = :1"; "jsmith").extract("clientName") +``` + + + ## .locked()
História @@ -781,6 +964,112 @@ Se nenhuma *curPassphrase* ou *curDataKey* for fornecida, `.provideDataKey()` re + +## .revokeFineGrainedToken() + +
História + +| Release | Mudanças | +| ------- | ---------- | +| 21 R6 | Adicionado | + +
+ +**.revokeFineGrainedToken**( *id* : Text ) : Boolean
**.revokeFineGrainedToken**( *tokenObj* : Object ) : Boolean + + +
+ +|Parâmetro|Tipo||Descrição| +|---|---|---|---| +|id|Text|→|Identificador do token a ser revogado| +|tokenObj|Object|→|Objeto com uma propriedade `token` contendo o token a ser revogado| +|Result|Boolean|←|True se o token foi revogado| +
+ + +#### Descrição + +A função `.revokeFineGrainedToken()` revoga um Fine-Grained Token do servidor MCP. + +Você designa o token: + +- no parâmetro *id*, com seu identificador (retornado por [`.generateFineGrainedToken()`](#generatefinegrainedtoken) e [`.listFineGrainedTokens()`](#listfinegrainedtokens)), +- ou no parâmetro *tokenObj*, com um objeto cuja propriedade `token` contém o próprio token (`"4dfgt_..."`), por exemplo para permitir que o detentor de um token o revogue. + +A função retorna **True** se o token foi revogado, **False** caso contrário (por exemplo, se o token não existir ou já tiver sido revogado). + +O token para de funcionar na próxima requisição, e as sessões MCP abertas com ele são fechadas. [Binary URLs](../WebServer/mcp-server.md#binary-attributes) já retornadas ao cliente permanecem válidas até expirarem (no máximo 10 minutos). + +Quando a função é chamada em contexto web (código executado para uma requisição web ou REST), ela só pode revogar um token cujos privilégios são todos detidos pela sessão atual. + +#### Exemplo + +Você revoga um token pelo seu id: + +```4d +var $tokens:=ds.listFineGrainedTokens().query("name = :1"; "Claude Desktop - jsmith") +If ($tokens.length>0) + ds.revokeFineGrainedToken($tokens[0].id) +End if +``` + +#### Veja também + +[.generateFineGrainedToken()](#generatefinegrainedtoken)
[.listFineGrainedTokens()](#listfinegrainedtokens) + + + + +## .revokeOAuthGrant() + +
História + +| Release | Mudanças | +| ------- | ---------- | +| 21 R6 | Adicionado | + +
+ +**.revokeOAuthGrant**( *id* : Text ) : Boolean + + +
+ +|Parâmetro|Tipo||Descrição| +|---|---|---|---| +|id|Text|→|Identificador do grant a ser revogado| +|Result|Boolean|←|True se o grant foi revogado| +
+ + +#### Descrição + +A função `.revokeOAuthGrant()` revoga um grant dado a um usuário através do modo OAuth do servidor MCP (veja [`.listOAuthGrants()`](#listoauthgrants)). + +A função retorna **True** se o grant foi revogado, **False** caso contrário (por exemplo, se o grant não existir ou já tiver sido revogado). + +Os access tokens do grant recebem um status HTTP 401 a partir da próxima requisição, seu refresh token é recusado, e suas sessões MCP são fechadas. O usuário deve fazer login novamente a partir do cliente MCP. + +Quando a função é chamada em contexto web (código executado para uma requisição web ou REST), ela só pode revogar um grant cujos privilégios são todos detidos pela sessão atual. + +#### Exemplo + +Quando você desativa um usuário da sua aplicação, você revoga seus grants OAuth: + +```4d +var $grant : Object +For each ($grant; ds.listOAuthGrants().query("userName = :1"; "jsmith")) + ds.revokeOAuthGrant($grant.id) +End for each +``` + +#### Veja também + +[.listOAuthGrants()](#listoauthgrants)
[.revokeFineGrainedToken()](#revokefinegrainedtoken) + + + ## .setAdminProtection() @@ -908,7 +1197,7 @@ ds.setGlobalStamp($newValue) | dataClassName | Text | -> | Nome da dataclass | | dataClassObject | 4D. DataClass | -> | dataclass object (e.g datastore. Employee) | | attributes | Text | -> | Lista de atributos separada por vírgulas | -| Atributos do tipo BLOB não são gerenciados na datastore. | Collection | -> | Coleção de nomes de atributos (text) | +| attributesColl | Collection | -> | Coleção de nomes de atributos (text) | | contextType | Text | -> | Se fornecido, o valor deve ser "main" ou "currentItem" | | pageLength | Integer | -> | Page length of the entity selection linked to the context (default is 80) | diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/API/MCPContextClass.md b/i18n/pt/docusaurus-plugin-content-docs/current/API/MCPContextClass.md new file mode 100644 index 00000000000000..e09e785f79bd68 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/API/MCPContextClass.md @@ -0,0 +1,305 @@ +--- +id: MCPContextClass +title: MCPContext +--- + +A classe `MCPContext` fornece informações sobre a chamada atual de uma ferramenta do [servidor MCP](../WebServer/mcp-server.md) e permite que a ferramenta solicite ao usuário uma confirmação ou valores antes de executar uma ação (consulte [Solicitando confirmação do usuário](../WebServer/mcp-server.md#asking-the-user-for-confirmation)). + +
Histórico + +|Versão|Alterações| +|---|---| +|21 R6|Classe adicionada| + +
+ +### Objeto MCPContext + +Objetos `MCPContext` são retornados pelo comando [`MCP`](../commands/mcp). + +O objeto é anexado ao processo enquanto uma função de [ferramenta personalizada](../WebServer/mcp-server.md#custom-tools) é executada, e está disponível nos métodos e funções chamados por essa função. Em qualquer outro lugar (por exemplo, em uma requisição REST ou em um método executado a partir do ambiente 4D), o objeto é inerte: suas funções não fazem nada e suas propriedades ficam vazias. + +### Resumo + +|| +|---| +|[](#bound)
| +|[](#canelicit)
| +|[](#clientinfo)
| +|[](#error)
| +|[](#hasinput)
| +|[](#input)
| +|[](#requireinput)
| +|[](#toolname)
| + + + + +## .bound + +**.bound** : any + +#### Descrição + +A propriedade `.bound` contém o valor *bind* passado para `.requireInput()` quando a entrada foi solicitada, conforme verificado pelo 4D. + +O valor retorna assinado junto com as respostas do usuário, assim a função pode compará-lo com o valor atual e detectar uma alteração que ocorreu enquanto o usuário respondia (por exemplo, uma entity modificada). Fica vazio quando a chamada não traz respostas verificadas. + +O valor *bind* é assinado, não criptografado: o cliente pode lê-lo. + +Esta propriedade é **somente leitura**. + +#### Exemplo + +Você verifica se a entity não foi modificada enquanto o usuário confirmava sua exclusão: + +```4d +If (MCP.bound#This.getStamp()) + MCP.error("The record was modified, please try again") + return +End if +``` + + + + + +## .canElicit + +**.canElicit** : Boolean + +#### Descrição + +A propriedade `.canElicit` contém **True** se o cliente MCP pode exibir formulários de entrada (declarou a capacidade `elicitation` na requisição), e **False** caso contrário ou fora de uma chamada de ferramenta MCP. + +Quando `.canElicit` é **False**, [`.requireInput()`](#requireinput) não solicita nada e a chamada retorna o erro "This action requires a confirmation your client cannot display". + +Esta propriedade é **somente leitura**. + +#### Exemplo + +Você retorna uma mensagem clara quando o cliente não pode exibir a confirmação: + +```4d +If (Not(MCP.canElicit)) + MCP.error("Please confirm this action from the application") + return +End if +``` + + + + + +## .clientInfo + +**.clientInfo** : Object + +#### Descrição + +A propriedade `.clientInfo` contém informações sobre o cliente MCP que enviou a requisição, conforme fornecido nos metadados (`_meta`) da requisição, por exemplo, seu nome e versão. É *Null* fora de uma chamada de ferramenta MCP. + +Esta propriedade é **somente leitura**. + +#### Exemplo + +Você registra o cliente que chamou a ferramenta: + +```4d +var $client:=MCP.clientInfo +If ($client#Null) + LOG EVENT(Into 4D debug message; "MCP call from "+String($client.name)) +End if +``` + + + + + +## .error() + +**.error**( { *message* : Text } ) + + +
+ +|Parâmetro|Tipo||Descrição| +|---|---|---|---| +|message|Text|→|Mensagem de erro retornada ao cliente| +
+ + +#### Descrição + +A função `.error()` faz com que a chamada atual da ferramenta retorne um resultado de erro com *message*. O resultado tem `isError: true`, e o valor retornado pela função é ignorado. Se *message* for omitido, a mensagem de erro fica vazia. + +`.error()` não interrompe a execução da função: chame `return` após ela, se necessário. + +Fora de uma chamada de ferramenta MCP, `.error()` não faz nada. + +#### Exemplo + +Você recusa um valor muito alto: + +```4d +exposed MCP Function refund($amount : Real) : Text + If ($amount>1000) + MCP.error("Refunds over 1000 must be done by an accountant") + return + End if + // ... +``` + + + + + +## .hasInput() + +**.hasInput**( { *name* : Text } ) : Boolean + + +
+ +|Parâmetro|Tipo||Descrição| +|---|---|---|---| +|name|Text|→|Nome de um campo solicitado com `.requireInput()`| +|Result|Boolean|←|True se o usuário respondeu este campo (ou qualquer campo se *name* for omitido)| +
+ + +#### Descrição + +A função `.hasInput()` retorna **True** se a chamada atual contém uma resposta verificada do usuário para o campo *name*. + +Se *name* for omitido ou vazio, `.hasInput()` retorna **True** se a chamada atual contém uma resposta verificada do usuário para pelo menos um campo. + +A resposta é verificada quando o cliente chama a ferramenta novamente com as respostas e um `requestState` válido: assinado pelo 4D para o mesmo token, ferramenta, argumentos e campos, há menos de 10 minutos, e desde que o servidor MCP foi ativado pela última vez. Caso contrário, `.hasInput()` retorna **False**. + +Fora de uma chamada de ferramenta MCP, `.hasInput()` retorna **False**. + +#### Exemplo + +Você solicita uma confirmação apenas se o usuário ainda não respondeu: + +```4d +If (Not(MCP.hasInput("confirm"))) + MCP.requireInput({confirm: {type: "boolean"; title: "Send the invoice to the customer"}}) + return +End if +``` + + + + + +## .input + +**.input** : Object + +#### Descrição + +A propriedade `.input` contém as respostas verificadas do usuário, uma propriedade para cada campo solicitado com `.requireInput()`. Apenas respostas cujo tipo corresponde ao tipo do campo solicitado são mantidas. + +Não contém nenhuma resposta quando a chamada não traz respostas verificadas, ou fora de uma chamada de ferramenta MCP. + +Esta propriedade é **somente leitura**. + +#### Exemplo + +Você utiliza o comentário inserido pelo usuário: + +```4d +If (MCP.hasInput("comment")) + This.closingComment:=MCP.input.comment +End if +``` + + + + + +## .requireInput() + +**.requireInput**( *fields* : Object {; *bind* : any} ) : Object + + +
+ +|Parâmetro|Tipo||Descrição| +|---|---|---|---| +|fields|Object|→|Mensagem e campos a serem exibidos para o usuário| +|bind|any|→|Valor assinado com as respostas, retornado em `.bound`| +|Result|Object|←|*Null* quando a entrada é solicitada| +
+ + +#### Descrição + +A função `.requireInput()` solicita ao usuário, através do cliente MCP, o preenchimento de um formulário antes que a ferramenta continue. + +Em *fields*, passe um objeto com: + +- uma propriedade opcional `message` (Text): o texto exibido para o usuário, +- uma propriedade para cada campo a ser exibido, cujo nome é o nome do campo e cujo valor é o JSON Schema de um campo `"boolean"`, `"string"`, `"number"` ou `"integer"` (por exemplo, `{type: "boolean"; title: "Confirm"}`). Um campo é obrigatório, a menos que seu schema contenha `required: False`. + +Quando a função da ferramenta retorna, o 4D responde à chamada com `resultType: "input_required"`, o formulário e um `requestState` assinado pelo 4D. O cliente exibe o formulário e, em seguida, chama a ferramenta novamente com as respostas. A função então é executada novamente **desde o início**: [`.hasInput()`](#hasinput) retorna **True** para os campos respondidos e [`.input`](#input) contém as respostas. Se as respostas já estiverem presentes e *bind* tiver o mesmo valor de quando a entrada foi solicitada, `.requireInput()` não solicita novamente. + +Em *bind*, você pode passar um valor para vincular às respostas, como o stamp de uma entity: ele é assinado junto com as respostas e retornado em [`.bound`](#bound) quando o cliente chama a ferramenta novamente, para que você possa verificar se nada mudou nesse meio tempo. Se *bind* mudou, a entrada é solicitada novamente. + +Se o cliente não puder exibir formulários (consulte [`.canElicit`](#canelicit)), `.requireInput()` não solicita nada e a chamada retorna o erro "This action requires a confirmation your client cannot display". + +Fora de uma chamada de ferramenta MCP, `.requireInput()` não solicita nada e retorna *Null*. + +:::caution + +Não solicite segredos como senhas com `.requireInput()`: as respostas passam pelo cliente de IA. + +::: + +#### Exemplo + +Você solicita ao usuário a confirmação do fechamento de um ticket e a inserção de um comentário opcional: + +```4d +// cs.TicketEntity class +Class extends Entity + +exposed MCP Function close() : Text + If (Not(MCP.hasInput("confirm"))) + MCP.requireInput({message: "Close ticket "+String(This.ID)+"?"; confirm: {type: "boolean"; title: "Close"}; comment: {type: "string"; title: "Comment"; required: False}}; This.getStamp()) + return + End if + If (MCP.input.confirm) + This.status:="closed" + This.comment:=String(MCP.input.comment) + This.save() + End if + return This.status +``` + + + + + +## .toolName + +**.toolName** : Text + +#### Descrição + +A propriedade `.toolName` contém o nome da ferramenta MCP sendo chamada, por exemplo `"OrderManager-getYearTotal"`. É uma string vazia fora de uma chamada de ferramenta MCP. + +Esta propriedade é **somente leitura**. + +#### Exemplo + +Você executa um método apenas quando ele é chamado por uma ferramenta MCP: + +```4d +If (MCP.toolName#"") + // called from an MCP tool +End if +``` + + diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/Notes/updates.md b/i18n/pt/docusaurus-plugin-content-docs/current/Notes/updates.md index 7a00fc6a504c48..ea76fd764fa780 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/Notes/updates.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/Notes/updates.md @@ -142,12 +142,11 @@ Leia [**O que há de novo no 4D v21 R2**](https://blog.4d.com/whats-new-in-4d-21 | ICU | 77.1 | 21 | This upgrade forces an automatic rebuild of alphanumeric, text and object indexes. | | libldap | 2.6.10 | 21 | | | libsasl | 2.1.28 | 20 | | -| Liblsquic | 4.2.0 | 20 R10 | Usado para QUIC | -| Libuv | 1.53.0 | **21 R5** | Usado para QUIC | +| Libuv | 1.53.0 | 21 R5 | Usado para QUIC | | libZip | 1.11.4 | 21 | Utilizado pelos componentes zip class, 4D Write Pro, svg e serverNet | | LZMA | 5.8.1 | 21 | | -| ngtcp2 | 1.24.0 | 21 R4 | Usado para QUIC | -| OpenSSL | 4.0.3 | **21 R5** | | +| ngtcp2 | 1.26.0 | **21 R6** | Usado para QUIC | +| OpenSSL | 4.0.3 | 21 R5 | | | PDFWriter | 4.7.0 | 21 | Used for [`WP Export document`](../WritePro/commands/wp-export-document.md) and [`WP Export variable`](../WritePro/commands/wp-export-variable.md) | | SpreadJS | 18.2.0 | 21 R2 | Veja [este post de blog](https://blog.4d.com/4d-view-pro-whats-new-in-4d-21-r2/) para uma visão geral dos novos recursos | | webKit | WKWebView | 19 | | diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/ViewPro/configuring.md b/i18n/pt/docusaurus-plugin-content-docs/current/ViewPro/configuring.md index 2b0f096090d0e1..4ad6a2a83e1836 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/ViewPro/configuring.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/ViewPro/configuring.md @@ -11,9 +11,9 @@ Using the area's property list, you can set [4D View Pro object properties](Form ![](../assets/en/ViewPro/vpPropertyList.png) -### Selecção de uma interface utilizador +### Selecionando uma interface de usuário -Puede seleccionar la interfaz a utilizar con sus áreas de formulario 4D View Pro en la **Lista de propiedades**, en **Apariencia**: +Você pode selecionar a interface a ser usada com suas áreas de formulário 4D View Pro na **Lista de Propriedades**, em **Aparência**: ![](../assets/en/ViewPro/vpUserInterface.PNG) @@ -35,17 +35,17 @@ Com barra de fórmula visível: #### Funcionalidades -Tanto os recursos relacionados ao Ribbon como o grupo da interface de ferramentas (toolbar) nas abas: +Tanto os recursos relacionados ao Ribbon como o grupo da interface de ferramentas (toolbar) nas abas: -| Tab | Acções | Interface Ribbon | Interface da barra de ferramentas | -| -------- | -------------------------------- | :--------------: | :-------------------------------: | -| File | Manipulação de ficheiros | X | | -| Inicio | Aspecto do texto | X | X | -| Inserir | Adicionar itens | X | X | -| Fórmulas | Cálculo de fórmulas e biblioteca | X | X | -| Dados | Manipulação de dados | X | X | -| Mostrar | Apresentação visual | X | X | -| Settings | Presentação da folha | X | | +|Tab| Actions |Ribbon Interface| Toolbar Interface| +|---|---|:---:|:---:| +|File|File manipulation|X| | +|Home|Text appearance|X|X| +|Insert|Add items| X| X| +|Formulas|Formula calculation and library| X|X| +|Data|Data manipulation|X| X| +|View|Visual presentation| X| X| +|Settings|Sheet presentation reference|X| | ## Eventos formulário @@ -157,7 +157,8 @@ Formatos de números se aplicam a todos os tipos de números (por exemplo, posit #### Exemplo ```4d -//Set the cell value as $125,571.35 VP SET VALUE(VP Cell("ViewProArea";3;2);New object("value";125571.35;"format";"_($* #,##0.00_)") +//Set the cell value as $125,571.35 +VP SET VALUE(VP Cell("ViewProArea";3;2);New object("value";125571.35;"format";"_($* #,##0.00_)") ``` ### Formatos data e hora @@ -172,14 +173,15 @@ Formatos de números se aplicam a todos os tipos de números (por exemplo, posit | `vk pattern month day` | "*monthDayPattern*" | Formato ISO 8601 para o mês e dia no padrão da localização atual: "MMMM dd" | | `vk pattern short date` | "*shortDatePattern*" | Formato ISO 8601 abreviado para a data na data atual de localização.USA padrão padrão: "MM/dd/yyyy" | | `vk pattern short time` | "*shortTimePattern*" | Formato abreviado ISO 8601 para a hora no padrão de localização.EUA atual: "HH:mm" | -| `vk pattern sortable date time` | "*sortableDateTimePattern*" | Formato ISO 8601 para a data e hora na localização atual que pode ser classificado.EUA padrão padrão: "yyyy\'-\'MM\'dd\'T\'H\':\'mm\':\':\'mm\':\'ss" | -| `vk pattern universal sortable date time` | "*universalSortableDateTimePattern*" | Formato ISO 8601 para a data e hora na localização atual usando UTC que pode ser classificado.EUA padrão padrão: "yyyy\'-\'MM\'-\'dd H\':\'mm\':\':\'ss\'Z\'" | +| `vk pattern sortable date time` | "*sortableDateTimePattern*" | Formato ISO 8601 para a data e hora na localização atual que pode ser classificado.EUA padrão padrão: "yyyy\'-\'MM\'-\'dd\'T\'HH\':\'mm\':\'ss" | +| `vk pattern universal sortable date time` | "*universalSortableDateTimePattern*" | Formato ISO 8601 para a data e hora na localização atual usando UTC que pode ser classificado.EUA padrão padrão: "yyyy\'-\'MM\'-\'dd HH\':\'mm\':\'ss\'Z\'" | | `vk pattern year month` | "*yearMonthPattern*" | Formato ISO 8601 para o mês e ano na localização atual. Padrão padrão para EUA: "MMM aaaa" | #### Exemplo ```4d -//Set the cell value as specific date and time VP SET VALUE(VP Cell("ViewProArea";3;9);New object("value";!2024-12-18!);"time";?14:30:10?;"format";vk pattern full date time)) +//Set the cell value as specific date and time +VP SET VALUE(VP Cell("ViewProArea";3;9);New object("value";!2024-12-18!);"time";?14:30:10?;"format";vk pattern full date time)) ``` ### Formatos data e hora personalizados @@ -400,7 +402,7 @@ Atributos de marca d'água são usados para sobrepor texto ou uma imagem na áre \* Se estiver usando o tipo de texto, passe o caminho do arquivo (absoluto ou relativo) da imagem. Se você passar por um caminho relativo, o arquivo deve estar localizado ao lado do arquivo de estrutura do banco de dados. No Windows, a extensão do ficheiro deve ser indicada. Não importa o tipo usado para definir uma imagem, a imagem em si (não é uma referência) é armazenada na área 4D View Pro sendo retornada pela [VP Get print info](commands/vp-get-print-info.md). -## Style Objects {#style-objects} {#style-objects} +## Style Objects {#style-objects} Objetos de estilo 4D View Pro e folhas de estilo permitem que você controle os aspectos gráficos e a aparência dos seus documentos 4D View Pro. @@ -496,7 +498,7 @@ Contém as seguintes propriedades: ## Variável de objeto do formulário 4D View Pro -La variable del objeto del formulario 4D View Pro es la variable del objeto asociada al área del formulario 4D View Pro. Gere a informação utilizada pelo objeto 4D View Pro. +A variável de objeto do formulário 4D View Pro é a variável [object](Concepts/dt_object.md) associada à área de formulário 4D View Pro. Gere a informação utilizada pelo objeto 4D View Pro. > A variável de objeto 4D View Pro é apenas para fins informativos (ou seja, depuração). Não deve, em caso algum, ser modificado. @@ -508,7 +510,7 @@ Contém as seguintes propriedades: | ViewPro.callbacks | Object | Armazena informações temporárias necessárias para comandos que requerem callbacks como importar e exportar. | | ViewPro.commandBuffers | Collection | Stores sequentially the commands called by the method and executes them as a batch (rather than individually) when exiting the method, when a command returns a value, or when the [VP FLUSH COMMANDS](commands/vp-flush-commands.md) is called. Esse mecanismo aumenta o desempenho ao reduzir o número de pedidos enviados. | | ViewPro.events | Object | [Eventos](#form-events). | -| ViewPro.formulaBar | Parâmetros | Indica se a barra de fórmulas é ou não apresentada. Disponível apenas para a interface "barra de ferramentas". | -| ViewPro.inited | Parâmetros | Indica si el área 4D View Pro ha sido inicializada o no (ver evento[On VP Ready](Events/onVpReady.md)). | +| ViewPro.formulaBar | Boolean | Indica se a barra de fórmulas é ou não apresentada. Disponível apenas para a interface "barra de ferramentas". | +| ViewPro.inited | Boolean | Indica se a área 4D View Pro foi inicializada ou não (ver evento [On VP Ready](Events/onVpReady.md)). | | ViewPro.interface | Text | Especifica o tipo de interface do usuário: "ribbon", "toolbar", "none". | diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/WebServer/webServer.md b/i18n/pt/docusaurus-plugin-content-docs/current/WebServer/webServer.md index 0370f4a0adc072..22732fa0d2b127 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/WebServer/webServer.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/WebServer/webServer.md @@ -6,12 +6,6 @@ title: Servidor Web 4D in local mode and 4D Server include a web server engine (aka http server) that enables you to design and publish powerful web applications that can make the most of your 4D databases. -:::warning Deprecated feature - - Usar o servidor web em um 4D remoto (4D client) é **obsoleto** a partir do 4D 21. Não é mais recomendado utilizar este recurso. - -::: - ## Monitorização fácil Você pode iniciar ou parar a publicação da aplicação web a qualquer momento. Para fazer isso, você só precisa selecionar um comando de menu ou executar uma única linha de código. @@ -67,3 +61,8 @@ O servidor web 4D suporta acesso a dados armazenados em suas aplicações 4D atr `On Web Authentication`, `On Web Connection`, así como también los métodos base`On REST Authentication` son los puntos de entrada de las peticiones en el servidor web; se pueden utilizar para evaluar y enrutar todo tipo de petición. +:::warning Deprecated feature + + Usar o servidor web em um 4D remoto (4D client) é **obsoleto** a partir do 4D 21. Não é mais recomendado utilizar este recurso. + +::: diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md b/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md index 9851dddf9c63f3..b2ea8ba8f482ef 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/4D Environment/set-database-parameter.md @@ -990,9 +990,9 @@ Esse seletor permite suspender/retomar todas as operações de histórico inicia **Se conserva entre duas sessões**: não -**Valores possíveis**: número inteiro positivo. Valor padrão = 15, valor mínimo = 1. +**Valores possíveis**: número inteiro positivo. Valor padrão = 900, valor mínimo = 60. -**Descrição**: tempo limite em minutos para sessões cliente/servidor em caso de desconexão inesperada ao utilizar a camada de rede QUIC. Este tempo limite é o período permitido para uma sessão durante o qual a conexão entre o servidor e o cliente pode ser restabelecida automaticamente após uma desconexão não intencional. Se, ao final deste tempo limite, a conexão não tiver sido restabelecida, a sessão será encerrada. +**Descrição**: tempo limite em segundos para sessões cliente/servidor em caso de desconexão inesperada ao utilizar a camada de rede QUIC. Este tempo limite é o período permitido para uma sessão durante o qual a conexão entre o servidor e o cliente pode ser restabelecida automaticamente após uma desconexão não intencional. Se, ao final deste tempo limite, a conexão não tiver sido restabelecida, a sessão do cliente é encerrada com uma mensagem. Esta configuração só pode ser definida no 4D Server e aplica-se a todas as novas sessões remotas 4D (o valor do tempo limite das sessões existentes não é alterado). diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md b/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md index 56f3013f11f486..8a804dd2235fee 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Forms/form-get-current-page.md @@ -1,4 +1,4 @@ ---- +--- id: form-get-current-page title: FORM Get current page slug: /commands/form-get-current-page @@ -32,7 +32,7 @@ displayed_sidebar: docs O comando **FORM Get current page** retorna o número da página atual do formulário mostrado atualmente ou do formulário atual carregado via o comando [FORM LOAD](../commands/form-load). -O parâmetro *\** é útil quando o comando é chamado no contexto de um subformulário em página que contém muitas páginas. Neste caso, quando passar este parâmetro, o comando muda a página do subformulário atual (a que chamou o comando). Por padrão, quando o parâmetro *\** é omitido, o comando é sempre aplicado ao formulário pai. +O parâmetro *\** é útil quando o comando é chamado no contexto de um subformulário em página que contém muitas páginas. Neste caso, quando passar este parâmetro, o comando retorna o número da página do subformulário atual (a que chamou o comando). Por padrão, quando o parâmetro *\** é omitido, o comando é sempre aplicado ao formulário pai. ## Exemplo diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md b/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md index 49a051cb2caf38..a09b10796f192b 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Selection/create-entity-selection.md @@ -1,4 +1,4 @@ ---- +--- id: create-entity-selection title: Criar uma seleção de entidades (entity selection) slug: /commands/create-entity-selection @@ -35,6 +35,7 @@ displayed_sidebar: docs O comando `Create entity selection` cria e retorna uma nova seleção de entidade [alterável](../../ORDA/entities.md#shareable-or-alterable-entity-selections) relacionada à classe de dados correspondente à *dsTable* fornecida, de acordo com a seleção atual dessa tabela. + Se a seleção atual for ordenada, uma entidade [ordenada](../../ORDA/dsMapping.md#ordered-or-unordered-entity-selection) é criada (a ordem da seleção atual é mantida). Se a seleção atual não for ordenada, se cria uma seleção de entidades não ordenada. Se *dsTable* não for exposta em [`ds`](../commands/ds), um erro será retornado. Esse comando não pode usado com uma datastore remota. @@ -45,6 +46,17 @@ No parâmetro opcional *settings*, você pode passar um objeto que contenha a se | ----------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ | | context | Text | Rótulo para o [contexto de otimização](../../ORDA/client-server-optimization.md) aplicado à seleção de entidades. | + +:::info + +Por razões de desempenho, no 4D monousuário e no 4D Server, a entity selection retornada está diretamente conectada à seleção atual de *dsTable* (não é uma cópia). Até que a seleção atual seja substituída, alterações feitas em uma são refletidas na outra. Por exemplo, [`REDUCE SELECTION`](../commands/reduce-selection) reduz a entity selection, e [`.add()`](../../API/EntitySelectionClass.md#add) na entity selection adiciona a entidade à seleção atual. Para obter uma entity selection independente, chame [`.copy()`](../../API/EntitySelectionClass.md#copy) no resultado: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Exemplo ```4d diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md b/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md index 59066664d8580a..1e82afc3903b26 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/language-legacy/Web Server/web-get-body-part.md @@ -1,4 +1,4 @@ ---- +--- id: web-get-body-part title: WEB GET BODY PART slug: /commands/web-get-body-part diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-19/API/CollectionClass.md b/i18n/pt/docusaurus-plugin-content-docs/version-19/API/CollectionClass.md index b1f134bbd89ef3..b30b8319a68117 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-19/API/CollectionClass.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-19/API/CollectionClass.md @@ -343,7 +343,7 @@ Como padrão, elementos *col2* são adicionados ao final da collection original. var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-20/API/CollectionClass.md b/i18n/pt/docusaurus-plugin-content-docs/version-20/API/CollectionClass.md index 4968d9e1a3905f..f488ca7f42363b 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-20/API/CollectionClass.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-20/API/CollectionClass.md @@ -438,7 +438,7 @@ Como padrão, elementos *col2* são adicionados ao final da collection original. var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-20/FormObjects/formObjects_overview.md b/i18n/pt/docusaurus-plugin-content-docs/version-20/FormObjects/formObjects_overview.md index d39c820b71c8da..e67c39ae5bef1d 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-20/FormObjects/formObjects_overview.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-20/FormObjects/formObjects_overview.md @@ -22,9 +22,10 @@ Pode adicionar ou modificar objetos de formulários 4D das seguintes formas: * **Linguagem 4D**: os comandos do tema [Objetos (Formulários)](https://doc.4d.com/4Dv20/4D/20.6/Objects-Forms.201-7486936.en.html), como `OBJECT DUPLICATE` ou `OBJECT SET FONT STYLE`, permitem criar e definir objetos de formulário. -* **Código JSON em formulários dinâmicos:** defina as propriedades usando JSON. Use a propriedade [type](properties_Object.md#type) para definir o tipo de objeto e, em seguida, defina suas propriedades disponíveis. Veja a página [Formulários Dinâmicos](https://doc.4d.com/4Dv21R4/4D/21-R4/Dynamic-Forms.300-7753010.en.html) para informações. - Exemplo de um objeto botão: - ``` +* **Código JSON em formulários dinâmicos:** defina as propriedades usando JSON. Use a propriedade [type](properties_Object.md#type) para definir o tipo de objeto e, em seguida, defina suas propriedades disponíveis. Veja a página [Formulários Dinâmicos](https://doc.4d.com/4Dv20/4D/20.2/Dynamic-Forms.300-6750140.en.html) para informações. + +Exemplo de um objeto botão: + ```json { "type": "button", "style": "bevel", diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/API/CollectionClass.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/API/CollectionClass.md index 2d4ab49d54ec33..a26d4aac064572 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/API/CollectionClass.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/API/CollectionClass.md @@ -272,13 +272,12 @@ Por padrão, os elementos *col2* são adicionados ao final da coleção original var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` - ## .concat()
História diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/ViewPro/configuring.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/ViewPro/configuring.md index 2b0f096090d0e1..75878cafaa95a1 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/ViewPro/configuring.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/ViewPro/configuring.md @@ -7,13 +7,13 @@ As propriedades da área 4D View Pro podem ser configuradas utilizando a lista d ## Propriedades da área do formulário -Using the area's property list, you can set [4D View Pro object properties](FormObjects/viewProArea_overview.md#supported-properties) such as **Object Name**, [**Variable or Expression**](#4d-view-pro-form-object-variable), **Appearance**, **Action**, and **Events**. +Usando a lista de propriedades da área, você pode definir [propriedades do objeto 4D View Pro](FormObjects/viewProArea_overview.md#supported-properties) como **Nome do Objeto**, [**Variável ou Expressão**](#4d-view-pro-form-object-variable), **Aparência**, **Ação** e **Eventos**. ![](../assets/en/ViewPro/vpPropertyList.png) -### Selecção de uma interface utilizador +### Seleção de uma interface de usuário -Puede seleccionar la interfaz a utilizar con sus áreas de formulario 4D View Pro en la **Lista de propiedades**, en **Apariencia**: +Você pode selecionar a interface a ser usada com suas áreas de formulário 4D View Pro na **Lista de Propriedades**, em **Aparência**: ![](../assets/en/ViewPro/vpUserInterface.PNG) @@ -35,23 +35,23 @@ Com barra de fórmula visível: #### Funcionalidades -Tanto os recursos relacionados ao Ribbon como o grupo da interface de ferramentas (toolbar) nas abas: +Tanto a interface Ribbon quanto a Toolbar agrupam funcionalidades relacionadas em abas: | Tab | Acções | Interface Ribbon | Interface da barra de ferramentas | | -------- | -------------------------------- | :--------------: | :-------------------------------: | | File | Manipulação de ficheiros | X | | -| Inicio | Aspecto do texto | X | X | -| Inserir | Adicionar itens | X | X | -| Fórmulas | Cálculo de fórmulas e biblioteca | X | X | -| Dados | Manipulação de dados | X | X | -| Mostrar | Apresentação visual | X | X | +| Home | Aspecto do texto | X | X | +| Insert | Adicionar itens | X | X | +| Formulas | Cálculo de fórmulas e biblioteca | X | X | +| Data | Manipulação de dados | X | X | +| View | Apresentação visual | X | X | | Settings | Presentação da folha | X | | ## Eventos formulário Os seguintes eventos de formulário estão disponíveis na lista de propriedades para as áreas 4D View Pro. -Alguns dos eventos são eventos padrão de formulário (disponíveis para todos os objetos ativos) e alguns são eventos específicos de forma 4D View Pro. Alguns dos eventos são eventos padrão de formulário (disponíveis para todos os objetos ativos) e alguns são eventos específicos de forma 4D View Pro. A tabela a seguir mostra quais eventos são padrões e quais são específicos ou fornecem informações adicionais para as áreas 4D View Pro: +Alguns dos eventos são eventos padrão de formulário (disponíveis para todos os objetos ativos) e alguns são eventos específicos de forma 4D View Pro. Alguns eventos padrão de formulário fornecem informações estendidas no objeto retornado pelo comando [`FORM Event`](../commands/form-event) quando são gerados para áreas 4D View Pro. A tabela a seguir mostra quais eventos são padrões e quais são específicos ou fornecem informações adicionais para as áreas 4D View Pro: | Eventos 4D ‘standard’ | Eventos 4D View Pro específicos e alargados | | ----------------------------------------------- | ----------------------------------------------------- | @@ -157,7 +157,8 @@ Formatos de números se aplicam a todos os tipos de números (por exemplo, posit #### Exemplo ```4d -//Set the cell value as $125,571.35 VP SET VALUE(VP Cell("ViewProArea";3;2);New object("value";125571.35;"format";"_($* #,##0.00_)") +//Set the cell value as $125,571.35 +VP SET VALUE(VP Cell("ViewProArea";3;2);New object("value";125571.35;"format";"_($* #,##0.00_)") ``` ### Formatos data e hora @@ -172,14 +173,15 @@ Formatos de números se aplicam a todos os tipos de números (por exemplo, posit | `vk pattern month day` | "*monthDayPattern*" | Formato ISO 8601 para o mês e dia no padrão da localização atual: "MMMM dd" | | `vk pattern short date` | "*shortDatePattern*" | Formato ISO 8601 abreviado para a data na data atual de localização.USA padrão padrão: "MM/dd/yyyy" | | `vk pattern short time` | "*shortTimePattern*" | Formato abreviado ISO 8601 para a hora no padrão de localização.EUA atual: "HH:mm" | -| `vk pattern sortable date time` | "*sortableDateTimePattern*" | Formato ISO 8601 para a data e hora na localização atual que pode ser classificado.EUA padrão padrão: "yyyy\'-\'MM\'dd\'T\'H\':\'mm\':\':\'mm\':\'ss" | -| `vk pattern universal sortable date time` | "*universalSortableDateTimePattern*" | Formato ISO 8601 para a data e hora na localização atual usando UTC que pode ser classificado.EUA padrão padrão: "yyyy\'-\'MM\'-\'dd H\':\'mm\':\':\'ss\'Z\'" | -| `vk pattern year month` | "*yearMonthPattern*" | Formato ISO 8601 para o mês e ano na localização atual. Padrão padrão para EUA: "MMM aaaa" | +| `vk pattern sortable date time` | "*sortableDateTimePattern*" | Formato ISO 8601 para a data e hora na localização atual que pode ser classificado.EUA padrão padrão: "yyyy\'-\'MM\'-\'dd\'T\'HH\':\'mm\':\'ss" | +| `vk pattern universal sortable date time` | "*universalSortableDateTimePattern*" | Formato ISO 8601 para a data e hora na localização atual usando UTC que pode ser classificado.EUA padrão padrão: "yyyy\'-\'MM\'-\'dd HH\':\'mm\':\'ss\'Z\'" | +| `vk pattern year month` | "*yearMonthPattern*" | Formato ISO 8601 para o mês e ano na localização atual. Padrão padrão para EUA: "yyyy MMMM" | #### Exemplo ```4d -//Set the cell value as specific date and time VP SET VALUE(VP Cell("ViewProArea";3;9);New object("value";!2024-12-18!);"time";?14:30:10?;"format";vk pattern full date time)) +//Set the cell value as specific date and time +VP SET VALUE(VP Cell("ViewProArea";3;9);New object("value";!2024-12-18!);"time";?14:30:10?;"format";vk pattern full date time)) ``` ### Formatos data e hora personalizados @@ -211,7 +213,7 @@ Para criar seus próprios padrões de data e hora, na sua localização atual, v | | \[ss] | Tempo decorrido em segundos | 50585 | | | AM/PM | Períodos do dia. Se omitido, utiliza-se o formato de 24 horas. | PM | -> O código "m" é interpretado de acordo com sua posição no padrão. Se for imediatamente após 'h' ou 'hh' ou imediatamente antes 't' ou 'ss', será interpretado como actos, caso contrário será interpretado como meses. +> O código "m" é interpretado de acordo com sua posição no padrão. Se for imediatamente após 'h' ou 'hh' ou imediatamente antes 's' ou 'ss', será interpretado como minutos, caso contrário será interpretado como meses. ### Símbolos adicionais @@ -312,7 +314,7 @@ Atributos de margem são usados para especificar a margem 4D View Pro para impre | | top | inteiro longo | Margem superior, em centésimos de polegada. Valor padrão = 75 | | | bottom | inteiro longo | Margem inferior, em centésimos de polegada. Valor padrão = 75 | | | left | inteiro longo | Margem esquerda, em centésimos de polegada. Valor padrão = 70 | -| | direita | inteiro longo | Margem direita, em centésimos de polegada. Valor padrão = 70 | +| | right | inteiro longo | Margem direita, em centésimos de polegada. Valor padrão = 70 | | | header | inteiro longo | Deslocação do cabeçalho, em centésimos de polegada. Valor padrão = 30 | | | footer | inteiro longo | Deslocamento do rodapé, em centésimos de polegada. Valor padrão = 30 | @@ -334,7 +336,7 @@ Os atributos de página são utilizados para especificar as definições gerais | --------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | blackAndWhite | boolean | Impressão apenas em preto e branco.

Valor padrão = false

**Nota**: os PDFs não são afetados por esse atributo. As cores nos PDFs mantêm-se.

| | centering | inteiro longo | A forma como o conteúdo é centrado na página impressa. Valores disponibles: `vk print centering both`, `vk print centering horizontal`, `vk print centering none` (por defecto), `vk print centering vertical` | -| firstPageNumber | inteiro longo | The page number to print on the first page. Default value = 1 | +| firstPageNumber | inteiro longo | O número da página a ser impresso na primeira página. Valor padrão = 1 | | pageOrder | inteiro longo | As páginas do pedido são impressas. Valores disponibles: `vk print page order auto` (por defecto), `vk print page order down then over`, `vk print page order over then down`. | | pageRange | text | O intervalo de páginas para impressão | | qualityFactor | inteiro longo | O fator de qualidade para impressão (1 a 8). The higher the quality factor, the better the printing quality, however printing performance may be affected.

Default value = 2

| @@ -353,14 +355,14 @@ Atributos do tamanho do papel são usados para especificar as dimensões ou mode | paperSize | | object | Dimensões do papel (altura, largura) ou formato específico (tipo) para impressão. | | | height | inteiro longo | Altura do papel, em centésimos de polegada. | | | width | inteiro longo | Largura do papel, em centésimos de polegada. | -| | kind | text | Name of standard paper size (e.g., A2, A4, legal, etc.) retornado por `Get Print Option`. Valor padrão = "letter" | +| | kind | text | Nome do tamanho de papel padrão (por exemplo, A2, A4, legal, etc.) retornado por `Get Print Option`. Valor padrão = "letter" | -- If the paper size is specified using the `height` and `width` properties, [`VP Get print info`](./commands/vp-get-print-info.md) returns a paper size with `custom` as value for `kind`. +- Se o tamanho do papel for especificado usando as propriedades `height` e `width`, [`VP Get print info`](./commands/vp-get-print-info.md) retorna um tamanho de papel com `custom` como valor para `kind`. -- Si establece el tamaño del papel mediante la propiedad `kind`, puede utilizar cualquiera de los dos: - - uno de los formatos de la [lista de formatos SpreadJS](https://developer.mescius.com/spreadjs/api/enums/GC.Spread.Sheets.Print.PaperKind) - - Nesse caso, [`VP Get print info`](./commands/vp-get-print-info.md) retorna o formato correspondente com a altura e a largura. - um dos formatos retornados pelo comando [`PRINT OPTION VALUES`](../commands/print-option-values). +- Se você definir o tamanho do papel usando a propriedade `kind`, você pode usar: + - um dos formatos da [lista de formatos SpreadJS](https://developer.mescius.com/spreadjs/api/enums/GC.Spread.Sheets.Print.PaperKind) + - um dos formatos retornados pelo comando [`PRINT OPTION VALUES`](../commands/print-option-values). + Nesse caso, [`VP Get print info`](./commands/vp-get-print-info.md) retorna o formato correspondente com a altura e a largura. ### Escala @@ -379,7 +381,7 @@ Mostrar / Ocultar atributos são usados para especificar a visibilidade (impress | Propriedade | Tipo | Descrição | | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| showBorder | boolean | Prints the outline border. Default value = "true" | +| showBorder | boolean | Imprime a borda do contorno. Valor padrão = "true" | | showColumnHeader | inteiro longo | Parâmetros de impressão do cabeçalho da coluna. Valores disponibles: `vk print visibility hide`, `vk print visibility inherit` (por defecto), `vk print visibility show`, `vk print visibility show once` | | showGridLine | boolean | Imprime as linhas de grade. Valor padrão = "false" | | showRowHeader | inteiro longo | Parâmetros de impressão de cabeçalhos de linha. Valores disponibles: `vk print visibility hide`, `vk print visibility inherit` (por defecto), `vk print visibility show`, `vk print visibility show once` | @@ -390,7 +392,7 @@ Atributos de marca d'água são usados para sobrepor texto ou uma imagem na áre | Propriedade | | Tipo | Descrição | | ------------- | ---------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| marca de água | | collection | Coleção de parâmetros de marcas de água. Valor padrão: undefined | +| watermark | | collection | Coleção de parâmetros de marcas de água. Valor padrão: undefined | | | \[ ].height | inteiro longo | A altura do texto/imagem da marca de água. | | | \[ ].imageSrc | picture | text\* | O texto/imagem da marca de água. | | | \[ ].page | text | A(s) página(s) onde a marca de água é impressa. Para todas as páginas: "all". Para páginas específicas: números de página ou intervalos de páginas separados por vírgulas. Ex.: "1,3,5-12" | @@ -400,7 +402,7 @@ Atributos de marca d'água são usados para sobrepor texto ou uma imagem na áre \* Se estiver usando o tipo de texto, passe o caminho do arquivo (absoluto ou relativo) da imagem. Se você passar por um caminho relativo, o arquivo deve estar localizado ao lado do arquivo de estrutura do banco de dados. No Windows, a extensão do ficheiro deve ser indicada. Não importa o tipo usado para definir uma imagem, a imagem em si (não é uma referência) é armazenada na área 4D View Pro sendo retornada pela [VP Get print info](commands/vp-get-print-info.md). -## Style Objects {#style-objects} {#style-objects} +## Style Objects {#style-objects} Objetos de estilo 4D View Pro e folhas de estilo permitem que você controle os aspectos gráficos e a aparência dos seus documentos 4D View Pro. @@ -408,7 +410,7 @@ Objetos de estilo 4D View Pro e folhas de estilo permitem que você controle os Os objetos estilo contêm os parâmetros de estilo. Podem ser utilizados numa folha de estilo ou por conta própria. Objetos de estilo também podem ser usados além de uma folha de estilo para que diferentes configurações possam ser especificadas para intervalos de células individuais sem afetar o resto do documento. Você pode usar objetos de estilo diretamente com os comandos [VP SET CELL STYLE](commands/vp-set-cell-style.md) e [VP SET PELO STYLE](commands/vp-set-default-style.md). You can also use style objects when defining custom table themes using the [VP SET TABLE THEME](commands/vp-set-table-theme.md) or [VP CREATE TABLE](commands/vp-create-table.md) commands. -Una **hoja de estilo** agrupa una combinación de propiedades en un objeto estilo para especificar el aspecto de todas las celdas de sus documentos 4D View Pro. Folhas de estilo salvas com o documento podem ser usadas para definir as propriedades para uma única folha, várias folhas ou um livro de trabalho inteiro. Quando criada, uma folha de estilo 4D View Pro é dado um nome que é salvo na folha de estilo na propriedade "nome". Isto permite que uma folha de estilo seja facilmente usada e, se cuidadosamente selecionada, pode facilitar sua identificação e propósito (por exemplo, Letterhead\_internal, Letterhead_external). +Uma **folha de estilo** agrupa uma combinação de propriedades em um objeto de estilo para especificar a aparência de todas as células dos seus documentos 4D View Pro. Folhas de estilo salvas com o documento podem ser usadas para definir as propriedades para uma única folha, várias folhas ou um livro de trabalho inteiro. Quando criada, uma folha de estilo 4D View Pro recebe um nome que é salvo na folha de estilo na propriedade "name". Isso permite que uma folha de estilo seja facilmente usada e, se cuidadosamente selecionada, pode facilitar sua identificação e propósito (por exemplo, Letterhead\_internal, Letterhead_external). Style sheets are created with the [VP ADD STYLESHEET](commands/vp-add-stylesheet.md) command and applied with the the [VP SET DEFAULT STYLE](commands/vp-set-default-style.md) or [VP SET CELL STYLE](commands/vp-set-cell-style.md) commands. Você pode remover uma folha de estilos com o comando [VP REMOVE STYLESHEET](commands/vp-remove-stylesheet.md). @@ -459,7 +461,7 @@ Exemplo: | textDecoration | | inteiro longo | Especifica a decoração adicionada ao texto. | `vk text decoration double underline`, `vk text decoration line through`, `vk text decoration none`, `vk text decoration overline`, `vk text decoration underline` | | textIndent | | inteiro longo | Define a unidade de indentação do texto. 1 = 8 píxeles | | | textOrientation | | inteiro longo | Define o ângulo de rotação do texto numa célula. Número entre -90 e 90 | | -| marca de água | | text | Define o conteúdo da marca de água (etiqueta da célula) | | +| watermark | | text | Define o conteúdo da marca de água (etiqueta da célula) | | | wordWrap | | boolean | Especifica se o texto deve ser envolvido. | True = texto embrulhado, False = texto não embrulhado | #### Layout @@ -496,7 +498,7 @@ Contém as seguintes propriedades: ## Variável de objeto do formulário 4D View Pro -La variable del objeto del formulario 4D View Pro es la variable del objeto asociada al área del formulario 4D View Pro. Gere a informação utilizada pelo objeto 4D View Pro. +A variável de objeto do formulário 4D View Pro é a variável [objeto](Concepts/dt_object.md) associada à área de formulário 4D View Pro. Gere a informação utilizada pelo objeto 4D View Pro. > A variável de objeto 4D View Pro é apenas para fins informativos (ou seja, depuração). Não deve, em caso algum, ser modificado. @@ -506,9 +508,9 @@ Contém as seguintes propriedades: | -------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ViewPro.area | Text | Nome da área 4D View Pro | | ViewPro.callbacks | Object | Armazena informações temporárias necessárias para comandos que requerem callbacks como importar e exportar. | -| ViewPro.commandBuffers | Collection | Stores sequentially the commands called by the method and executes them as a batch (rather than individually) when exiting the method, when a command returns a value, or when the [VP FLUSH COMMANDS](commands/vp-flush-commands.md) is called. Esse mecanismo aumenta o desempenho ao reduzir o número de pedidos enviados. | +| ViewPro.commandBuffers | Collection | Armazena sequencialmente os comandos chamados pelo método e os executa em lote (em vez de individualmente) ao sair do método, quando um comando retorna um valor ou quando o [VP FLUSH COMMANDS](commands/vp-flush-commands.md) é chamado. Esse mecanismo aumenta o desempenho ao reduzir o número de pedidos enviados. | | ViewPro.events | Object | [Eventos](#form-events). | -| ViewPro.formulaBar | Parâmetros | Indica se a barra de fórmulas é ou não apresentada. Disponível apenas para a interface "barra de ferramentas". | -| ViewPro.inited | Parâmetros | Indica si el área 4D View Pro ha sido inicializada o no (ver evento[On VP Ready](Events/onVpReady.md)). | +| ViewPro.formulaBar | Boolean | Indica se a barra de fórmulas é ou não apresentada. Disponível apenas para a interface "barra de ferramentas". | +| ViewPro.inited | Boolean | Indica se a área 4D View Pro foi inicializada ou não (ver evento [On VP Ready](Events/onVpReady.md)). | | ViewPro.interface | Text | Especifica o tipo de interface do usuário: "ribbon", "toolbar", "none". | diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/WebServer/webServer.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/WebServer/webServer.md index 589599829b9d0a..a4221cfd701ade 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/WebServer/webServer.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/WebServer/webServer.md @@ -6,11 +6,6 @@ title: Servidor Web 4D in local mode and 4D Server include a web server engine (aka http server) that enables you to design and publish powerful web applications that can make the most of your 4D databases. -:::warning Deprecated feature - - Usar o servidor web em um 4D remoto (4D client) está **obsoleto** a partir do 4D 21. Não é mais recomendado utilizar este recurso. - -::: ## Monitorização fácil @@ -67,3 +62,9 @@ O servidor web 4D suporta acesso a dados armazenados em suas aplicações 4D atr `On Web Authentication`, `On Web Connection`, así como también los métodos base`On REST Authentication` son los puntos de entrada de las peticiones en el servidor web; se pueden utilizar para evaluar y enrutar todo tipo de petición. + +:::warning Deprecated feature + + Usar o servidor web em um 4D remoto (4D client) está **obsoleto** a partir do 4D 21. Não é mais recomendado utilizar este recurso. + +::: diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md index fc4bbe9074390f..c66cdac01a6702 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md @@ -997,9 +997,9 @@ Esse seletor permite suspender/retomar todas as operações de histórico inicia **Se conserva entre duas sessões**: não -**Valores possíveis**: número inteiro positivo. Valor padrão = 15, valor mínimo = 1. +**Valores possíveis**: número inteiro positivo. Valor padrão = 900, valor mínimo = 60. -**Descrição**: tempo limite em minutos para sessões cliente/servidor em caso de desconexão inesperada ao utilizar a camada de rede QUIC. Este tempo limite é o período permitido para uma sessão durante o qual a conexão entre o servidor e o cliente pode ser restabelecida automaticamente após uma desconexão não intencional. Se, ao final deste tempo limite, a conexão não tiver sido restabelecida, a sessão será encerrada. +**Descrição**: tempo limite em segundos para sessões cliente/servidor em caso de desconexão inesperada ao utilizar a camada de rede QUIC. Este tempo limite é o período permitido para uma sessão durante o qual a conexão entre o servidor e o cliente pode ser restabelecida automaticamente após uma desconexão não intencional. Se, ao final deste tempo limite, a conexão não tiver sido restabelecida, a sessão do cliente é encerrada com uma mensagem. Esta configuração só pode ser definida no 4D Server e aplica-se a todas as novas sessões remotas 4D (o valor do tempo limite das sessões existentes não é alterado). diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md index 56f3013f11f486..8a804dd2235fee 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Forms/form-get-current-page.md @@ -1,4 +1,4 @@ ---- +--- id: form-get-current-page title: FORM Get current page slug: /commands/form-get-current-page @@ -32,7 +32,7 @@ displayed_sidebar: docs O comando **FORM Get current page** retorna o número da página atual do formulário mostrado atualmente ou do formulário atual carregado via o comando [FORM LOAD](../commands/form-load). -O parâmetro *\** é útil quando o comando é chamado no contexto de um subformulário em página que contém muitas páginas. Neste caso, quando passar este parâmetro, o comando muda a página do subformulário atual (a que chamou o comando). Por padrão, quando o parâmetro *\** é omitido, o comando é sempre aplicado ao formulário pai. +O parâmetro *\** é útil quando o comando é chamado no contexto de um subformulário em página que contém muitas páginas. Neste caso, quando passar este parâmetro, o comando retorna o número da página do subformulário atual (a que chamou o comando). Por padrão, quando o parâmetro *\** é omitido, o comando é sempre aplicado ao formulário pai. ## Exemplo diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md index 49a051cb2caf38..c7aeafa1f60511 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Selection/create-entity-selection.md @@ -1,4 +1,4 @@ ---- +--- id: create-entity-selection title: Criar uma seleção de entidades (entity selection) slug: /commands/create-entity-selection @@ -45,6 +45,16 @@ No parâmetro opcional *settings*, você pode passar um objeto que contenha a se | ----------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ | | context | Text | Rótulo para o [contexto de otimização](../../ORDA/client-server-optimization.md) aplicado à seleção de entidades. | +:::info + +Por questões de desempenho, no 4D monousuário e no 4D Server, a entity selection retornada está diretamente conectada à seleção atual de *dsTable* (não é uma cópia). Até que a seleção atual seja substituída, as alterações feitas em uma são refletidas na outra. Por exemplo, [`REDUCE SELECTION`](../commands/reduce-selection) reduz a entity selection, e [`.add()`](../../API/EntitySelectionClass.md#add) na entity selection adiciona a entidade à seleção atual. Para obter uma entity selection independente, chame [`.copy()`](../../API/EntitySelectionClass.md#copy) no resultado: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Exemplo ```4d diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md index 59066664d8580a..1e82afc3903b26 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md @@ -1,4 +1,4 @@ ---- +--- id: web-get-body-part title: WEB GET BODY PART slug: /commands/web-get-body-part diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/API/CollectionClass.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/API/CollectionClass.md index 2d4ab49d54ec33..a26d4aac064572 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/API/CollectionClass.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/API/CollectionClass.md @@ -272,13 +272,12 @@ Por padrão, os elementos *col2* são adicionados ao final da coleção original var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` - ## .concat()
História diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/ViewPro/configuring.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/ViewPro/configuring.md index 2b0f096090d0e1..70a70e2fcfc00e 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/ViewPro/configuring.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/ViewPro/configuring.md @@ -11,9 +11,9 @@ Using the area's property list, you can set [4D View Pro object properties](Form ![](../assets/en/ViewPro/vpPropertyList.png) -### Selecção de uma interface utilizador +### Selecionando uma interface de usuário -Puede seleccionar la interfaz a utilizar con sus áreas de formulario 4D View Pro en la **Lista de propiedades**, en **Apariencia**: +Você pode selecionar a interface a ser usada com suas áreas de formulário 4D View Pro na **Lista de Propriedades**, em **Aparência**: ![](../assets/en/ViewPro/vpUserInterface.PNG) @@ -35,16 +35,16 @@ Com barra de fórmula visível: #### Funcionalidades -Tanto os recursos relacionados ao Ribbon como o grupo da interface de ferramentas (toolbar) nas abas: +Tanto a interface Ribbon quanto a Toolbar agrupam funcionalidades relacionadas em abas: | Tab | Acções | Interface Ribbon | Interface da barra de ferramentas | | -------- | -------------------------------- | :--------------: | :-------------------------------: | | File | Manipulação de ficheiros | X | | -| Inicio | Aspecto do texto | X | X | -| Inserir | Adicionar itens | X | X | -| Fórmulas | Cálculo de fórmulas e biblioteca | X | X | -| Dados | Manipulação de dados | X | X | -| Mostrar | Apresentação visual | X | X | +| Home | Aspecto do texto | X | X | +| Insert | Adicionar itens | X | X | +| Formulas | Cálculo de fórmulas e biblioteca | X | X | +| Data | Manipulação de dados | X | X | +| View | Apresentação visual | X | X | | Settings | Presentação da folha | X | | ## Eventos formulário @@ -400,7 +400,7 @@ Atributos de marca d'água são usados para sobrepor texto ou uma imagem na áre \* Se estiver usando o tipo de texto, passe o caminho do arquivo (absoluto ou relativo) da imagem. Se você passar por um caminho relativo, o arquivo deve estar localizado ao lado do arquivo de estrutura do banco de dados. No Windows, a extensão do ficheiro deve ser indicada. Não importa o tipo usado para definir uma imagem, a imagem em si (não é uma referência) é armazenada na área 4D View Pro sendo retornada pela [VP Get print info](commands/vp-get-print-info.md). -## Style Objects {#style-objects} {#style-objects} +## Style Objects {#style-objects} Objetos de estilo 4D View Pro e folhas de estilo permitem que você controle os aspectos gráficos e a aparência dos seus documentos 4D View Pro. @@ -496,7 +496,7 @@ Contém as seguintes propriedades: ## Variável de objeto do formulário 4D View Pro -La variable del objeto del formulario 4D View Pro es la variable del objeto asociada al área del formulario 4D View Pro. Gere a informação utilizada pelo objeto 4D View Pro. +A variável de objeto do formulário 4D View Pro é a variável [object](Concepts/dt_object.md) associada à área de formulário 4D View Pro. Gere a informação utilizada pelo objeto 4D View Pro. > A variável de objeto 4D View Pro é apenas para fins informativos (ou seja, depuração). Não deve, em caso algum, ser modificado. @@ -508,7 +508,7 @@ Contém as seguintes propriedades: | ViewPro.callbacks | Object | Armazena informações temporárias necessárias para comandos que requerem callbacks como importar e exportar. | | ViewPro.commandBuffers | Collection | Stores sequentially the commands called by the method and executes them as a batch (rather than individually) when exiting the method, when a command returns a value, or when the [VP FLUSH COMMANDS](commands/vp-flush-commands.md) is called. Esse mecanismo aumenta o desempenho ao reduzir o número de pedidos enviados. | | ViewPro.events | Object | [Eventos](#form-events). | -| ViewPro.formulaBar | Parâmetros | Indica se a barra de fórmulas é ou não apresentada. Disponível apenas para a interface "barra de ferramentas". | -| ViewPro.inited | Parâmetros | Indica si el área 4D View Pro ha sido inicializada o no (ver evento[On VP Ready](Events/onVpReady.md)). | +| ViewPro.formulaBar | Boolean | Indica se a barra de fórmulas é ou não apresentada. Disponível apenas para a interface "barra de ferramentas". | +| ViewPro.inited | Boolean | Indica se a área 4D View Pro foi inicializada ou não (ver evento [On VP Ready](Events/onVpReady.md)). | | ViewPro.interface | Text | Especifica o tipo de interface do usuário: "ribbon", "toolbar", "none". | diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/WebServer/webServer.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/WebServer/webServer.md index c9e8c49f7b335c..bc53a4ab2251d5 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/WebServer/webServer.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/WebServer/webServer.md @@ -6,12 +6,6 @@ title: Servidor Web 4D in local mode and 4D Server include a web server engine (aka http server) that enables you to design and publish powerful web applications that can make the most of your 4D databases. -:::warning Deprecated feature - - Usar o servidor web em um 4D remoto (4D client) está **obsoleto** a partir do 4D 21. Não é mais recomendado utilizar este recurso. - -::: - ## Monitorização fácil Você pode iniciar ou parar a publicação da aplicação web a qualquer momento. Para fazer isso, você só precisa selecionar um comando de menu ou executar uma única linha de código. @@ -67,3 +61,8 @@ O servidor web 4D suporta acesso a dados armazenados em suas aplicações 4D atr `On Web Authentication`, `On Web Connection`, así como también los métodos base`On REST Authentication` son los puntos de entrada de las peticiones en el servidor web; se pueden utilizar para evaluar y enrutar todo tipo de petición. +:::warning Deprecated feature + + Usar o servidor web em um 4D remoto (4D client) está **obsoleto** a partir do 4D 21. Não é mais recomendado utilizar este recurso. + +::: diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md index c56107446c0a28..7ab75c3a7a06a4 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md @@ -988,9 +988,9 @@ Esse seletor permite suspender/retomar todas as operações de histórico inicia **Se conserva entre duas sessões**: não -**Valores possíveis**: número inteiro positivo. Valor padrão = 15, valor mínimo = 1. +**Valores possíveis**: número inteiro positivo. Valor padrão = 900, valor mínimo = 60. -**Descrição**: tempo limite em minutos para sessões cliente/servidor em caso de desconexão inesperada ao utilizar a camada de rede QUIC. Este tempo limite é o período permitido para uma sessão durante o qual a conexão entre o servidor e o cliente pode ser restabelecida automaticamente após uma desconexão não intencional. Se, ao final deste tempo limite, a conexão não tiver sido restabelecida, a sessão será encerrada. +**Descrição**: tempo limite em segundos para sessões cliente/servidor em caso de desconexão inesperada ao utilizar a camada de rede QUIC. Este tempo limite é o período permitido para uma sessão durante o qual a conexão entre o servidor e o cliente pode ser restabelecida automaticamente após uma desconexão não intencional. Se, ao final deste tempo limite, a conexão não tiver sido restabelecida, a sessão do cliente é encerrada com uma mensagem. Esta configuração só pode ser definida no 4D Server e aplica-se a todas as novas sessões remotas 4D (o valor do tempo limite das sessões existentes não é alterado). diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md index 56f3013f11f486..8a804dd2235fee 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Forms/form-get-current-page.md @@ -1,4 +1,4 @@ ---- +--- id: form-get-current-page title: FORM Get current page slug: /commands/form-get-current-page @@ -32,7 +32,7 @@ displayed_sidebar: docs O comando **FORM Get current page** retorna o número da página atual do formulário mostrado atualmente ou do formulário atual carregado via o comando [FORM LOAD](../commands/form-load). -O parâmetro *\** é útil quando o comando é chamado no contexto de um subformulário em página que contém muitas páginas. Neste caso, quando passar este parâmetro, o comando muda a página do subformulário atual (a que chamou o comando). Por padrão, quando o parâmetro *\** é omitido, o comando é sempre aplicado ao formulário pai. +O parâmetro *\** é útil quando o comando é chamado no contexto de um subformulário em página que contém muitas páginas. Neste caso, quando passar este parâmetro, o comando retorna o número da página do subformulário atual (a que chamou o comando). Por padrão, quando o parâmetro *\** é omitido, o comando é sempre aplicado ao formulário pai. ## Exemplo diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md index 49a051cb2caf38..c7aeafa1f60511 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Selection/create-entity-selection.md @@ -1,4 +1,4 @@ ---- +--- id: create-entity-selection title: Criar uma seleção de entidades (entity selection) slug: /commands/create-entity-selection @@ -45,6 +45,16 @@ No parâmetro opcional *settings*, você pode passar um objeto que contenha a se | ----------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ | | context | Text | Rótulo para o [contexto de otimização](../../ORDA/client-server-optimization.md) aplicado à seleção de entidades. | +:::info + +Por questões de desempenho, no 4D monousuário e no 4D Server, a entity selection retornada está diretamente conectada à seleção atual de *dsTable* (não é uma cópia). Até que a seleção atual seja substituída, as alterações feitas em uma são refletidas na outra. Por exemplo, [`REDUCE SELECTION`](../commands/reduce-selection) reduz a entity selection, e [`.add()`](../../API/EntitySelectionClass.md#add) na entity selection adiciona a entidade à seleção atual. Para obter uma entity selection independente, chame [`.copy()`](../../API/EntitySelectionClass.md#copy) no resultado: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Exemplo ```4d diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md index 59066664d8580a..1e82afc3903b26 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md @@ -1,4 +1,4 @@ ---- +--- id: web-get-body-part title: WEB GET BODY PART slug: /commands/web-get-body-part diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21/API/CollectionClass.md b/i18n/pt/docusaurus-plugin-content-docs/version-21/API/CollectionClass.md index 3d3b327086cc65..4e1bec45b8dec2 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21/API/CollectionClass.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21/API/CollectionClass.md @@ -266,13 +266,12 @@ Por padrão, os elementos *col2* são adicionados ao final da coleção original var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` - ## .concat()
História diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21/ViewPro/configuring.md b/i18n/pt/docusaurus-plugin-content-docs/version-21/ViewPro/configuring.md index 009c3421bd6b05..da4289380a0713 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21/ViewPro/configuring.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21/ViewPro/configuring.md @@ -13,7 +13,7 @@ Using the area's property list, you can set [4D View Pro object properties](Form ### Selecção de uma interface utilizador -Puede seleccionar la interfaz a utilizar con sus áreas de formulario 4D View Pro en la **Lista de propiedades**, en **Apariencia**: +Você pode selecionar a interface a ser usada com suas áreas de formulário 4D View Pro na **Lista de Propriedades**, em **Aparência**: ![](../assets/en/ViewPro/vpUserInterface.PNG) @@ -157,7 +157,8 @@ Formatos de números se aplicam a todos os tipos de números (por exemplo, posit #### Exemplo ```4d -//Set the cell value as $125,571.35 VP SET VALUE(VP Cell("ViewProArea";3;2);New object("value";125571.35;"format";"_($* #,##0.00_)") +//Set the cell value as $125,571.35 +VP SET VALUE(VP Cell("ViewProArea";3;2);New object("value";125571.35;"format";"_($* #,##0.00_)") ``` ### Formatos data e hora @@ -179,7 +180,8 @@ Formatos de números se aplicam a todos os tipos de números (por exemplo, posit #### Exemplo ```4d -//Set the cell value as specific date and time VP SET VALUE(VP Cell("ViewProArea";3;9);New object("value";!2024-12-18!);"time";?14:30:10?;"format";vk pattern full date time)) +//Set the cell value as specific date and time +VP SET VALUE(VP Cell("ViewProArea";3;9);New object("value";!2024-12-18!);"time";?14:30:10?;"format";vk pattern full date time)) ``` ### Formatos data e hora personalizados @@ -400,7 +402,7 @@ Atributos de marca d'água são usados para sobrepor texto ou uma imagem na áre \* Se estiver usando o tipo de texto, passe o caminho do arquivo (absoluto ou relativo) da imagem. Se você passar por um caminho relativo, o arquivo deve estar localizado ao lado do arquivo de estrutura do banco de dados. No Windows, a extensão do ficheiro deve ser indicada. Não importa o tipo usado para definir uma imagem, a imagem em si (não é uma referência) é armazenada na área 4D View Pro sendo retornada pela [VP Get print info](commands/vp-get-print-info.md). -## Style Objects {#style-objects} {#style-objects} +## Style Objects {#style-objects} Objetos de estilo 4D View Pro e folhas de estilo permitem que você controle os aspectos gráficos e a aparência dos seus documentos 4D View Pro. @@ -496,7 +498,7 @@ Contém as seguintes propriedades: ## Variável de objeto do formulário 4D View Pro -La variable del objeto del formulario 4D View Pro es la variable del objeto asociada al área del formulario 4D View Pro. Gere a informação utilizada pelo objeto 4D View Pro. +A variável de objeto do formulário 4D View Pro é a variável [object](Concepts/dt_object.md) associada à área de formulário 4D View Pro. Gere a informação utilizada pelo objeto 4D View Pro. > A variável de objeto 4D View Pro é apenas para fins informativos (ou seja, depuração). Não deve, em caso algum, ser modificado. @@ -508,6 +510,6 @@ Contém as seguintes propriedades: | ViewPro.callbacks | Object | Armazena informações temporárias necessárias para comandos que requerem callbacks como importar e exportar. | | ViewPro.commandBuffers | Collection | Stores sequentially the commands called by the method and executes them as a batch (rather than individually) when exiting the method, when a command returns a value, or when the [VP FLUSH COMMANDS](commands/vp-flush-commands.md) is called. Esse mecanismo aumenta o desempenho ao reduzir o número de pedidos enviados. | | ViewPro.events | Object | [Eventos](#form-events). | -| ViewPro.formulaBar | Parâmetros | Indica se a barra de fórmulas é ou não apresentada. Disponível apenas para a interface "barra de ferramentas". | -| ViewPro.inited | Parâmetros | Indica si el área 4D View Pro ha sido inicializada o no (ver evento[On VP Ready](Events/onVpReady.md)). | +| ViewPro.formulaBar | Boolean | Indica se a barra de fórmulas é ou não apresentada. Disponível apenas para a interface "barra de ferramentas". | +| ViewPro.inited | Boolean | Indica se a área 4D View Pro foi inicializada ou não (ver evento [On VP Ready](Events/onVpReady.md)). | | ViewPro.interface | Text | Especifica o tipo de interface do usuário: "ribbon", "toolbar", "none". | diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21/WebServer/webServer.md b/i18n/pt/docusaurus-plugin-content-docs/version-21/WebServer/webServer.md index 82f61b634fd311..e15dcfe47d1bba 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21/WebServer/webServer.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21/WebServer/webServer.md @@ -6,12 +6,6 @@ title: Servidor Web 4D in local mode and 4D Server include a web server engine (aka http server) that enables you to design and publish powerful web applications that can make the most of your 4D databases. -:::warning Deprecated feature - - Usar o servidor web em um 4D remoto (4D client) está **obsoleto** a partir do 4D 21. Não é mais recomendado utilizar este recurso. - -::: - ## Monitorização fácil Você pode iniciar ou parar a publicação da aplicação web a qualquer momento. Para fazer isso, você só precisa selecionar um comando de menu ou executar uma única linha de código. @@ -66,3 +60,10 @@ O servidor web 4D suporta acesso a dados armazenados em suas aplicações 4D atr ## Métodos banco de dados dedicados `On Web Authentication`, `On Web Connection`, así como también los métodos base`On REST Authentication` son los puntos de entrada de las peticiones en el servidor web; se pueden utilizar para evaluar y enrutar todo tipo de petición. + + +:::warning Deprecated feature + + Usar o servidor web em um 4D remoto (4D client) está **obsoleto** a partir do 4D 21. Não é mais recomendado utilizar este recurso. + +::: diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21/commands-legacy/form-get-current-page.md b/i18n/pt/docusaurus-plugin-content-docs/version-21/commands-legacy/form-get-current-page.md index d6cd9543febf1f..582cedc42c774e 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21/commands-legacy/form-get-current-page.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21/commands-legacy/form-get-current-page.md @@ -32,7 +32,7 @@ displayed_sidebar: docs O comando **FORM Get current page** retorna o número da página atual do formulário mostrado atualmente ou do formulário atual carregado via o comando [FORM LOAD](../commands/form-load.md). -O parâmetro *\** é útil quando o comando é chamado no contexto de um subformulário em página que contém muitas páginas. Neste caso, quando passar este parâmetro, o comando muda a página do subformulário atual (a que chamou o comando). Por padrão, quando o parâmetro *\** é omitido, o comando é sempre aplicado ao formulário pai. +O parâmetro *\** é útil quando o comando é chamado no contexto de um subformulário em página que contém muitas páginas. Neste caso, quando passar este parâmetro, o comando retorna o número da página do subformulário atual (a que chamou o comando). Por padrão, quando o parâmetro *\** é omitido, o comando é sempre aplicado ao formulário pai. ## Exemplo diff --git a/i18n/pt/docusaurus-plugin-content-docs/version-21/commands/create-entity-selection.md b/i18n/pt/docusaurus-plugin-content-docs/version-21/commands/create-entity-selection.md index b115f00e09afb3..dd5379ecbc5b66 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/version-21/commands/create-entity-selection.md +++ b/i18n/pt/docusaurus-plugin-content-docs/version-21/commands/create-entity-selection.md @@ -44,6 +44,17 @@ No parâmetro opcional *settings*, você pode passar um objeto que contenha a se | ----------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ | | context | Text | Rótulo para o [contexto de otimização](../ORDA/client-server-optimization.md) aplicado à seleção de entidades. | + +:::info + +Por razões de desempenho, no 4D single-user e no 4D Server, a entity selection retornada está diretamente conectada à seleção atual de *dsTable* (não é uma cópia). Até que a seleção atual seja substituída, alterações feitas em uma são refletidas na outra. Por exemplo, [`REDUCE SELECTION`](../commands-legacy/reduce-selection.md) reduz a entity selection, e [`.add()`](../API/EntitySelectionClass.md#add) na entity selection adiciona a entidade à seleção atual. Para obter uma entity selection independente, chame [`.copy()`](../API/EntitySelectionClass.md#copy) no resultado: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Exemplo ```4d diff --git a/versioned_docs/version-19/API/CollectionClass.md b/versioned_docs/version-19/API/CollectionClass.md index 9da0a684a9792f..fb54d33b4ac0fb 100644 --- a/versioned_docs/version-19/API/CollectionClass.md +++ b/versioned_docs/version-19/API/CollectionClass.md @@ -349,7 +349,7 @@ By default, *col2* elements are added at the end of the orginal collection. You var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` diff --git a/versioned_docs/version-20/API/CollectionClass.md b/versioned_docs/version-20/API/CollectionClass.md index 6fde292c2785e0..c5a2a45bd4a5e5 100644 --- a/versioned_docs/version-20/API/CollectionClass.md +++ b/versioned_docs/version-20/API/CollectionClass.md @@ -445,7 +445,7 @@ By default, *col2* elements are added at the end of the orginal collection. You var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` diff --git a/versioned_docs/version-20/FormObjects/formObjects_overview.md b/versioned_docs/version-20/FormObjects/formObjects_overview.md index 3cd6f459118d03..cfbea2b6cb2225 100644 --- a/versioned_docs/version-20/FormObjects/formObjects_overview.md +++ b/versioned_docs/version-20/FormObjects/formObjects_overview.md @@ -22,9 +22,10 @@ See the [Building Forms](https://doc.4d.com/4Dv20/4D/20.2/Building-forms.200-675 * **4D language**: Commands from the [Objects (Forms)](https://doc.4d.com/4Dv20/4D/20.6/Objects-Forms.201-7486936.en.html) theme such as `OBJECT DUPLICATE` or `OBJECT SET FONT STYLE` allow to create and define form objects. -* **JSON code in dynamic forms:** Define the properties using JSON. Use the [type](properties_Object.md#type) property to define the object type, then set its available properties. See the [Dynamic Forms](https://doc.4d.com/4Dv21R4/4D/21-R4/Dynamic-Forms.300-7753010.en.html) page for information. +* **JSON code in dynamic forms:** Define the properties using JSON. Use the [type](properties_Object.md#type) property to define the object type, then set its available properties. See the [Dynamic Forms](https://doc.4d.com/4Dv20/4D/20.2/Dynamic-Forms.300-6750140.en.html) page for information. + Example for a button object: - ``` + ```json { "type": "button", "style": "bevel", diff --git a/versioned_docs/version-21-R4/API/CollectionClass.md b/versioned_docs/version-21-R4/API/CollectionClass.md index d5a6020ca7fcef..025e2731f2298a 100644 --- a/versioned_docs/version-21-R4/API/CollectionClass.md +++ b/versioned_docs/version-21-R4/API/CollectionClass.md @@ -292,7 +292,7 @@ By default, *col2* elements are added at the end of the orginal collection. You var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` diff --git a/versioned_docs/version-21-R4/API/WebServerClass.md b/versioned_docs/version-21-R4/API/WebServerClass.md index 62c22e5283db3d..a8cf97032f1abf 100644 --- a/versioned_docs/version-21-R4/API/WebServerClass.md +++ b/versioned_docs/version-21-R4/API/WebServerClass.md @@ -608,7 +608,7 @@ The "SameSite" session |Constant|Value|Description| |---|---|---| |Web SameSite Strict|"Strict"|*Default value* - Cookies are only sent in a first-party context| -|Web SameSite Lax|"Lax"|Cookies are also sent on cross-site subrequests but only when a user is navigating to the origin site (i.e. when following a link).| +|Web SameSite Lax|"Lax"|Cookies are not sent with requests coming from other websites (images, frames, forms, scripts), except when the user navigates to the site from another website with a GET request (following a link, redirection).| |Web SameSite None|"None"|Cookies are sent in all contexts, i.e in responses to both first-party and cross-origin requests. See the [Session Cookie SameSite](WebServer/webServerConfig.md#session-cookie-samesite) description for detailed information. diff --git a/versioned_docs/version-21-R4/ORDA/ordaClasses.md b/versioned_docs/version-21-R4/ORDA/ordaClasses.md index e6efa26ad6d232..c23067a359bf04 100644 --- a/versioned_docs/version-21-R4/ORDA/ordaClasses.md +++ b/versioned_docs/version-21-R4/ORDA/ordaClasses.md @@ -1062,7 +1062,7 @@ $status:=$remoteDS.Schools.registerNewStudent($student) // OK $id:=$remoteDS.Schools.computeIDNumber() // Error "Unknown member method" ``` -## onHTTPGet keyword +## `onHTTPGet` keyword Use the `onHTTPGet` keyword to declare functions that can be called through HTTP requests using the `GET` verb. Such functions can return any web contents, for example using the [`4D.OutgoingMessage`](../API/OutgoingMessageClass.md) class. @@ -1086,7 +1086,9 @@ The `exposed` keyword must also be added in this case, otherwise an error will b :::caution -As this type of call is an easy offered action, the developer must ensure no sensitive action is done in such functions. +`onHTTPGet` lets the function also be called with GET, for example by following a link. Depending on the session cookie's [`SameSite` value](../WebServer/webServerConfig.md#session-cookie-samesite), a link on another website can then send a request that runs in the session of the user logged in to your application. + +Use `onHTTPGet` only for functions that read and return content, such as a file to download, a picture or a report. Do not use `onHTTPGet` for a function that changes anything (i.e. that creates, modifies or deletes data, issues or revokes credentials, sends a message). ::: diff --git a/versioned_docs/version-21-R4/REST/ClassFunctions.md b/versioned_docs/version-21-R4/REST/ClassFunctions.md index b8176863d7ca0c..1f58c816d979ff 100644 --- a/versioned_docs/version-21-R4/REST/ClassFunctions.md +++ b/versioned_docs/version-21-R4/REST/ClassFunctions.md @@ -82,7 +82,11 @@ See [Exposed vs non-exposed functions](../ORDA/ordaClasses.md#exposed-vs-non-exp ### `onHTTPGet` -Functions allowed to be called from HTTP `GET` requests must also be specifically declared with the [`onHTTPGet` keyword](../ORDA/ordaClasses.md#onhttpget-keyword). For example: +Functions allowed to be called from HTTP `GET` requests must also be specifically declared with the [`onHTTPGet` keyword](../ORDA/ordaClasses.md#onhttpget-keyword). Functions declared with `exposed` alone can only be called with `POST`. + +Declare with `onHTTPGet` only functions that read and return content: depending on the session cookie's [`SameSite` value](../WebServer/webServerConfig.md#session-cookie-samesite), a link on another website can send a request that runs in the session of a logged-in user (see the caution in [`onHTTPGet` keyword section](../ORDA/ordaClasses.md#onhttpget-keyword)). + +For example: ```4d //allowing GET requests diff --git a/versioned_docs/version-21-R4/ViewPro/configuring.md b/versioned_docs/version-21-R4/ViewPro/configuring.md index e33a7d61cb9049..fc7601e2dd879f 100644 --- a/versioned_docs/version-21-R4/ViewPro/configuring.md +++ b/versioned_docs/version-21-R4/ViewPro/configuring.md @@ -403,7 +403,7 @@ Watermark attributes are used to superimpose text or an image onto the 4D View P \* If using text type, pass the filepath (absolute or relative) of the image. If you pass a relative path, the file should be located next to the database structure file. In Windows, the file extension must be indicated. No matter the type used to set an image, the image itself (not a reference) is stored in the 4D View Pro area and is returned by [VP Get print info](commands/vp-get-print-info.md). -## Style Objects {#style-objects} {#style-objects} +## Style Objects {#style-objects} 4D View Pro style objects and style sheets allow you to control the graphical aspects and the look of your 4D View Pro documents. diff --git a/versioned_docs/version-21-R4/WebServer/webServer.md b/versioned_docs/version-21-R4/WebServer/webServer.md index a025034b9c8da3..1781ec9a9b8b24 100644 --- a/versioned_docs/version-21-R4/WebServer/webServer.md +++ b/versioned_docs/version-21-R4/WebServer/webServer.md @@ -6,11 +6,6 @@ title: Web Server 4D in local mode and 4D Server include a web server engine (aka http server) that enables you to design and publish powerful web applications that can make the most of your 4D databases. -:::warning Deprecated feature - - Using the web server on a remote 4D (4D client) is **deprecated** as of 4D 21. It is no longer recommended to use this feature. - -::: ## Easy Monitoring @@ -67,3 +62,9 @@ The 4D web server supports access to data stored in your 4D applications through `On Web Authentication`, `On Web Connection`, as well as `On REST Authentication` database methods are the entry points of requests in the web server; they can be used to evaluate and route any type of request. + +:::warning Deprecated feature + + Using the web server on a remote 4D (4D client) is **deprecated** as of 4D 21. It is no longer recommended to use this feature. + +::: diff --git a/versioned_docs/version-21-R4/WebServer/webServerConfig.md b/versioned_docs/version-21-R4/WebServer/webServerConfig.md index 80a10e74848074..22086c39b6b062 100644 --- a/versioned_docs/version-21-R4/WebServer/webServerConfig.md +++ b/versioned_docs/version-21-R4/WebServer/webServerConfig.md @@ -617,13 +617,31 @@ Value of the `SameSite` attribute value of the session cookie. This attribute al Three values are available: -- "Strict" (default `SameSite` attribute value for 4D session cookies): cookies will only be sent in the first-party context, i.e. context matching the domain of the current site, and never to third-party websites. -- "Lax": Cookies are not sent on cross-site subrequests (for example to load images or frames into a third-party site), but are sent when a user is navigating to the origin site (i.e. they follow a link). +- "Strict" (default `SameSite` attribute value for 4D session cookies): the session cookie is only sent with requests coming from pages of the same site, and never with requests coming from other websites. A "site" is a domain with all its subdomains, with the same scheme: `https://app.example.com` and `https://blog.example.com` are the same site, `http://app.example.com` is another one. +- "Lax": Cookies are not sent on cross-site subrequests (for example to load images or frames into a third-party site), but are sent when a user is navigating to the origin site with a GET request (i.e. they follow a link). - "None": Cookies are sent in all contexts, i.e in responses to both first-party and cross-origin requests. When "None" value is used, the cookie `Secure` attribute must also be set (or the cookie will be blocked). -The `Secure` attribute value of the session cookie is automatically set to "True" if the connection is HTTPS (whatever the `SameSite` attribute value). +#### Effect on exposed functions -> It is not recommended to set `SameSite=None` on a HTTP server since the `Secure` attribute will be missing (used in HTTPS only) and cookies will be blocked. +Any web page open in a user's browser can make that browser send requests to your application. If the user has opened a 4D web session in the same browser, the `SameSite` value determines whether these requests carry the 4D session cookie: +- with the cookie, the request runs in the user's session. This can be intended (from an intranet portal, for example), but a malicious website can use it to act on behalf of the user (cross-site request forgery, CSRF); +- without the cookie, the request runs as a guest. + +In both cases, the function is executed only if the privileges of that session allow it. + +|Request from another website to|"Strict"|"Lax"|"None"| +|---|---|---|---| +|an [exposed](../ORDA/ordaClasses.md#exposed-vs-non-exposed-functions) function (POST only)|Runs as a guest|Runs as a guest|Runs in the user's session (form, script)| +|an exposed [onHTTPGet](../ORDA/ordaClasses.md#onhttpget-keyword) function (GET and POST)|Runs as a guest|Runs in the user's session through a link or a redirection; as a guest otherwise|Runs in the user's session (link, redirection, image, form, script)| + + +:::note Notes + +- Keep in mind that a site includes its subdomains. Whatever the `SameSite` value, requests sent by pages of another application on your site (for example https://blog.example.com for https://app.example.com) run in the user's session. +- Use "None" only if your application must be used inside another website (for example in a frame), and check that each exposed function can safely run in the user's session when another website requests it. +- The `Secure` attribute value of the session cookie is automatically set to "True" if the connection is HTTPS (whatever the `SameSite` attribute value). It is not recommended to set `SameSite=None` on a HTTP server since the `Secure` attribute will be missing (used in HTTPS only) and cookies will be blocked. + +::: diff --git a/versioned_docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md b/versioned_docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md index 7463aa1174347b..39f50b5f7f46c3 100644 --- a/versioned_docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md +++ b/versioned_docs/version-21-R4/language-legacy/4D Environment/set-database-parameter.md @@ -812,9 +812,9 @@ Refer to example 2. **Kept between two sessions**: No -**Possible values**: Positive integer. Default value = 15, minimum value = 1. +**Possible values**: Positive integer. Default value = 900, minimum value = 60. -**Description**: Timeout in minutes for client/server sessions in the event of an unexpected disconnection from the QUIC network layer. This timeout is the period of time allowed for a session during which the connection between the server and the client can be automatically reestablished following an unintended disconnection. If, at the end of this timeout, the connection has not been reestablished. +**Description**: Timeout in seconds for client/server sessions in the event of an unexpected disconnection from the QUIC network layer. This timeout is the period of time allowed for a session during which the connection between the server and the client can be automatically reestablished following an unintended disconnection. If, at the end of this timeout, the connection has not been reestablished, the client session is closed with a message. This setting can only be set on 4D Server and applies to all new 4D remote sessions (existing sessions timeout value is untouched). diff --git a/versioned_docs/version-21-R4/language-legacy/Forms/form-get-current-page.md b/versioned_docs/version-21-R4/language-legacy/Forms/form-get-current-page.md index be0a9ba1c72451..4b681171317d8e 100644 --- a/versioned_docs/version-21-R4/language-legacy/Forms/form-get-current-page.md +++ b/versioned_docs/version-21-R4/language-legacy/Forms/form-get-current-page.md @@ -32,7 +32,7 @@ displayed_sidebar: docs The **FORM Get current page** command returns the number of the currently displayed form page or of the current form loaded by the [FORM LOAD](../commands/form-load) command. -The *\** parameter is useful when the command is called in the context of a page type subform containing several pages. In this case, when you pass this parameter, the command changes the page of the current subform (the one that called the command). By default, when the *\** parameter is omitted, the command is always applied to the parent form. +The *\** parameter is useful when the command is called in the context of a page type subform containing several pages. In this case, when you pass this parameter, the command returns the page number of the current subform (the one that called the command). By default, when the *\** parameter is omitted, the command is always applied to the parent form. ## Example diff --git a/versioned_docs/version-21-R4/language-legacy/Selection/create-entity-selection.md b/versioned_docs/version-21-R4/language-legacy/Selection/create-entity-selection.md index 75d089df2c725a..0ffe9cc0713d46 100644 --- a/versioned_docs/version-21-R4/language-legacy/Selection/create-entity-selection.md +++ b/versioned_docs/version-21-R4/language-legacy/Selection/create-entity-selection.md @@ -43,6 +43,16 @@ In the optional *settings* parameter, you can pass an object containing the foll |context|Text|Label for the [optimization context](../../ORDA/client-server-optimization.md) applied to the entity selection.| +:::info + +For performance reasons, in 4D single-user and 4D Server, the returned entity selection is directly connected to the current selection of *dsTable* (it is not a copy). Until the current selection is replaced, changes made to one are reflected in the other. For example, [`REDUCE SELECTION`](../commands/reduce-selection) shortens the entity selection, and [`.add()`](../../API/EntitySelectionClass.md#add) on the entity selection adds the entity to the current selection. To get an independent entity selection, call [`.copy()`](../../API/EntitySelectionClass.md#copy) on the result: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Example ```4d diff --git a/versioned_docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md b/versioned_docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md index ac613bb721ec65..c83c16eeb7ac90 100644 --- a/versioned_docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md +++ b/versioned_docs/version-21-R4/language-legacy/Web Server/web-get-body-part.md @@ -39,8 +39,8 @@ The *contents* parameter receives the contents of the part. When the parts to be The *name* parameter receives the variable name of the HTTP input field. -The *mimeType* and *name* parameters receive the Mime type and the name of the original file, if any. A *name* is only received when the file was submitted as ``. -*mimeType* and *name* are optional but must be passed together. +The *mimeType* and *fileName* parameters receive the Mime type and the name of the original file, if any. A *fileName* is only received when the file was submitted as ``. +*mimeType* and *fileName* are optional but must be passed together. **Note:** In the context of a multi-part request, the first array of the [WEB GET VARIABLES](../commands/web-get-variables) command returns all parts of the form, in the same order as the **WEB GET BODY PART** command. You can use it in order to get the position of the parts of the form directly. diff --git a/versioned_docs/version-21-R5/API/CollectionClass.md b/versioned_docs/version-21-R5/API/CollectionClass.md index d5a6020ca7fcef..025e2731f2298a 100644 --- a/versioned_docs/version-21-R5/API/CollectionClass.md +++ b/versioned_docs/version-21-R5/API/CollectionClass.md @@ -292,7 +292,7 @@ By default, *col2* elements are added at the end of the orginal collection. You var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` diff --git a/versioned_docs/version-21-R5/API/WebServerClass.md b/versioned_docs/version-21-R5/API/WebServerClass.md index c5fa041c9d8b02..3737e3d13bceeb 100644 --- a/versioned_docs/version-21-R5/API/WebServerClass.md +++ b/versioned_docs/version-21-R5/API/WebServerClass.md @@ -718,7 +718,7 @@ The "SameSite" session |Constant|Value|Description| |---|---|---| |Web SameSite Strict|"Strict"|*Default value* - Cookies are only sent in a first-party context| -|Web SameSite Lax|"Lax"|Cookies are also sent on cross-site subrequests but only when a user is navigating to the origin site (i.e. when following a link).| +|Web SameSite Lax|"Lax"|Cookies are not sent with requests coming from other websites (images, frames, forms, scripts), except when the user navigates to the site from another website with a GET request (following a link, redirection).| |Web SameSite None|"None"|Cookies are sent in all contexts, i.e in responses to both first-party and cross-origin requests. See the [Session Cookie SameSite](WebServer/webServerConfig.md#session-cookie-samesite) description for detailed information. diff --git a/versioned_docs/version-21-R5/ORDA/ordaClasses.md b/versioned_docs/version-21-R5/ORDA/ordaClasses.md index e6efa26ad6d232..c23067a359bf04 100644 --- a/versioned_docs/version-21-R5/ORDA/ordaClasses.md +++ b/versioned_docs/version-21-R5/ORDA/ordaClasses.md @@ -1062,7 +1062,7 @@ $status:=$remoteDS.Schools.registerNewStudent($student) // OK $id:=$remoteDS.Schools.computeIDNumber() // Error "Unknown member method" ``` -## onHTTPGet keyword +## `onHTTPGet` keyword Use the `onHTTPGet` keyword to declare functions that can be called through HTTP requests using the `GET` verb. Such functions can return any web contents, for example using the [`4D.OutgoingMessage`](../API/OutgoingMessageClass.md) class. @@ -1086,7 +1086,9 @@ The `exposed` keyword must also be added in this case, otherwise an error will b :::caution -As this type of call is an easy offered action, the developer must ensure no sensitive action is done in such functions. +`onHTTPGet` lets the function also be called with GET, for example by following a link. Depending on the session cookie's [`SameSite` value](../WebServer/webServerConfig.md#session-cookie-samesite), a link on another website can then send a request that runs in the session of the user logged in to your application. + +Use `onHTTPGet` only for functions that read and return content, such as a file to download, a picture or a report. Do not use `onHTTPGet` for a function that changes anything (i.e. that creates, modifies or deletes data, issues or revokes credentials, sends a message). ::: diff --git a/versioned_docs/version-21-R5/REST/ClassFunctions.md b/versioned_docs/version-21-R5/REST/ClassFunctions.md index b8176863d7ca0c..1f58c816d979ff 100644 --- a/versioned_docs/version-21-R5/REST/ClassFunctions.md +++ b/versioned_docs/version-21-R5/REST/ClassFunctions.md @@ -82,7 +82,11 @@ See [Exposed vs non-exposed functions](../ORDA/ordaClasses.md#exposed-vs-non-exp ### `onHTTPGet` -Functions allowed to be called from HTTP `GET` requests must also be specifically declared with the [`onHTTPGet` keyword](../ORDA/ordaClasses.md#onhttpget-keyword). For example: +Functions allowed to be called from HTTP `GET` requests must also be specifically declared with the [`onHTTPGet` keyword](../ORDA/ordaClasses.md#onhttpget-keyword). Functions declared with `exposed` alone can only be called with `POST`. + +Declare with `onHTTPGet` only functions that read and return content: depending on the session cookie's [`SameSite` value](../WebServer/webServerConfig.md#session-cookie-samesite), a link on another website can send a request that runs in the session of a logged-in user (see the caution in [`onHTTPGet` keyword section](../ORDA/ordaClasses.md#onhttpget-keyword)). + +For example: ```4d //allowing GET requests diff --git a/versioned_docs/version-21-R5/ViewPro/configuring.md b/versioned_docs/version-21-R5/ViewPro/configuring.md index e33a7d61cb9049..fc7601e2dd879f 100644 --- a/versioned_docs/version-21-R5/ViewPro/configuring.md +++ b/versioned_docs/version-21-R5/ViewPro/configuring.md @@ -403,7 +403,7 @@ Watermark attributes are used to superimpose text or an image onto the 4D View P \* If using text type, pass the filepath (absolute or relative) of the image. If you pass a relative path, the file should be located next to the database structure file. In Windows, the file extension must be indicated. No matter the type used to set an image, the image itself (not a reference) is stored in the 4D View Pro area and is returned by [VP Get print info](commands/vp-get-print-info.md). -## Style Objects {#style-objects} {#style-objects} +## Style Objects {#style-objects} 4D View Pro style objects and style sheets allow you to control the graphical aspects and the look of your 4D View Pro documents. diff --git a/versioned_docs/version-21-R5/WebServer/webServer.md b/versioned_docs/version-21-R5/WebServer/webServer.md index 4def5c935bcf20..90dee70f4ab113 100644 --- a/versioned_docs/version-21-R5/WebServer/webServer.md +++ b/versioned_docs/version-21-R5/WebServer/webServer.md @@ -6,11 +6,6 @@ title: Web Server 4D in local mode and 4D Server include a web server engine (aka http server) that enables you to design and publish powerful web applications that can make the most of your 4D databases. -:::warning Deprecated feature - - Using the web server on a remote 4D (4D client) is **deprecated** as of 4D 21. It is no longer recommended to use this feature. - -::: ## Easy Monitoring @@ -67,3 +62,9 @@ The 4D web server supports access to data stored in your 4D applications through `On Web Authentication`, `On Web Connection`, as well as `On REST Authentication` database methods are the entry points of requests in the web server; they can be used to evaluate and route any type of request. + +:::warning Deprecated feature + + Using the web server on a remote 4D (4D client) is **deprecated** as of 4D 21. It is no longer recommended to use this feature. + +::: diff --git a/versioned_docs/version-21-R5/WebServer/webServerConfig.md b/versioned_docs/version-21-R5/WebServer/webServerConfig.md index 80a10e74848074..22086c39b6b062 100644 --- a/versioned_docs/version-21-R5/WebServer/webServerConfig.md +++ b/versioned_docs/version-21-R5/WebServer/webServerConfig.md @@ -617,13 +617,31 @@ Value of the `SameSite` attribute value of the session cookie. This attribute al Three values are available: -- "Strict" (default `SameSite` attribute value for 4D session cookies): cookies will only be sent in the first-party context, i.e. context matching the domain of the current site, and never to third-party websites. -- "Lax": Cookies are not sent on cross-site subrequests (for example to load images or frames into a third-party site), but are sent when a user is navigating to the origin site (i.e. they follow a link). +- "Strict" (default `SameSite` attribute value for 4D session cookies): the session cookie is only sent with requests coming from pages of the same site, and never with requests coming from other websites. A "site" is a domain with all its subdomains, with the same scheme: `https://app.example.com` and `https://blog.example.com` are the same site, `http://app.example.com` is another one. +- "Lax": Cookies are not sent on cross-site subrequests (for example to load images or frames into a third-party site), but are sent when a user is navigating to the origin site with a GET request (i.e. they follow a link). - "None": Cookies are sent in all contexts, i.e in responses to both first-party and cross-origin requests. When "None" value is used, the cookie `Secure` attribute must also be set (or the cookie will be blocked). -The `Secure` attribute value of the session cookie is automatically set to "True" if the connection is HTTPS (whatever the `SameSite` attribute value). +#### Effect on exposed functions -> It is not recommended to set `SameSite=None` on a HTTP server since the `Secure` attribute will be missing (used in HTTPS only) and cookies will be blocked. +Any web page open in a user's browser can make that browser send requests to your application. If the user has opened a 4D web session in the same browser, the `SameSite` value determines whether these requests carry the 4D session cookie: +- with the cookie, the request runs in the user's session. This can be intended (from an intranet portal, for example), but a malicious website can use it to act on behalf of the user (cross-site request forgery, CSRF); +- without the cookie, the request runs as a guest. + +In both cases, the function is executed only if the privileges of that session allow it. + +|Request from another website to|"Strict"|"Lax"|"None"| +|---|---|---|---| +|an [exposed](../ORDA/ordaClasses.md#exposed-vs-non-exposed-functions) function (POST only)|Runs as a guest|Runs as a guest|Runs in the user's session (form, script)| +|an exposed [onHTTPGet](../ORDA/ordaClasses.md#onhttpget-keyword) function (GET and POST)|Runs as a guest|Runs in the user's session through a link or a redirection; as a guest otherwise|Runs in the user's session (link, redirection, image, form, script)| + + +:::note Notes + +- Keep in mind that a site includes its subdomains. Whatever the `SameSite` value, requests sent by pages of another application on your site (for example https://blog.example.com for https://app.example.com) run in the user's session. +- Use "None" only if your application must be used inside another website (for example in a frame), and check that each exposed function can safely run in the user's session when another website requests it. +- The `Secure` attribute value of the session cookie is automatically set to "True" if the connection is HTTPS (whatever the `SameSite` attribute value). It is not recommended to set `SameSite=None` on a HTTP server since the `Secure` attribute will be missing (used in HTTPS only) and cookies will be blocked. + +::: diff --git a/versioned_docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md b/versioned_docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md index 7463aa1174347b..39f50b5f7f46c3 100644 --- a/versioned_docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md +++ b/versioned_docs/version-21-R5/language-legacy/4D Environment/set-database-parameter.md @@ -812,9 +812,9 @@ Refer to example 2. **Kept between two sessions**: No -**Possible values**: Positive integer. Default value = 15, minimum value = 1. +**Possible values**: Positive integer. Default value = 900, minimum value = 60. -**Description**: Timeout in minutes for client/server sessions in the event of an unexpected disconnection from the QUIC network layer. This timeout is the period of time allowed for a session during which the connection between the server and the client can be automatically reestablished following an unintended disconnection. If, at the end of this timeout, the connection has not been reestablished. +**Description**: Timeout in seconds for client/server sessions in the event of an unexpected disconnection from the QUIC network layer. This timeout is the period of time allowed for a session during which the connection between the server and the client can be automatically reestablished following an unintended disconnection. If, at the end of this timeout, the connection has not been reestablished, the client session is closed with a message. This setting can only be set on 4D Server and applies to all new 4D remote sessions (existing sessions timeout value is untouched). diff --git a/versioned_docs/version-21-R5/language-legacy/Forms/form-get-current-page.md b/versioned_docs/version-21-R5/language-legacy/Forms/form-get-current-page.md index be0a9ba1c72451..4b681171317d8e 100644 --- a/versioned_docs/version-21-R5/language-legacy/Forms/form-get-current-page.md +++ b/versioned_docs/version-21-R5/language-legacy/Forms/form-get-current-page.md @@ -32,7 +32,7 @@ displayed_sidebar: docs The **FORM Get current page** command returns the number of the currently displayed form page or of the current form loaded by the [FORM LOAD](../commands/form-load) command. -The *\** parameter is useful when the command is called in the context of a page type subform containing several pages. In this case, when you pass this parameter, the command changes the page of the current subform (the one that called the command). By default, when the *\** parameter is omitted, the command is always applied to the parent form. +The *\** parameter is useful when the command is called in the context of a page type subform containing several pages. In this case, when you pass this parameter, the command returns the page number of the current subform (the one that called the command). By default, when the *\** parameter is omitted, the command is always applied to the parent form. ## Example diff --git a/versioned_docs/version-21-R5/language-legacy/Selection/create-entity-selection.md b/versioned_docs/version-21-R5/language-legacy/Selection/create-entity-selection.md index 75d089df2c725a..0ffe9cc0713d46 100644 --- a/versioned_docs/version-21-R5/language-legacy/Selection/create-entity-selection.md +++ b/versioned_docs/version-21-R5/language-legacy/Selection/create-entity-selection.md @@ -43,6 +43,16 @@ In the optional *settings* parameter, you can pass an object containing the foll |context|Text|Label for the [optimization context](../../ORDA/client-server-optimization.md) applied to the entity selection.| +:::info + +For performance reasons, in 4D single-user and 4D Server, the returned entity selection is directly connected to the current selection of *dsTable* (it is not a copy). Until the current selection is replaced, changes made to one are reflected in the other. For example, [`REDUCE SELECTION`](../commands/reduce-selection) shortens the entity selection, and [`.add()`](../../API/EntitySelectionClass.md#add) on the entity selection adds the entity to the current selection. To get an independent entity selection, call [`.copy()`](../../API/EntitySelectionClass.md#copy) on the result: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Example ```4d diff --git a/versioned_docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md b/versioned_docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md index ac613bb721ec65..c83c16eeb7ac90 100644 --- a/versioned_docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md +++ b/versioned_docs/version-21-R5/language-legacy/Web Server/web-get-body-part.md @@ -39,8 +39,8 @@ The *contents* parameter receives the contents of the part. When the parts to be The *name* parameter receives the variable name of the HTTP input field. -The *mimeType* and *name* parameters receive the Mime type and the name of the original file, if any. A *name* is only received when the file was submitted as ``. -*mimeType* and *name* are optional but must be passed together. +The *mimeType* and *fileName* parameters receive the Mime type and the name of the original file, if any. A *fileName* is only received when the file was submitted as ``. +*mimeType* and *fileName* are optional but must be passed together. **Note:** In the context of a multi-part request, the first array of the [WEB GET VARIABLES](../commands/web-get-variables) command returns all parts of the form, in the same order as the **WEB GET BODY PART** command. You can use it in order to get the position of the parts of the form directly. diff --git a/versioned_docs/version-21/API/CollectionClass.md b/versioned_docs/version-21/API/CollectionClass.md index fa1f4e2444a5b0..03399a350cf7b5 100644 --- a/versioned_docs/version-21/API/CollectionClass.md +++ b/versioned_docs/version-21/API/CollectionClass.md @@ -287,7 +287,7 @@ By default, *col2* elements are added at the end of the orginal collection. You var $c; $fruits : Collection $c:=New collection(1;2;3;4;5;6) $fruits:=New collection("Orange";"Banana";"Apple";"Grape") -$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] +$c.combine($fruits;3) //$c=[1,2,3,"Orange","Banana","Apple","Grape",4,5,6] ``` diff --git a/versioned_docs/version-21/API/WebServerClass.md b/versioned_docs/version-21/API/WebServerClass.md index fbf9bb7018cdde..5b83d2f4c85912 100644 --- a/versioned_docs/version-21/API/WebServerClass.md +++ b/versioned_docs/version-21/API/WebServerClass.md @@ -605,7 +605,7 @@ The "SameSite" session |Constant|Value|Description| |---|---|---| |Web SameSite Strict|"Strict"|*Default value* - Cookies are only sent in a first-party context| -|Web SameSite Lax|"Lax"|Cookies are also sent on cross-site subrequests but only when a user is navigating to the origin site (i.e. when following a link).| +|Web SameSite Lax|"Lax"|Cookies are not sent with requests coming from other websites (images, frames, forms, scripts), except when the user navigates to the site from another website with a GET request (following a link, redirection).| |Web SameSite None|"None"|Cookies are sent in all contexts, i.e in responses to both first-party and cross-origin requests. See the [Session Cookie SameSite](WebServer/webServerConfig.md#session-cookie-samesite) description for detailed information. diff --git a/versioned_docs/version-21/ORDA/ordaClasses.md b/versioned_docs/version-21/ORDA/ordaClasses.md index dbc536a7815172..985c508147f0dd 100644 --- a/versioned_docs/version-21/ORDA/ordaClasses.md +++ b/versioned_docs/version-21/ORDA/ordaClasses.md @@ -1051,7 +1051,7 @@ $status:=$remoteDS.Schools.registerNewStudent($student) // OK $id:=$remoteDS.Schools.computeIDNumber() // Error "Unknown member method" ``` -## onHTTPGet keyword +## `onHTTPGet` keyword Use the `onHTTPGet` keyword to declare functions that can be called through HTTP requests using the `GET` verb. Such functions can return any web contents, for example using the [`4D.OutgoingMessage`](../API/OutgoingMessageClass.md) class. @@ -1075,7 +1075,9 @@ The `exposed` keyword must also be added in this case, otherwise an error will b :::caution -As this type of call is an easy offered action, the developer must ensure no sensitive action is done in such functions. +`onHTTPGet` lets the function also be called with GET, for example by following a link. Depending on the session cookie's [`SameSite` value](../WebServer/webServerConfig.md#session-cookie-samesite), a link on another website can then send a request that runs in the session of the user logged in to your application. + +Use `onHTTPGet` only for functions that read and return content, such as a file to download, a picture or a report. Do not use `onHTTPGet` for a function that changes anything (i.e. that creates, modifies or deletes data, issues or revokes credentials, sends a message). ::: diff --git a/versioned_docs/version-21/REST/ClassFunctions.md b/versioned_docs/version-21/REST/ClassFunctions.md index b8176863d7ca0c..1f58c816d979ff 100644 --- a/versioned_docs/version-21/REST/ClassFunctions.md +++ b/versioned_docs/version-21/REST/ClassFunctions.md @@ -82,7 +82,11 @@ See [Exposed vs non-exposed functions](../ORDA/ordaClasses.md#exposed-vs-non-exp ### `onHTTPGet` -Functions allowed to be called from HTTP `GET` requests must also be specifically declared with the [`onHTTPGet` keyword](../ORDA/ordaClasses.md#onhttpget-keyword). For example: +Functions allowed to be called from HTTP `GET` requests must also be specifically declared with the [`onHTTPGet` keyword](../ORDA/ordaClasses.md#onhttpget-keyword). Functions declared with `exposed` alone can only be called with `POST`. + +Declare with `onHTTPGet` only functions that read and return content: depending on the session cookie's [`SameSite` value](../WebServer/webServerConfig.md#session-cookie-samesite), a link on another website can send a request that runs in the session of a logged-in user (see the caution in [`onHTTPGet` keyword section](../ORDA/ordaClasses.md#onhttpget-keyword)). + +For example: ```4d //allowing GET requests diff --git a/versioned_docs/version-21/ViewPro/configuring.md b/versioned_docs/version-21/ViewPro/configuring.md index 8bb6d1da2e9714..bb701c3a253fa8 100644 --- a/versioned_docs/version-21/ViewPro/configuring.md +++ b/versioned_docs/version-21/ViewPro/configuring.md @@ -403,7 +403,7 @@ Watermark attributes are used to superimpose text or an image onto the 4D View P \* If using text type, pass the filepath (absolute or relative) of the image. If you pass a relative path, the file should be located next to the database structure file. In Windows, the file extension must be indicated. No matter the type used to set an image, the image itself (not a reference) is stored in the 4D View Pro area and is returned by [VP Get print info](commands/vp-get-print-info.md). -## Style Objects {#style-objects} {#style-objects} +## Style Objects {#style-objects} 4D View Pro style objects and style sheets allow you to control the graphical aspects and the look of your 4D View Pro documents. diff --git a/versioned_docs/version-21/WebServer/webServer.md b/versioned_docs/version-21/WebServer/webServer.md index 1d686094925126..b05ae3ded19aac 100644 --- a/versioned_docs/version-21/WebServer/webServer.md +++ b/versioned_docs/version-21/WebServer/webServer.md @@ -6,11 +6,6 @@ title: Web Server 4D in local mode and 4D Server include a web server engine (aka http server) that enables you to design and publish powerful web applications that can make the most of your 4D databases. -:::warning Deprecated feature - - Using the web server on a remote 4D (4D client) is **deprecated** as of 4D 21. It is no longer recommended to use this feature. - -::: ## Easy Monitoring @@ -66,3 +61,11 @@ The 4D web server supports access to data stored in your 4D applications through ## Dedicated Database Methods `On Web Authentication`, `On Web Connection`, as well as `On REST Authentication` database methods are the entry points of requests in the web server; they can be used to evaluate and route any type of request. + + + +:::warning Deprecated feature + + Using the web server on a remote 4D (4D client) is **deprecated** as of 4D 21. It is no longer recommended to use this feature. + +::: diff --git a/versioned_docs/version-21/WebServer/webServerConfig.md b/versioned_docs/version-21/WebServer/webServerConfig.md index 80a10e74848074..22086c39b6b062 100644 --- a/versioned_docs/version-21/WebServer/webServerConfig.md +++ b/versioned_docs/version-21/WebServer/webServerConfig.md @@ -617,13 +617,31 @@ Value of the `SameSite` attribute value of the session cookie. This attribute al Three values are available: -- "Strict" (default `SameSite` attribute value for 4D session cookies): cookies will only be sent in the first-party context, i.e. context matching the domain of the current site, and never to third-party websites. -- "Lax": Cookies are not sent on cross-site subrequests (for example to load images or frames into a third-party site), but are sent when a user is navigating to the origin site (i.e. they follow a link). +- "Strict" (default `SameSite` attribute value for 4D session cookies): the session cookie is only sent with requests coming from pages of the same site, and never with requests coming from other websites. A "site" is a domain with all its subdomains, with the same scheme: `https://app.example.com` and `https://blog.example.com` are the same site, `http://app.example.com` is another one. +- "Lax": Cookies are not sent on cross-site subrequests (for example to load images or frames into a third-party site), but are sent when a user is navigating to the origin site with a GET request (i.e. they follow a link). - "None": Cookies are sent in all contexts, i.e in responses to both first-party and cross-origin requests. When "None" value is used, the cookie `Secure` attribute must also be set (or the cookie will be blocked). -The `Secure` attribute value of the session cookie is automatically set to "True" if the connection is HTTPS (whatever the `SameSite` attribute value). +#### Effect on exposed functions -> It is not recommended to set `SameSite=None` on a HTTP server since the `Secure` attribute will be missing (used in HTTPS only) and cookies will be blocked. +Any web page open in a user's browser can make that browser send requests to your application. If the user has opened a 4D web session in the same browser, the `SameSite` value determines whether these requests carry the 4D session cookie: +- with the cookie, the request runs in the user's session. This can be intended (from an intranet portal, for example), but a malicious website can use it to act on behalf of the user (cross-site request forgery, CSRF); +- without the cookie, the request runs as a guest. + +In both cases, the function is executed only if the privileges of that session allow it. + +|Request from another website to|"Strict"|"Lax"|"None"| +|---|---|---|---| +|an [exposed](../ORDA/ordaClasses.md#exposed-vs-non-exposed-functions) function (POST only)|Runs as a guest|Runs as a guest|Runs in the user's session (form, script)| +|an exposed [onHTTPGet](../ORDA/ordaClasses.md#onhttpget-keyword) function (GET and POST)|Runs as a guest|Runs in the user's session through a link or a redirection; as a guest otherwise|Runs in the user's session (link, redirection, image, form, script)| + + +:::note Notes + +- Keep in mind that a site includes its subdomains. Whatever the `SameSite` value, requests sent by pages of another application on your site (for example https://blog.example.com for https://app.example.com) run in the user's session. +- Use "None" only if your application must be used inside another website (for example in a frame), and check that each exposed function can safely run in the user's session when another website requests it. +- The `Secure` attribute value of the session cookie is automatically set to "True" if the connection is HTTPS (whatever the `SameSite` attribute value). It is not recommended to set `SameSite=None` on a HTTP server since the `Secure` attribute will be missing (used in HTTPS only) and cookies will be blocked. + +::: diff --git a/versioned_docs/version-21/commands-legacy/form-get-current-page.md b/versioned_docs/version-21/commands-legacy/form-get-current-page.md index 75a8baf558480b..a7dc1c6b896b04 100644 --- a/versioned_docs/version-21/commands-legacy/form-get-current-page.md +++ b/versioned_docs/version-21/commands-legacy/form-get-current-page.md @@ -32,7 +32,7 @@ displayed_sidebar: docs The **FORM Get current page** command returns the number of the currently displayed form page or of the current form loaded by the [FORM LOAD](../commands/form-load.md) command. -The *\** parameter is useful when the command is called in the context of a page type subform containing several pages. In this case, when you pass this parameter, the command changes the page of the current subform (the one that called the command). By default, when the *\** parameter is omitted, the command is always applied to the parent form. +The *\** parameter is useful when the command is called in the context of a page type subform containing several pages. In this case, when you pass this parameter, the command returns the page number of the current subform (the one that called the command). By default, when the *\** parameter is omitted, the command is always applied to the parent form. ## Example diff --git a/versioned_docs/version-21/commands-legacy/web-get-body-part.md b/versioned_docs/version-21/commands-legacy/web-get-body-part.md index 8db0483ae6ae1e..06736d656cada4 100644 --- a/versioned_docs/version-21/commands-legacy/web-get-body-part.md +++ b/versioned_docs/version-21/commands-legacy/web-get-body-part.md @@ -39,8 +39,8 @@ The *contents* parameter receives the contents of the part. When the parts to be The *name* parameter receives the variable name of the HTTP input field. -The *mimeType* and *name* parameters receive the Mime type and the name of the original file, if any. A *name* is only received when the file was submitted as ``. -*mimeType* and *name* are optional but must be passed together. +The *mimeType* and *fileName* parameters receive the Mime type and the name of the original file, if any. A *fileName* is only received when the file was submitted as ``. +*mimeType* and *fileName* are optional but must be passed together. **Note:** In the context of a multi-part request, the first array of the [WEB GET VARIABLES](web-get-variables.md) command returns all parts of the form, in the same order as the **WEB GET BODY PART** command. You can use it in order to get the position of the parts of the form directly. diff --git a/versioned_docs/version-21/commands/create-entity-selection.md b/versioned_docs/version-21/commands/create-entity-selection.md index 47fc7565167235..67d19cea8c40c3 100644 --- a/versioned_docs/version-21/commands/create-entity-selection.md +++ b/versioned_docs/version-21/commands/create-entity-selection.md @@ -42,6 +42,16 @@ In the optional *settings* parameter, you can pass an object containing the foll |context|Text|Label for the [optimization context](../ORDA/client-server-optimization.md) applied to the entity selection.| +:::info + +For performance reasons, in 4D single-user and 4D Server, the returned entity selection is directly connected to the current selection of *dsTable* (it is not a copy). Until the current selection is replaced, changes made to one are reflected in the other. For example, [`REDUCE SELECTION`](../commands-legacy/reduce-selection.md) shortens the entity selection, and [`.add()`](../API/EntitySelectionClass.md#add) on the entity selection adds the entity to the current selection. To get an independent entity selection, call [`.copy()`](../API/EntitySelectionClass.md#copy) on the result: + +```4d +$es:=Create entity selection([Employee]).copy() +``` + +::: + ## Example ```4d