diff --git a/i18n/es/docusaurus-plugin-content-docs/current/API/QuotaManagerClass.md b/i18n/es/docusaurus-plugin-content-docs/current/API/QuotaManagerClass.md index 13a1bbe1bc77a3..5a1a2846fc5303 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/API/QuotaManagerClass.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/API/QuotaManagerClass.md @@ -11,12 +11,6 @@ La clase `4D.QuotaManager` le ofrece una interfaz para configurar y monitorizar ::: -:::tip Entradas de blog relacionadas - -[Un servidor web 4D que sabe cuándo decir No](https://blog.4d.com/a-4d-web-server-that-knows-when-to-say-no/) - -::: - Los objetos `4D.QuotaManager` se pueden instanciar de las siguientes maneras: - la [propiedad `quotas` de un objeto Session](./SessionClass.md#quotas) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/Develop/preemptive.md b/i18n/es/docusaurus-plugin-content-docs/current/Develop/preemptive.md index 3d68172398d401..6d49343ef332ff 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/Develop/preemptive.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/Develop/preemptive.md @@ -41,7 +41,7 @@ Dado que un hilo se maneja de forma independiente a partir del método del proce La propiedad "seguridad de hilo" de cada elemento depende del elemento en sí: -- Comandos 4D: hilo seguro es una propiedad interna. En la documentación de 4D, los comandos hilo seguro se identifican con el icono ![](../assets/en/Develop/thread-safe.png). También puede utilizar el comando [`Nombre del comando`](../commands/command-name) para saber si un comando es hilo seguro. Gran parte de los comandos 4D pueden ejecutarse en modo apropiativo. +- Comandos 4D: hilo seguro es una propiedad interna. The 4D documentation indicates whether each command is thread-safe or not in the Properties section. También puede utilizar el comando [`Nombre del comando`](../commands/command-name) para saber si un comando es hilo seguro. Gran parte de los comandos 4D pueden ejecutarse en modo apropiativo. - Métodos de proyecto: las condiciones para seguridad de hilo se listan en [este párrafo](#writing-a-thread-safe-method). Básicamente, el código que se ejecuta en hilos apropiativos no puede llamar a las partes con las interacciones externas, tal como el código plug-in o las variables interproceso. Los accesos a los datos, sin embargo, son permitidos desde el servidor de datos 4D que soporta la ejecución apropiativa. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/ORDA/privileges.md b/i18n/es/docusaurus-plugin-content-docs/current/ORDA/privileges.md index 073e5b23ce628c..1994b1debf07f8 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/ORDA/privileges.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/ORDA/privileges.md @@ -294,6 +294,12 @@ The project's web security settings are defined in `roles.json`: ::: +:::warning + +When a permission entry references an undeclared [privilege](#privileges-and-roles), 4D logs an error and ignores the entry. In this case, the permission is ignored. If the [restricted mode by default](#restriction-modes) is not enabled, the resource is accessible to `guest` sessions. + +::: + ### Default location and content New projects generate `roles.json` at: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/WebServer/quotas.md b/i18n/es/docusaurus-plugin-content-docs/current/WebServer/quotas.md index 32690cf53b00ec..5d96247ccab09c 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/WebServer/quotas.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/WebServer/quotas.md @@ -12,12 +12,6 @@ Las cuotas del servidor web le permiten controlar el uso de recursos limitando e ::: -:::tip Entradas de blog relacionadas - -[Un servidor web 4D que sabe cuándo decir No](https://blog.4d.com/a-4d-web-server-that-knows-when-to-say-no/) - -::: - ## Requisitos La configuración de cuotas requiere la activación de las [sesiones escalables](./sessions.md#enabling-web-sessions). 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/assets/en/embedding-studio/menu.png b/i18n/es/docusaurus-plugin-content-docs/current/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/current/assets/en/embedding-studio/menu.png differ diff --git a/i18n/es/docusaurus-plugin-content-docs/current/assets/en/embedding-studio/studio-interface.png b/i18n/es/docusaurus-plugin-content-docs/current/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/current/assets/en/embedding-studio/studio-interface.png differ diff --git a/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Definition.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Definition.md new file mode 100644 index 00000000000000..f0ba84a11ef136 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Definition.md @@ -0,0 +1,165 @@ +--- +id: definición +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/current/embedding-studio/Classes/Embedder.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Embedder.md new file mode 100644 index 00000000000000..211a2476dbd758 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/EmbedderResult.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/EmbedderResult.md new file mode 100644 index 00000000000000..b0da967bd3ba2f --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/Phrase.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Phrase.md new file mode 100644 index 00000000000000..43155973191b05 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/Process.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Process.md new file mode 100644 index 00000000000000..c35ad20417a1fd --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Process.md @@ -0,0 +1,188 @@ +--- +id: proceso +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/current/embedding-studio/Classes/ProcessError.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/ProcessError.md new file mode 100644 index 00000000000000..95a9debef40b85 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/ProcessErrorCode.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/ProcessErrorCode.md new file mode 100644 index 00000000000000..f5d1b0d6e065bb --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/ProcessResult.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/ProcessResult.md new file mode 100644 index 00000000000000..7263643f095e95 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/Scheduler.md b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Scheduler.md new file mode 100644 index 00000000000000..e2ba1bd8ee043e --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Scheduler.md @@ -0,0 +1,369 @@ +--- +id: backups periódicos +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/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/server/exit.md b/i18n/es/docusaurus-plugin-content-docs/current/server/exit.md index 7203df2d4d4348..8cf369d1645c45 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/server/exit.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/server/exit.md @@ -27,15 +27,15 @@ Aparecerá una ventana idéntica en cada máquina 4D remota. Esta ventana se rep - **Espere a que todos los clientes se desconecten.** -El servidor solo se cerrará una vez que todos los clientes, incluidos los que estén en modo de suspensión, se hayan desconectado. Esta opción podría ser inadecuada para operaciones de mantenimiento durante el almuerzo, por ejemplo, ya que es probable que haya clientes en [modo inactivo](../ServerWindow/users.md#managing-sleeping-users). +El servidor solo se cerrará una vez que todos los clientes, incluidos los que estén en modo de suspensión, se hayan desconectado. Esta opción podría ser inadecuada para operaciones de mantenimiento durante el almuerzo, por ejemplo, ya que es probable que haya clientes en [modo inactivo](../ServerWindow/sessions.md#management-of-sleeping-client-sessions). - **Espere a que los clientes activos se desconecten. (Ignorar a los clientes inactivos)** -El servidor solo se cerrará después de que todos los clientes activos se hayan desconectado (en otras palabras, todas las máquinas cliente que no están en [modo inactivo](../ServerWindow/users.md#managing-sleeping-users)). Con esta opción, los clientes que se encuentren en modo inactivo no se consideran conectados. Utilice esta opción si desea realizar operaciones de mantenimiento durante el almuerzo, por ejemplo. Cuando se utiliza esta opción, cualquier cliente que se encuentre en modo inactivo experimentará un error de conexión al reactivarse. +El servidor solo se cerrará después de que todos los clientes activos se hayan desconectado (en otras palabras, todas las máquinas cliente que no están en [modo inactivo](../ServerWindow/sessions.md#management-of-sleeping-client-sessions)). Con esta opción, los clientes que se encuentren en modo inactivo no se consideran conectados. Utilice esta opción si desea realizar operaciones de mantenimiento durante el almuerzo, por ejemplo. Cuando se utiliza esta opción, cualquier cliente que se encuentre en modo inactivo experimentará un error de conexión al reactivarse. :::note -Un *cliente inactivo* se refiere a una aplicación 4D remota en una máquina que ha pasado a [modo inactivo](../ServerWindow/users.md#managing-sleeping-users) mientras la conexión a la máquina servidor seguía activa. +Un *cliente inactivo* se refiere a una aplicación 4D remota en una máquina que ha pasado a [modo inactivo](../ServerWindow/sessions.md#management-of-sleeping-client-sessions) mientras la conexión a la máquina servidor seguía activa. ::: diff --git a/i18n/es/docusaurus-plugin-content-docs/version-20/Concepts/dt_number.md b/i18n/es/docusaurus-plugin-content-docs/version-20/Concepts/dt_number.md index 6769ae087795d5..f3e123979ce720 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-20/Concepts/dt_number.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-20/Concepts/dt_number.md @@ -69,7 +69,7 @@ El operador modulo % divide el primer número entre el segundo y devuelve un res :::warning -El operador modulo % devuelve valores significativos con números que están en el rango de los enteros largos (de –2^31 hasta 2^31 menos 1). To calculate the modulo with numbers outside of this range, use the [`Mod`(https://doc.4d.com/4dv20/help/command/en/page98.html)] command. +El operador modulo % devuelve valores significativos con números que están en el rango de los enteros largos (de –2^31 hasta 2^31 menos 1). Para calcular el módulo con números fuera de este rango, utilice el comando [`Mod`](https://doc.4d.com/4dv20/help/command/en/page98.html). ::: diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md index 3d68172398d401..6d49343ef332ff 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md @@ -41,7 +41,7 @@ Dado que un hilo se maneja de forma independiente a partir del método del proce La propiedad "seguridad de hilo" de cada elemento depende del elemento en sí: -- Comandos 4D: hilo seguro es una propiedad interna. En la documentación de 4D, los comandos hilo seguro se identifican con el icono ![](../assets/en/Develop/thread-safe.png). También puede utilizar el comando [`Nombre del comando`](../commands/command-name) para saber si un comando es hilo seguro. Gran parte de los comandos 4D pueden ejecutarse en modo apropiativo. +- Comandos 4D: hilo seguro es una propiedad interna. The 4D documentation indicates whether each command is thread-safe or not in the Properties section. También puede utilizar el comando [`Nombre del comando`](../commands/command-name) para saber si un comando es hilo seguro. Gran parte de los comandos 4D pueden ejecutarse en modo apropiativo. - Métodos de proyecto: las condiciones para seguridad de hilo se listan en [este párrafo](#writing-a-thread-safe-method). Básicamente, el código que se ejecuta en hilos apropiativos no puede llamar a las partes con las interacciones externas, tal como el código plug-in o las variables interproceso. Los accesos a los datos, sin embargo, son permitidos desde el servidor de datos 4D que soporta la ejecución apropiativa. diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/CollectionClass.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/CollectionClass.md index 6efed8c62af40d..6c8c482f75ecfd 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/CollectionClass.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/CollectionClass.md @@ -2207,7 +2207,7 @@ También puede pasar un parámetro de criterios para definir cómo deben ordenar Esta sintaxis sólo ordena los valores escalares de la colección (otros tipos de elementos, como objetos o colecciones, se devuelven desordenados). -Si la colección contiene elementos de diferentes [tipos](../Concepts/data-types.md), se ordenarán según los [principios de ordenación de 4D](../Concepts/ordering.md). +Si la colección contiene elementos de diferentes [tipos](../Concepts/data-types.md), se ordenarán según los [principios de ordenación 4D](../Concepts/ordering.md). #### Ejemplo 1 diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/CryptoKeyClass.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/CryptoKeyClass.md index b1ae8c232a244c..504b76a599bf12 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/CryptoKeyClass.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/CryptoKeyClass.md @@ -57,12 +57,12 @@ La función `4D.CryptoKey.new()` crea un #### *settings* -| Propiedad | Tipo | Descripción | -| --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [type](#type) | text | Define el tipo de clave a crear:
  • "RSA": genera un par de llaves RSA, utilizando [.size](#size) como tamaño.
  • "ECDSA": genera un par de llaves Elliptic Curve Digital Signature Algorithm, utilizando [.curve](#curve) como curva. Tenga en cuenta que las llaves ECDSA no pueden utilizarse para cifrar, sino sólo para firmar.
  • "PEM": carga una definición de par de llaves en formato PEM, utilizando [.pem](#pem).
    • | -| [curve](#curve) | text | Nombre de la curva ECDSA | -| [pem](#pem) | text | Definición PEM de una llave de cifrado a cargar | -| [size](#size) | integer | Tamaño de la llave RSA en bits | +| Propiedad | Tipo | Descripción | +| --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [type](#type) | text | Define el tipo de llave a crear:
  • "RSA": genera un par de llaves RSA, utilizando [.size](#size) como tamaño.
  • "ECDSA": genera un par de llaves Elliptic Curve Digital Signature Algorithm, utilizando [.curve](#curve) como curva. Tenga en cuenta que las llaves ECDSA no pueden utilizarse para el cifrado, sino solo para la firma.
  • "PEM": carga una definición de par de llaves en formato PEM, utilizando [.pem](#pem).
    • | +| [curve](#curve) | text | Nombre de la curva ECDSA | +| [pem](#pem) | text | Definición PEM de una llave de cifrado a cargar | +| [size](#size) | integer | Tamaño de la llave RSA en bits | #### *CryptoKey* diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/DataStoreClass.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/DataStoreClass.md index 5e26815a43b39b..58003eb5d415be 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/DataStoreClass.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/API/DataStoreClass.md @@ -457,7 +457,7 @@ La función `.getInfo()` devuelve | Propiedad | Tipo | Descripción | | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | string |
  • "4D": datastore principal, disponible a través de ds
  • "4D Server": datastore remoto, abrir con Open datastore
    • | -| networked | boolean |
  • True: el datastore se alcanza a través de una conexión de red.
  • False: el datastore no se alcanza a través de una conexión de red (base de datos local)
    • | +| networked | boolean |
  • True: el almacén de datos se alcanza a través de una conexión de red.
  • False: no se llega al almacén de datos a través de una conexión de red (base de datos local)
    • | | localID | text | ID del almacén de datos en la máquina. ID del almacén de datos en la máquina. Cadena vacía ("") para el almacén de datos principal. | | connection | object | Objeto que describe la conexión del almacén de datos remoto (no se devuelve para el almacén de datos principal). Propiedades disponibles:
    PropiedadTipoDescripción
    nombre de hosttextoDirección IP o nombre del datastore remoto + ":" + número de puerto
    tlsbooleanoTrue si se utiliza una conexión segura con el datastore remoto
    idleTimeoutnúmeroTiempo de inactividad de la sesión (en minutos)
    usuariotextoUsuario autenticado en el almacén de datos remoto
    | @@ -524,7 +524,7 @@ En un almacén de datos remoto: #### Descripción -La función `.getRemoteContextInfo()` devuelve un objeto que contiene información sobre el contexto de optimización *contextName* en el datastore. +La función `.getRemoteContextInfo()` devuelve un objeto que contiene información sobre el contexto de optimización *contextName* en el datastore.. Para obtener más información sobre cómo se pueden crear contextos de optimización, consulte [optimización cliente/servidor](../ORDA/client-server-optimization.md#optimization-context). @@ -1063,13 +1063,13 @@ Para una descripción del formato del registro de peticiones ORDA, por favor con Para crear un registro de peticiones ORDA del lado del cliente, llame a esta función en una máquina remota. El registro puede enviarse a un archivo o a la memoria, según el tipo de parámetro: -- Si se pasa un objeto *file* creado con el comando `File`, los datos de registro se escriben en este archivo como una colección de objetos (formato JSON). Cada objeto representa una petición.
    Si el archivo no existe ya, se crea. En caso contrario, si el archivo ya existe, los nuevos datos de registro se añaden a él. +- Si se pasa un objeto *file* creado con el comando `File`, los datos de registro se escriben en este archivo como una colección de objetos (formato JSON). Cada objeto representa una petición.
    Si el archivo no existe, se crea. En caso contrario, si el archivo ya existe, los nuevos datos de registro se añaden a él. En caso contrario, si el archivo ya existe, los nuevos datos de registro se añaden a él. Si se llama a `.startRequestLog()` con un archivo mientras se inició previamente un registro en memoria, el registro en memoria se detiene y se vacía. > Debe añadirse manualmente un carácter \N al final del archivo para realizar una validación JSON -- Si se pasa un entero *reqNum*, se vacía el registro en memoria (si lo hay) y se inicializa un nuevo registro. Mantendrá *reqNum* en memoria las peticiones hasta que se alcance el número, en cuyo caso se vacían las entradas más antiguas (pila FIFO).
    Si se llama a `.startRequestLog()` con un *reqNum* mientras se ha iniciado previamente un registro en un archivo, se detiene el registro en el archivo. +- Si se pasa un entero *reqNum*, se vacía el registro en memoria (si lo hay) y se inicializa un nuevo registro. Si se pasa un entero *reqNum*, se vacía el registro en memoria (si lo hay) y se inicializa un nuevo registro.Conserva las peticiones *reqNum* en memoria hasta que se alcance el número, en cuyo caso se vacían las entradas más antiguas (pila FIFO).
    - Si no ha pasado ningún parámetro, el registro se inicia en la memoria. Si `.startRequestLog()` fue llamado previamente con un *reqNum* (antes de una `.stopRequestLog()`), los datos del registro se apilan en memoria hasta la próxima vez que se vacíe el registro o se llame a `.stopRequestLog()`. diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md index 3d68172398d401..6d49343ef332ff 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md @@ -41,7 +41,7 @@ Dado que un hilo se maneja de forma independiente a partir del método del proce La propiedad "seguridad de hilo" de cada elemento depende del elemento en sí: -- Comandos 4D: hilo seguro es una propiedad interna. En la documentación de 4D, los comandos hilo seguro se identifican con el icono ![](../assets/en/Develop/thread-safe.png). También puede utilizar el comando [`Nombre del comando`](../commands/command-name) para saber si un comando es hilo seguro. Gran parte de los comandos 4D pueden ejecutarse en modo apropiativo. +- Comandos 4D: hilo seguro es una propiedad interna. The 4D documentation indicates whether each command is thread-safe or not in the Properties section. También puede utilizar el comando [`Nombre del comando`](../commands/command-name) para saber si un comando es hilo seguro. Gran parte de los comandos 4D pueden ejecutarse en modo apropiativo. - Métodos de proyecto: las condiciones para seguridad de hilo se listan en [este párrafo](#writing-a-thread-safe-method). Básicamente, el código que se ejecuta en hilos apropiativos no puede llamar a las partes con las interacciones externas, tal como el código plug-in o las variables interproceso. Los accesos a los datos, sin embargo, son permitidos desde el servidor de datos 4D que soporta la ejecución apropiativa. diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md index 0f30ac45b441df..2e75ed028fb22b 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md @@ -1,11 +1,11 @@ --- id: structure-indexes -title: Indexes +title: Índices --- -You can associate indexes with fields that you frequently use for searching and sorting. For example, you might index LastName, CompanyName, or ProductName if you plan to search or sort entities using these attributes. You also use this property for fields that establish relations between tables. +Puede asociar índices con campos que utiliza frecuentemente para buscar y ordenar. Por ejemplo, puede indexar LastName, CompanyName o ProductName si planea buscar o ordenar entidades usando estos atributos. También utiliza esta propiedad para campos que establecen relaciones entre las tablas. -When an index is associated with a field, 4D creates an internal index table for the field. This table allows 4D to perform rapid searches and sorts on the field. When searching or sorting on an unindexed field, 4D moves through data sequentially, examining each record in order. Indexing allows 4D to search and sort without going through every record. +Cuando un índice está asociado con un campo, 4D crea una tabla de índice interna para el campo. Esta tabla permite a 4D realizar búsquedas y ordenaciones rápidas en ese campo. Al buscar o ordenar en un campo indexado, 4D se mueve a través de datos secuencialmente, examinando cada registro en el orden. La indexación permite a 4D realizar búsquedas y ordenar los datos sin tener que revisar todos los registros. You can index fields of the Alpha, Text, Date, Time, Boolean, Integer, Long integer, Integer 64 bits, Real, Picture and Object type. As you add and delete records, 4D automatically updates its index table. If you create an index for a field that already exists, 4D automatically indexes the existing data. You can specify as many indexed fields as you want. Indexes are also rebuilt during specific operations such as conversion of earlier databases or [data compacting](../MSC/compact.md). @@ -105,7 +105,7 @@ The ![](../assets/en/Develop/index-list.png) button of the toolbar in the Struct The Index List can be used to view the main properties of the indexes: -- **Type:** Index type. Each type of index (B-tree, Cluster B-tree, Keyword, Euclidean, Cosine, Dot) is depicted with a different icon. +- **Tipo:** tipo de índice. Each type of index (B-tree, Cluster B-tree, Keyword, Euclidean, Cosine, Dot) is depicted with a different icon. - **Description:** Table and field(s) of index. For a composite index, this list contains all the fields of the index. - **Name:** Index name. This property is used in particular by the language commands. You can change or add an index name by double-clicking in this column. @@ -147,7 +147,7 @@ To add a field to the index, click on the **[+]** button. The list of fields of - If you want to create a composite index, add each field to be included in the index successively. Once the list is completed, you can reorder the fields using the arrow buttons or using drag and drop. - If you create a composite index based on primary key fields, make sure you put the fields in the same order in the primary key and in the index. -- If you have chosen the “Keyword Index” type, only Alpha or Text fields can be selected. Also in this case, you cannot include only one field in the index. +- If you have chosen the “Keyword Index” type, only Alpha, Text, or Picture fields can be selected. Also in this case, you can include only one field in the index. To delete a field from the index, select it in the list and click on the **[-]** button. diff --git a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md index bf0c7824300d03..8e41289bd5ba6c 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md @@ -67,6 +67,12 @@ Las acciones disponibles están relacionadas con el recurso de destino. Los parámetros de permisos requieren ser consistentes, en particular los permisos **update** y **drop** también necesitan el permiso **read** (pero **create** no lo necesita). +:::warning + +When a permission entry references an undeclared [privilege](#privileges-and-roles), 4D logs an error and ignores the entry. In this case, the permission is ignored. If the [restricted mode by default](#restriction-modes) is not enabled, the resource is accessible to `guest` sessions. + +::: + ### Permisos heredados Una acción de permiso definida en un nivel determinado se hereda por defecto en los niveles inferiores, pero se pueden establecer varios permisos: 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/code-editor/write-class-method.md b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/code-editor/write-class-method.md index 36f2eda5f138f0..374ebadde5ecbf 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21-R5/code-editor/write-class-method.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/code-editor/write-class-method.md @@ -25,16 +25,16 @@ Si está acostumbrado a codificar con **VS Code**, también puede utilizar este Cada ventana del Editor de Código tiene una barra de herramientas que ofrece acceso instantáneo a las funciones básicas relacionadas con la ejecución y edición de código. -| Elemento | Icono | Descripción | -| ------------------------------------ | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Ejecución del método** | ![execute-method](../assets/en/code-editor/execute-method.png) | Cuando se trabaja con métodos, cada ventana del Editor de Código tiene un botón que puede utilizarse para ejecutar el método actual. Utilizando el menú asociado a este botón, puede elegir el tipo de ejecución:
    • **Ejecutar nuevo proceso**: Crea un proceso y ejecuta el método en modo estándar en este proceso.
    • **Ejecutar y depurar nuevo proceso**: Crea un nuevo proceso y muestra el método en la ventana Depurador para su ejecución paso a paso en este proceso.
    • **Ejecutar en proceso Aplicación**: Ejecuta el método en modo estándar en el contexto del proceso Aplicación (es decir, en la ventana de visualización del registro).
    • **Ejecutar y depurar en el proceso Aplicación**: Muestra el método en la ventana del Depurador para su ejecución paso a paso en el contexto del proceso Aplicación (en otras palabras, la ventana de visualización de registros).
    Para más información sobre la ejecución de métodos, ver [Métodos proyecto](../Project/project-method-properties.md). | -| **Buscar en el método** | ![search-icon](../assets/en/code-editor/search.png) | Muestra el [*Área de búsqueda*](#find-and-replace). | -| **Macros** | ![macros-button](../assets/en/code-editor/macros.png) | Inserta una macro en la selección. Haga clic en la flecha desplegable para mostrar una lista de macros disponibles. Para obtener más información sobre como crear e instanciar macros, consulte [Macros](#macros). | -| **Expandir todo/Contraer todo** | ![expand-collapse-button](../assets/en/code-editor/expand-collapse-all.png) | Estos botones permiten expandir o contraer todas las estructuras de flujo de control del código. | -| **Información del método** | ![method-information-icon](../assets/en/code-editor/method-information.png) | Muestra el diálogo [Propiedades del método](../Project/project-method-properties.md) (sólo métodos proyecto). | -| **Últimos valores del portapapeles** | ![last-clipboard-values-icon](../assets/en/code-editor/last-clipboard-values.png) | Muestra los últimos valores almacenados en el portapapeles. | -| **Portapapeles** | ![clipboard icons](../assets/en/code-editor/clipboards.png) | Nueve portapapeles disponibles en el editor de código. Puede [utilizar estos portapapeles](#clipboards) haciendo clic directamente en ellos o utilizando los atajos de teclado. Puede utilizar la opción [Preferencias](Preferences/methods.md#options-1) para ocultarlas. | -| **Menú desplegable de navegación** | ![code-navigation-icons](../assets/en/code-editor/tags.png) | Le permite navegar dentro de métodos y clases con contenido etiquetado automáticamente o marcadores declarados manualmente. Ver abajo | +| Elemento | Icono | Descripción | +| ------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Ejecución del método** | ![execute-method](../assets/en/code-editor/execute-method.png) | Cuando se trabaja con métodos, cada ventana del Editor de Código tiene un botón que puede utilizarse para ejecutar el método actual. Utilizando el menú asociado a este botón, puede elegir el tipo de ejecución:
    • **Ejecutar nuevo proceso**: Crea un proceso y ejecuta el método en modo estándar en este proceso.
    • **Ejecutar y depurar nuevo proceso**: crea un nuevo proceso y muestra el método en la ventana del depurador para la ejecución paso a paso en este proceso.
    • **Ejecutar en el proceso de la aplicación**: ejecuta el método en modo estándar en el contexto del proceso de la aplicación (es decir, la ventana de visualización de los registros).
    • **Ejecutar y depurar en el proceso Aplicación**: muestra el método en la ventana Depurador para su ejecución paso a paso en el contexto del proceso Aplicación (es decir, en la ventana de visualización de registros).
    Para más información sobre la ejecución de métodos, ver [Métodos proyecto](../Project/project-method-properties.md). | +| **Buscar en el método** | ![search-icon](../assets/en/code-editor/search.png) | Muestra el [*Área de búsqueda*](#find-and-replace). | +| **Macros** | ![macros-button](../assets/en/code-editor/macros.png) | Inserta una macro en la selección. Haga clic en la flecha desplegable para mostrar una lista de macros disponibles. Para obtener más información sobre como crear e instanciar macros, consulte [Macros](#macros). | +| **Expandir todo/Contraer todo** | ![expand-collapse-button](../assets/en/code-editor/expand-collapse-all.png) | Estos botones permiten expandir o contraer todas las estructuras de flujo de control del código. | +| **Información del método** | ![method-information-icon](../assets/en/code-editor/method-information.png) | Muestra el diálogo [Propiedades del método](../Project/project-method-properties.md) (sólo métodos proyecto). | +| **Últimos valores del portapapeles** | ![last-clipboard-values-icon](../assets/en/code-editor/last-clipboard-values.png) | Muestra los últimos valores almacenados en el portapapeles. | +| **Portapapeles** | ![clipboard icons](../assets/en/code-editor/clipboards.png) | Nueve portapapeles disponibles en el editor de código. Puede [utilizar estos portapapeles](#clipboards) haciendo clic directamente en ellos o utilizando los atajos de teclado. Puede utilizar la opción [Preferencias](Preferences/methods.md#options-1) para ocultarlas. | +| **Menú desplegable de navegación** | ![code-navigation-icons](../assets/en/code-editor/tags.png) | Le permite navegar dentro de métodos y clases con contenido etiquetado automáticamente o marcadores declarados manualmente. Ver abajo | ### Área de edición 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..c35ad20417a1fd --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Process.md @@ -0,0 +1,188 @@ +--- +id: proceso +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/Develop/preemptive.md b/i18n/es/docusaurus-plugin-content-docs/version-21/Develop/preemptive.md index bed4c92fde62d2..9fb4b00c7f07b1 100644 --- a/i18n/es/docusaurus-plugin-content-docs/version-21/Develop/preemptive.md +++ b/i18n/es/docusaurus-plugin-content-docs/version-21/Develop/preemptive.md @@ -41,7 +41,7 @@ Dado que un hilo se maneja de forma independiente a partir del método del proce La propiedad "seguridad de hilo" de cada elemento depende del elemento en sí: -- Comandos 4D: hilo seguro es una propiedad interna. En la documentación de 4D, los comandos hilo seguro se identifican con el icono ![](../assets/en/Develop/thread-safe.png). También puede utilizar el comando [`Nombre del comando`](../commands/command-name.md) para saber si un comando es hilo seguro. Gran parte de los comandos 4D pueden ejecutarse en modo apropiativo. +- Comandos 4D: hilo seguro es una propiedad interna. The 4D documentation indicates whether each command is thread-safe or not in the Properties section. También puede utilizar el comando [`Nombre del comando`](../commands/command-name.md) para saber si un comando es hilo seguro. Gran parte de los comandos 4D pueden ejecutarse en modo apropiativo. - Métodos de proyecto: las condiciones para seguridad de hilo se listan en [este párrafo](#writing-a-thread-safe-method). Básicamente, el código que se ejecuta en hilos apropiativos no puede llamar a las partes con las interacciones externas, tal como el código plug-in o las variables interproceso. Los accesos a los datos, sin embargo, son permitidos desde el servidor de datos 4D que soporta la ejecución apropiativa. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/API/DataClassClass.md b/i18n/fr/docusaurus-plugin-content-docs/current/API/DataClassClass.md index d7a157d1e8e383..46c030662a1a6d 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/API/DataClassClass.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/API/DataClassClass.md @@ -636,42 +636,42 @@ La méthode projet ***SearchDuplicate*** recherche des valeurs dupliquées dans
    -| Paramètres | Type | | Description | -| ---------- | ---------- | --------------------------- | --------------------------- | -| Résultat | Collection | <- | Collection of index objects | +| Paramètres | Type | | Description | +| ---------- | ---------- | --------------------------- | ------------------------- | +| Résultat | Collection | <- | Collection d'objets index |
    #### Description -The `.getIndexes()` function returns a collection of all indexes related to the dataclass. +La fonction `.getIndexes()` retourne une collection de tous les index liés à la dataclass. -Each index is an object of the collection. Indexes are returned in the creation/modification order. An empty collection is returned if there is no index in the dataclass. +Chaque index est un objet de la collection. Les index sont retournés dans l'ordre de création/modification. Une collection vide est retournée s'il n'y a pas d'index dans la dataclass. **Collection retournée** -Each object of the returned collection has the following properties: +Chaque objet de la collection retournée contient les propriétés suivantes : -| Propriété | Type | Description | -| ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| type | Integer | Index type: -1 = Keywords, 0 = default, 1 = Standard B-Tree, 3 = Cluster B-Tree, 4 = Cosine, 5 = Dot, 6 = Euclidean. If the index is set to Automatic, the type property represents the type of the indexing algorithm used | -| automatic | Boolean | True if "automatic" index is selected | -| name | Text | Index name if defined | -| kind | Text | "keywords" if *keyword index* checked, otherwise "regular" | -| attributes | Collection | Index attribute or list of attributes (for composite index) | -| UUID | Text | Index UUID | -| uniqueKey | Boolean | True if index has the Unique key property | +| Propriété | Type | Description | +| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| type | Integer | Type d'index : -1 = Mots-clés, 0 = Par défaut, 1 = B-Tree standard, 3 = B-Tree cluster, 4 = Cosinus, 5 = Produit scalaire, 6 = Euclidien. Si l'index est défini sur Automatique, la propriété type représente le type de l'algorithme d'indexation utilisé | +| automatic | Boolean | True si l'index "automatique" est sélectionné | +| name | Text | Nom de l'index si défini | +| kind | Text | "keywords" si *Index mots-clés* est coché, sinon "regular" | +| attributes | Collection | Attribut de l'index ou liste d'attributs (pour les index composites) | +| UUID | Text | UUID de l'index | +| uniqueKey | Boolean | True si l'index a la propriété Unique | :::tip Article(s) de blog sur le sujet -[Managing 4D Indexes Programmatically with getIndexes()](https://blog.4d.com/managing-4d-indexes-programmatically-with-getindexes) +[Gestion des index 4D par programmation à l’aide de la fonction getIndexes()](https://blog.4d.com/managing-4d-indexes-programmatically-with-getindexes) ::: #### Exemple -Considering the following table: +Considérant la table suivante : ![table-indexes](../assets/en/API/table-index.png) @@ -1342,7 +1342,7 @@ Voir [plus d'exemples ci-dessous](#example-4-2) (exemples 4 et 5). - [4D AI : Recherche d'entités par similarité vectorielle en 4D](https://blog.4d.com/4d-ai-searching-entities-by-vector-similarity-in-4d) - [4D AI : Tri des résultats d'une requête en fonction de la similarité vectorielle](https://blog.4d.com/4d-ai-sorting-query-results-by-vector-similarity/) -- [Why Your Search Stack Feels Broken — and How Vector Search Fixes It](https://blog.4d.com/why-your-search-stack-feels-broken-and-how-vector-search-fixes-it) +- [Pourquoi votre pile de recherche semble brisée – et comment Vector Search y remédie](https://blog.4d.com/why-your-search-stack-feels-broken-and-how-vector-search-fixes-it) ::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/API/QuotaManagerClass.md b/i18n/fr/docusaurus-plugin-content-docs/current/API/QuotaManagerClass.md index 08c5d2b928ec6c..63398ec7faf8ec 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/API/QuotaManagerClass.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/API/QuotaManagerClass.md @@ -11,12 +11,6 @@ La classe `4D.QuotaManager` vous offre une interface permettant de configurer et ::: -:::tip Article de blog lié - -[Un serveur web 4D qui sait quand dire « non »](https://blog.4d.com/a-4d-web-server-that-knows-when-to-say-no/) - -::: - Les objets `4D.QuotaManager` peuvent être instanciés par: - la [propriété `quotas` d'un objet Session](./SessionClass.md#quotas) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/Develop/preemptive.md b/i18n/fr/docusaurus-plugin-content-docs/current/Develop/preemptive.md index 548b17b1d76767..f910900c7a523f 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/Develop/preemptive.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/Develop/preemptive.md @@ -41,7 +41,7 @@ Le code 4D ne peut être exécuté dans un process préemptif que lorsque certai La propriété "thread safety" de chaque élément dépend de l'élément lui-même : -- Commandes 4D : la propriété thread-safe est une propriété interne. Dans la documentation 4D, les commandes thread-safe sont identifiées par l'icône ![](../assets/en/Develop/thread-safe.png). Vous pouvez également utiliser la commande [`Command name`](../commands/command-name) pour savoir si une commande est thread-safe. Une grande partie des commandes 4D peut s'exécuter en mode préemptif. +- Commandes 4D : la propriété thread-safe est une propriété interne. The 4D documentation indicates whether each command is thread-safe or not in the Properties section. Vous pouvez également utiliser la commande [`Command name`](../commands/command-name) pour savoir si une commande est thread-safe. Une grande partie des commandes 4D peut s'exécuter en mode préemptif. - Méthodes projet : les conditions pour être thread-safe sont répertoriées dans [ce paragraphe](#writing-a-thread-safe-method). Fondamentalement, le code à exécuter dans des threads préemptifs ne peut pas appeler des parties avec des interactions externes, telles que du code de plug-in ou des variables interprocess. Cependant, l'accès aux données est autorisé car le serveur de données 4D et ORDA prennent en charge l'exécution préemptive. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/ORDA/privileges.md b/i18n/fr/docusaurus-plugin-content-docs/current/ORDA/privileges.md index a23ede3289c37b..f5c2fc4526cfb2 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/ORDA/privileges.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/ORDA/privileges.md @@ -294,6 +294,12 @@ The project's web security settings are defined in `roles.json`: ::: +:::warning + +When a permission entry references an undeclared [privilege](#privileges-and-roles), 4D logs an error and ignores the entry. In this case, the permission is ignored. If the [restricted mode by default](#restriction-modes) is not enabled, the resource is accessible to `guest` sessions. + +::: + ### Default location and content New projects generate `roles.json` at: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/WebServer/quotas.md b/i18n/fr/docusaurus-plugin-content-docs/current/WebServer/quotas.md index 8ad057192055f0..5152c83e3ef3e1 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/WebServer/quotas.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/WebServer/quotas.md @@ -12,12 +12,6 @@ Les quotas du serveur Web vous permettent de contrôler l'utilisation des ressou ::: -:::tip Article de blog lié - -[Un serveur web 4D qui sait quand dire « non »](https://blog.4d.com/a-4d-web-server-that-knows-when-to-say-no/) - -::: - ## Conditions requises La configuration des quotas nécessite l'activation des [sessions évolutives](./sessions.md#enabling-web-sessions). 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/assets/en/embedding-studio/menu.png b/i18n/fr/docusaurus-plugin-content-docs/current/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/current/assets/en/embedding-studio/menu.png differ diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/assets/en/embedding-studio/studio-interface.png b/i18n/fr/docusaurus-plugin-content-docs/current/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/current/assets/en/embedding-studio/studio-interface.png differ diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Definition.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Definition.md new file mode 100644 index 00000000000000..fd8c5c92276afd --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Definition.md @@ -0,0 +1,165 @@ +--- +id: définition +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/current/embedding-studio/Classes/Embedder.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Embedder.md new file mode 100644 index 00000000000000..2d8e5d846103ad --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/EmbedderResult.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/EmbedderResult.md new file mode 100644 index 00000000000000..853bd158d5fd4d --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/Phrase.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Phrase.md new file mode 100644 index 00000000000000..7f8a82daec5ef0 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/Process.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Process.md new file mode 100644 index 00000000000000..e15505f9d524e5 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/ProcessError.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/ProcessError.md new file mode 100644 index 00000000000000..3dfb9471b01545 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/ProcessErrorCode.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/ProcessErrorCode.md new file mode 100644 index 00000000000000..44567dbacab051 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/ProcessResult.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/ProcessResult.md new file mode 100644 index 00000000000000..855a11dff50861 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/Scheduler.md b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Scheduler.md new file mode 100644 index 00000000000000..67c5622ffdd04a --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Scheduler.md @@ -0,0 +1,369 @@ +--- +id: périodicité +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/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/settings/client-server.md b/i18n/fr/docusaurus-plugin-content-docs/current/settings/client-server.md index 28de1150c14efa..7b182cb2eb6684 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/settings/client-server.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/settings/client-server.md @@ -135,7 +135,7 @@ Ce paramètre permet de définir globalement le mode de mise à jour de l'instan - **Jamais** : Le dossier **Resources** local n'est pas mis à jour pendant la session. La notification envoyée par le serveur est ignorée. Le dossier **Resources** local peut être mis à jour manuellement à l'aide de la commande **Update Local Resources** du menu d'action (voir [Utilisation de l'explorateur de ressources](https://doc.4d.com/4Dv20/4D/20.2/Using-the-Resources-explorer.300-6750254.en.html)). - **Toujours** : La synchronisation du dossier local **Resources** est automatiquement effectuée pendant la session chaque fois qu'une notification est envoyée par le serveur. - **Demander** : Lorsque la notification est envoyée par le serveur, une boîte de dialogue est affichée sur les postes clients, indiquant la modification. L'utilisateur peut ensuite accepter ou refuser la synchronisation du dossier **Resources** local.\ - Le dossier **Resources** centralise les fichiers personnalisés nécessaires à l'interface de la base de données (fichiers de traduction, images, etc.). Des mécanismes automatiques ou manuels permettent de notifier chaque client lorsque le contenu de ce dossier a été modifié. Pour plus d'informations, veuillez consulter la section [Gestion du dossier Resources](../Desktop/clientServer.md#managing-the-resources-folder). + Le dossier **Resources** centralise les fichiers personnalisés nécessaires à l'interface de la base de données (fichiers de traduction, images, etc.). Des mécanismes automatiques ou manuels permettent de notifier chaque client lorsque le contenu de ce dossier a été modifié. For more information, please refer to the [Resources folder](../Desktop/clientServer.md#resources-folder) section. ## Page Configuration IP diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-20/API/CollectionClass.md b/i18n/fr/docusaurus-plugin-content-docs/version-20/API/CollectionClass.md index eb76591dd1c51a..39a475e8259846 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-20/API/CollectionClass.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-20/API/CollectionClass.md @@ -81,27 +81,27 @@ Une collection est initialisée avec : | Paramètres | Type | | Description | | ---------- | ----------------------------------------------------------------------- | :-------------------------: | ------------------------------------------ | | value | Number, Text, Date, Time, Boolean, Object, Collection, Picture, Pointer | -> | Valeur(s) de collection | -| Résultat | Collection | <- | nombres | +| Résultat | Collection | <- | La nouvelle collection | #### Description -Recherche avec des dates : +La commande `New collection` crée une nouvelle collection vide ou préremplie et retourne sa référence. -Prise en charge des formules +Si vous ne passez aucun paramètre, `New collection` crée une collection vide et retourne sa référence. Vous devez affecter la référence retournée à une variable 4D de type Collection. -> Utilisation de parenthèses +> N'oubliez pas que les instructions `var : Collection` ou `C_COLLECTION` déclarent une variable du type `Collection` mais ne créent pas de collection. -Condition Not appliquée à une assertion +Optionnellement, vous pouvez préremplir la nouvelle collection en passant une ou plusieurs *value*(s) comme paramètre(s). Sinon, vous pouvez ajouter ou modifier des éléments ultérieurement par affectation. Par exemple : ```4d -Vous pouvez fournir des paramètres supplémentaires à la callback si nécessaire. + myCol[10]:="Mon nouvel élément" ``` Si l'indice du nouvel élément est au-delà du dernier élément existant de la collection, la collection est automatiquement redimensionnée et tous les nouveaux éléments intermédiaires reçoivent la valeur **null**. @@ -110,7 +110,7 @@ Vous pouvez passer n'importe quel nombre de valeurs de n'importe quel type pris Vous devez prêter attention aux problèmes de conversion suivants : -- La nouvelle collection partagée +- Si vous passez un pointeur, il est conservé "tel quel" ; il est évalué à l'aide de la commande `JSON Stringify` - Les dates sont stockées sous la forme de date « aaaa-mm-jj » ou des chaînes au format « AAAA-MM-JJTHH: ss.SSSZ: mm » , selon la configuration actuelle « dates à l'intérieur des objets » de la base de données. Lors de la conversion de dates 4D en texte avant de les stocker dans la collection, par défaut le programme prend en compte le fuseau horaire local. Indice de fin (non inclus) - Si vous passez une heure, elle est stockée sous la forme d'un nombre de millisecondes (Réel). @@ -175,11 +175,11 @@ Vous souhaitez créer une nouvelle collection puis ajouter un élément : La commande `New shared collection` crée une nouvelle collection partagée vide ou préremplie et retourne sa référence. -Par exemple : Par exemple : La lecture d'un élément sans structure *Use...End use* est cependant possible. +L'ajout d'un élément à cette collection à l'aide de l'opérateur d'assignation doit être entouré de la structure [`Use...End use`](Concepts/shared.md#useend-use), sinon une erreur est générée (cela n'est pas nécessaire lors de l'ajout d'éléments à l'aide de fonctions telles que [`push()`](#push) ou [`map()`](#map) car elles utilisent automatiquement une structure interne *Use...End use*). La lecture d'un élément sans structure *Use...End use* est cependant possible. :::info -Les symboles suivants sont pris en charge : +Pour plus d'informations sur les collections partagées, veuillez vous référer à la page [Objets et collections partagés](Concepts/shared.md). ::: @@ -187,7 +187,7 @@ Si vous ne passez aucun paramètre, `New shared collection` crée une collection Vous devez affecter la référence retournée à une variable 4D de type Collection. -> Utilisation de parenthèses +> N'oubliez pas que les instructions `var : Collection` ou `C_COLLECTION` déclarent une variable du type `Collection` mais ne créent pas de collection. Optionnellement, vous pouvez préremplir la nouvelle collection partagée en passant une ou plusieurs *value*(s) comme paramètre(s). Sinon, vous pouvez ajouter ou modifier des éléments ultérieurement via l'assignation en notation objet (cf. exemple). @@ -201,8 +201,8 @@ Vous pouvez passer tout nombre de valeurs de n'importe quel type pris en charge - date - heure (stockée en nombre de milliseconds - réel) - Null -- Si vous souhaitez que l'évaluation soit sensible à la casse ou pour différencier des caractères accentués, passez la constante `ck diacritical` dans le paramètre option. -- Sommaire +- objet partagé +- collection partagée :::note @@ -1224,7 +1224,7 @@ Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les - *formula* (syntaxe recommandée), un [objet Formula](FunctionClass.md) qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet; - soit *methodName*, le nom d'une méthode projet (texte). -La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). La callback peut effectuer n'importe quel test, avec ou sans le(s) paramètre(s) et doit retourner **true** pour chaque élément remplissant le test. Elle reçoit un `Objet` en premier paramètre ($1). +La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). Elle reçoit un `Objet` en premier paramètre ($1). La callback reçoit les paramètres suivants : @@ -1315,7 +1315,7 @@ Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les - *formula* (syntaxe recommandée), un [objet Formula](FunctionClass.md) qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet; - *methodName*, le nom d'une méthode projet (texte). -La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). La callback peut effectuer n'importe quel test, avec ou sans le(s) paramètre(s) et doit retourner **true** pour chaque élément remplissant le test. Elle reçoit un `Objet` en premier paramètre ($1). +La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). Elle reçoit un `Objet` en premier paramètre ($1). La callback reçoit les paramètres suivants : @@ -1499,7 +1499,7 @@ Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les - *formula* (syntaxe recommandée), un [objet Formula](FunctionClass.md) qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet; - soit *methodName*, le nom d'une méthode projet (texte). -La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). Elle reçoit un `Objet` en premier paramètre ($1). +La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). La callback est appelée avec le(s) paramètre(s) passés dans param (facultatif). Elle reçoit un `Objet` en premier paramètre ($1). La callback reçoit les paramètres suivants : @@ -1597,7 +1597,7 @@ Dans *toSearch*, passez l'expression à trouver dans la collection. Vous pouvez Optionnellement, vous pouvez passer l'indice de la collection à partir duquel démarrer la recherche dans *startFrom*. - Si *startFrom* >= la longueur de la collection, False est retourné, ce qui signifie que la recherche n'est pas effectuée. -- Si *startFrom* < 0, la fin de la collection est considérée comme point de départ du calcul de la position (*startFrom:=startFrom+length*). **Note**: Même si *startFrom* est négatif, la collection est toujours recherchée de gauche à droite. +- Si *startFrom* < 0, la fin de la collection est considérée comme point de départ du calcul de la position (*startFrom:=startFrom+length*). **Attention** : N'oubliez pas que la numérotation des éléments de collection débute à 0. - Si *startFrom* = 0, l'ensemble de la collection est évalué (défaut). #### Exemple @@ -2023,7 +2023,7 @@ Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les - *formula* (syntaxe recommandée), un [objet Formula](FunctionClass.md) qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet; - soit *methodName*, le nom d'une méthode projet (texte). -La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). Elle reçoit un `Objet` en premier paramètre ($1). +La callback est appelée avec le(s) paramètre(s) passé(s) dans *param* (facultatif). La callback est appelée avec le(s) paramètre(s) passés dans param (facultatif). Elle reçoit un `Objet` en premier paramètre ($1). La callback reçoit les paramètres suivants : @@ -2543,9 +2543,9 @@ Le paramètre *queryString* doit respecter la syntaxe suivante : propertyPath comparator value {logicalOperator propertyPath comparator value} ``` -For detailed information on how to build a query using *queryString*, *value* and *querySettings* parameters, please refer to the [`dataClass.query()`](DataClassClass.md#query) function description. +Pour plus d'informations sur la génération d'une requête à l'aide des paramètres *queryString*, *value* et *querySettings*, reportez-vous à la description de la fonction de DataClass [`query()`](DataClassClass.md#query). -> Formulas are not supported by the `collection.query()` function, neither in the *queryString* parameter nor as *formula* object parameter. +> Les formules ne sont pas prises en charge par la fonction `collection.query()`, ni dans le paramètre *queryString*, ni en tant que paramètre objet *formula*. #### Exemple 1 @@ -2758,8 +2758,7 @@ Elle peut définir le(s) paramètre(s) suivant(s) : ```4d var $c : Collection $c:=New collection(5;3;5;1;3;4;4;6;2;2) -$r:=$c.reduceRight(Formula($1.accumulator=$1.value); 1) //returns 86400 - +$r:=$c.reduceRight(Formula($1.accumulator=$1.value); 1) //86400 ``` @@ -3195,7 +3194,7 @@ La callback reçoit les paramètres suivants : Si vous avez utilisé une méthode, vous devez définir le paramètre suivant : -- *$1.result* (boolean): **True** if *$1.value < $1.value2*, **False** otherwise. +- *$1.result* (booléen) : **true** si *$1.value < $1.value2*, **false** sinon. #### Exemple 1 diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-20/Concepts/dt_number.md b/i18n/fr/docusaurus-plugin-content-docs/version-20/Concepts/dt_number.md index 0b254e27ab9be2..663e68937a5e73 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-20/Concepts/dt_number.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-20/Concepts/dt_number.md @@ -69,7 +69,7 @@ L'opérateur modulo % divise le premier nombre par le second et retourne le rest :::warning -L'opérateur modulo % retourne des valeurs significatives avec des nombres appartenant à la catégorie des entiers longs (de –2^31 à +2^31 moins 1). Pour calculer le modulo avec des nombres en dehors de cet intervalle, utilisez la commande [Mod](https://doc.4d.com/4dv20/help/command/en/page98.html). +L'opérateur modulo % retourne des valeurs significatives avec des nombres appartenant à la catégorie des entiers longs (de –2^31 à +2^31 moins 1). Pour calculer le modulo avec des nombres en dehors de cette plage, utilisez la commande [`Mod`](https://doc.4d.com/4dv20/help/command/en/page98.html). ::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/API/DataClassClass.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/API/DataClassClass.md index dedc785f9e8ae4..46e33024705b1b 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/API/DataClassClass.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/API/DataClassClass.md @@ -1270,7 +1270,7 @@ Voir [plus d'exemples ci-dessous](#example-4-2) (exemples 4 et 5). - [4D AI : Recherche d'entités par similarité vectorielle en 4D](https://blog.4d.com/4d-ai-searching-entities-by-vector-similarity-in-4d) - [4D AI : Tri des résultats d'une requête en fonction de la similarité vectorielle](https://blog.4d.com/4d-ai-sorting-query-results-by-vector-similarity/) -- [Why Your Search Stack Feels Broken — and How Vector Search Fixes It](https://blog.4d.com/why-your-search-stack-feels-broken-and-how-vector-search-fixes-it) +- [Pourquoi votre pile de recherche semble brisée – et comment Vector Search y remédie](https://blog.4d.com/why-your-search-stack-feels-broken-and-how-vector-search-fixes-it) ::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md index 548b17b1d76767..f910900c7a523f 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md @@ -41,7 +41,7 @@ Le code 4D ne peut être exécuté dans un process préemptif que lorsque certai La propriété "thread safety" de chaque élément dépend de l'élément lui-même : -- Commandes 4D : la propriété thread-safe est une propriété interne. Dans la documentation 4D, les commandes thread-safe sont identifiées par l'icône ![](../assets/en/Develop/thread-safe.png). Vous pouvez également utiliser la commande [`Command name`](../commands/command-name) pour savoir si une commande est thread-safe. Une grande partie des commandes 4D peut s'exécuter en mode préemptif. +- Commandes 4D : la propriété thread-safe est une propriété interne. The 4D documentation indicates whether each command is thread-safe or not in the Properties section. Vous pouvez également utiliser la commande [`Command name`](../commands/command-name) pour savoir si une commande est thread-safe. Une grande partie des commandes 4D peut s'exécuter en mode préemptif. - Méthodes projet : les conditions pour être thread-safe sont répertoriées dans [ce paragraphe](#writing-a-thread-safe-method). Fondamentalement, le code à exécuter dans des threads préemptifs ne peut pas appeler des parties avec des interactions externes, telles que du code de plug-in ou des variables interprocess. Cependant, l'accès aux données est autorisé car le serveur de données 4D et ORDA prennent en charge l'exécution préemptive. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/CryptoKeyClass.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/CryptoKeyClass.md index f9e55bee5c5ab0..5747ef65cf51c0 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/CryptoKeyClass.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/CryptoKeyClass.md @@ -57,12 +57,12 @@ La fonction `4D.CryptoKey.new()` crée u #### *settings* -| Propriété | Type | Description | -| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [type](#type) | text | Définit le type de clé à créer : "
  • RSA" : génère une paire de clés RSA, en utilisant [.size](#size) comme taille.
  • "ECDSA" : génère une paire de clés Elliptic Curve Digital Signature Algorithm, en utilisant [.curve](#curve) comme courbe. Notez que les clés ECDSA ne peuvent pas être utilisées pour le chiffrement, mais uniquement pour la signature.
  • "PEM" : charge une définition de paire de clés au format PEM, en utilisant [.pem](#pem)
    • . | -| [curve](#curve) | text | Nom de la courbe ECDSA | -| [pem](#pem) | text | Définition PEM d'une clé de chiffrement à charger | -| [size](#size) | integer | Taille de la clé RSA en octets | +| Propriété | Type | Description | +| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [type](#type) | text | Définit le type de clé à créer :
  • "RSA" : génère une paire de clés RSA, en utilisant [.size](#size) comme taille.
  • "ECDSA" : génère une paire de clés Elliptic Curve Digital Signature Algorithm, en utilisant [.curve](#curve) comme courbe. A noter que les clés ECDSA ne peuvent pas être utilisées pour le chiffrement, mais uniquement pour la signature.
  • "PEM" : charge une définition de paire de clés au format PEM, en utilisant [.pem](#pem).
    • | +| [curve](#curve) | text | Nom de la courbe ECDSA | +| [pem](#pem) | text | Définition PEM d'une clé de chiffrement à charger | +| [size](#size) | integer | Taille de la clé RSA en octets | #### *CryptoKey* diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/DataClassClass.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/DataClassClass.md index 61b725e12317b6..46c030662a1a6d 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/DataClassClass.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/DataClassClass.md @@ -51,24 +51,24 @@ Les objets renvoyés ont des propriétés que vous pouvez lire pour obtenir des Les objets attributs retournés contiennent les propriétés suivantes : -| Propriété | Type | Description | -| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| autoFilled | Boolean | Vrai si la valeur de l'attribut est automatiquement remplie par 4D. Correspond aux propriétés de champs 4D suivantes : "Autoincrement" pour les champs de type numérique et "UUID Auto" pour les champs UUID (alpha). Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". | -| exposed | Boolean | Vrai si l'attribut est exposé en REST | -| fieldNumber | integer | Numéro interne du champ 4D correspondant à l'attribut. Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". | -| fieldType | Integer | Type de champ de la base de données 4D de l'attribut. Dépend de l'attribut `kind`. Valeurs possibles :
  • si `.kind` = "storage" : type de champ 4D correspondant, voir [`Value type`](../commands/value-type)
  • si `.kind` = "relatedEntity" : 38 (`is object`)
  • si `.kind` = "relatedEntities" : 42 (`is collection`)
  • si `.kind` = "calculated" ou "alias" = même chose que ci-dessus, en fonction de la valeur résultante (type de champ, relatedEntity ou relatedEntities)
    • | -| indexed | Boolean | Vrai s'il existe un index B-tree ou Cluster B-tree sur l'attribut. Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". | -| inverseName | Text | Nom de l'attribut qui se trouve à l'autre côté de la relation. Renvoyé uniquement lorsque `.kind` = "relatedEntity" ou "relatedEntities". | -| keywordIndexed | Boolean | Vrai s'il existe un index de mots-clés sur l'attribut. Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". | -| kind | Text | Catégorie de l'attribut. Valeurs possibles :
  • "storage" : attribut de stockage (ou scalaire), c'est-à-dire attribut stockant une valeur et non une référence à un autre attribut
  • "calculated" : attribut calculé, c'est-à-dire défini par une [fonction `get`](../ORDA/ordaClasses.md#function-get-attributename)
  • "alias" : attribut construit sur [un autre attribut](../ORDA/ordaClasses.md#alias-attributes-1)
  • "relatedEntity" : attribut de relation N -> 1 (référence à une entité)
  • "relatedEntities" : attribut de relation 1->N (référence à une entity selection)
    • | -| obligatoire | Boolean | Vrai si la saisie d'une valeur null est rejetée pour l'attribut. Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". Attention : Cette propriété correspond à la propriété du champ "Reject NULL value input" au niveau de la base de données 4D. Elle n'est pas liée à la propriété "Mandatory" existante qui est une option de contrôle de la saisie de données pour une table. | -| name | Text | Nom de l'attribut sous forme de chaîne | -| path | Text | Chemin d'un [attribut alias](../ORDA/ordaClasses.md#alias-attributes-1) basé sur une relation | -| readOnly | Boolean | Vrai si l'attribut est en lecture seule. Par exemple, les attributs calculés sans la fonction [`set`](../ORDA/ordaClasses.md#function-set-attributename) sont en lecture seule. | -| relatedDataClass | Text | Nom de la dataclass liée à l'attribut. Renvoyé uniquement lorsque `.kind` = "relatedEntity" ou "relatedEntities". | -| type | Text | Type conceptuel de la valeur de l'attribut, utile pour la programmation générique. Dépend de l'attribut `kind`. Valeurs possibles :
  • si `.kind` = "storage" : "blob", "bool", "date", "image", "number", "object", ou "string". "number" est renvoyé pour tous les types numériques, y compris la durée ; "string" est renvoyé pour les types d'attributs uuid, alpha et texte ; les attributs "blob" sont des [objets blob](../Concepts/dt_blob.md#blob-types).
  • si `.kind` = "relatedEntity" : nom de la dataClass liée
  • si `.kind` = "relatedEntities" : nom de la dataClass liée + suffixe "Selection"
  • si `.kind` = "calculated" ou "alias" : même chose que ci-dessus, en fonction du résultat
    • | -| unique | Boolean | Vrai si la valeur de l'attribut doit être unique. Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". | -| classID | Text | Disponible uniquement si `.type = "object"` et si une classe a été spécifiée dans l'éditeur de structure.
    Retourne le nom de la classe utilisée pour instancier l'objet. | +| Propriété | Type | Description | +| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| autoFilled | Boolean | Vrai si la valeur de l'attribut est automatiquement remplie par 4D. Correspond aux propriétés de champs 4D suivantes : "Autoincrement" pour les champs de type numérique et "UUID Auto" pour les champs UUID (alpha). Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". | +| exposed | Boolean | Vrai si l'attribut est exposé en REST | +| fieldNumber | integer | Numéro interne du champ 4D correspondant à l'attribut. Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". | +| fieldType | Integer | Type de champ de la base de données 4D de l'attribut. Dépend de l'attribut `kind`. Valeurs possibles :
  • si `.kind` = "storage" : type de champ 4D correspondant, voir [`Value type`](../commands/value-type)
  • si `.kind` = "relatedEntity" : 38 (`is object`)
  • si `.kind` = "relatedEntities" : 42 (`is collection`)
  • si `.kind` = "calculated" ou "alias" = même chose que ci-dessus, en fonction de la valeur résultante (type de champ, relatedEntity ou relatedEntities)
    • | +| indexed | Boolean | Vrai s'il existe un index B-tree ou Cluster B-tree sur l'attribut. Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". | +| inverseName | Text | Nom de l'attribut qui se trouve à l'autre côté de la relation. Renvoyé uniquement lorsque `.kind` = "relatedEntity" ou "relatedEntities". | +| keywordIndexed | Boolean | Vrai s'il existe un index de mots-clés sur l'attribut. Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". | +| kind | Text | Catégorie de l'attribut. Valeurs possibles :
  • "storage" : attribut de stockage (ou scalaire), c'est-à-dire attribut stockant une valeur et non une référence à un autre attribut
  • "calculated" : attribut calculé, c'est-à-dire défini par une [fonction `get`](../ORDA/ordaClasses.md#function-get-attributename)
  • "alias" : attribut construit sur [un autre attribut](../ORDA/ordaClasses.md#alias-attributes-1)
  • "relatedEntity" : attribut de relation N -> 1 (référence à une entité)
  • "relatedEntities" : attribut de relation 1->N (référence à une entity selection)
    • | +| obligatoire | Boolean | Vrai si la saisie d'une valeur null est rejetée pour l'attribut. Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". Attention : Cette propriété correspond à la propriété du champ "Reject NULL value input" au niveau de la base de données 4D. Elle n'est pas liée à la propriété "Mandatory" existante qui est une option de contrôle de la saisie de données pour une table. | +| name | Text | Nom de l'attribut sous forme de chaîne | +| path | Text | Chemin d'un [attribut alias](../ORDA/ordaClasses.md#alias-attributes-1) basé sur une relation | +| readOnly | Boolean | Vrai si l'attribut est en lecture seule. Par exemple, les attributs calculés sans la fonction [`set`](../ORDA/ordaClasses.md#function-set-attributename) sont en lecture seule. | +| relatedDataClass | Text | Nom de la dataclass liée à l'attribut. Renvoyé uniquement lorsque `.kind` = "relatedEntity" ou "relatedEntities". | +| type | Text | Type conceptuel de la valeur de l'attribut, utile pour la programmation générique. Dépend de l'attribut `kind`. Valeurs possibles :
  • si `.kind` = "storage" : "blob", "bool", "date", "image", "number", "object", ou "string". "number" est renvoyé pour tous les types numériques, y compris duration ; "string" est renvoyé pour les types d'attributs uuid, alpha et texte ; les attributs "blob" sont des [objets blob](../Concepts/dt_blob.md#blob-types).
  • si `.kind` = "relatedEntity" : nom de la dataClass liée
  • si `.kind` = "relatedEntities" : nom de la dataClass liée + suffixe "Selection
  • si `.kind` = "calculated" ou "alias" : même chose que ci-dessus, en fonction du résultat
    • | +| unique | Boolean | Vrai si la valeur de l'attribut doit être unique. Non retourné si `.kind` = "relatedEntity" ou "relatedEntities". | +| classID | Text | Disponible uniquement si `.type = "object"` et si une classe a été spécifiée dans l'éditeur de structure.
    Retourne le nom de la classe utilisée pour instancier l'objet. | :::tip @@ -636,42 +636,42 @@ La méthode projet ***SearchDuplicate*** recherche des valeurs dupliquées dans
    -| Paramètres | Type | | Description | -| ---------- | ---------- | --------------------------- | --------------------------- | -| Résultat | Collection | <- | Collection of index objects | +| Paramètres | Type | | Description | +| ---------- | ---------- | --------------------------- | ------------------------- | +| Résultat | Collection | <- | Collection d'objets index |
    #### Description -The `.getIndexes()` function returns a collection of all indexes related to the dataclass. +La fonction `.getIndexes()` retourne une collection de tous les index liés à la dataclass. -Each index is an object of the collection. Indexes are returned in the creation/modification order. An empty collection is returned if there is no index in the dataclass. +Chaque index est un objet de la collection. Les index sont retournés dans l'ordre de création/modification. Une collection vide est retournée s'il n'y a pas d'index dans la dataclass. **Collection retournée** -Each object of the returned collection has the following properties: +Chaque objet de la collection retournée contient les propriétés suivantes : -| Propriété | Type | Description | -| ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| type | Integer | Index type: -1 = Keywords, 0 = default, 1 = Standard B-Tree, 3 = Cluster B-Tree, 4 = Cosine, 5 = Dot, 6 = Euclidean. If the index is set to Automatic, the type property represents the type of the indexing algorithm used | -| automatic | Boolean | True if "automatic" index is selected | -| name | Text | Index name if defined | -| kind | Text | "keywords" if *keyword index* checked, otherwise "regular" | -| attributes | Collection | Index attribute or list of attributes (for composite index) | -| UUID | Text | Index UUID | -| uniqueKey | Boolean | True if index has the Unique key property | +| Propriété | Type | Description | +| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| type | Integer | Type d'index : -1 = Mots-clés, 0 = Par défaut, 1 = B-Tree standard, 3 = B-Tree cluster, 4 = Cosinus, 5 = Produit scalaire, 6 = Euclidien. Si l'index est défini sur Automatique, la propriété type représente le type de l'algorithme d'indexation utilisé | +| automatic | Boolean | True si l'index "automatique" est sélectionné | +| name | Text | Nom de l'index si défini | +| kind | Text | "keywords" si *Index mots-clés* est coché, sinon "regular" | +| attributes | Collection | Attribut de l'index ou liste d'attributs (pour les index composites) | +| UUID | Text | UUID de l'index | +| uniqueKey | Boolean | True si l'index a la propriété Unique | :::tip Article(s) de blog sur le sujet -[Managing 4D Indexes Programmatically with getIndexes()](https://blog.4d.com/managing-4d-indexes-programmatically-with-getindexes) +[Gestion des index 4D par programmation à l’aide de la fonction getIndexes()](https://blog.4d.com/managing-4d-indexes-programmatically-with-getindexes) ::: #### Exemple -Considering the following table: +Considérant la table suivante : ![table-indexes](../assets/en/API/table-index.png) @@ -793,7 +793,7 @@ La fonction `.getInfo()` renvoie u #### Description -La fonction `.getRemoteCache()` renvoie un objet qui contient le contenu du cache ORDA pour une dataclass. +La fonction `.setRemoteCacheSettings()` définit le timeout et la taille maximale du cache ORDA pour une dataclass.. Si elle est appelée depuis une application 4D monoposte, la fonction retourne `Null`. @@ -1096,18 +1096,18 @@ L'utilisation de placeholders dans les recherches **est recommandée** pour les 1. Cela empêche l'injection de code malveillant : si vous utilisez dans la chaîne de recherche des variables dont le contenu provient directement de la saisie de l'utilisateur, celui-ci pourrait modifier les conditions de recherche en saisissant des arguments de recherche supplémentaires. Par exemple, imaginez une chaîne de recherche du type : -```4d - $vquery:="status = 'public' & name = "+myname //l'utilisateur saisit son nom - $result:=$col.query($vquery) -``` + ```4d + $vquery:="status = 'public' & name = "+myname //l'utilisateur saisit son nom + $result:=$col.query($vquery) + ``` Cette recherche semble sécurisée puisque les données non publiques sont filtrées. Cependant, si l'utilisateur saisit dans la zone *myname* une chaîne du type *"smith OR status='private'*, la chaîne de recherche sera modifiée à l'étape de l'interprétation et pourra retourner des données privées. Lorsque vous utilisez des placeholders, le contournement des options de sécurité n'est pas possible : -```4d - $result:=$col.query("status='public' & name=:1";myname) -``` + ```4d + $result:=$col.query("status='public' & name=:1";myname) + ``` Dans ce cas, si l'utilisateur saisit *smith OR status='private'* dans la zone *myname*, cela ne sera pas interprété dans la chaîne de recherche, mais uniquement passé en tant que valeur. La recherche d'une personne nommée "smith OR status='private"' échouera simplement. @@ -1115,10 +1115,10 @@ Dans ce cas, si l'utilisateur saisit *smith OR status='private'* dans la zone *m 3. Cela permet l'utilisation de variables ou d'expressions dans les arguments de recherche. Exemples : -```4d -$result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@") -$result2:=$col.query("company.name = :1";"John's Pizzas") -``` + ```4d + $result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@") + $result2:=$col.query("company.name = :1";"John's Pizzas") + ``` ### Recherche de valeurs null @@ -1288,11 +1288,11 @@ Si *attributePath* désigne un attribut stockant des [**objets vecteurs**](../AP Dans ce cas, le paramètre *value* doit être un **objet vecteur de comparaison** contenant les propriétés suivantes : -| Propriété | Type | Description | -| --------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| vector | [4D.Vector](../API/VectorClass.md) | Obligatoire. Le vecteur à comparer | -| metric | Text | Optionnel. [Calcul vectoriel](../API/VectorClass.md#understanding-the-different-vector-computations) à utiliser pour la recherche. Vous pouvez utiliser l'une des constantes (texte) suivantes :
  • `mk cosine` (valeur par défaut si non spécifiée) : calcule la [similarité cosinus](./VectorClass.md#cosinesimilarity) entre deux vecteurs.
  • `mk dot` : calcule la [similarité scalaire](VectorClass.md#dotsimilarity) entre deux vecteurs.
  • `mk euclidean` : calcule la [distance euclidienne](./VectorClass.md#euclideandistance) entre des vecteurs. | -| threshold | Real | Facultatif (valeur par défaut : 0,5). Valeur seuil utilisée pour filtrer les comparaisons de vecteurs sur la base de leur score de similarité cosinus, point ou euclidienne selon la "métrique" sélectionnée. Il est fortement recommandé de choisir une similitude qui corresponde le mieux à votre cas d'utilisation spécifique pour des résultats optimaux. | +| Propriété | Type | Description | +| --------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| vector | [4D.Vector](../API/VectorClass.md) | Obligatoire. Le vecteur à comparer | +| metric | Text | Optionnel. [Calcul vectoriel](../API/VectorClass.md#understanding-the-different-vector-computations) à utiliser pour la recherche. Vous pouvez utiliser l'une des constantes (Text) suivantes :
  • `mk cosine` (valeur par défaut si non spécifiée) : calcule la [similarité cosinus](./VectorClass.md#cosinesimilarity) entre deux vecteurs.
  • `mk dot` : calcule la [similarité par produit scalaire](VectorClass.md#dotsimilarity) entre des vecteurs.
  • `mk euclidean` : calcule la [distance euclidienne](./VectorClass.md#euclideandistance) entre deux vecteurs. | +| threshold | Real | Facultatif (valeur par défaut : 0,5). Valeur seuil utilisée pour filtrer les comparaisons de vecteurs sur la base de leur score de similarité cosinus, point ou euclidienne selon la "métrique" sélectionnée. Il est fortement recommandé de choisir une similitude qui corresponde le mieux à votre cas d'utilisation spécifique pour des résultats optimaux. | Seul un sous-ensemble de symboles **comparateurs** est pris en charge. Notez qu'ils comparent les résultats à la valeur de seuil (threshold) : @@ -1342,7 +1342,7 @@ Voir [plus d'exemples ci-dessous](#example-4-2) (exemples 4 et 5). - [4D AI : Recherche d'entités par similarité vectorielle en 4D](https://blog.4d.com/4d-ai-searching-entities-by-vector-similarity-in-4d) - [4D AI : Tri des résultats d'une requête en fonction de la similarité vectorielle](https://blog.4d.com/4d-ai-sorting-query-results-by-vector-similarity/) -- [Why Your Search Stack Feels Broken — and How Vector Search Fixes It](https://blog.4d.com/why-your-search-stack-feels-broken-and-how-vector-search-fixes-it) +- [Pourquoi votre pile de recherche semble brisée – et comment Vector Search y remédie](https://blog.4d.com/why-your-search-stack-feels-broken-and-how-vector-search-fixes-it) ::: @@ -1766,7 +1766,7 @@ var $results := ds.MyTable.query("myVectorField <= :1 AND salary>100000 order by #### Description -La fonction `.setRemoteCacheSettings()` définit le timeout et la taille maximale du cache ORDA pour une dataclass.. +La fonction `.getRemoteCache()` renvoie un objet qui contient le contenu du cache ORDA pour une dataclass.. Dans le paramètre *settings*, passez un objet contenant les propriétés suivantes : diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/DataStoreClass.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/DataStoreClass.md index 80d9d4535a9855..d6d91dd09d0479 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/DataStoreClass.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/DataStoreClass.md @@ -457,7 +457,7 @@ La fonction `.getInfo()` renvoie u | Propriété | Type | Description | | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | string |
  • "4D": datastore principal, disponible via ds
  • "4D Server": datastore distant, ouvert avec Open datastore
    • | -| networked | boolean |
  • True: le datastore est atteint via une connexion réseau.
  • False : le datastore n'est pas atteint via une connexion réseau (base de données locale)
    • | +| networked | boolean |
  • Vrai : le datastore est accessible via une connexion réseau.
  • Faux : le datastore n'est pas accessible via une connexion réseau (base locale)
    • | | localID | text | Identifiant du datastore sur la machine. Identifiant du datastore sur la machine. Chaîne vide ("") pour le datastore principal. | | connection | object | Objet décrivant la connexion au datastore distant (non retourné pour le datastore principal). Propriétés disponibles:
    PropriétéTypeDescription
    hostnametextAdresse IP ou nom du datastore distant + ":" + numéro de port
    tlsbooleannTrue si une connexion sécurisée est utilisée avec le datastore distant
    idleTimeoutnumberDélai d'inactivité de la session (en minutes)
    usertextUtilisateur authentifié sur le datastore distant
    | @@ -524,7 +524,7 @@ Sur un datastore distant : #### Description -La fonction `.getRemoteContextInfo()` renvoie un objet qui contient des informations sur le contexte d'optimisation *contextName* dans le datastore. +La fonction `.getRemoteContextInfo()` renvoie un objet qui contient des informations sur le contexte d'optimisation *contextName* dans le datastore.. Pour plus d'informations sur la façon dont les contextes peuvent être créés, voir [Optimisation client/serveur](../ORDA/client-server-optimization.md#optimization-context). @@ -1064,12 +1064,12 @@ Pour une description du format du journal des requêtes ORDA, veuillez vous réf Pour créer un journal des requêtes ORDA côté client, appelez cette fonction sur une machine distante. Le journal peut être envoyé à un fichier ou en mémoire, selon le type de paramètre : -- Si vous avez passé un objet *file* créé à l'aide de la commande `File`, les données de l'enregistrement sont écrites dans ce fichier sous forme de collection d'objets (format JSON). Chaque objet représente une requête.
    Si le fichier n'existe pas encore, il est créé. Sinon, s'il existe déjà, les nouvelles données d'enregistrement y sont ajoutées. +- Si vous avez passé un objet *file* créé à l'aide de la commande `File`, les données de l'enregistrement sont écrites dans ce fichier sous forme de collection d'objets (format JSON). Si vous avez passé un objet *file* créé à l'aide de la commande `File`, les données de l'enregistrement sont écrites dans ce fichier sous forme de collection d'objets (format JSON).Si le fichier n'existe pas encore, il est créé. Sinon, s'il existe déjà, les nouvelles données d'enregistrement y sont ajoutées. Si la fonction `.startRequestLog()` est appelée avec un fichier alors qu'un enregistrement des requêtes est déjà en cours en mémoire, l'enregistrement en mémoire est stoppé et vidé. > Un caractère \] doit être ajouté manuellement à la fin du fichier pour effectuer une validation JSON -- Si vous avez passé un numéro *reqNum*, l'enregistrement en mémoire est vidé (le cas échéant) et un nouvel enregistrement est lancé. Il gardera en mémoire les requêtes jusqu'à atteindre le nombre *reqNum*, auquel cas les entrées les plus anciennes sont vidées (pile FIFO).
    Si la fonction `.startRequestLog()` est appelée avec un *reqNum* alors qu'un enregistrement des requêtes était déjà en cours dans un fichier, l'enregistrement dans le fichier est stoppé. +- Si vous avez passé un numéro *reqNum*, l'enregistrement en mémoire est vidé (le cas échéant) et un nouvel enregistrement est lancé. Si vous avez passé un numéro *reqNum*, l'enregistrement en mémoire est vidé (le cas échéant) et un nouvel enregistrement est lancé.Il conserve les demandes *reqNum* en mémoire jusqu'à ce que le nombre soit atteint, auquel cas les entrées les plus anciennes sont vidées (pile FIFO).
    - Si vous n'avez passé aucun paramètre, l'enregistrement est lancé dans la mémoire. Si `.startRequestLog()` a été préalablement appelée avec un *reqNum* (avant un `.stopRequestLog()`), les données enregistrées sont empilées dans la mémoire jusqu'au prochain vidage ou appel de `.stopRequestLog()`. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/EntityClass.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/EntityClass.md index d8a0740e3397d8..36658fb937d632 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/EntityClass.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/EntityClass.md @@ -399,15 +399,15 @@ L'objet renvoyé par `.drop()` contient les propriétés suivantes : (\*) Les valeurs suivantes peuvent être retournées dans les propriétés *status* et *statusText* de l'objet *Résultat* en cas d'erreur : -| Constante | Valeur | Commentaire | -| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `dk status entity does not exist anymore` | 5 | L'entité n'existe plus dans les données. Cette erreur peut se produire dans les cas suivants:
  • l'entité a été supprimée (le marqueur a changé et l'espace mémoire est maintenant libre)
  • l'entité a été supprimée et remplacée par une autre avec une autre clé primaire (le marqueur a changé et une nouvelle entité utilise maintenant l'espace mémoire). Lors de l'utilisation de entity.drop(), cette erreur peut être renvoyée lorsque l'option dk force drop if stamp changed est utilisée. Lors de l'utilisation de entity.lock(), cette erreur peut être renvoyée lorsque l'option dk reload if stamp changed est utilisée.
    • **statusText associé** : "Entity does not exist anymore" | -| `dk status locked` | 3 | L'entité est verrouillée par un verrou pessimiste.
    **statusText associé** : "Already locked" | -| `dk status validation failed` | 7 | Erreur non fatale envoyée par le développeur pour un [événement de validation](../ORDA/orda-events.md). **statusText associé**: "Mild Validation Error" | -| `dk status serious error` | 4 | Une erreur critique peut être une erreur de bas niveau de la base de données (ex. clé dupliquée), une erreur matérielle, etc.
    **statusText associé** : "Other error" | -| `dk status serious validation error` | 8 | Erreur critique envoyée par le développeur pour un [événement de validation](../ORDA/orda-events.md). **statusText associé**: "Serious Validation Error" | -| `dk status stamp has changed` | 2 | La valeur interne du stamp de l'entité ne correspond pas à celle de l'entité stockée dans les données (verrouillage optimiste).
  • avec `.save()` : erreur seulement si l'option `dk auto merge` n'est pas utilisée
  • avec `.drop()` : erreur seulement si l'option `dk force drop if stamp changed` n'est pas utilisée
  • avec `.lock()` : erreur seulement si l'option `dk reload if stamp changed` n'est pas utilisée
  • **statusText associé** : "Stamp has changed"
    • | -| `dk status wrong permission` | 1 | Les privilèges courants ne permettent pas de supprimer l'entité. **statusText associé** : "Permission error" | +| Constante | Valeur | Commentaire | +| ----------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dk status entity does not exist anymore` | 5 | L'entité n'existe plus dans les données. Cette erreur peut se produire dans les cas suivants:
  • l'entité a été supprimée (le marqueur a changé et l'espace mémoire est maintenant libre)
  • l'entité a été supprimée et remplacée par une autre avec une autre clé primaire (le marqueur a changé et une nouvelle entité utilise maintenant l'espace mémoire). Lors de l'utilisation de entity.drop(), cette erreur peut être renvoyée lorsque l'option dk force drop if stamp changed est utilisée. Lors de l'utilisation de entity.lock(), cette erreur peut être renvoyée si l'option dk reload if stamp changed est utilisée.
    • \*\*statusText associé : "Entity does not exist anymore" | +| `dk status locked` | 3 | L'entité est verrouillée par un verrou pessimiste.
    **statusText associé** : "Already locked" | +| `dk status validation failed` | 7 | Erreur non fatale envoyée par le développeur pour un [événement de validation](../ORDA/orda-events.md). **statusText associé**: "Mild Validation Error" | +| `dk status serious error` | 4 | Une erreur critique peut être une erreur de bas niveau de la base de données (ex. clé dupliquée), une erreur matérielle, etc.
    **statusText associé** : "Other error" | +| `dk status serious validation error` | 8 | Erreur critique envoyée par le développeur pour un [événement de validation](../ORDA/orda-events.md). **statusText associé**: "Serious Validation Error" | +| `dk status stamp has changed` | 2 | La valeur du marqueur interne (stamp) de l'entité ne correspond pas à celle de l'entité stockée dans les données (verrouillage optimiste).
  • avec `.save()` : erreur seulement si l'option `dk auto merge` n'est pas utilisée
  • avec `.drop()` : erreur seulement si l'option `dk force drop if stamp changed` n'est pas utilisée
  • avec `.lock()` : erreur seulement si l'option `dk reload if stamp changed` n'est pas utilisée

    • **Associated statusText** : "Stamp has changed" | +| `dk status wrong permission` | 1 | Les privilèges courants ne permettent pas de supprimer l'entité. **statusText associé** : "Permission error" | #### Exemple 1 @@ -1058,7 +1058,7 @@ L'objet retourné par `.lock()` contient les propriétés suivantes : | `dk status entity does not exist anymore` | 5 | L'entité n'existe plus dans les données. Cette erreur peut se produire dans les cas suivants:
  • l'entité a été supprimée (le marqueur a changé et l'espace mémoire est maintenant libre)
  • l'entité a été supprimée et remplacée par une autre avec une autre clé primaire (le marqueur a changé et une nouvelle entité utilise maintenant l'espace mémoire). Lors de l'utilisation de `.drop()`, cette erreur peut être retournée lorsque l'option dk force drop if stamp changed est utilisée. Lors de l'utilisation de `.lock()`, cette erreur peut être retournée lorsque l'option `dk reload if stamp changed` est utilisée

    • **statusText associé** : "Entity does not exist anymore" | | `dk status locked` | 3 | L'entité est verrouillée par un verrou pessimiste.
    **statusText associé** : "Already locked" | | `dk status serious error` | 4 | Une erreur critique peut être une erreur de bas niveau de la base de données (ex. clé dupliquée), une erreur matérielle, etc.
    **statusText associé** : "Other error" | -| `dk status stamp has changed` | 2 | La valeur du stamp interne de l'entité ne correspond pas à celle de l'entité stockée dans les données (verrouillage optimiste).
  • avec `.save()` : erreur seulement si l'option `dk auto merge` n'est pas utilisée
  • avec `.drop()` : erreur seulement si l'option `dk force drop if stamp changed` n'est pas utilisée
  • avec `.lock()`: erreur seulement si l'option `dk reload if stamp changed` n'est pas utilisée

    • **statusText associé** : "Stamp has changed" | +| `dk status stamp has changed` | 2 | La valeur du marqueur interne (stamp) de l'entité ne correspond pas à celle de l'entité stockée dans les données (verrouillage optimiste).
  • avec `.save()` : erreur seulement si l'option `dk auto merge` n'est pas utilisée
  • avec `.drop()` : erreur seulement si l'option `dk force drop if stamp changed` n'est pas utilisée
  • avec `.lock()` : erreur seulement si l'option `dk reload if stamp changed` n'est pas utilisée

    • **statusText associé** : "Stamp has changed" | #### Exemple 1 @@ -1334,7 +1334,7 @@ Les valeurs suivantes peuvent être retournées dans les propriétés `status` e | `dk status validation failed` | 7 | Erreur non fatale envoyée par le développeur pour un [événement de validation](../ORDA/orda-events.md). **statusText associé**: "Mild Validation Error" | | `dk status serious error` | 4 | Une erreur critique peut être une erreur de bas niveau de la base de données (ex. clé dupliquée), une erreur matérielle, etc. **statusText associé** : "Other error" | | `dk status serious validation error` | 8 | Erreur critique envoyée par le développeur pour un [événement de validation](../ORDA/orda-events.md). **statusText associé**: "Serious Validation Error" | -| `dk status stamp has changed` | 2 | La valeur du marqueur interne de l'entité ne correspond pas à celle de l'entité stockée dans les données (verrouillage optimiste).
  • avec `.save()`: erreur uniquement si l'option `dk auto merge` n'est pas utilisée
  • avec `.drop()`: erreur uniquement si l'option `dk force drop if stamp changed` n'est pas utilisée
  • avec `.lock()`: erreur uniquement si l'option `dk reload if stamp changed` n'est pas utilisée

    • **StatusText associé**: "Stamp has changed" | +| `dk status stamp has changed` | 2 | La valeur du marqueur interne (stamp) de l'entité ne correspond pas à celle de l'entité stockée dans les données (verrouillage optimiste).
  • avec `.save()` : erreur seulement si l'option `dk auto merge` n'est pas utilisée
  • avec `.drop()` : erreur uniquement si l'option `dk force drop if stamp changed` n'est pas utilisée
  • avec `.lock()` : erreur seulement si l'option `dk reload if stamp changed` n'est pas utilisée
  • **statusText associé** : "Stamp has chaged"
    • | | `dk status wrong permission` | 1 | Les privilèges courants ne permettent pas de supprimer l'entité. **statusText associé** : "Permission error" | #### Exemple 1 diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/HTTPRequestClass.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/HTTPRequestClass.md index e551709aa5f01f..02ece52e0ff76f 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/HTTPRequestClass.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/HTTPRequestClass.md @@ -412,7 +412,7 @@ La propriété `.url` contient l'URL d ## .wait() -**.wait**( { *timeout* : Real } ) : 4D.HTTPRequest +**.wait**( { *time* : Real } ) : 4D.HTTPRequest diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/IMAPTransporterClass.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/IMAPTransporterClass.md index 6816ff744e187d..57d21497732143 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/IMAPTransporterClass.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/API/IMAPTransporterClass.md @@ -53,7 +53,7 @@ Les objets IMAP Transporter sont instanciés avec la commande [IMAP New transpor | Paramètres | Type | | Description | | ---------- | ---------------------------------- | :-------------------------: | -------------------------------------------------- | -| parameter | Object | -> | Configuration du serveur de messagerie | +| paramètres | Object | -> | Configuration du serveur de messagerie | | Résultat | 4D.IMAPTransporter | <- | [Objet transporteur IMAP](#objet-imap-transporter) | @@ -683,7 +683,7 @@ End if #### Description -La fonction `.expunge()` supprime tous les messages marqués "deleted" du serveur de messagerie IMAP. Le marqueur "deleted" peut être fixé avec les fonctions [`.delete()`](#delete) ou [`.addFlags()`](#addflags). +La fonction `.expunge()` supprime tous les messages avec le flag "deleted" du serveur de messagerie IMAP. Le flag "deleted" peut être défini avec les méthodes [`.delete()`](#delete) ou [`.addFlags()`](#addflags). **Objet retourné** @@ -835,7 +835,7 @@ Chaque objet de la collection retournée contient les propriétés suivantes : | \[].name | Text | Nom de la boîte de réception. Retourné si withBoxProperties=true ou withBoxInfo=true | | \[].selectable | Boolean | Indique si les droits d'accès permettent ou non de sélectionner la boîte aux lettres :
    • true - la boîte aux lettres peut être sélectionnée
    • false - la boîte aux lettres ne peut pas être sélectionnée
    Retourné si withBoxProperties=true | | \[].inferior | Boolean | Indique si les droits d'accès permettent ou non de créer une hiérarchie inférieure dans la boîte aux lettres :
    • true - un niveau inférieur peut être créé
    • false - un niveau inférieur ne peut pas être créé
    Retourné si withBoxProperties=true | -| \[].interesting | Boolean | Indique si la boîte aux lettres a été marquée comme "intéressante" par le serveur :
    • true - La boîte aux lettres a été marquée comme "intéressante" par le serveur. Par exemple, elle peut contenir de nouveaux messages.
    • false - La boîte aux lettres n'a pas été marquée comme "intéressante" par le serveur
      • .
    Retourné si withBoxProperties=true | +| \[].interesting | Boolean | Indique si la boîte aux lettres a été marquée comme "intéressante" par le serveur :
    • true - La boîte aux lettres a été marquée comme "intéressante" par le serveur. Par exemple, elle peut contenir de nouveaux messages.
    • faux - la boite de réception n'a pas été marquée comme "intéressante" par le serveur.
    Retourné si withBoxProperties=true | | [].mailCount | Number | Nombre de messages dans la boîte inbox. Retourné si withBoxInfo=true | | [].mailRecent | Number | Nombre de messages portant le marqueur "recent" (indiquant les nouveaux messages). Retourné si withBoxInfo=true | | [].mailUnseen | Number | Nombre de messages marqués "unseen". Retourné si withBoxInfo=true | @@ -969,7 +969,7 @@ Le paramètre facultatif *options* vous permet de passer un objet définissant d > - La fonction génère une erreur et retourne **Null** si *msgID* désigne un message non existant, > - Si aucune boite de réception n'est sélectionnée avec la [fonction `.selectBox()`](#selectbox), une erreur est générée, -> - S'il n'y a pas de connexion ouverte, `.getMail()` ouvrira une connexion avec la dernière boite de réception spécifiée à l'aide de [`.selectBox()`](#selectbox)\\\\`. +> - S'il n'y a pas de connexion ouverte, `.getMail()` ouvrira une connexion avec la dernière boite de réception spécifiée à l'aide de [`.selectBox()`](#selectbox)\\\`. #### Résultat @@ -1071,10 +1071,10 @@ Le paramètre optionnel *options* vous permet de définir les parties de message `.getMails()` retourne un objet contenant les collections suivantes : -| Propriété | Type | Description | -| --------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| list | Collection | Collection d'[objets Email](EmailObjectClass.md#objet-email). Si aucun objet Email n'est trouvé, une collection vide est retournée. | -| notFound | Collection | Collection de :
    • première syntaxe - ID de messages passés précédemment qui n'existent pas
    • deuxième syntaxe - numéros de séquence des messages entre startMsg et endMsg qui n'existent pas.
    Une collection vide est renvoyée si tous les messages ont été trouvés. | +| Propriété | Type | Description | +| --------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| list | Collection | Collection d'[objets Email](EmailObjectClass.md#objet-email). Si aucun objet Email n'est trouvé, une collection vide est retournée. | +| notFound | Collection | Collection de :
    • première syntaxe - ID de messages passés précédemment qui n'existent pas
    • deuxième syntaxe - numéros de séquence des messages entre startMsg et endMsg qui n'existent pas.
    Une collection vide est renvoyée si tous les messages ont été trouvés. | #### Exemple @@ -1589,7 +1589,7 @@ End if > Cette fonction est basée sur la spécification du [protocole IMAP](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol). -La fonction `.searchMails()` recherche les messages qui correspondent aux critères de recherche *searchCriteria* dans la boîte aux lettres courante. . . +La fonction `.searchMails()` recherche les messages qui correspondent aux critères de recherche *searchCriteria* dans la boîte aux lettres courante. . *searchCriteria* est un paramètre texte listant un ou plusieurs critères de recherche (voir [Mots-clés de recherche autorisés](#mots-cles-de-recherche-autorises) ci-dessous) associés ou non à des valeurs à rechercher. Un critère de recherche peut être composé d'un ou plusieurs éléments. Par exemple : diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md index 548b17b1d76767..f910900c7a523f 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md @@ -41,7 +41,7 @@ Le code 4D ne peut être exécuté dans un process préemptif que lorsque certai La propriété "thread safety" de chaque élément dépend de l'élément lui-même : -- Commandes 4D : la propriété thread-safe est une propriété interne. Dans la documentation 4D, les commandes thread-safe sont identifiées par l'icône ![](../assets/en/Develop/thread-safe.png). Vous pouvez également utiliser la commande [`Command name`](../commands/command-name) pour savoir si une commande est thread-safe. Une grande partie des commandes 4D peut s'exécuter en mode préemptif. +- Commandes 4D : la propriété thread-safe est une propriété interne. The 4D documentation indicates whether each command is thread-safe or not in the Properties section. Vous pouvez également utiliser la commande [`Command name`](../commands/command-name) pour savoir si une commande est thread-safe. Une grande partie des commandes 4D peut s'exécuter en mode préemptif. - Méthodes projet : les conditions pour être thread-safe sont répertoriées dans [ce paragraphe](#writing-a-thread-safe-method). Fondamentalement, le code à exécuter dans des threads préemptifs ne peut pas appeler des parties avec des interactions externes, telles que du code de plug-in ou des variables interprocess. Cependant, l'accès aux données est autorisé car le serveur de données 4D et ORDA prennent en charge l'exécution préemptive. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md index d831a6fda84d21..2f897e2c80f683 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md @@ -147,7 +147,7 @@ Pour ajouter un champ à l'index, cliquez sur le bouton **[+]**. La liste des ch - Si vous souhaitez créer un index composite, ajoutez successivement chaque champ à inclure dans l'index. Une fois la liste complétée, vous pouvez réorganiser les champs à l'aide des boutons fléchés ou par glisser-déposer. - Si vous créez un index composite basé sur les champs de la clé primaire, veillez à ce que l'ordre des champs soit identique dans la clé primaire et dans l'index. -- Si vous avez choisi le type "Index de mots-clés", seuls les champs Alpha ou Texte peuvent être sélectionnés. Dans ce cas également, vous ne pouvez inclure qu'un seul champ dans l'index. +- If you have chosen the “Keyword Index” type, only Alpha, Text, or Picture fields can be selected. Also in this case, you can include only one field in the index. Pour supprimer un champ de l'index, sélectionnez-le dans la liste et cliquez sur le bouton **[-]**. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md index 1d8b5699ab5475..7adb2d78b89396 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md @@ -67,6 +67,12 @@ Les actions disponibles sont liées à la ressource cible. Le paramétrage des permissions nécessite d'être cohérent, en particulier les permissions **update** et **drop** ont également besoin d'une permission **read** (mais **create** n'en a pas besoin). +:::warning + +When a permission entry references an undeclared [privilege](#privileges-and-roles), 4D logs an error and ignores the entry. In this case, the permission is ignored. If the [restricted mode by default](#restriction-modes) is not enabled, the resource is accessible to `guest` sessions. + +::: + ### Permissions héritées Une action de permission définie à un certain niveau est héritée par défaut aux niveaux inférieurs, mais plusieurs niveaux de permissions peuvent être définis : 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/code-editor/write-class-method.md b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/code-editor/write-class-method.md index 0e77b2fcaecb8c..6f8f20b4b09c69 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/code-editor/write-class-method.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21-R5/code-editor/write-class-method.md @@ -25,16 +25,16 @@ Si vous avez l'habitude de coder avec **VS Code**, vous pouvez également utilis Chaque fenêtre de l'éditeur de code dispose d'une barre d'outils qui permet un accès instantané aux fonctionnalités de base liées à l'exécution et à l'édition du code. -| Élément | Icône | Description | -| --------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Exécuter la méthode** | ![execute-method](../assets/en/code-editor/execute-method.png) | Lorsque vous travaillez avec des méthodes, chaque fenêtre de l'éditeur de code dispose d'un bouton qui peut être utilisé pour exécuter la méthode en cours. En utilisant le menu associé à ce bouton, vous pouvez choisir le type d'exécution :
    • **Exécuter nouveau process** : Crée un process et exécute la méthode en mode standard dans ce process.
    • **Exécuter et déboguer nouveau process** : Crée un nouveau process et affiche la méthode dans la fenêtre du débogueur pour une exécution pas à pas dans ce process.
    • **Exécuter dans le process application** : Exécute la méthode en mode standard dans le contexte du process de l'application (c'est-à-dire la fenêtre d'affichage des enregistrements).
    • **Exécuter et déboguer dans le process application** : Affiche la méthode dans la fenêtre du débogueur pour une exécution pas à pas dans le contexte du process de l'application.
    Pour plus d'informations sur l'exécution des méthodes, voir [Méthodes projet](../Project/project-method-properties.md). | -| **Chercher dans la méthode** | ![search-icon](../assets/en/code-editor/search.png) | Affiche la [*zone de recherche*](#find-and-replace). | -| **Macros** | ![macros-button](../assets/en/code-editor/macros.png) | Insère une macro dans la sélection. Cliquez sur la flèche déroulante pour afficher la liste des macros disponibles. Pour plus d'informations sur la création et l'instanciation des macros, voir [Macros](#macros). | -| **Déployer tout / Contracter tout** | ![expand-collapse-button](../assets/en/code-editor/expand-collapse-all.png) | Ces boutons permettent de déployer ou de contracter toutes les structures de flux de contrôle du code. | -| **Informations sur la méthode** | ![method-information-icon](../assets/en/code-editor/method-information.png) | Affiche la boîte de dialogue [Propriétés de la méthode](../Project/project-method-properties.md) (méthodes de projet uniquement). | -| **Dernières valeurs du presse-papiers** | ![last-clipboard-values-icon](../assets/en/code-editor/last-clipboard-values.png) | Affiche les dernières valeurs stockées dans le presse-papiers. | -| **Presse-papiers** | ![clipboard icons](../assets/en/code-editor/clipboards.png) | Neuf presse-papiers sont disponibles dans l'éditeur de code. Vous pouvez [utiliser ces presse-papiers](#clipboards) en cliquant directement dessus ou en utilisant des raccourcis clavier. Vous pouvez utiliser une option des [Préférences](Preferences/methods.md#options-1) pour les masquer. | -| **Menu déroulant de navigation** | ![code-navigation-icons](../assets/en/code-editor/tags.png) | Vous permet de naviguer à l'intérieur des méthodes et des classes avec du contenu étiqueté automatiquement ou des marqueurs déclarés manuellement. Voir ci-dessous | +| Élément | Icône | Description | +| --------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Exécuter la méthode** | ![execute-method](../assets/en/code-editor/execute-method.png) | Lorsque vous travaillez avec des méthodes, chaque fenêtre de l'éditeur de code dispose d'un bouton qui peut être utilisé pour exécuter la méthode en cours. Le menu associé à ce bouton permet de choisir le type d'exécution :
    • **Exécuter nouveau process** : Crée un process et exécute la méthode en mode standard dans ce process.
    • **Exécuter et déboguer nouveau process** : Crée un nouveau process et affiche la méthode dans la fenêtre du débogueur pour une exécution pas à pas dans ce process.
    • **Exécuter dans le process de l'application** : Exécute la méthode en mode standard dans le contexte du process de l'application (c'est-à-dire la fenêtre d'affichage des enregistrements).
    • **Exécuter et déboguer dans le process de l'application** : Affiche la méthode dans la fenêtre du débogueur pour une exécution pas à pas dans le contexte du process de l'application (la fenêtre d'affichage des enregistrements).
    Pour plus d'informations sur l'exécution des méthodes, consultez la page [Méthodes de projet](../Project/project-method-properties.md). | +| **Chercher dans la méthode** | ![search-icon](../assets/en/code-editor/search.png) | Affiche la [*zone de recherche*](#find-and-replace). | +| **Macros** | ![macros-button](../assets/en/code-editor/macros.png) | Insère une macro dans la sélection. Cliquez sur la flèche déroulante pour afficher la liste des macros disponibles. Pour plus d'informations sur la création et l'instanciation des macros, voir [Macros](#macros). | +| **Déployer tout / Contracter tout** | ![expand-collapse-button](../assets/en/code-editor/expand-collapse-all.png) | Ces boutons permettent de déployer ou de contracter toutes les structures de flux de contrôle du code. | +| **Informations sur la méthode** | ![method-information-icon](../assets/en/code-editor/method-information.png) | Affiche la boîte de dialogue [Propriétés de la méthode](../Project/project-method-properties.md) (méthodes de projet uniquement). | +| **Dernières valeurs du presse-papiers** | ![last-clipboard-values-icon](../assets/en/code-editor/last-clipboard-values.png) | Affiche les dernières valeurs stockées dans le presse-papiers. | +| **Presse-papiers** | ![clipboard icons](../assets/en/code-editor/clipboards.png) | Neuf presse-papiers sont disponibles dans l'éditeur de code. Vous pouvez [utiliser ces presse-papiers](#clipboards) en cliquant directement dessus ou en utilisant des raccourcis clavier. Vous pouvez utiliser une option des [Préférences](Preferences/methods.md#options-1) pour les masquer. | +| **Menu déroulant de navigation** | ![code-navigation-icons](../assets/en/code-editor/tags.png) | Vous permet de naviguer à l'intérieur des méthodes et des classes avec du contenu étiqueté automatiquement ou des marqueurs déclarés manuellement. Voir ci-dessous | ### Zone d'édition 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/Develop/preemptive.md b/i18n/fr/docusaurus-plugin-content-docs/version-21/Develop/preemptive.md index d545a396a2356b..ee10e775d1305e 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/version-21/Develop/preemptive.md +++ b/i18n/fr/docusaurus-plugin-content-docs/version-21/Develop/preemptive.md @@ -41,7 +41,7 @@ Le code 4D ne peut être exécuté dans un process préemptif que lorsque certai La propriété "thread safety" de chaque élément dépend de l'élément lui-même : -- Commandes 4D : la propriété thread-safe est une propriété interne. Dans la documentation 4D, les commandes thread-safe sont identifiées par l'icône ![](../assets/en/Develop/thread-safe.png). Commandes 4D : la propriété thread-safe est une propriété interne. Une grande partie des commandes 4D peut s'exécuter en mode préemptif. +- Commandes 4D : la propriété thread-safe est une propriété interne. The 4D documentation indicates whether each command is thread-safe or not in the Properties section. Commandes 4D : la propriété thread-safe est une propriété interne. Une grande partie des commandes 4D peut s'exécuter en mode préemptif. - Méthodes projet : les conditions pour être thread-safe sont répertoriées dans [ce paragraphe](#writing-a-thread-safe-method). Fondamentalement, le code à exécuter dans des threads préemptifs ne peut pas appeler des parties avec des interactions externes, telles que du code de plug-in ou des variables interprocess. Cependant, l'accès aux données est autorisé car le serveur de données 4D et ORDA prennent en charge l'exécution préemptive. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/API/UDPSocketClass.md b/i18n/ja/docusaurus-plugin-content-docs/current/API/UDPSocketClass.md index d33015ed99ac86..c7ca24f1434184 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/API/UDPSocketClass.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/API/UDPSocketClass.md @@ -50,7 +50,7 @@ UDPSocket オブジェクトは以下のプロパティと関数を提供しま | 引数 | 型 | | 説明 | | ------- | ---------------------------- | --------------------------- | ------------------------------------------------------------------------ | | port | Integer | -> | UDP ソケットに使用されるローカルのポート番号(0 または省略時には使用されていないポートを探して使用) | -| options | Object | -> | ソケットの接続[オプション](#options引数) | +| options | Object | -> | ソケットの接続[オプション](#options-引数) | | 戻り値 | 4D.UDPSocket | <- | 新規UDPSocket オブジェクト | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/API/WebSocketServerClass.md b/i18n/ja/docusaurus-plugin-content-docs/current/API/WebSocketServerClass.md index 80c0e06aa26048..09d2a346b74a78 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/API/WebSocketServerClass.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/API/WebSocketServerClass.md @@ -37,7 +37,7 @@ WebSocketプロトコルは、WebSocketサーバーとクライアント (Webブ - サーバー接続を処理するためのユーザークラス - メッセージを処理するためのユーザークラス -接続を維持するため、[WebSocketサーバーの作成](#4dwebsocketservernew) は [ワーカー](../Develop/processes.md#worker-プロセス) 内にて行う必要があります。 +接続を維持するため、[WebSocketサーバーの作成](#4dwebsocketservernew) は [ワーカー](../Develop/processes.md#ワーカープロセス) 内にて行う必要があります。 [4D Webサーバー](WebServerClass.md) を起動しておく必要があります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/Concepts/methods.md b/i18n/ja/docusaurus-plugin-content-docs/current/Concepts/methods.md index 6fceb51a31e39a..6779385e1814af 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/Concepts/methods.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/Concepts/methods.md @@ -5,7 +5,7 @@ title: メソッド メソッドとは、1つ以上の動作を実行するコードのことです。メソッドは、1つ以上のステートメントで構成されます。 -ステートメントは 1つの命令を実行し、単純な場合もあれば複雑な場合もあります。ステートメントとは通常、メソッドの 1行のことを指します (必要に応じて [`\` 文字を使って行を分割](quick-tour.md#行を分割する) することができます。 +ステートメントは 1つの命令を実行し、単純な場合もあれば複雑な場合もあります。ステートメントとは通常、メソッドの 1行のことを指します (必要に応じて [`\` 文字を使って行を分割](quick-tour.md#行を分割する)することができます)。 メソッドは最大 2GBのテキストまたは、32000行まで記述できます。 @@ -17,14 +17,14 @@ title: メソッド | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **プロジェクトメソッド** | プロジェクトメソッド名が[呼び出された時](../Project/project-method-properties.md) に応じて | ◯ | 任意のアクションを実行するためのコードです。作成されたプロジェクトメソッドは、そのプロジェクトのランゲージの一部となります。 | | **オブジェクト (ウィジェット) メソッド** | メソッドが設定されたフォームオブジェクトに関連したイベント発生時に | × | フォームオブジェクト (ウィジェットとも呼びます) のプロパティです。 | -| **フォームメソッド** | メソッドが設定されたフォームに関連したイベント発生時に | × | フォームのプロパティです。フォームメソッドを使用してデータとオブジェクトを管理することができます。 ただし、これら目的には、オブジェクトメソッドを使用する方が通常は簡単であり、より効果的です。 | +| **フォームメソッド** | メソッドが設定されたフォームに関連したイベント発生時に | × | フォームのプロパティです。フォームメソッドを使用してデータとオブジェクトを管理することができます。ただし、これら目的には、オブジェクトメソッドを使用する方が通常は簡単であり、より効果的です。 | | **トリガー** (別名 *テーブルメソッド*) | テーブルのレコード操作 (追加・削除・修正) の度に | × | テーブルのプロパティです。トリガーは、データベースのレコードに対して「不正な」操作がおこなわれることを防ぎます。 | | **データベースメソッド** | 作業セッションのイベント発生時に | ○ (既定) | 4D には 16のデータベースメソッドがあります。 | | **クラス** | クラスのオブジェクトがインスタンス化されたとき、あるいは他のメソッドや[データベースフィールド](../Develop/field-properties.md#class) 内においてオブジェクトインスタンス上でクラスの関数が実行されたときに自動的に呼び出されます。 | ◯(クラス関数) | オブジェクトのクラスの[constructor](./classes.md#class-constructor), [properties](./classes.md#property) と[関数](./classes.md#function) を宣言および設定するためには、**Class** が使用されます。[**クラス**](classes.md) および[**Function** クラス](../API/FunctionClass.md) 参照。 | ## ランゲージトークン -4Dランゲージでは、コード内で使用される全てのオブジェクト名(定数、コマンド、テーブル、フィールドそしてキーワード) 全てに対してユニークな トークナイゼーションシステムというものを持っています。これらの名前をトークナイズするということは、それらをコードエディターにタイプする際に内部で絶対参照 (数値) として保存され、実行時、あるいは表示時にコンテキストに応じてテキストとして復元されるということを意味します。これにより、コードは常に正しく解釈されるということが保証され、テーブルやフィールドの名前を変更した場合でも、4Dランゲージコマンドが異なるアプリケーションのバージョンに置いて改名された場合等でも正しく解釈されます。 +4Dランゲージでは、コード内で使用される全てのオブジェクト名(定数、コマンド、テーブル、フィールドそしてキーワード) 全てに対してユニークな トークナイゼーションシステムというものを持っています。これらの名前をトークナイズするということは、それらをコードエディターにタイプする際に内部で絶対参照 (数値) として保存され、実行時、あるいは表示時にコンテキストに応じてテキストとして復元されるということを意味します。これにより、コードは常に正しく解釈されるということが保証され、テーブルやフィールドの名前を変更した場合でも、4Dランゲージコマンドが異なるアプリケーションのバージョンにおいて改名された場合等でも正しく解釈されます。 **注意:** これは環境設定のメソッドページの["リージョンシステム設定を使用"オプション](../Preferences/methods.md#4dプログラミングランゲージ-リージョンシステム設定を使う) を有効化し、お使いの4D を異なる言語設定でデータベースを開いた際にも、コードの自動翻訳が正確であることを保証します。 @@ -48,7 +48,7 @@ title: メソッド ### トークンシンタックス -式の中でトークナイズ可能な名前付き要素に対して、4D はトークンを直接参照するための特別な信託巣を提供しています。要素名の後に型(コマンド、フィールド、など)を指定する特定の接頭辞を追加し、そのあとに参照を追加します。以下の表にこのトークンシンタックスについての詳細がまとめてあります: +式の中でトークナイズ可能な名前付き要素に対して、4D はトークンを直接参照するための特別なシンタックスを提供しています。要素名の後に型(コマンド、フィールド、など)を指定する特定の接頭辞を追加し、そのあとに参照を追加します。以下の表にこのトークンシンタックスについての詳細がまとめてあります: | 機能 | 使用例(標準のシンタックス) | 接尾辞 | 使用例(トークンシンタックス) | コメント | | -------- | ------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | @@ -58,7 +58,7 @@ title: メソッド | フィールド | [Employees]Name | :xx | [Employees:1]Name:2 | xx はフィールド番号です | | 4D プラグイン | PV PRINT(area) | :Pxx:yy | PV PRINT:P13000:229(area) | xx はプラグインIDで、yy はコマンドのインデックスです | -**注意:** 接頭辞には大文字(C, P)を使用しなければなりません。そうでない場合には正常に解釈されません。 +**注意:** 接尾辞には大文字 (C, P) を使用しなければなりません。そうでない場合には正常に解釈されません。 このシンタックスを使用することにより、フォーミュラの名前が変更された場合でも、データベースが異なる言語において実行された場合でも、フォーミュラが正しく解釈される事を保証します。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/Desktop/labels.md b/i18n/ja/docusaurus-plugin-content-docs/current/Desktop/labels.md index 70073d18ad1a8d..29b65f2314faab 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/Desktop/labels.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/Desktop/labels.md @@ -164,7 +164,7 @@ title: ラベル var myVar+=1 ``` -3. プロジェクトメソッドに対して["コンポーネントとホストデータベース間で共有"](../Project/project-method-properties.md#コンポーネントとホストデータベース間で共有) オプションを設定します。 +3. プロジェクトメソッドに対して["コンポーネントとホストデータベース間で共有"](../Project/project-method-properties.md#コンポーネントとホストプロジェクト間で共有) オプションを設定します。 4. ラベルエディターを表示する前に、以下のコードを実行してプロジェクトメソッドが確実に許可されているようにします: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/Develop/preemptive.md b/i18n/ja/docusaurus-plugin-content-docs/current/Develop/preemptive.md index 8f3647df6fbe95..15b0b4faa7ef73 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/Develop/preemptive.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/Develop/preemptive.md @@ -41,7 +41,7 @@ title: プリエンプティブプロセス 要素毎の "スレッドセーフティ" プロパティは、その要素自身によります: -- 4Dコマンド: スレッドセーフティは内部プロパティです。 4D ドキュメンテーション内においては、スレッドセーフなコマンドには ![](../assets/en/Develop/thread-safe.png) アイコンが表示されています。 [`Command name`](../commands/command-name) コマンドを使用して、コマンドがスレッドセーフであるかどうかを知ることもできます。 4Dコマンドの大部分はプリエンプティブモードで実行可能です。 +- 4Dコマンド: スレッドセーフティは内部プロパティです。 The 4D documentation indicates whether each command is thread-safe or not in the Properties section. [`Command name`](../commands/command-name) コマンドを使用して、コマンドがスレッドセーフであるかどうかを知ることもできます。 4Dコマンドの大部分はプリエンプティブモードで実行可能です。 - プロジェクトメソッド: スレッドセーフであるための条件は [こちらの段落](#スレッドセーフなメソッドの書き方) にまとめられています。 原則として、プリエンプティブスレッド内で実行されるコードは外部との相互作用する部分、たとえばプラグインコードやインタープロセス変数などを呼び出すことはできません。しかしながら、4Dデータサーバーと ORDA はプリエンプティブ実行をサポートしていることから、データアクセスは可能です。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/Develop/processes.md b/i18n/ja/docusaurus-plugin-content-docs/current/Develop/processes.md index d7eb693b4a3da8..65c53df3caa564 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/Develop/processes.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/Develop/processes.md @@ -50,7 +50,7 @@ title: プロセスとワーカー ### インターフェース要素 -インターフェース要素は、[デスクトップアプリケーション](../category/desktop-applications) で使用されます。 以下のものがあります: 以下のものがあります: +インターフェース要素は、[デスクトップアプリケーション](../category/desktop-applications) で使用されます。以下のものがあります: - [メニューバー](../Menus/creating.md): 各プロセスは、独自のカレントメニューバーを持つことができます。最前面のプロセスのメニューバーがアプリケーションのカレントメニューバーになります。 - 1つ以上のウィンドウ: 各プロセスは、1つまたは複数のウィンドウを同時に開くことができます。他方、ウィンドウをまったく持たないプロセスもあります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormEditor/createStylesheet.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormEditor/createStylesheet.md index 7437841e5f8e7e..259036be4d84d9 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormEditor/createStylesheet.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormEditor/createStylesheet.md @@ -101,7 +101,7 @@ text, input { } ``` -### Class +### クラス CSS の **クラスセレクター**と同様に、スタイルの適用対象をフォームオブジェクトの `class` 属性で指定することができます。 @@ -126,7 +126,7 @@ text.center { } ``` -4D フォームの詳細では、[CSSクラス](../FormObjects/properties_Object.md#cssクラス) 属性を使用してクラス名を割り当てます。この属性には一つ以上のクラス名を指定することができます。 複数の場合はクラス名を半角スペースで区切ります: +4D フォームの詳細では、[CSSクラス](../FormObjects/properties_Object.md#cssクラス) 属性を使用してクラス名を割り当てます。この属性には一つ以上のクラス名を指定することができます。複数の場合はクラス名を半角スペースで区切ります: ```css class: "okButtons important" diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/buttonGrid_overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/buttonGrid_overview.md index cade194a67e03e..2115f3afd5cba8 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/buttonGrid_overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/buttonGrid_overview.md @@ -26,11 +26,11 @@ title: ボタングリッド ボタングリッドにページ指定用の `gotoPage` [標準アクション](/Desktop/standard-actions)を割り当てることができます。この標準アクションを設定すると、4D はボタングリッドで選択されたボタンの番号に相当するフォームページを自動的に表示します。たとえばグリッド上の 10 番目のボタンを選択すると、4D は現在のフォームの 10 ページ目を表示します (存在する場合)。 -## Supported standard actions +## サポートされる標準アクション -- [gotoPage](../Desktop-legacy/standard-actions.md#gotopage): Uses the selected button number as described in [Goto page](#goto-page). +- [gotoPage](../Desktop-legacy/standard-actions.md#gotopage): [ページ指定アクション](#ページ指定アクション) の説明に従って選択されたボタン番号を使用します。 -See the [standard action compatibility table](../Desktop-legacy/standard-actions.md#supported-form-objects). +詳細については[標準アクション互換性表](../Desktop-legacy/standard-actions.md#サポートされるフォームオブジェクト) を参照してください。 ## プロパティ一覧 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/button_overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/button_overview.md index 125739531a6cfe..a39c1f0ec411f0 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/button_overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/button_overview.md @@ -332,11 +332,11 @@ Windows Classic UI テーマでは、このスタイルはサポートされま } ``` -## Supported standard actions +## サポートされる標準アクション -The following standard actions can be assigned to buttons: +ボタンには、以下の標準アクションを割り当てることができます: -### Records and forms +### レコードとフォーム - [accept](../Desktop-legacy/standard-actions.md#accept) - [cancel](../Desktop-legacy/standard-actions.md#cancel) @@ -350,7 +350,7 @@ The following standard actions can be assigned to buttons: - [nextRecord](../Desktop-legacy/standard-actions.md#nextrecord) - [previousRecord](../Desktop-legacy/standard-actions.md#previousrecord) -### Pages +### ページ - [firstPage](../Desktop-legacy/standard-actions.md#firstpage) - [lastPage](../Desktop-legacy/standard-actions.md#lastpage) @@ -358,7 +358,7 @@ The following standard actions can be assigned to buttons: - [previousPage](../Desktop-legacy/standard-actions.md#previouspage) - [gotoPage?value=\](../Desktop-legacy/standard-actions.md#gotopagevaluepage) -### Editing and expressions +### 編集と式 - [clear](../Desktop-legacy/standard-actions.md#clear) - [copy](../Desktop-legacy/standard-actions.md#copy) @@ -371,7 +371,7 @@ The following standard actions can be assigned to buttons: - [freezeExpressions](../Desktop-legacy/standard-actions.md#freezeexpressions) - [visibleReferences](../Desktop-legacy/standard-actions.md#visiblereferences) -### Formatting +### 書式設定 - [backgroundColor/showDialog](../Desktop-legacy/standard-actions.md#backgroundcolorshowdialog) - [backgroundColor?value=\](../Desktop-legacy/standard-actions.md#backgroundcolorvaluecolor) @@ -384,7 +384,7 @@ The following standard actions can be assigned to buttons: - [fontSize?value=\](../Desktop-legacy/standard-actions.md#fontsizevaluesize) - [fontUnderline](../Desktop-legacy/standard-actions.md#fontunderline) -### Spellchecking +### スペルチェック - [spell/autoCorrectionEnabled](../Desktop-legacy/standard-actions.md#spellautocorrectionenabled) - [spell/autoDashSubstitutionsEnabled](../Desktop-legacy/standard-actions.md#spellautodashsubstitutionsenabled) @@ -402,14 +402,14 @@ The following standard actions can be assigned to buttons: - [spell/unLearn](../Desktop-legacy/standard-actions.md#spellunlearn) - [spell/visibleSubstitutions](../Desktop-legacy/standard-actions.md#spellvisiblesubstitutions) -### Web-area controls +### Webエリアコントロール - [openBackURL](../Desktop-legacy/standard-actions.md#openbackurl) - [openForwardURL](../Desktop-legacy/standard-actions.md#openforwardurl) - [refreshCurrentURL](../Desktop-legacy/standard-actions.md#refreshcurrenturl) - [stopLoadingURL](../Desktop-legacy/standard-actions.md#stoploadingurl) -### Other actions +### その他のアクション - [databaseSettings](../Desktop-legacy/standard-actions.md#databasesettings) - [designMode](../Desktop-legacy/standard-actions.md#designmode) @@ -418,15 +418,15 @@ The following standard actions can be assigned to buttons: - [showClipboard](../Desktop-legacy/standard-actions.md#showclipboard) - [writingTools](../Desktop-legacy/standard-actions.md#writingtools) -### Invisible buttons only +### 非表示ボタンのみ - [automaticSplitter](../Desktop-legacy/standard-actions.md#automaticsplitter) -### 4D Write Pro standard actions +### 4D Write Pro標準アクション - [formulaHighlight?value=\](../WritePro/user-legacy/standard-actions.md#action-formulahighlight) -The [empty action](../Desktop-legacy/standard-actions.md#-empty-string) leaves the button's behavior to its method. See the [standard action compatibility table](../Desktop-legacy/standard-actions.md#supported-form-objects) for comparisons with other objects. +[empty アクション](../Desktop-legacy/standard-actions.md#-empty-string) の場合にはボタンの振る舞いはそのオブジェクトメソッドに移譲されます。他のオブジェクトとの比較のためには[標準アクション互換性表](../Desktop-legacy/standard-actions.md#サポートされるフォームオブジェクト) を参照してください。 ## プロパティ一覧 @@ -441,7 +441,7 @@ The [empty action](../Desktop-legacy/standard-actions.md#-empty-string) leaves t [カスタム](#カスタム) スタイルのボタンに対しては特有の追加のプロパティが利用可能です: -[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#境界線カラー) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [デフォルトボタン](properties_Appearance.md#デフォルトボタン) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) +[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#border-color) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [デフォルトボタン](properties_Appearance.md#デフォルトボタン) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) ### フラットおよび通常ボタンにおける追加のプロパティ diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/checkbox_overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/checkbox_overview.md index f653d44656ba03..ebeb575fa6858a 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/checkbox_overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/checkbox_overview.md @@ -348,7 +348,7 @@ Office XP スタイルのチェックボックスの反転表示と背景のカ } ``` -## Supported standard actions +## サポートされる標準アクション true/false ステータスで表すことのできるアクション ("checkable" アクション) のみがサポートされます: @@ -385,7 +385,7 @@ true/false ステータスで表すことのできるアクション ("checkable これらのアクションについての詳細は、[標準アクション](properties_Action.md#標準アクション) の章を参照してください。 -See also the [standard action compatibility table](../Desktop-legacy/standard-actions.md#supported-form-objects). +[標準アクション互換性表](../Desktop-legacy/standard-actions.md#supported-form-objects) も参照してください。 ## プロパティ一覧 @@ -400,7 +400,7 @@ See also the [standard action compatibility table](../Desktop-legacy/standard-ac [カスタム](#カスタム) スタイルのチェックボックスに対しては特有の追加のプロパティが利用可能です: -[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#境界線カラー) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) +[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#border-color) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) ### フラットおよび通常チェックボックスにおける追加のプロパティ diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/dropdownList_Overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/dropdownList_Overview.md index d7b4e2756d2794..6cf2fd2badde38 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/dropdownList_Overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/dropdownList_Overview.md @@ -163,21 +163,21 @@ Form.myDrop.index //3 > この機能は、階層型のドロップダウンリストでは使用できません。 -## Supported standard actions +## サポートされる標準アクション -The following actions are available in the drop-down list standard-action selector. See [Standard actions](../Desktop-legacy/standard-actions.md) and [4D Write Pro standard actions](../WritePro/user-legacy/standard-actions.md) for action descriptions and requirements. +ドロップダウンリストの標準アクションセレクターでは、以下の標準アクションが利用可能です。アクションの詳細と必要要件については[標準アクション](../Desktop-legacy/standard-actions.md) および[4D Write Pro 標準アクション](../WritePro/user-legacy/standard-actions.md) を参照してください。 [`gotoPage`](../Desktop-legacy/standard-actions.md#gotopage) - [`fontSize`](../Desktop-legacy/standard-actions.md#fontsize) - [`color`](../Desktop-legacy/standard-actions.md#color) - [`backgroundColor`](../WritePro/user-legacy/standard-actions.md#action-backgroundcolor) - [`textUnderlineStyle`](../WritePro/user-legacy/standard-actions.md#action-textunderlinestyle) - [`textUnderlineColor`](../WritePro/user-legacy/standard-actions.md#action-textunderlinecolor) - [`textLinethroughStyle`](../WritePro/user-legacy/standard-actions.md#action-textlinethroughstyle) - [`textLinethroughColor`](../WritePro/user-legacy/standard-actions.md#action-textlinethroughcolor) - [`textShadowOffset`](../WritePro/user-legacy/standard-actions.md#action-textshadowoffset) - [`textShadowColor`](../WritePro/user-legacy/standard-actions.md#action-textshadowcolor) - [`textTransform`](../WritePro/user-legacy/standard-actions.md#action-texttransform) - [`dpi`](../WritePro/user-legacy/standard-actions.md#action-dpi) - [`zoom`](../WritePro/user-legacy/standard-actions.md#action-zoom) - [`userUnit`](../WritePro/user-legacy/standard-actions.md#action-userunit) - [`pageMode`](../WritePro/user-legacy/standard-actions.md#action-pagemode) - [`pageSize`](../WritePro/user-legacy/standard-actions.md#action-pagesize) - [`tabDecimalSeparator`](../WritePro/user-legacy/standard-actions.md#action-tabdecimalseparator) - [`pageOrientation`](../WritePro/user-legacy/standard-actions.md#action-pageorientation) - [`section/pageOrientation`](../WritePro/user-legacy/standard-actions.md#action-pageorientation) - [`columnCount`](../WritePro/user-legacy/standard-actions.md#action-columncount) - [`section/columnCount`](../WritePro/user-legacy/standard-actions.md#action-columncount) - [`columnSpacing`](../WritePro/user-legacy/standard-actions.md#action-columnspacing) - [`section/columnSpacing`](../WritePro/user-legacy/standard-actions.md#action-columnspacing) - [`columnRuleStyle`](../WritePro/user-legacy/standard-actions.md#action-columnrulestyle) - [`section/columnRuleStyle`](../WritePro/user-legacy/standard-actions.md#action-columnrulestyle) - [`columnRuleColor`](../WritePro/user-legacy/standard-actions.md#action-columnrulecolor) - [`section/columnRuleColor`](../WritePro/user-legacy/standard-actions.md#action-columnrulecolor) - [`columnRuleWidth`](../WritePro/user-legacy/standard-actions.md#action-columnrulewidth) - [`section/columnRuleWidth`](../WritePro/user-legacy/standard-actions.md#action-columnrulewidth) - [`bookmark`](../WritePro/user-legacy/standard-actions.md#action-bookmark) - [`width`](../WritePro/user-legacy/standard-actions.md#action-width) - [`paragraph/width`](../WritePro/user-legacy/standard-actions.md#action-width) - [`image/width`](../WritePro/user-legacy/standard-actions.md#action-width) - [`column/width`](../WritePro/user-legacy/standard-actions.md#action-width) - [`image/height`](../WritePro/user-legacy/standard-actions.md#action-height) - [`row/height`](../WritePro/user-legacy/standard-actions.md#action-height) - [`minWidth`](../WritePro/user-legacy/standard-actions.md#action-minwidth) - [`paragraph/minWidth`](../WritePro/user-legacy/standard-actions.md#action-minwidth) - [`image/minWidth`](../WritePro/user-legacy/standard-actions.md#action-minwidth) - [`minHeight`](../WritePro/user-legacy/standard-actions.md#action-minheight) - [`paragraph/minHeight`](../WritePro/user-legacy/standard-actions.md#action-minheight) - [`image/minHeight`](../WritePro/user-legacy/standard-actions.md#action-minheight) - [`margin`](../WritePro/user-legacy/standard-actions.md#action-margin) - [`doc/margin`](../WritePro/user-legacy/standard-actions.md#action-margin) - [`paragraph/margin`](../WritePro/user-legacy/standard-actions.md#action-margin) - [`paragraph/inside/margin`](../WritePro/user-legacy/standard-actions.md#action-margin) - [`paragraph/outside/margin`](../WritePro/user-legacy/standard-actions.md#action-margin) - [`image/margin`](../WritePro/user-legacy/standard-actions.md#action-margin) - [`section/margin`](../WritePro/user-legacy/standard-actions.md#action-margin) - [`header/margin`](../WritePro/user-legacy/standard-actions.md#action-margin) - [`footer/margin`](../WritePro/user-legacy/standard-actions.md#action-margin) - [`table/margin`](../WritePro/user-legacy/standard-actions.md#action-margin) - [`padding`](../WritePro/user-legacy/standard-actions.md#action-padding) - [`doc/padding`](../WritePro/user-legacy/standard-actions.md#action-padding) - [`paragraph/padding`](../WritePro/user-legacy/standard-actions.md#action-padding) - [`paragraph/inside/padding`](../WritePro/user-legacy/standard-actions.md#action-padding) - [`paragraph/outside/padding`](../WritePro/user-legacy/standard-actions.md#action-padding) - [`image/padding`](../WritePro/user-legacy/standard-actions.md#action-padding) - [`section/padding`](../WritePro/user-legacy/standard-actions.md#action-padding) - [`header/padding`](../WritePro/user-legacy/standard-actions.md#action-padding) - [`footer/padding`](../WritePro/user-legacy/standard-actions.md#action-padding) - [`cell/padding`](../WritePro/user-legacy/standard-actions.md#action-padding) - [`column/padding`](../WritePro/user-legacy/standard-actions.md#action-padding) - [`doc/backgroundColor`](../WritePro/user-legacy/standard-actions.md#action-backgroundcolor) - [`paragraph/backgroundColor`](../WritePro/user-legacy/standard-actions.md#action-backgroundcolor) - [`image/backgroundColor`](../WritePro/user-legacy/standard-actions.md#action-backgroundcolor) - [`section/backgroundColor`](../WritePro/user-legacy/standard-actions.md#action-backgroundcolor) - [`header/backgroundColor`](../WritePro/user-legacy/standard-actions.md#action-backgroundcolor) - [`footer/backgroundColor`](../WritePro/user-legacy/standard-actions.md#action-backgroundcolor) - [`table/backgroundColor`](../WritePro/user-legacy/standard-actions.md#action-backgroundcolor) - [`row/backgroundColor`](../WritePro/user-legacy/standard-actions.md#action-backgroundcolor) - [`cell/backgroundColor`](../WritePro/user-legacy/standard-actions.md#action-backgroundcolor) - [`column/backgroundColor`](../WritePro/user-legacy/standard-actions.md#action-backgroundcolor) - [`backgroundPositionH`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionh) - [`doc/backgroundPositionH`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionh) - [`paragraph/backgroundPositionH`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionh) - [`image/backgroundPositionH`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionh) - [`section/backgroundPositionH`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionh) - [`header/backgroundPositionH`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionh) - [`footer/backgroundPositionH`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionh) - [`table/backgroundPositionH`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionh) - [`row/backgroundPositionH`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionh) - [`cell/backgroundPositionH`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionh) - [`column/backgroundPositionH`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionh) - [`backgroundPositionV`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionv) - [`doc/backgroundPositionV`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionv) - [`paragraph/backgroundPositionV`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionv) - [`image/backgroundPositionV`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionv) - [`section/backgroundPositionV`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionv) - [`header/backgroundPositionV`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionv) - [`footer/backgroundPositionV`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionv) - [`table/backgroundPositionV`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionv) - [`row/backgroundPositionV`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionv) - [`cell/backgroundPositionV`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionv) - [`column/backgroundPositionV`](../WritePro/user-legacy/standard-actions.md#action-backgroundpositionv) - [`backgroundRepeat`](../WritePro/user-legacy/standard-actions.md#action-backgroundrepeat) - [`doc/backgroundRepeat`](../WritePro/user-legacy/standard-actions.md#action-backgroundrepeat) - [`paragraph/backgroundRepeat`](../WritePro/user-legacy/standard-actions.md#action-backgroundrepeat) - [`image/backgroundRepeat`](../WritePro/user-legacy/standard-actions.md#action-backgroundrepeat) - [`section/backgroundRepeat`](../WritePro/user-legacy/standard-actions.md#action-backgroundrepeat) - [`header/backgroundRepeat`](../WritePro/user-legacy/standard-actions.md#action-backgroundrepeat) - [`footer/backgroundRepeat`](../WritePro/user-legacy/standard-actions.md#action-backgroundrepeat) - [`table/backgroundRepeat`](../WritePro/user-legacy/standard-actions.md#action-backgroundrepeat) - [`row/backgroundRepeat`](../WritePro/user-legacy/standard-actions.md#action-backgroundrepeat) - [`cell/backgroundRepeat`](../WritePro/user-legacy/standard-actions.md#action-backgroundrepeat) - [`column/backgroundRepeat`](../WritePro/user-legacy/standard-actions.md#action-backgroundrepeat) - [`backgroundClip`](../WritePro/user-legacy/standard-actions.md#action-backgroundclip) - [`doc/backgroundClip`](../WritePro/user-legacy/standard-actions.md#action-backgroundclip) - [`paragraph/backgroundClip`](../WritePro/user-legacy/standard-actions.md#action-backgroundclip) - [`image/backgroundClip`](../WritePro/user-legacy/standard-actions.md#action-backgroundclip) - [`section/backgroundClip`](../WritePro/user-legacy/standard-actions.md#action-backgroundclip) - [`header/backgroundClip`](../WritePro/user-legacy/standard-actions.md#action-backgroundclip) - [`table/backgroundClip`](../WritePro/user-legacy/standard-actions.md#action-backgroundclip) - [`row/backgroundClip`](../WritePro/user-legacy/standard-actions.md#action-backgroundclip) - [`cell/backgroundClip`](../WritePro/user-legacy/standard-actions.md#action-backgroundclip) - [`column/backgroundClip`](../WritePro/user-legacy/standard-actions.md#action-backgroundclip) - [`backgroundOrigin`](../WritePro/user-legacy/standard-actions.md#action-backgroundorigin) - [`doc/backgroundOrigin`](../WritePro/user-legacy/standard-actions.md#action-backgroundorigin) - [`paragraph/backgroundOrigin`](../WritePro/user-legacy/standard-actions.md#action-backgroundorigin) - [`image/backgroundOrigin`](../WritePro/user-legacy/standard-actions.md#action-backgroundorigin) - [`section/backgroundOrigin`](../WritePro/user-legacy/standard-actions.md#action-backgroundorigin) - [`header/backgroundOrigin`](../WritePro/user-legacy/standard-actions.md#action-backgroundorigin) - [`footer/backgroundOrigin`](../WritePro/user-legacy/standard-actions.md#action-backgroundorigin) - [`table/backgroundOrigin`](../WritePro/user-legacy/standard-actions.md#action-backgroundorigin) - [`row/backgroundOrigin`](../WritePro/user-legacy/standard-actions.md#action-backgroundorigin) - [`cell/backgroundOrigin`](../WritePro/user-legacy/standard-actions.md#action-backgroundorigin) - [`column/backgroundOrigin`](../WritePro/user-legacy/standard-actions.md#action-backgroundorigin) - [`backgroundSizeH`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizeh) - [`doc/backgroundSizeH`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizeh) - [`paragraph/backgroundSizeH`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizeh) - [`image/backgroundSizeH`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizeh) - [`section/backgroundSizeH`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizeh) - [`header/backgroundSizeH`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizeh) - [`footer/backgroundSizeH`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizeh) - [`table/backgroundSizeH`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizeh) - [`row/backgroundSizeH`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizeh) - [`cell/backgroundSizeH`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizeh) - [`column/backgroundSizeH`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizeh) - [`backgroundSizeV`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizev) - [`doc/backgroundSizeV`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizev) - [`paragraph/backgroundSizeV`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizev) - [`image/backgroundSizeV`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizev) - [`section/backgroundSizeV`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizev) - [`header/backgroundSizeV`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizev) - [`footer/backgroundSizeV`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizev) - [`table/backgroundSizeV`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizev) - [`row/backgroundSizeV`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizev) - [`cell/backgroundSizeV`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizev) - [`column/backgroundSizev`](../WritePro/user-legacy/standard-actions.md#action-backgroundsizev) - [`borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`doc/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`paragraph/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`paragraph/inside/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`paragraph/outside/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`image/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`section/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`header/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`footer/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`table/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`row/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`cell/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`column/borderStyle`](../WritePro/user-legacy/standard-actions.md#action-borderstyle) - [`borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`doc/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`paragraph/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`paragraph/inside/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`paragraph/outside/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`image/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`section/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`header/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`footer/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`table/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`row/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`cell/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`column/borderColor`](../WritePro/user-legacy/standard-actions.md#action-bordercolor) - [`borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth)- [`doc/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`paragraph/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`paragraph/inside/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`paragraph/outside/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`image/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`section/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`header/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`footer/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`table/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`row/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`cell/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`column/borderWidth`](../WritePro/user-legacy/standard-actions.md#action-borderwidth) - [`borderRadius`](../WritePro/user-legacy/standard-actions.md#action-borderradius) - [`doc/borderRadius`](../WritePro/user-legacy/standard-actions.md#action-borderradius) - [`paragraph/borderRadius`](../WritePro/user-legacy/standard-actions.md#action-borderradius) - [`image/borderRadius`](../WritePro/user-legacy/standard-actions.md#action-borderradius) - [`section/borderRadius`](../WritePro/user-legacy/standard-actions.md#action-borderradius) - [`header/borderRadius`](../WritePro/user-legacy/standard-actions.md#action-borderradius) - [`footer/borderRadius`](../WritePro/user-legacy/standard-actions.md#action-borderradius) - [`direction`](../WritePro/user-legacy/standard-actions.md#action-direction) - [`textAlign`](../WritePro/user-legacy/standard-actions.md#action-textalign) - [`lineHeight`](../WritePro/user-legacy/standard-actions.md#action-lineheight) - [`listStyleType`](../WritePro/user-legacy/standard-actions.md#action-liststyletype) - [`listStartNumber`](../WritePro/user-legacy/standard-actions.md#action-liststartnumber) - [`listNumberFormat`](../WritePro/user-legacy/standard-actions.md#action-listnumberformat) - [`textIndent`](../WritePro/user-legacy/standard-actions.md#action-textindent) - [`verticalAlign`](../WritePro/user-legacy/standard-actions.md#action-verticalalign) - [`image/verticalAlign`](../WritePro/user-legacy/standard-actions.md#action-image-verticalalign) - [`cell/verticalAlign`](../WritePro/user-legacy/standard-actions.md#action-verticalalign) - [`column/verticalAlign`](../WritePro/user-legacy/standard-actions.md#action-verticalalign) - [`tableAlign`](../WritePro/user-legacy/standard-actions.md#action-tablealign) - [`table/tableAlign`](../WritePro/user-legacy/standard-actions.md#action-tablealign) - [`emptyDatasource`](../WritePro/user-legacy/standard-actions.md#action-emptydatasource) - [`table/emptyDatasource`](../WritePro/user-legacy/standard-actions.md#action-emptydatasource) - [`styleSheet`](../WritePro/user-legacy/standard-actions.md#action-stylesheet) - [`paragraph/styleSheet`](../WritePro/user-legacy/standard-actions.md#action-stylesheet) - [`image/styleSheet`](../WritePro/user-legacy/standard-actions.md#action-stylesheet) - [`newLineStyleSheet`](../WritePro/user-legacy/standard-actions.md#action-newlinestylesheet) - [`anchorLayout`](../WritePro/user-legacy/standard-actions.md#action-anchorlayout) - [`anchorHorizontalAlign`](../WritePro/user-legacy/standard-actions.md#action-anchorhorizontalalign) - [`anchorVerticalAlign`](../WritePro/user-legacy/standard-actions.md#action-anchorverticalalign) - [`anchorOrigin`](../WritePro/user-legacy/standard-actions.md#action-anchororigin) - [`anchorSection`](../WritePro/user-legacy/standard-actions.md#action-anchorsection) - [`anchorPage`](../WritePro/user-legacy/standard-actions.md#action-anchorpage) - [`image/displayMode`](../WritePro/user-legacy/standard-actions.md#action-image-displaymode) - [`backgroundDisplayMode`](../WritePro/user-legacy/standard-actions.md#action-backgrounddisplaymode) - [`doc/backgroundDisplayMode`](../WritePro/user-legacy/standard-actions.md#action-backgrounddisplaymode) - [`paragraph/backgroundDisplayMode`](../WritePro/user-legacy/standard-actions.md#action-backgrounddisplaymode) - [`image/backgroundDisplayMode`](../WritePro/user-legacy/standard-actions.md#action-backgrounddisplaymode) - [`section/backgroundDisplayMode`](../WritePro/user-legacy/standard-actions.md#action-backgrounddisplaymode) - [`header/backgroundDisplayMode`](../WritePro/user-legacy/standard-actions.md#action-backgrounddisplaymode) - [`footer/backgroundDisplayMode`](../WritePro/user-legacy/standard-actions.md#action-backgrounddisplaymode) - [`table/backgroundDisplayMode`](../WritePro/user-legacy/standard-actions.md#action-backgrounddisplaymode) - [`row/backgroundDisplayMode`](../WritePro/user-legacy/standard-actions.md#action-backgrounddisplaymode) - [`cell/backgroundDisplayMode`](../WritePro/user-legacy/standard-actions.md#action-backgrounddisplaymode) - [`column/backgroundDisplayMode`](../WritePro/user-legacy/standard-actions.md#action-backgrounddisplaymode) - [`formulaHighlight`](../WritePro/user-legacy/standard-actions.md#action-formulahighlight) - [`formulaHighlightColor`](../WritePro/user-legacy/standard-actions.md#action-formulahighlightcolor) - [`headerRowCount`](../WritePro/user-legacy/standard-actions.md#action-headerrowcount) :::note -For automatic text-formatting lists, see [Using a standard action](#using-a-standard-action) for target-area and focus requirements, and the restriction on hierarchical drop-down lists. The text-formatting target-area and focus requirements do not apply to `gotoPage`. +リストの自動テキスト書式設定に関しては、階層ドロップダウンリストの使用可能エリア、フォーカス要件、および制約については[標準アクションの使用](#標準アクションの使用) を参照してください。テキスト書式設定ターゲットエリアとフォーカス要件は、`gotoPage` に関しては適用されません。 -Actions assigned to individual choice-list items are separate from the action assigned to the drop-down list. +個別の選択リスト項目に割り当てられたアクションは、ドロップダウンリストに割り当てられたアクションとは異なります。 ::: -See the [standard action compatibility table](../Desktop-legacy/standard-actions.md#supported-form-objects). +詳細については[標準アクション互換性表](../Desktop-legacy/standard-actions.md#サポートされるフォームオブジェクト) を参照してください。 ## プロパティ一覧 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/list_overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/list_overview.md index fd94cf34329db2..34b81a7fb41886 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/list_overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/list_overview.md @@ -145,7 +145,7 @@ SET LIST ITEM FONT(*;"mylist1";*;thefont) ## プロパティ一覧 -[タイプ](properties_Object.md#タイプ) - [オブジェクト名](properties_Object.md#オブジェクト名) - [変数あるいは式](properties_Object.md#変数あるいは式) - [CSSクラス](properties_Object.md#cssクラス) - [左](properties_CoordinatesAndSizing.md#左) - [上](properties_CoordinatesAndSizing.md#上) - [右](properties_CoordinatesAndSizing.md#右) - [下](properties_CoordinatesAndSizing.md#下) - [幅](properties_CoordinatesAndSizing.md#幅) - [高さ](properties_CoordinatesAndSizing.md#高さ) - [横方向サイズ変更](properties_ResizingOptions.md#横方向サイズ変更) - [縦方向サイズ変更](properties_ResizingOptions.md#縦方向サイズ変更) - [入力可](properties_Entry.md#入力可) - [フォーカス可](properties_Entry.md#フォーカス可) - [選択リスト](properties_DataSource.md#選択リスト) - [フォーカス可](properties_Entry.md#フォーカス可) - [表示状態](properties_Display.md#表示状態) - [フォーカスの四角を隠す](properties_Appearance.md#フォーカスの四角を隠す) - [横スクロールバー](properties_Appearance.md#横スクロールバー) - [縦スクロールバー](properties_Appearance.md#縦スクロールバー) - [塗りカラー](properties_BackgroundAndBorder.md#背景色-塗りカラー) - [境界線カラー](./properties_BackgroundAndBorder.md#境界線カラー) - [境界線スタイル](properties_BackgroundAndBorder.md#border-line-style) - [フォント](properties_Text.md#フォント) - [フォントサイズ](properties_Text.md#フォントサイズ) - [太字](properties_Text.md#太字) - [イタリック](properties_Text.md#イタリック) - [下線](properties_Text.md#下線) - [フォントカラー](properties_Text.md#フォントカラー) - [ドラッグ有効](properties_Action.md#ドラッグ有効) - [ドロップ有効](properties_Action.md#ドロップ有効) - [複数選択可](properties_Action.md#複数選択可) - [ヘルプTips](properties_Help.md#ヘルプtips) +[タイプ](properties_Object.md#タイプ) - [オブジェクト名](properties_Object.md#オブジェクト名) - [変数あるいは式](properties_Object.md#変数あるいは式) - [CSSクラス](properties_Object.md#cssクラス) - [左](properties_CoordinatesAndSizing.md#左) - [上](properties_CoordinatesAndSizing.md#上) - [右](properties_CoordinatesAndSizing.md#右) - [下](properties_CoordinatesAndSizing.md#下) - [幅](properties_CoordinatesAndSizing.md#幅) - [高さ](properties_CoordinatesAndSizing.md#高さ) - [横方向サイズ変更](properties_ResizingOptions.md#横方向サイズ変更) - [縦方向サイズ変更](properties_ResizingOptions.md#縦方向サイズ変更) - [入力可](properties_Entry.md#入力可) - [フォーカス可](properties_Entry.md#フォーカス可) - [選択リスト](properties_DataSource.md#選択リスト) - [フォーカス可](properties_Entry.md#フォーカス可) - [表示状態](properties_Display.md#表示状態) - [フォーカスの四角を隠す](properties_Appearance.md#フォーカスの四角を隠す) - [横スクロールバー](properties_Appearance.md#横スクロールバー) - [縦スクロールバー](properties_Appearance.md#縦スクロールバー) - [塗りカラー](properties_BackgroundAndBorder.md#背景色-塗りカラー) - [境界線カラー](./properties_BackgroundAndBorder.md#border-color) - [境界線スタイル](properties_BackgroundAndBorder.md#border-line-style) - [フォント](properties_Text.md#フォント) - [フォントサイズ](properties_Text.md#フォントサイズ) - [太字](properties_Text.md#太字) - [イタリック](properties_Text.md#イタリック) - [下線](properties_Text.md#下線) - [フォントカラー](properties_Text.md#フォントカラー) - [ドラッグ有効](properties_Action.md#ドラッグ有効) - [ドロップ有効](properties_Action.md#ドロップ有効) - [複数選択可](properties_Action.md#複数選択可) - [ヘルプTips](properties_Help.md#ヘルプtips) ## サポートされるイベント diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/listbox-object.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/listbox-object.md index 2c463b8f4c585d..76955e48d4ce6d 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/listbox-object.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/listbox-object.md @@ -53,13 +53,13 @@ LIST TO ARRAY("ListName";varCol) myCol:=myCol.push("new value") // リストボックスに new value を表示 ``` -## Supported standard actions +## サポートされる標準アクション -- [gotoPage](../Desktop-legacy/standard-actions.md#gotopage): Available for array list boxes; see the [supported properties by list box type](#supported-properties). +- [gotoPage](../Desktop-legacy/standard-actions.md#gotopage): 配列型リストボックスに対して利用可能です。詳細は[リストボックス型ごとにサポートされるプロパティ](#プロパティ一覧) を参照してください。 -The [addSubrecord](../Desktop-legacy/standard-actions.md#addsubrecord), [deleteSubrecord](../Desktop-legacy/standard-actions.md#deletesubrecord), [displaySubrecord](../Desktop-legacy/standard-actions.md#displaysubrecord), and [editSubrecord](../Desktop-legacy/standard-actions.md#editsubrecord) actions can affect selection list boxes, but are assigned to buttons or menu commands, not to the selection list box itself. +[addSubrecord](../Desktop-legacy/standard-actions.md#addsubrecord)、 [deleteSubrecord](../Desktop-legacy/standard-actions.md#deletesubrecord)、 [displaySubrecord](../Desktop-legacy/standard-actions.md#displaysubrecord)、および [editSubrecord](../Desktop-legacy/standard-actions.md#editsubrecord) アクションはセレクション型リストボックスに影響をおよぼす可能性がありますが、これらはボタンまたはメニューコマンドに対して割り当てられるもので、セレクション型リストボックス自体に割り当てられるものではありません。 -See the [standard action compatibility table](../Desktop-legacy/standard-actions.md#supported-form-objects). +詳細については[標準アクション互換性表](../Desktop-legacy/standard-actions.md#サポートされるフォームオブジェクト) を参照してください。 ## プロパティ一覧 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/pictureButton_overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/pictureButton_overview.md index 33926b9b43accd..576b34ab592035 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/pictureButton_overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/pictureButton_overview.md @@ -58,15 +58,15 @@ title: ピクチャーボタン > ピクチャーボタンに [関連付けた変数](properties_Object.md#変数あるいは式) は、ピクチャーのサムネールテーブルで現在表示されているピクチャーのインデックス番号を返します。このテーブル内のピクチャー番号は 0 から始まります。 -## Supported standard actions +## サポートされる標準アクション -Picture buttons support the same [standard actions as buttons](button_overview.md#supported-standard-actions), except for actions restricted to a specific button style, such as [automaticSplitter](../Desktop-legacy/standard-actions.md#automaticsplitter) for invisible buttons. Assign an action using the [Standard action property](properties_Action.md#standard-action). +ピクチャーボタンは[ボタンと同じ標準アクション](button_overview.md#サポートされる標準アクション) と同じアクションをサポートしますが、非表示ボタンにおける[automaticSplitter](../Desktop-legacy/standard-actions.md#automaticsplitter) など、特定のボタンスタイルでのみ使用可能なアクションを除きます。[標準アクションプロパティ](properties_Action.md#標準アクション) を使用して標準アクションを割り当てます。 -For action descriptions and activation conditions, see [Standard actions](../Desktop-legacy/standard-actions.md#available-actions). See also the [standard action compatibility table](../Desktop-legacy/standard-actions.md#supported-form-objects). +アクションの詳細と有効化条件については、[標準アクション](../Desktop-legacy/standard-actions.md#利用可能なアクション) を参照してください。[標準アクション互換性表](../Desktop-legacy/standard-actions.md#supported-form-objects) も参照してください。 ## プロパティ一覧 -[タイプ](properties_Object.md#タイプ) - [オブジェクト名](properties_Object.md#オブジェクト名) - [変数あるいは式](properties_Object.md#変数あるいは式) - [タイトル](properties_Object.md#タイトル) - [CSSクラス](properties_Object.md#cssクラス) - [ボタンスタイル](properties_TextAndPicture.md#ボタンスタイル) - [パス名](properties_Picture.md#パス名) - [マウス押下中は自動更新](properties_Animation.md#マウス押下中は自動更新) - [先頭フレームに戻る](properties_Animation.md#先頭フレームに戻る) - [ロールオーバー効果](properties_Animation.md#ロールオーバー効果) - [無効時に最終フレームを使用](properties_Animation.md#無効時に最終フレームを使用) - [アニメーション間隔 (tick)](properties_Animation.md#アニメーション間隔-tick) - [行](properties_Crop.md#行) - [列](properties_Crop.md#列) - [左](properties_CoordinatesAndSizing.md#左) - [上](properties_CoordinatesAndSizing.md#上) - [右](properties_CoordinatesAndSizing.md#右) - [下](properties_CoordinatesAndSizing.md#下) - [幅](properties_CoordinatesAndSizing.md#幅) - [高さ](properties_CoordinatesAndSizing.md#高さ) - [横方向サイズ変更](properties_ResizingOptions.md#横方向サイズ変更) - [縦方向サイズ変更](properties_ResizingOptions.md#縦方向サイズ変更) - [ショートカット](properties_Entry.md#ショートカット) - [フォーカス可](properties_Entry.md#フォーカス可) - [表示状態](properties_Display.md#表示状態) - [境界線カラー](./properties_BackgroundAndBorder.md#境界線カラー) - [境界線スタイル](properties_BackgroundAndBorder.md#border-line-style) - [イタリック](properties_Text.md#イタリック) - [ヘルプTips](properties_Help.md#ヘルプtips) - [標準アクション](properties_Action.md#標準アクション) +[タイプ](properties_Object.md#タイプ) - [オブジェクト名](properties_Object.md#オブジェクト名) - [変数あるいは式](properties_Object.md#変数あるいは式) - [タイトル](properties_Object.md#タイトル) - [CSSクラス](properties_Object.md#cssクラス) - [ボタンスタイル](properties_TextAndPicture.md#ボタンスタイル) - [パス名](properties_Picture.md#パス名) - [マウス押下中は自動更新](properties_Animation.md#マウス押下中は自動更新) - [先頭フレームに戻る](properties_Animation.md#先頭フレームに戻る) - [ロールオーバー効果](properties_Animation.md#ロールオーバー効果) - [無効時に最終フレームを使用](properties_Animation.md#無効時に最終フレームを使用) - [アニメーション間隔 (tick)](properties_Animation.md#アニメーション間隔-tick) - [行](properties_Crop.md#行) - [列](properties_Crop.md#列) - [左](properties_CoordinatesAndSizing.md#左) - [上](properties_CoordinatesAndSizing.md#上) - [右](properties_CoordinatesAndSizing.md#右) - [下](properties_CoordinatesAndSizing.md#下) - [幅](properties_CoordinatesAndSizing.md#幅) - [高さ](properties_CoordinatesAndSizing.md#高さ) - [横方向サイズ変更](properties_ResizingOptions.md#横方向サイズ変更) - [縦方向サイズ変更](properties_ResizingOptions.md#縦方向サイズ変更) - [ショートカット](properties_Entry.md#ショートカット) - [フォーカス可](properties_Entry.md#フォーカス可) - [表示状態](properties_Display.md#表示状態) - [境界線カラー](./properties_BackgroundAndBorder.md#border-color) - [境界線スタイル](properties_BackgroundAndBorder.md#border-line-style) - [イタリック](properties_Text.md#イタリック) - [ヘルプTips](properties_Help.md#ヘルプtips) - [標準アクション](properties_Action.md#標準アクション) ## サポートされるイベント diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/picturePopupMenu_overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/picturePopupMenu_overview.md index 6fb07ff3be640f..22a1f0df90bb26 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/picturePopupMenu_overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/picturePopupMenu_overview.md @@ -21,13 +21,13 @@ title: ピクチャーポップアップメニュー たとえば、ユーザーが3番目の要素をクリックすると、4D はカレントフォームの 3ページ目 (存在する場合) を表示します。クリックをプログラムから管理したい場合は "動作なし" を選択します。 -## Supported standard actions +## サポートされる標準アクション -The following standard actions are available for picture pop-up menus. See [Standard actions](../Desktop-legacy/standard-actions.md) for descriptions and activation conditions. +ピクチャーポップアップメニューにおいては以下の標準アクションが利用可能です。アクションの詳細と有効化条件については[標準アクション](../Desktop-legacy/standard-actions.md) を参照してください。 -[`cancel`](../Desktop-legacy/standard-actions.md#cancel) - [`accept`](../Desktop-legacy/standard-actions.md#accept) - [`nextRecord`](../Desktop-legacy/standard-actions.md#nextrecord) - [`previousRecord`](../Desktop-legacy/standard-actions.md#previousrecord) - [`firstRecord`](../Desktop-legacy/standard-actions.md#firstrecord) - [`lastRecord`](../Desktop-legacy/standard-actions.md#lastrecord) - [`deleteRecord`](../Desktop-legacy/standard-actions.md#deleterecord) - [`nextPage`](../Desktop-legacy/standard-actions.md#nextpage) - [`previousPage`](../Desktop-legacy/standard-actions.md#previouspage) - [`firstPage`](../Desktop-legacy/standard-actions.md#firstpage) - [`lastPage`](../Desktop-legacy/standard-actions.md#lastpage) - [`editSubrecord`](../Desktop-legacy/standard-actions.md#editsubrecord) - [`displaySubrecord`](../Desktop-legacy/standard-actions.md#displaysubrecord) - [`deleteSubrecord`](../Desktop-legacy/standard-actions.md#deletesubrecord) - `addSublist` - [`addSubrecord`](../Desktop-legacy/standard-actions.md#addsubrecord) - [`undo`](../Desktop-legacy/standard-actions.md#undo) - [`redo`](../Desktop-legacy/standard-actions.md#redo) - [`cut`](../Desktop-legacy/standard-actions.md#cut) - [`copy`](../Desktop-legacy/standard-actions.md#copy) - [`paste`](../Desktop-legacy/standard-actions.md#paste) - [`clear`](../Desktop-legacy/standard-actions.md#clear) - [`selectAll`](../Desktop-legacy/standard-actions.md#selectall) - [`showClipboard`](../Desktop-legacy/standard-actions.md#showclipboard) - [`design`](../Desktop-legacy/standard-actions.md#designmode) - [`databaseSettings`](../Desktop-legacy/standard-actions.md#databasesettings) - `userMode` - [`quit`](../Desktop-legacy/standard-actions.md#quit) - `duplicate` - [`msc`](../Desktop-legacy/standard-actions.md#msc) - [`openBackURL`](../Desktop-legacy/standard-actions.md#openbackurl) - [`openForwardURL`](../Desktop-legacy/standard-actions.md#openforwardurl) - [`refreshCurrentURL`](../Desktop-legacy/standard-actions.md#refreshcurrenturl) - [`stopLoadingURL`](../Desktop-legacy/standard-actions.md#stoploadingurl) - [`font/showDialog`](../Desktop-legacy/standard-actions.md#fontshowdialog) - [`spell/grammarEnabled`](../Desktop-legacy/standard-actions.md#spellgrammarenabled) - [`spell/autoDashSubstitutionsEnabled`](../Desktop-legacy/standard-actions.md#spellautodashsubstitutionsenabled) - [`spell/autoQuoteSubstitutionsEnabled`](../Desktop-legacy/standard-actions.md#spellautoquotesubstitutionsenabled) - [`spell/autoLanguageEnabled`](../Desktop-legacy/standard-actions.md#spellautolanguageenabled) - [`computeExpressions`](../Desktop-legacy/standard-actions.md#computeexpressions) - [`freezeExpressions`](../Desktop-legacy/standard-actions.md#freezeexpressions) - [`writingTools`](../Desktop-legacy/standard-actions.md#writingtools) - [`spell/removeSubstitutions`](../Desktop-legacy/standard-actions.md#spellremovesubstitution) - [`spell/learn`](../Desktop-legacy/standard-actions.md#spelllearn) - [`spell/unLearn`](../Desktop-legacy/standard-actions.md#spellunlearn) - [`spell/ignore`](../Desktop-legacy/standard-actions.md#spellignore) - [`spell/forgetIgnore`](../Desktop-legacy/standard-actions.md#spellforgetignore) - [`spell/showDialog`](../Desktop-legacy/standard-actions.md#spellshowdialog) - [`insertSoftHyphen`](../WritePro/user-legacy/standard-actions.md#action-insertsofthyphen) - [`removeSoftHyphens`](../WritePro/user-legacy/standard-actions.md#action-removesofthyphens) - [`insertImage`](../WritePro/user-legacy/standard-actions.md#action-insertimage) - [`insertPageBreak`](../WritePro/user-legacy/standard-actions.md#action-insertpagebreak) - [`insertSectionBreak`](../WritePro/user-legacy/standard-actions.md#action-insertsectionbreak) - [`insertContinuousSectionBreak`](../WritePro/user-legacy/standard-actions.md#action-insertcontinuoussectionbreak) - [`insertColumnBreak`](../WritePro/user-legacy/standard-actions.md#action-insertcolumnbreak) - [`insertTextBox`](../WritePro/user-legacy/standard-actions.md#action-inserttextbox) - [`textBox/remove`](../WritePro/user-legacy/standard-actions.md#action-textbox-remove) - [`listLevelInc`](../WritePro/user-legacy/standard-actions.md#action-listlevelinc) - [`listLevelDec`](../WritePro/user-legacy/standard-actions.md#action-listleveldec) - [`listLevelAppend`](../WritePro/user-legacy/standard-actions.md#action-listlevelappend) - [`insertRowAbove`](../WritePro/user-legacy/standard-actions.md#action-insertrowabove) - [`insertRowBelow`](../WritePro/user-legacy/standard-actions.md#action-insertrowbelow) - [`insertColumnToTheLeft`](../WritePro/user-legacy/standard-actions.md#action-insertcolumntotheleft) - [`insertColumnToTheRight`](../WritePro/user-legacy/standard-actions.md#action-insertcolumntotheright) - [`deleteRows`](../WritePro/user-legacy/standard-actions.md#action-deleterows) - [`deleteColumns`](../WritePro/user-legacy/standard-actions.md#action-deletecolumns) - [`cell/merge`](../WritePro/user-legacy/standard-actions.md#action-merge) - [`cell/split`](../WritePro/user-legacy/standard-actions.md#action-split) - [`refreshImages`](../WritePro/user-legacy/standard-actions.md#action-refreshimages) - [`print`](../WritePro/user-legacy/standard-actions.md#action-print) - [`merge`](../WritePro/user-legacy/standard-actions.md#action-merge) - [`split`](../WritePro/user-legacy/standard-actions.md#action-split) - [`borderCollapse`](../WritePro/user-legacy/standard-actions.md#action-bordercollapse) - [`section/name/showDialog`](../WritePro/user-legacy/standard-actions.md#action-section-nameshowdialog) - [`header/remove`](../WritePro/user-legacy/standard-actions.md#action-header-remove) - [`footer/remove`](../WritePro/user-legacy/standard-actions.md#action-footer-remove) - [`backgroundColor/showDialog`](../Desktop-legacy/standard-actions.md#backgroundcolorshowdialog) - [`section/remove`](../WritePro/user-legacy/standard-actions.md#action-section-remove) - [`moveToFront`](../WritePro/user-legacy/standard-actions.md#action-movetofront) - [`moveToBack`](../WritePro/user-legacy/standard-actions.md#action-movetoback) - [`gotoPage`](../Desktop-legacy/standard-actions.md#gotopage). +[`cancel`](../Desktop-legacy/standard-actions.md#cancel) - [`accept`](../Desktop-legacy/standard-actions.md#accept) - [`nextRecord`](../Desktop-legacy/standard-actions.md#nextrecord) - [`previousRecord`](../Desktop-legacy/standard-actions.md#previousrecord) - [`firstRecord`](../Desktop-legacy/standard-actions.md#firstrecord) - [`lastRecord`](../Desktop-legacy/standard-actions.md#lastrecord) - [`deleteRecord`](../Desktop-legacy/standard-actions.md#deleterecord) - [`nextPage`](../Desktop-legacy/standard-actions.md#nextpage) - [`previousPage`](../Desktop-legacy/standard-actions.md#previouspage) - [`firstPage`](../Desktop-legacy/standard-actions.md#firstpage) - [`lastPage`](../Desktop-legacy/standard-actions.md#lastpage) - [`editSubrecord`](../Desktop-legacy/standard-actions.md#editsubrecord) - [`displaySubrecord`](../Desktop-legacy/standard-actions.md#displaysubrecord) - [`deleteSubrecord`](../Desktop-legacy/standard-actions.md#deletesubrecord) - `addSublist` - [`addSubrecord`](../Desktop-legacy/standard-actions.md#addsubrecord) - [`undo`](../Desktop-legacy/standard-actions.md#undo) - [`redo`](../Desktop-legacy/standard-actions.md#redo) - [`cut`](../Desktop-legacy/standard-actions.md#cut) - [`copy`](../Desktop-legacy/standard-actions.md#copy) - [`paste`](../Desktop-legacy/standard-actions.md#paste) - [`clear`](../Desktop-legacy/standard-actions.md#clear) - [`selectAll`](../Desktop-legacy/standard-actions.md#selectall) - [`showClipboard`](../Desktop-legacy/standard-actions.md#showclipboard) - [`design`](../Desktop-legacy/standard-actions.md#designmode) - [`databaseSettings`](../Desktop-legacy/standard-actions.md#databasesettings) - `userMode` - [`quit`](../Desktop-legacy/standard-actions.md#quit) - `duplicate` - [`msc`](../Desktop-legacy/standard-actions.md#msc) - [`openBackURL`](../Desktop-legacy/standard-actions.md#openbackurl) - [`openForwardURL`](../Desktop-legacy/standard-actions.md#openforwardurl) - [`refreshCurrentURL`](../Desktop-legacy/standard-actions.md#refreshcurrenturl) - [`stopLoadingURL`](../Desktop-legacy/standard-actions.md#stoploadingurl) - [`font/showDialog`](../Desktop-legacy/standard-actions.md#fontshowdialog) - [`spell/grammarEnabled`](../Desktop-legacy/standard-actions.md#spellgrammarenabled) - [`spell/autoDashSubstitutionsEnabled`](../Desktop-legacy/standard-actions.md#spellautodashsubstitutionsenabled) - [`spell/autoQuoteSubstitutionsEnabled`](../Desktop-legacy/standard-actions.md#spellautoquotesubstitutionsenabled) - [`spell/autoLanguageEnabled`](../Desktop-legacy/standard-actions.md#spellautolanguageenabled) - [`computeExpressions`](../Desktop-legacy/standard-actions.md#computeexpressions) - [`freezeExpressions`](../Desktop-legacy/standard-actions.md#freezeexpressions) - [`writingTools`](../Desktop-legacy/standard-actions.md#writingtools) - [`spell/removeSubstitutions`](../Desktop-legacy/standard-actions.md#spellremovesubstitution) - [`spell/learn`](../Desktop-legacy/standard-actions.md#spelllearn) - [`spell/unLearn`](../Desktop-legacy/standard-actions.md#spellunlearn) - [`spell/ignore`](../Desktop-legacy/standard-actions.md#spellignore) - [`spell/forgetIgnore`](../Desktop-legacy/standard-actions.md#spellforgetignore) - [`spell/showDialog`](../Desktop-legacy/standard-actions.md#spellshowdialog) - [`insertSoftHyphen`](../WritePro/user-legacy/standard-actions.md#action-insertsofthyphen) - [`removeSoftHyphens`](../WritePro/user-legacy/standard-actions.md#action-removesofthyphens) - [`insertImage`](../WritePro/user-legacy/standard-actions.md#action-insertimage) - [`insertPageBreak`](../WritePro/user-legacy/standard-actions.md#action-insertpagebreak) - [`insertSectionBreak`](../WritePro/user-legacy/standard-actions.md#action-insertsectionbreak) - [`insertContinuousSectionBreak`](../WritePro/user-legacy/standard-actions.md#action-insertcontinuoussectionbreak) - [`insertColumnBreak`](../WritePro/user-legacy/standard-actions.md#action-insertcolumnbreak) - [`insertTextBox`](../WritePro/user-legacy/standard-actions.md#action-inserttextbox) - [`textBox/remove`](../WritePro/user-legacy/standard-actions.md#action-textbox-remove) - [`listLevelInc`](../WritePro/user-legacy/standard-actions.md#action-listlevelinc) - [`listLevelDec`](../WritePro/user-legacy/standard-actions.md#action-listleveldec) - [`listLevelAppend`](../WritePro/user-legacy/standard-actions.md#action-listlevelappend) - [`insertRowAbove`](../WritePro/user-legacy/standard-actions.md#action-insertrowabove) - [`insertRowBelow`](../WritePro/user-legacy/standard-actions.md#action-insertrowbelow) - [`insertColumnToTheLeft`](../WritePro/user-legacy/standard-actions.md#action-insertcolumntotheleft) - [`insertColumnToTheRight`](../WritePro/user-legacy/standard-actions.md#action-insertcolumntotheright) - [`deleteRows`](../WritePro/user-legacy/standard-actions.md#action-deleterows) - [`deleteColumns`](../WritePro/user-legacy/standard-actions.md#action-deletecolumns) - [`cell/merge`](../WritePro/user-legacy/standard-actions.md#action-merge) - [`cell/split`](../WritePro/user-legacy/standard-actions.md#action-split) - [`refreshImages`](../WritePro/user-legacy/standard-actions.md#action-refreshimages) - [`print`](../WritePro/user-legacy/standard-actions.md#action-print) - [`merge`](../WritePro/user-legacy/standard-actions.md#action-merge) - [`split`](../WritePro/user-legacy/standard-actions.md#action-split) - [`borderCollapse`](../WritePro/user-legacy/standard-actions.md#action-bordercollapse) - [`section/name/showDialog`](../WritePro/user-legacy/standard-actions.md#action-section-nameshowdialog) - [`header/remove`](../WritePro/user-legacy/standard-actions.md#action-header-remove) - [`footer/remove`](../WritePro/user-legacy/standard-actions.md#action-footer-remove) - [`backgroundColor/showDialog`](../Desktop-legacy/standard-actions.md#backgroundcolorshowdialog) - [`section/remove`](../WritePro/user-legacy/standard-actions.md#action-section-remove) - [`moveToFront`](../WritePro/user-legacy/standard-actions.md#action-movetofront) - [`moveToBack`](../WritePro/user-legacy/standard-actions.md#action-movetoback) - [`gotoPage`](../Desktop-legacy/standard-actions.md#gotopage) -See the [standard action compatibility table](../Desktop-legacy/standard-actions.md#supported-form-objects). +詳細については[標準アクション互換性表](../Desktop-legacy/standard-actions.md#サポートされるフォームオブジェクト) を参照してください。 ## プロパティ一覧 @@ -47,7 +47,7 @@ See the [standard action compatibility table](../Desktop-legacy/standard-actions [横方向サイズ変更](properties_ResizingOptions.md#横方向サイズ変更) - [縦方向サイズ変更](properties_ResizingOptions.md#縦方向サイズ変更) - [表示状態](properties_Display.md#表示状態) - -[境界線カラー](./properties_BackgroundAndBorder.md#境界線カラー) - +[境界線カラー](./properties_BackgroundAndBorder.md#border-color) - [境界線スタイル](properties_BackgroundAndBorder.md#境界線スタイル) - [太字](properties_Text.md#太字) - [ヘルプTips](properties_Help.md#ヘルプtips) - diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/pluginArea_overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/pluginArea_overview.md index 9637bfb4d8e6ce..2e7f7f6b0566a3 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/pluginArea_overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/pluginArea_overview.md @@ -19,7 +19,7 @@ title: プラグインエリア ## プロパティ一覧 -[タイプ](properties_Object.md#タイプ) - [プラグインの種類](properties_Object.md#プラグインの種類) - [オブジェクト名](properties_Object.md#オブジェクト名) - [変数あるいは式](properties_Object.md#変数あるいは式) - [式の型](properties_Object.md#式の型式タイプ) - [CSSクラス](properties_Object.md#cssクラス) - [左](properties_CoordinatesAndSizing.md#左) - [上](properties_CoordinatesAndSizing.md#上) - [右](properties_CoordinatesAndSizing.md#右) - [下](properties_CoordinatesAndSizing.md#下) - [幅](properties_CoordinatesAndSizing.md#幅) - [高さ](properties_CoordinatesAndSizing.md#高さ) - [横方向サイズ変更](properties_ResizingOptions.md#横方向サイズ変更) - [縦方向サイズ変更](properties_ResizingOptions.md#縦方向サイズ変更) - [フォーカス可](properties_Entry.md#フォーカス可) - [表示状態](properties_Display.md#表示状態) - [境界線カラー](./properties_BackgroundAndBorder.md#境界線カラー) - [境界線スタイル](properties_BackgroundAndBorder.md#border-line-style) - [詳細設定](properties_Plugins.md) - [ドラッグ有効](properties_Action.md#ドラッグ有効) - [ドロップ有効](properties_Action.md#ドロップ有効) - [メソッド](properties_Action.md#メソッド) +[タイプ](properties_Object.md#タイプ) - [プラグインの種類](properties_Object.md#プラグインの種類) - [オブジェクト名](properties_Object.md#オブジェクト名) - [変数あるいは式](properties_Object.md#変数あるいは式) - [式の型](properties_Object.md#式の型式タイプ) - [CSSクラス](properties_Object.md#cssクラス) - [左](properties_CoordinatesAndSizing.md#左) - [上](properties_CoordinatesAndSizing.md#上) - [右](properties_CoordinatesAndSizing.md#右) - [下](properties_CoordinatesAndSizing.md#下) - [幅](properties_CoordinatesAndSizing.md#幅) - [高さ](properties_CoordinatesAndSizing.md#高さ) - [横方向サイズ変更](properties_ResizingOptions.md#横方向サイズ変更) - [縦方向サイズ変更](properties_ResizingOptions.md#縦方向サイズ変更) - [フォーカス可](properties_Entry.md#フォーカス可) - [表示状態](properties_Display.md#表示状態) - [境界線カラー](./properties_BackgroundAndBorder.md#border-color) - [境界線スタイル](properties_BackgroundAndBorder.md#border-line-style) - [詳細設定](properties_Plugins.md) - [ドラッグ有効](properties_Action.md#ドラッグ有効) - [ドロップ有効](properties_Action.md#ドロップ有効) - [メソッド](properties_Action.md#メソッド) ## サポートされるイベント diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/progressIndicator.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/progressIndicator.md index b00234de9ddf83..4bcdcd59a4503e 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/progressIndicator.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/progressIndicator.md @@ -62,7 +62,7 @@ title: 進捗インジケーター [入力可](properties_Entry.md#入力可) - [数値フォーマット](properties_Display.md#数値フォーマット) - [表示状態](properties_Display.md#表示状態) - -[境界線カラー](./properties_BackgroundAndBorder.md#境界線カラー) - +[境界線カラー](./properties_BackgroundAndBorder.md#border-color) - [境界線スタイル](properties_BackgroundAndBorder.md#border-line-style) - [フォント](properties_Text.md#フォント) - [フォントサイズ](properties_Text.md#フォントサイズ) - diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/properties_BackgroundAndBorder.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/properties_BackgroundAndBorder.md index 659c3eb0e1ce96..c98697bfd7bd99 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/properties_BackgroundAndBorder.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/properties_BackgroundAndBorder.md @@ -27,7 +27,7 @@ title: 背景色と境界線 ## 背景色/塗りカラー -オブジェクトの背景色/塗りカラーを設定します。 It can be defined for some standard objects (`fill` JSON property) or ["custom style" objects](#custom-button-custom-check-box-or-custom-radio-button) (`borderFillColor` JSON property). +オブジェクトの背景色/塗りカラーを設定します。一部の標準のオブジェクト(`fill` JSON プロパティを使用) あるいは["custom style" オブジェクト](#custom-button-custom-check-box-or-custom-radio-button)(`borderFillColor` JSON プロパティを使用) に対して定義することが可能です。 :::note @@ -105,17 +105,17 @@ title: 背景色と境界線 ## 境界線カラー{#border-color} -Allows defining the border color. The effect of this property varies slightly depending on the type of object to which it is applied. +境界線のカラーを定義することができます。このプロパティの効果は、適用されるオブジェクトのタイプによって若干異なります。 -- **objects with text properties**: [buttons](./button_overview.md) (all styles except "custom", see below), [hierarchical lists](list_overview.md), [inputs](input_overview.md), [list boxes](listbox_overview.md), [progress indicators](./progressIndicator.md), [rulers](./ruler.md), and [text areas](text.md). - By default, the border color of these objects is automatically set to their [**font color**](./properties_Text.md#font-color) property. This default configuration corresponds to the **Same as font** option in the Property List (`borderColor` property is undefined in JSON). - You can separate these two properties by setting a color value for the object's "Border color" property (only available when the [**border line style**](#border-line-style) property is **plain** (`solid` in JSON property) or **dotted**). +- **テキストプロパティを持つオブジェクト**: [ボタン](./button_overview.md) ("カスタム" を除く全てのスタイル、詳細は以下参照)、[階層リスト](list_overview.md)、[入力](input_overview.md)、[リストボックス](listbox_overview.md)、[進捗インジケーター](./progressIndicator.md)、[ルーラー](./ruler.md), and [text areas](text.md)。 + デフォルトで、これらのオブジェクトの境界線カラーは自動的に[**フォントカラー**](./properties_Text.md#フォントカラー) プロパティと同じに設定されています。このデフォルトの設定はプロパティリストの**Same as font** オプションに対応しています(`borderColor` プロパティはJSON では未定義です)。 + これらの二つのプロパティはオブジェクトの"境界線カラー" プロパティ([**境界線スタイル**](#border-line-style) プロパティが**実線** (JSON プロパティでは`solid`) あるいは **点線**のときのみ利用可能) にカラー値を設定することで分離させることができます。 -- **objects without text properties**: [4D View Pro areas](viewProArea_overview.md), [4D Write Pro areas](writeProArea_overview.md), [button grids](buttonGrid_overview.md), [picture buttons](pictureButton_overview.md), [picture pop-up menus](picturePopupMenu_overview.md), [plug-in areas](pluginArea_overview.md), [subforms](subform_overview.md), [spinners](spinner.md), [splitters](splitters.md), [steppers](stepper.md), [web areas](webArea_overview.md). - The border color property sets the color of the borders. The default color value is "Automatic", i.e. the border is displayed with the automatic color set by your OS. +- **テキストプロパティを持たないオブジェクト**: [4D View Pro エリア](viewProArea_overview.md)、[4D Write Pro エリア](writeProArea_overview.md)、[ボタングリッド](buttonGrid_overview.md)、[ピクチャーボタン](pictureButton_overview.md)、[ピクチャーポップアップメニュー](picturePopupMenu_overview.md)、[プラグインエリア](pluginArea_overview.md)、[サブフォーム](subform_overview.md)、[スピナー](spinner.md)、[スプリッター](splitters.md)、[ステッパー](stepper.md)、[Web エリア](webArea_overview.md)。 + 境界線カラープロパティは境界線のカラーを設定します。デフォルトのカラー値は"自動"で、これは境界線がOS によって設定されている自動カラーで表示されることを意味します。 -- **custom-styled buttons**: [custom buttons](./button_overview.md#custom) with ["custom" Border Line Style](#border-line-style), [custom check boxes](./checkbox_overview.md#custom), and [custom radio buttons](./radio_overview.md#custom). - In this case, the border color property defines the color of an *inner* border, which is an attribute of the object itself ans not a decoration property. This inner border can also have a [width](#border-width) (it is displayed only if the width > 0). +- **カスタムスタイルのボタン**: ["カスタム" 境界線スタイル](#border-line-style)をもった[カスタムボタン](./button_overview.md#カスタム)、[カスタムチェックボックス](./checkbox_overview.md#カスタム)、および[カスタムラジオボタン](./radio_overview.md#カスタム)。 + この場合、境界線カラープロパティーは*内側の* 境界線カラーを定義し、これはオブジェクト自身の属性であり、装飾プロパティではありません。内側の境界線は[幅](#border-width) を持つこともできます(幅が0 より大きい場合にのみ表示されます)。 #### JSON 文法 @@ -125,7 +125,26 @@ Allows defining the border color. The effect of this property varies slightly de #### 対象オブジェクト -[4D View Pro area](viewProArea_overview.md) - [4D Write Pro area](writeProArea_overview.md) - [Button](./button_overview.md) - [Button Grid](buttonGrid_overview.md) - [Check Box ("custom" style)](checkbox_overview.md#custom) - [Hierarchical List](list_overview.md) - [Input](input_overview.md) - [List Box](listbox_overview.md) - [Picture Button](pictureButton_overview.md) - [Picture Pop-up Menu](picturePopupMenu_overview.md) - [Plug-in Area](pluginArea_overview.md) - [Progress Indicator](./progressIndicator.md) - [Radio Button ("custom" style)](radio_overview.md#custom) - [Ruler](./ruler.md) - [Text Area](text.md) - [Spinner](spinner.md) - [Splitter](splitters.md) - [Stepper](stepper.md) - [Subform](subform_overview.md) - [Web Area](webArea_overview.md) +[4D View Pro エリア](viewProArea_overview.md) - +[4D Write Pro エリア](writeProArea_overview.md) - +[ボタン](button_overview.md) - +[ボタングリッド](buttonGrid_overview.md) - +[チェックボックス("カスタム"スタイル)](checkbox_overview.md#custom) - +[階層リスト](list_overview.md) - +[入力](input_overview.md) - +[リストボックス](listbox_overview.md) - +[ピクチャーボタン](pictureButton_overview.md) - +[ピクチャーポップアップメニュー](picturePopupMenu_overview.md) - +[プラグインエリア](pluginArea_overview.md) - +[進捗インジケーター](progressIndicator.md) - +[ラジオボタン("カスタム"スタイル)](radio_overview.md#custom) - +[ルーラー](ruler.md) - +[テキストエリア](text.md) - +[スピナー](spinner.md) - +[Splitter](splitters.md) - +[ステッパー](stepper.md) - +[サブフォーム](subform_overview.md) - +[Web エリア](webArea_overview.md) #### コマンド @@ -133,25 +152,25 @@ Allows defining the border color. The effect of this property varies slightly de #### 参照 -[Line Color](#line-color) (for shapes) +[線カラー](#線カラー) (図形用) ## 境界線スタイル{#border-line-style} -Allows setting a style for the object border. The following choices are available (all choices are not possible depending on the object): +オブジェクトの境界線のスタイルを設定することができます。以下の選択肢が利用可能です(オブジェクトによっては全ての選択肢が利用可能ではないこともあります): -| Style | Objects (\*) | 説明 | -| -------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| なし | all | Objects appear with no border. | -| Plain | all | Objects appear framed with a continuous 1-pt. border line. ("solid" json value) | -| Dotted | all | Objects appear framed with a dotted 1-pt. border line. | -| Raised | all | Objects appear framed with a 3D effect. | -| Sunken | all | Objects appear framed with a sunken 3D effect. | -| Double | all | Objects appear framed with a double line, i.e., two continuous 1-pt. lines separated by a pixel. | -| System | all *except* [buttons](button_overview.md) and [text areas](text.md) | Objects appear with a border line based on the graphic specifications of the OS. | -| System rounded | [inputs](input_overview.md) | On macOS, objects appear with a native "Liquid Glass" system border effect (for information about Liquid Glass, see [this 4D blog post](https://blog.4d.com/the-new-macos-tahoe-design-comes-to-your-4d-applications/)). It includes system-defined inner border, corner radius, grey border color, and inner padding. Note that the "Liquid Glass" appearance is *not* used in a multiline input object if the [scroll bars property](./properties_Appearance.md#vertical-scroll-bar) is enabled ("System" is used in this case).
    On Windows, this style is similar to "System" at runtime. | -| カスタム | [custom buttons](./button_overview.md#custom) | Enables the inner border design, that includes a set of extra properties: [Fill color](#fill-color), [Border color](#border-color), [Border width](#border-width), and [Corner radius](#corner-radius).
    ![](../assets/en/FormObjects/custom-button.png) | +| スタイル | オブジェクト(\*) | 説明 | +| --------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| なし | all | オブジェクトは境界線なしで表示されます。 | +| 標準 | all | オブジェクトは連続した1pt の幅の境界線で表示されます。 ("solid" json 値) | +| ドット | all | オブジェクトは点線の1pt の幅の境界線で表示されます。 | +| 浮き上がり | all | オブジェクトは3D エフェクトの境界線で表示されます。 | +| くぼみ | all | オブジェクトは、くぼみ3D エフェクトの境界線で表示されます。 | +| 二重 | all | オブジェクトは連続した1pt の幅の二重線の境界線で表示されます。二重線は1ピクセル間の隙間で表示されます。 | +| システム | [ボタン](button_overview.md)および [テキストエリア](text.md) を *除く* 全て | オブジェクトはOS のグラフィック仕様に基づいた境界線で表示されます。 | +| システムの角の丸み | [入力](input_overview.md) | macOS では、オブジェクトはネイティブの"Liquid Glass" システム境界線エフェクトで表示されます(Liquid Glass についての情報については[こちらの4D blog 記事](https://blog.4d.com/the-new-macos-tahoe-design-comes-to-your-4d-applications/))。これにはシステム定義の内側の境界線、角の半径、グレーの境界線カラー、そして内側のパディングが含まれます。[スクロールバープロパティ](./properties_Appearance.md#縦スクロールバー) が有効化されている複数行の入力オブジェクト内においてはアピアランスは使用されないという点に注意してください(この場合には"システム"が使用されます)。
    Windows においては、このスタイルはランタイムでは"システム" に似たスタイルで表示されます。 | +| カスタム | [カスタムボタン](./button_overview.md#カスタム) | 内側の境界線デザインを有効化し、これには以下の追加のプロパティのセットが含まれます: [塗りカラー](#背景色-塗りカラー)、[境界線カラー](#border-color)、[境界線幅](#border-width)、および[角の半径](#角の半径)。
    ![](../assets/en/FormObjects/custom-button.png) | -(\*) "all" means "all objects supported" listed below. +(\*) この"all" または"全て" とは、以下の"サポートされる全てのオブジェクト" を意味します。 :::tip 関連したblog 記事 @@ -165,7 +184,7 @@ Allows setting a style for the object border. The following choices are availabl | 名称 | データタイプ | とりうる値 | | ----------- | ------ | -------------------------------------------------------------------------------------------- | -| borderStyle | text | "custom", "dotted", "double", "none", "raised", "solid", "sunken", "system", "systemRounded" | +| borderStyle | text | "custom"、 "dotted"、 "double"、 "none"、 "raised"、 "solid"、 "sunken"、 "system"、 "systemRounded" | #### 対象オブジェクト @@ -193,7 +212,7 @@ Allows setting a style for the object border. The following choices are availabl #### 参照 -[Dotted Line Type](#dotted-line-type) (shapes) +[点線タイプ](#dotted-line-type) (図形) --- @@ -217,7 +236,7 @@ Allows setting a style for the object border. The following choices are availabl #### 対象オブジェクト -[Button ("custom" style)](./button_overview.md#custom) (with ["custom" Border Line Style](#border-line-style)) - [Check Box ("custom style")](checkbox_overview.md#custom) - [Radio Button ("custom" style)](radio_overview.md#custom) +(["カスタム" 境界線スタイル](#border-line-style)を持った)[ボタン("カスタム"スタイル)](./button_overview.md#カスタム) - [チェックボックス("カスタムスタイル")](checkbox_overview.md#カスタム) - [ラジオボタン("カスタム" スタイル)](radio_overview.md#カスタム) --- @@ -258,7 +277,7 @@ Allows setting a style for the object border. The following choices are availabl #### 対象オブジェクト -[Button ("custom" style)](./button_overview.md#custom) (with ["custom" Border Line Style](#border-line-style)) - [Check Box ("custom" style)](checkbox_overview.md#custom) - [Input](input_overview.md) - [Rectangle](shapes_overview.md#rectangle) - [Text Area](text.md) - [Radio Button ("custom" style)](radio_overview.md#custom) +(["カスタム"境界線スタイル](#border-line-style)を持った)[ボタン("カスタム"スタイル)](./button_overview.md#カスタム) - [チェックボックス("カスタム" スタイル)](checkbox_overview.md#カスタム) - [入力](input_overview.md) - [四角形](shapes_overview.md#四角形) - [テキストエリア](text.md) - [ラジオボタン("カスタム" スタイル)](radio_overview.md#カスタム) #### コマンド @@ -326,7 +345,7 @@ Allows setting a style for the object border. The following choices are availabl :::note -This property is also available for objects with text properties, in which case it designates both the [Font color](properties_Text.md#font-color) and the object's lines, except if you used the [Border color](#border-color) property. +このプロパティはテキストプロパティを持つオブジェクトでも利用可能で、その場合には[フォントカラー](properties_Text.md#フォントカラー) とオブジェクトの線の両方を指定します(ただし[境界線カラー](#border-color) プロパティを使用していた場合を除く)。 ::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/properties_DataSource.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/properties_DataSource.md index eb65c9a24b8189..a49a59fa28efef 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/properties_DataSource.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/properties_DataSource.md @@ -330,7 +330,7 @@ title: データソース 使用する命名セレクションを指定します。有効な命名セレクションの名前を入力しなければなりません。使用できるのはプロセスあるいはインタープロセス命名セレクションです。リストボックスの内容はこのセレクションに基づきます。選択された命名セレクションは、リストボックスが表示される時点で存在し、有効でなければなりません。 そうでない場合、リストボックスは空で表示されます。 -> 命名セレクションはソート済みのレコードリストです。これはセレクション中のカレントレコードと並び順をメモリに保持するために使用されます。 For more information, refer to [**Named Selections**](../Develop/named-selections) section. +> 命名セレクションはソート済みのレコードリストです。これはセレクション中のカレントレコードと並び順をメモリに保持するために使用されます。詳細な情報については、[**命名セレクション**](../Develop/named-selections) の章を参照してください。 #### JSON 文法 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/radio_overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/radio_overview.md index 42308774eca1c3..3141ea53ed0c0a 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/radio_overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/radio_overview.md @@ -154,7 +154,7 @@ Office XPボタンの反転表示と背景のカラーはシステムカラー [カスタム](#カスタム) スタイルのラジオボタンに対しては特有の追加のプロパティが利用可能です: -[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#境界線カラー) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) +[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#border-color) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) ## サポートされるイベント diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/tabControl.md b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/tabControl.md index 3ea815ce123ad3..b3860876cef6cd 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/tabControl.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/FormObjects/tabControl.md @@ -114,11 +114,11 @@ FORM GOTO PAGE(arrPages) たとえば、ユーザーが 3番目のタブをクリックすると、4Dはカレントフォームの 3ページ目 (存在する場合) を表示します。 -## Supported standard actions +## サポートされる標準アクション - [gotoPage](../Desktop-legacy/standard-actions.md#gotopage): Uses the selected tab number as described in [Goto Page action](#goto-page-action). -See the [standard action compatibility table](../Desktop-legacy/standard-actions.md#supported-form-objects). +詳細については[標準アクション互換性表](../Desktop-legacy/standard-actions.md#サポートされるフォームオブジェクト) を参照してください。 ## プロパティ一覧 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/ORDA/privileges.md b/i18n/ja/docusaurus-plugin-content-docs/current/ORDA/privileges.md index dc6b76048c5606..c847cf6200c088 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/ORDA/privileges.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/ORDA/privileges.md @@ -294,6 +294,12 @@ The project's web security settings are defined in `roles.json`: ::: +:::warning + +When a permission entry references an undeclared [privilege](#privileges-and-roles), 4D logs an error and ignores the entry. In this case, the permission is ignored. If the [restricted mode by default](#restriction-modes) is not enabled, the resource is accessible to `guest` sessions. + +::: + ### Default location and content New projects generate `roles.json` at: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/WebServer/quotas.md b/i18n/ja/docusaurus-plugin-content-docs/current/WebServer/quotas.md index 9f2f6270a841c4..c0fe1d6fca8c80 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/WebServer/quotas.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/WebServer/quotas.md @@ -12,12 +12,6 @@ Web サーバークォータを使用して、トラフィック、リクエス ::: -:::tip 関連したBlog 記事 - -[A 4D web server that knows when to say No](https://blog.4d.com/a-4d-web-server-that-knows-when-to-say-no/) - -::: - ## 要件 クォータの設定のためには、[スケーラブルセッション](./sessions.md#Webセッションの有効化) が有効化されている必要があります。 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/assets/en/embedding-studio/menu.png b/i18n/ja/docusaurus-plugin-content-docs/current/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/current/assets/en/embedding-studio/menu.png differ diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/assets/en/embedding-studio/studio-interface.png b/i18n/ja/docusaurus-plugin-content-docs/current/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/current/assets/en/embedding-studio/studio-interface.png differ diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Definition.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Definition.md new file mode 100644 index 00000000000000..7b9bf4e7a585df --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Definition.md @@ -0,0 +1,165 @@ +--- +id: 定義 +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/current/embedding-studio/Classes/Embedder.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Embedder.md new file mode 100644 index 00000000000000..1d0f1ae886f748 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/EmbedderResult.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/EmbedderResult.md new file mode 100644 index 00000000000000..c2c44f170ee6e7 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/Phrase.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Phrase.md new file mode 100644 index 00000000000000..151bec7cb2c351 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/Process.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Process.md new file mode 100644 index 00000000000000..c71a3fa7cee303 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Process.md @@ -0,0 +1,188 @@ +--- +id: プロセス +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/current/embedding-studio/Classes/ProcessError.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/ProcessError.md new file mode 100644 index 00000000000000..fa8a4e0316d6d6 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/ProcessErrorCode.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/ProcessErrorCode.md new file mode 100644 index 00000000000000..dafd474bde19ec --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/ProcessResult.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/ProcessResult.md new file mode 100644 index 00000000000000..7c690d7eeda9f1 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/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/current/embedding-studio/Classes/Scheduler.md b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Scheduler.md new file mode 100644 index 00000000000000..975db1e02ec8e0 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/embedding-studio/Classes/Scheduler.md @@ -0,0 +1,369 @@ +--- +id: スケジューラー +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/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/version-20/Concepts/dt_number.md b/i18n/ja/docusaurus-plugin-content-docs/version-20/Concepts/dt_number.md index 75e2ddbdda1e4f..631b5099ef4acb 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-20/Concepts/dt_number.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-20/Concepts/dt_number.md @@ -69,7 +69,7 @@ title: 数値 (実数、倍長整数、整数) :::warning -モジューロ演算子 % は倍長整数の範囲内 (-2^31 から (2^31)-1 まで) の数値に対して有効な値を返します。この範囲外の数値のモジューロ演算を実行するには、[`Mod`](https://doc.4d.com/4dv20/help/command/ja/page98.html) コマンドを使用します。 +モジューロ演算子 % は倍長整数の範囲内 (-2^31 から (2^31)-1 まで) の数値に対して有効な値を返します。範囲外の数値に対してモジューロを計算したい場合には、[`Mod`](https://doc.4d.com/4dv20/help/command/en/page98.html) コマンドを使用してください。 ::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-20/FormEditor/createStylesheet.md b/i18n/ja/docusaurus-plugin-content-docs/version-20/FormEditor/createStylesheet.md index a9f7e82321de26..bec2c9ab9fb1cd 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-20/FormEditor/createStylesheet.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-20/FormEditor/createStylesheet.md @@ -126,7 +126,7 @@ text.center { } ``` -4D フォームの詳細では、[CSSクラス](../FormObjects/properties_Object.md#cssクラス) 属性を使用してクラス名を割り当てます。この属性には一つ以上のクラス名を指定することができます。 複数の場合はクラス名を半角スペースで区切ります: +4D フォームの詳細では、[CSSクラス](../FormObjects/properties_Object.md#cssクラス) 属性を使用してクラス名を割り当てます。この属性には一つ以上のクラス名を指定することができます。複数の場合はクラス名を半角スペースで区切ります: ``` class: "okButtons important" diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Desktop/labels.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Desktop/labels.md index 70073d18ad1a8d..29b65f2314faab 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Desktop/labels.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Desktop/labels.md @@ -164,7 +164,7 @@ title: ラベル var myVar+=1 ``` -3. プロジェクトメソッドに対して["コンポーネントとホストデータベース間で共有"](../Project/project-method-properties.md#コンポーネントとホストデータベース間で共有) オプションを設定します。 +3. プロジェクトメソッドに対して["コンポーネントとホストデータベース間で共有"](../Project/project-method-properties.md#コンポーネントとホストプロジェクト間で共有) オプションを設定します。 4. ラベルエディターを表示する前に、以下のコードを実行してプロジェクトメソッドが確実に許可されているようにします: diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md index 8f3647df6fbe95..15b0b4faa7ef73 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop/preemptive.md @@ -41,7 +41,7 @@ title: プリエンプティブプロセス 要素毎の "スレッドセーフティ" プロパティは、その要素自身によります: -- 4Dコマンド: スレッドセーフティは内部プロパティです。 4D ドキュメンテーション内においては、スレッドセーフなコマンドには ![](../assets/en/Develop/thread-safe.png) アイコンが表示されています。 [`Command name`](../commands/command-name) コマンドを使用して、コマンドがスレッドセーフであるかどうかを知ることもできます。 4Dコマンドの大部分はプリエンプティブモードで実行可能です。 +- 4Dコマンド: スレッドセーフティは内部プロパティです。 The 4D documentation indicates whether each command is thread-safe or not in the Properties section. [`Command name`](../commands/command-name) コマンドを使用して、コマンドがスレッドセーフであるかどうかを知ることもできます。 4Dコマンドの大部分はプリエンプティブモードで実行可能です。 - プロジェクトメソッド: スレッドセーフであるための条件は [こちらの段落](#スレッドセーフなメソッドの書き方) にまとめられています。 原則として、プリエンプティブスレッド内で実行されるコードは外部との相互作用する部分、たとえばプラグインコードやインタープロセス変数などを呼び出すことはできません。しかしながら、4Dデータサーバーと ORDA はプリエンプティブ実行をサポートしていることから、データアクセスは可能です。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop/processes.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop/processes.md index d7eb693b4a3da8..65c53df3caa564 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop/processes.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop/processes.md @@ -50,7 +50,7 @@ title: プロセスとワーカー ### インターフェース要素 -インターフェース要素は、[デスクトップアプリケーション](../category/desktop-applications) で使用されます。 以下のものがあります: 以下のものがあります: +インターフェース要素は、[デスクトップアプリケーション](../category/desktop-applications) で使用されます。以下のものがあります: - [メニューバー](../Menus/creating.md): 各プロセスは、独自のカレントメニューバーを持つことができます。最前面のプロセスのメニューバーがアプリケーションのカレントメニューバーになります。 - 1つ以上のウィンドウ: 各プロセスは、1つまたは複数のウィンドウを同時に開くことができます。他方、ウィンドウをまったく持たないプロセスもあります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/FormEditor/createStylesheet.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/FormEditor/createStylesheet.md index 5e5cd912ba4201..68b7055ec7ae72 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/FormEditor/createStylesheet.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R4/FormEditor/createStylesheet.md @@ -126,7 +126,7 @@ text.center { } ``` -4D フォームの詳細では、[CSSクラス](../FormObjects/properties_Object.md#cssクラス) 属性を使用してクラス名を割り当てます。この属性には一つ以上のクラス名を指定することができます。 複数の場合はクラス名を半角スペースで区切ります: +4D フォームの詳細では、[CSSクラス](../FormObjects/properties_Object.md#cssクラス) 属性を使用してクラス名を割り当てます。この属性には一つ以上のクラス名を指定することができます。複数の場合はクラス名を半角スペースで区切ります: ```css class: "okButtons important" diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/API/UDPSocketClass.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/API/UDPSocketClass.md index d33015ed99ac86..c7ca24f1434184 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/API/UDPSocketClass.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/API/UDPSocketClass.md @@ -50,7 +50,7 @@ UDPSocket オブジェクトは以下のプロパティと関数を提供しま | 引数 | 型 | | 説明 | | ------- | ---------------------------- | --------------------------- | ------------------------------------------------------------------------ | | port | Integer | -> | UDP ソケットに使用されるローカルのポート番号(0 または省略時には使用されていないポートを探して使用) | -| options | Object | -> | ソケットの接続[オプション](#options引数) | +| options | Object | -> | ソケットの接続[オプション](#options-引数) | | 戻り値 | 4D.UDPSocket | <- | 新規UDPSocket オブジェクト | diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/API/WebSocketServerClass.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/API/WebSocketServerClass.md index 80c0e06aa26048..09d2a346b74a78 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/API/WebSocketServerClass.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/API/WebSocketServerClass.md @@ -37,7 +37,7 @@ WebSocketプロトコルは、WebSocketサーバーとクライアント (Webブ - サーバー接続を処理するためのユーザークラス - メッセージを処理するためのユーザークラス -接続を維持するため、[WebSocketサーバーの作成](#4dwebsocketservernew) は [ワーカー](../Develop/processes.md#worker-プロセス) 内にて行う必要があります。 +接続を維持するため、[WebSocketサーバーの作成](#4dwebsocketservernew) は [ワーカー](../Develop/processes.md#ワーカープロセス) 内にて行う必要があります。 [4D Webサーバー](WebServerClass.md) を起動しておく必要があります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Desktop/labels.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Desktop/labels.md index 70073d18ad1a8d..29b65f2314faab 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Desktop/labels.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Desktop/labels.md @@ -164,7 +164,7 @@ title: ラベル var myVar+=1 ``` -3. プロジェクトメソッドに対して["コンポーネントとホストデータベース間で共有"](../Project/project-method-properties.md#コンポーネントとホストデータベース間で共有) オプションを設定します。 +3. プロジェクトメソッドに対して["コンポーネントとホストデータベース間で共有"](../Project/project-method-properties.md#コンポーネントとホストプロジェクト間で共有) オプションを設定します。 4. ラベルエディターを表示する前に、以下のコードを実行してプロジェクトメソッドが確実に許可されているようにします: diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md index 8f3647df6fbe95..15b0b4faa7ef73 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/preemptive.md @@ -41,7 +41,7 @@ title: プリエンプティブプロセス 要素毎の "スレッドセーフティ" プロパティは、その要素自身によります: -- 4Dコマンド: スレッドセーフティは内部プロパティです。 4D ドキュメンテーション内においては、スレッドセーフなコマンドには ![](../assets/en/Develop/thread-safe.png) アイコンが表示されています。 [`Command name`](../commands/command-name) コマンドを使用して、コマンドがスレッドセーフであるかどうかを知ることもできます。 4Dコマンドの大部分はプリエンプティブモードで実行可能です。 +- 4Dコマンド: スレッドセーフティは内部プロパティです。 The 4D documentation indicates whether each command is thread-safe or not in the Properties section. [`Command name`](../commands/command-name) コマンドを使用して、コマンドがスレッドセーフであるかどうかを知ることもできます。 4Dコマンドの大部分はプリエンプティブモードで実行可能です。 - プロジェクトメソッド: スレッドセーフであるための条件は [こちらの段落](#スレッドセーフなメソッドの書き方) にまとめられています。 原則として、プリエンプティブスレッド内で実行されるコードは外部との相互作用する部分、たとえばプラグインコードやインタープロセス変数などを呼び出すことはできません。しかしながら、4Dデータサーバーと ORDA はプリエンプティブ実行をサポートしていることから、データアクセスは可能です。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/processes.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/processes.md index d7eb693b4a3da8..65c53df3caa564 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/processes.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/processes.md @@ -50,7 +50,7 @@ title: プロセスとワーカー ### インターフェース要素 -インターフェース要素は、[デスクトップアプリケーション](../category/desktop-applications) で使用されます。 以下のものがあります: 以下のものがあります: +インターフェース要素は、[デスクトップアプリケーション](../category/desktop-applications) で使用されます。以下のものがあります: - [メニューバー](../Menus/creating.md): 各プロセスは、独自のカレントメニューバーを持つことができます。最前面のプロセスのメニューバーがアプリケーションのカレントメニューバーになります。 - 1つ以上のウィンドウ: 各プロセスは、1つまたは複数のウィンドウを同時に開くことができます。他方、ウィンドウをまったく持たないプロセスもあります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md index 51fb40856f799a..900653e927faf4 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/Develop/structure-indexes.md @@ -144,7 +144,7 @@ QUERY([PICTURES];[PICTURES]Photos %"cats") - 複合インデックスを作成するには、インデックスに含めるフィールドを複数選択します。フィールドリストが完成したら、矢印ボタンやドラッグ＆ドロップを使用してフィールドの並びを変更できます。 - 主キーフィールドをもとに複合インデックスを作成する場合、フィールドの並び順が主キーとインデックスとで同じ順番になるようにしてください。 -- If you have chosen the “Keyword Index” type, only Alpha or Text fields can be selected. Also in this case, you cannot include only one field in the index. +- “キーワードインデックス”タイプは文字やテキスト、またはピクチャーフィールドタイプでのみ使用できます。またこの場合、インデックスに含めることができるのは1つのフィールドのみです。 インデックスからフィールドを削除するには、リスト中でそれを選択し、 **[-]** ボタンをクリックします。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormEditor/createStylesheet.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormEditor/createStylesheet.md index 95135802fba700..c04b7efede079d 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormEditor/createStylesheet.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormEditor/createStylesheet.md @@ -126,7 +126,7 @@ text.center { } ``` -4D フォームの詳細では、[CSSクラス](../FormObjects/properties_Object.md#cssクラス) 属性を使用してクラス名を割り当てます。この属性には一つ以上のクラス名を指定することができます。 複数の場合はクラス名を半角スペースで区切ります: +4D フォームの詳細では、[CSSクラス](../FormObjects/properties_Object.md#cssクラス) 属性を使用してクラス名を割り当てます。この属性には一つ以上のクラス名を指定することができます。複数の場合はクラス名を半角スペースで区切ります: ```css class: "okButtons important" diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/button_overview.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/button_overview.md index fecdf422a61587..02cd7b02532fde 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/button_overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/button_overview.md @@ -345,7 +345,7 @@ Windows Classic UI テーマでは、このスタイルはサポートされま [カスタム](#カスタム) スタイルのボタンに対しては特有の追加のプロパティが利用可能です: -[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#境界線カラー) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [デフォルトボタン](properties_Appearance.md#デフォルトボタン) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) +[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#border-color) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [デフォルトボタン](properties_Appearance.md#デフォルトボタン) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) ### フラットおよび通常ボタンにおける追加のプロパティ diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/checkbox_overview.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/checkbox_overview.md index 080be1d0eaaa86..5b9373e65e4647 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/checkbox_overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/checkbox_overview.md @@ -396,7 +396,7 @@ Office XP スタイルのチェックボックスの反転表示と背景のカ [カスタム](#カスタム) スタイルのチェックボックスに対しては特有の追加のプロパティが利用可能です: -[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#境界線カラー) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) +[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#border-color) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) ### フラットおよび通常チェックボックスにおける追加のプロパティ diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/properties_BackgroundAndBorder.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/properties_BackgroundAndBorder.md index 659c3eb0e1ce96..c98697bfd7bd99 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/properties_BackgroundAndBorder.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/properties_BackgroundAndBorder.md @@ -27,7 +27,7 @@ title: 背景色と境界線 ## 背景色/塗りカラー -オブジェクトの背景色/塗りカラーを設定します。 It can be defined for some standard objects (`fill` JSON property) or ["custom style" objects](#custom-button-custom-check-box-or-custom-radio-button) (`borderFillColor` JSON property). +オブジェクトの背景色/塗りカラーを設定します。一部の標準のオブジェクト(`fill` JSON プロパティを使用) あるいは["custom style" オブジェクト](#custom-button-custom-check-box-or-custom-radio-button)(`borderFillColor` JSON プロパティを使用) に対して定義することが可能です。 :::note @@ -105,17 +105,17 @@ title: 背景色と境界線 ## 境界線カラー{#border-color} -Allows defining the border color. The effect of this property varies slightly depending on the type of object to which it is applied. +境界線のカラーを定義することができます。このプロパティの効果は、適用されるオブジェクトのタイプによって若干異なります。 -- **objects with text properties**: [buttons](./button_overview.md) (all styles except "custom", see below), [hierarchical lists](list_overview.md), [inputs](input_overview.md), [list boxes](listbox_overview.md), [progress indicators](./progressIndicator.md), [rulers](./ruler.md), and [text areas](text.md). - By default, the border color of these objects is automatically set to their [**font color**](./properties_Text.md#font-color) property. This default configuration corresponds to the **Same as font** option in the Property List (`borderColor` property is undefined in JSON). - You can separate these two properties by setting a color value for the object's "Border color" property (only available when the [**border line style**](#border-line-style) property is **plain** (`solid` in JSON property) or **dotted**). +- **テキストプロパティを持つオブジェクト**: [ボタン](./button_overview.md) ("カスタム" を除く全てのスタイル、詳細は以下参照)、[階層リスト](list_overview.md)、[入力](input_overview.md)、[リストボックス](listbox_overview.md)、[進捗インジケーター](./progressIndicator.md)、[ルーラー](./ruler.md), and [text areas](text.md)。 + デフォルトで、これらのオブジェクトの境界線カラーは自動的に[**フォントカラー**](./properties_Text.md#フォントカラー) プロパティと同じに設定されています。このデフォルトの設定はプロパティリストの**Same as font** オプションに対応しています(`borderColor` プロパティはJSON では未定義です)。 + これらの二つのプロパティはオブジェクトの"境界線カラー" プロパティ([**境界線スタイル**](#border-line-style) プロパティが**実線** (JSON プロパティでは`solid`) あるいは **点線**のときのみ利用可能) にカラー値を設定することで分離させることができます。 -- **objects without text properties**: [4D View Pro areas](viewProArea_overview.md), [4D Write Pro areas](writeProArea_overview.md), [button grids](buttonGrid_overview.md), [picture buttons](pictureButton_overview.md), [picture pop-up menus](picturePopupMenu_overview.md), [plug-in areas](pluginArea_overview.md), [subforms](subform_overview.md), [spinners](spinner.md), [splitters](splitters.md), [steppers](stepper.md), [web areas](webArea_overview.md). - The border color property sets the color of the borders. The default color value is "Automatic", i.e. the border is displayed with the automatic color set by your OS. +- **テキストプロパティを持たないオブジェクト**: [4D View Pro エリア](viewProArea_overview.md)、[4D Write Pro エリア](writeProArea_overview.md)、[ボタングリッド](buttonGrid_overview.md)、[ピクチャーボタン](pictureButton_overview.md)、[ピクチャーポップアップメニュー](picturePopupMenu_overview.md)、[プラグインエリア](pluginArea_overview.md)、[サブフォーム](subform_overview.md)、[スピナー](spinner.md)、[スプリッター](splitters.md)、[ステッパー](stepper.md)、[Web エリア](webArea_overview.md)。 + 境界線カラープロパティは境界線のカラーを設定します。デフォルトのカラー値は"自動"で、これは境界線がOS によって設定されている自動カラーで表示されることを意味します。 -- **custom-styled buttons**: [custom buttons](./button_overview.md#custom) with ["custom" Border Line Style](#border-line-style), [custom check boxes](./checkbox_overview.md#custom), and [custom radio buttons](./radio_overview.md#custom). - In this case, the border color property defines the color of an *inner* border, which is an attribute of the object itself ans not a decoration property. This inner border can also have a [width](#border-width) (it is displayed only if the width > 0). +- **カスタムスタイルのボタン**: ["カスタム" 境界線スタイル](#border-line-style)をもった[カスタムボタン](./button_overview.md#カスタム)、[カスタムチェックボックス](./checkbox_overview.md#カスタム)、および[カスタムラジオボタン](./radio_overview.md#カスタム)。 + この場合、境界線カラープロパティーは*内側の* 境界線カラーを定義し、これはオブジェクト自身の属性であり、装飾プロパティではありません。内側の境界線は[幅](#border-width) を持つこともできます(幅が0 より大きい場合にのみ表示されます)。 #### JSON 文法 @@ -125,7 +125,26 @@ Allows defining the border color. The effect of this property varies slightly de #### 対象オブジェクト -[4D View Pro area](viewProArea_overview.md) - [4D Write Pro area](writeProArea_overview.md) - [Button](./button_overview.md) - [Button Grid](buttonGrid_overview.md) - [Check Box ("custom" style)](checkbox_overview.md#custom) - [Hierarchical List](list_overview.md) - [Input](input_overview.md) - [List Box](listbox_overview.md) - [Picture Button](pictureButton_overview.md) - [Picture Pop-up Menu](picturePopupMenu_overview.md) - [Plug-in Area](pluginArea_overview.md) - [Progress Indicator](./progressIndicator.md) - [Radio Button ("custom" style)](radio_overview.md#custom) - [Ruler](./ruler.md) - [Text Area](text.md) - [Spinner](spinner.md) - [Splitter](splitters.md) - [Stepper](stepper.md) - [Subform](subform_overview.md) - [Web Area](webArea_overview.md) +[4D View Pro エリア](viewProArea_overview.md) - +[4D Write Pro エリア](writeProArea_overview.md) - +[ボタン](button_overview.md) - +[ボタングリッド](buttonGrid_overview.md) - +[チェックボックス("カスタム"スタイル)](checkbox_overview.md#custom) - +[階層リスト](list_overview.md) - +[入力](input_overview.md) - +[リストボックス](listbox_overview.md) - +[ピクチャーボタン](pictureButton_overview.md) - +[ピクチャーポップアップメニュー](picturePopupMenu_overview.md) - +[プラグインエリア](pluginArea_overview.md) - +[進捗インジケーター](progressIndicator.md) - +[ラジオボタン("カスタム"スタイル)](radio_overview.md#custom) - +[ルーラー](ruler.md) - +[テキストエリア](text.md) - +[スピナー](spinner.md) - +[Splitter](splitters.md) - +[ステッパー](stepper.md) - +[サブフォーム](subform_overview.md) - +[Web エリア](webArea_overview.md) #### コマンド @@ -133,25 +152,25 @@ Allows defining the border color. The effect of this property varies slightly de #### 参照 -[Line Color](#line-color) (for shapes) +[線カラー](#線カラー) (図形用) ## 境界線スタイル{#border-line-style} -Allows setting a style for the object border. The following choices are available (all choices are not possible depending on the object): +オブジェクトの境界線のスタイルを設定することができます。以下の選択肢が利用可能です(オブジェクトによっては全ての選択肢が利用可能ではないこともあります): -| Style | Objects (\*) | 説明 | -| -------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| なし | all | Objects appear with no border. | -| Plain | all | Objects appear framed with a continuous 1-pt. border line. ("solid" json value) | -| Dotted | all | Objects appear framed with a dotted 1-pt. border line. | -| Raised | all | Objects appear framed with a 3D effect. | -| Sunken | all | Objects appear framed with a sunken 3D effect. | -| Double | all | Objects appear framed with a double line, i.e., two continuous 1-pt. lines separated by a pixel. | -| System | all *except* [buttons](button_overview.md) and [text areas](text.md) | Objects appear with a border line based on the graphic specifications of the OS. | -| System rounded | [inputs](input_overview.md) | On macOS, objects appear with a native "Liquid Glass" system border effect (for information about Liquid Glass, see [this 4D blog post](https://blog.4d.com/the-new-macos-tahoe-design-comes-to-your-4d-applications/)). It includes system-defined inner border, corner radius, grey border color, and inner padding. Note that the "Liquid Glass" appearance is *not* used in a multiline input object if the [scroll bars property](./properties_Appearance.md#vertical-scroll-bar) is enabled ("System" is used in this case).
    On Windows, this style is similar to "System" at runtime. | -| カスタム | [custom buttons](./button_overview.md#custom) | Enables the inner border design, that includes a set of extra properties: [Fill color](#fill-color), [Border color](#border-color), [Border width](#border-width), and [Corner radius](#corner-radius).
    ![](../assets/en/FormObjects/custom-button.png) | +| スタイル | オブジェクト(\*) | 説明 | +| --------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| なし | all | オブジェクトは境界線なしで表示されます。 | +| 標準 | all | オブジェクトは連続した1pt の幅の境界線で表示されます。 ("solid" json 値) | +| ドット | all | オブジェクトは点線の1pt の幅の境界線で表示されます。 | +| 浮き上がり | all | オブジェクトは3D エフェクトの境界線で表示されます。 | +| くぼみ | all | オブジェクトは、くぼみ3D エフェクトの境界線で表示されます。 | +| 二重 | all | オブジェクトは連続した1pt の幅の二重線の境界線で表示されます。二重線は1ピクセル間の隙間で表示されます。 | +| システム | [ボタン](button_overview.md)および [テキストエリア](text.md) を *除く* 全て | オブジェクトはOS のグラフィック仕様に基づいた境界線で表示されます。 | +| システムの角の丸み | [入力](input_overview.md) | macOS では、オブジェクトはネイティブの"Liquid Glass" システム境界線エフェクトで表示されます(Liquid Glass についての情報については[こちらの4D blog 記事](https://blog.4d.com/the-new-macos-tahoe-design-comes-to-your-4d-applications/))。これにはシステム定義の内側の境界線、角の半径、グレーの境界線カラー、そして内側のパディングが含まれます。[スクロールバープロパティ](./properties_Appearance.md#縦スクロールバー) が有効化されている複数行の入力オブジェクト内においてはアピアランスは使用されないという点に注意してください(この場合には"システム"が使用されます)。
    Windows においては、このスタイルはランタイムでは"システム" に似たスタイルで表示されます。 | +| カスタム | [カスタムボタン](./button_overview.md#カスタム) | 内側の境界線デザインを有効化し、これには以下の追加のプロパティのセットが含まれます: [塗りカラー](#背景色-塗りカラー)、[境界線カラー](#border-color)、[境界線幅](#border-width)、および[角の半径](#角の半径)。
    ![](../assets/en/FormObjects/custom-button.png) | -(\*) "all" means "all objects supported" listed below. +(\*) この"all" または"全て" とは、以下の"サポートされる全てのオブジェクト" を意味します。 :::tip 関連したblog 記事 @@ -165,7 +184,7 @@ Allows setting a style for the object border. The following choices are availabl | 名称 | データタイプ | とりうる値 | | ----------- | ------ | -------------------------------------------------------------------------------------------- | -| borderStyle | text | "custom", "dotted", "double", "none", "raised", "solid", "sunken", "system", "systemRounded" | +| borderStyle | text | "custom"、 "dotted"、 "double"、 "none"、 "raised"、 "solid"、 "sunken"、 "system"、 "systemRounded" | #### 対象オブジェクト @@ -193,7 +212,7 @@ Allows setting a style for the object border. The following choices are availabl #### 参照 -[Dotted Line Type](#dotted-line-type) (shapes) +[点線タイプ](#dotted-line-type) (図形) --- @@ -217,7 +236,7 @@ Allows setting a style for the object border. The following choices are availabl #### 対象オブジェクト -[Button ("custom" style)](./button_overview.md#custom) (with ["custom" Border Line Style](#border-line-style)) - [Check Box ("custom style")](checkbox_overview.md#custom) - [Radio Button ("custom" style)](radio_overview.md#custom) +(["カスタム" 境界線スタイル](#border-line-style)を持った)[ボタン("カスタム"スタイル)](./button_overview.md#カスタム) - [チェックボックス("カスタムスタイル")](checkbox_overview.md#カスタム) - [ラジオボタン("カスタム" スタイル)](radio_overview.md#カスタム) --- @@ -258,7 +277,7 @@ Allows setting a style for the object border. The following choices are availabl #### 対象オブジェクト -[Button ("custom" style)](./button_overview.md#custom) (with ["custom" Border Line Style](#border-line-style)) - [Check Box ("custom" style)](checkbox_overview.md#custom) - [Input](input_overview.md) - [Rectangle](shapes_overview.md#rectangle) - [Text Area](text.md) - [Radio Button ("custom" style)](radio_overview.md#custom) +(["カスタム"境界線スタイル](#border-line-style)を持った)[ボタン("カスタム"スタイル)](./button_overview.md#カスタム) - [チェックボックス("カスタム" スタイル)](checkbox_overview.md#カスタム) - [入力](input_overview.md) - [四角形](shapes_overview.md#四角形) - [テキストエリア](text.md) - [ラジオボタン("カスタム" スタイル)](radio_overview.md#カスタム) #### コマンド @@ -326,7 +345,7 @@ Allows setting a style for the object border. The following choices are availabl :::note -This property is also available for objects with text properties, in which case it designates both the [Font color](properties_Text.md#font-color) and the object's lines, except if you used the [Border color](#border-color) property. +このプロパティはテキストプロパティを持つオブジェクトでも利用可能で、その場合には[フォントカラー](properties_Text.md#フォントカラー) とオブジェクトの線の両方を指定します(ただし[境界線カラー](#border-color) プロパティを使用していた場合を除く)。 ::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/properties_DataSource.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/properties_DataSource.md index eb65c9a24b8189..a49a59fa28efef 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/properties_DataSource.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/properties_DataSource.md @@ -330,7 +330,7 @@ title: データソース 使用する命名セレクションを指定します。有効な命名セレクションの名前を入力しなければなりません。使用できるのはプロセスあるいはインタープロセス命名セレクションです。リストボックスの内容はこのセレクションに基づきます。選択された命名セレクションは、リストボックスが表示される時点で存在し、有効でなければなりません。 そうでない場合、リストボックスは空で表示されます。 -> 命名セレクションはソート済みのレコードリストです。これはセレクション中のカレントレコードと並び順をメモリに保持するために使用されます。 For more information, refer to [**Named Selections**](../Develop/named-selections) section. +> 命名セレクションはソート済みのレコードリストです。これはセレクション中のカレントレコードと並び順をメモリに保持するために使用されます。詳細な情報については、[**命名セレクション**](../Develop/named-selections) の章を参照してください。 #### JSON 文法 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/radio_overview.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/radio_overview.md index 42308774eca1c3..3141ea53ed0c0a 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/radio_overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/FormObjects/radio_overview.md @@ -154,7 +154,7 @@ Office XPボタンの反転表示と背景のカラーはシステムカラー [カスタム](#カスタム) スタイルのラジオボタンに対しては特有の追加のプロパティが利用可能です: -[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#境界線カラー) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) +[背景パス名](properties_TextAndPicture.md#背景パス名) - [境界線カラー](./properties_BackgroundAndBorder.md#border-color) - [境界線幅](./properties_BackgroundAndBorder.md#境界線幅) - [横方向マージン](properties_TextAndPicture.md#横方向マージン) - [アイコンオフセット](properties_TextAndPicture.md#アイコンオフセット) - [縦方向マージン](properties_TextAndPicture.md#縦方向マージン) - [角の半径](properties_CoordinatesAndSizing.md#角の半径) - [塗りカラー](./properties_BackgroundAndBorder.md#背景色塗りカラー) ## サポートされるイベント diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md index 152a9ae07d86a3..45c7da959b4da2 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/ORDA/privileges.md @@ -67,6 +67,12 @@ Webユーザーまたは RESTユーザーがログインすると、そのセッ 権限の設定には一貫性が必要です。特に、**update** および **drop** 権限は**read** 権限も必要とします(ただし**create** はそれを必要としません)。 +:::warning + +When a permission entry references an undeclared [privilege](#privileges-and-roles), 4D logs an error and ignores the entry. In this case, the permission is ignored. If the [restricted mode by default](#restriction-modes) is not enabled, the resource is accessible to `guest` sessions. + +::: + ### 継承されたパーミッション あるレベルにおいて定義されたパーミッションは基本的に下位レベルに継承されますが、パーミッションは複数のレベルで設定することもできます: 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..c71a3fa7cee303 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/embedding-studio/Classes/Process.md @@ -0,0 +1,188 @@ +--- +id: プロセス +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/server/exit.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/server/exit.md index e82964e7c77c85..aeb7a0c9bdc984 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/server/exit.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/server/exit.md @@ -27,15 +27,15 @@ title: 4D Serverを終了する - **全てのクライアントが切断するのを待つ** -サーバーは、スリープモードに入っているものも含めて全てのクライアントが切断するまで終了するのをまちます。このオプションは、例えば昼休み中のメンテナンス処理などには不向きな可能性があります。何故なら[スリープモード](../ServerWindow/users.md#managing-sleeping-users) に入っているクライアントがあることが容易に想像できるからです。 +サーバーは、スリープモードに入っているものも含めて全てのクライアントが切断するまで終了するのをまちます。サーバーは、スリープモードに入っているものも含めて全てのクライアントが切断するまで終了するのをまちます。このオプションは、例えば昼休み中のメンテナンス処理などには不向きな可能性があります。何故なら[スリープモード](../ServerWindow/sessions.md#management-of-sleeping-client-sessions) に入っているクライアントがあることが容易に想像できるからです。 - **アクティブなクライアントが切断するのを待つ(スリープのクライアントは無視)** -サーバーはアクティブなクライアントが全て切断したあとに終了します(言い換えると、[スリープモード](../ServerWindow/users.md#managing-sleeping-users) に入っていない全てのクライアントマシンということです)。このオプションを使用すると、スリープモードに入っているクライアントはどれも接続しているとは見なされません。例えば昼休み中にメンテナンスオペレーションを実行したい場合などは、このオプションを使用して下さい。このオプションが使用されているとき、スリープモードに入っているクライアントは復帰時に接続エラーが表示されます。 +サーバーはアクティブなクライアントが全て切断したあとに終了します(言い換えると、[スリープモード](../ServerWindow/sessions.md#management-of-sleeping-client-sessions) に入っていない全てのクライアントマシンということです)。このオプションを使用すると、スリープモードに入っているクライアントはどれも接続しているとは見なされません。例えば昼休み中にメンテナンスオペレーションを実行したい場合などは、このオプションを使用して下さい。このオプションが使用されているとき、スリープモードに入っているクライアントは復帰時に接続エラーが表示されます。 :::note -*スリープ中のクライアント* とは、サーバーマシンへの接続がアクティブである間に[スリープモード](../ServerWindow/users.md#managing-sleeping-users) へと切り替わったマシン上にあるリモートの4Dアプリケーションのことをさします。 +*スリープ中のクライアント* とは、サーバーマシンへの接続がアクティブである間に[スリープモード](../ServerWindow/sessions.md#management-of-sleeping-client-sessions) へと切り替わったマシン上にあるリモートの4Dアプリケーションのことをさします。 ::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/settings/client-server.md b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/settings/client-server.md index c1fa2e6bd3e050..c227a9f481a69c 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/settings/client-server.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21-R5/settings/client-server.md @@ -133,7 +133,7 @@ Single Sign On (SSO) が有効になっている場合 (上述参照)、認証 - **しない**: ローカルの **Resources** フォルダーはセッション中に更新されません。サーバーから送信される通知は無視されます。**ローカルリソースを更新** アクションメニューコマンド [(リソースエクスプローラーを使用する](https://doc.4d.com/4Dv20/4D/20.2/Using-the-Resources-explorer.300-6750254.ja.html) 参照) を使用すれば、ローカルの **Resources**フォルダーを手動で更新することができます。 - **常に**: セッション中にサーバーから通知が送信されると、ローカルの **Resources** フォルダーは自動で同期されます。 -- **その都度指定**: サーバーから通知を受け取ると、クライアントマシン上でダイアログボックスが表示されます。ユーザーはローカルの **Resources** フォルダーの同期を受け入れ、あるいは拒否できます。\ **Resources** フォルダーは、データベースインターフェースで使用されるカスタムファイルを格納しています (翻訳ファイルやピクチャーなど)。このフォルダーの内容が更新されたときには、自動又は手動メカニズムを使用して各クライアントに通知できます。詳細な情報については、[Resources フォルダーの管理](../Desktop/clientServer.md#resources-フォルダー) の章を参照してください。 +- **その都度指定**: サーバーから通知を受け取ると、クライアントマシン上でダイアログボックスが表示されます。ユーザーはローカルの **Resources** フォルダーの同期を受け入れ、あるいは拒否できます。\ **Resources** フォルダーは、データベースインターフェースで使用されるカスタムファイルを格納しています (翻訳ファイルやピクチャーなど)。このフォルダーの内容が更新されたときには、自動又は手動メカニズムを使用して各クライアントに通知できます。 For more information, please refer to the [Resources folder](../Desktop/clientServer.md#resources-folder) section. ## IP設定ページ diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21/API/UDPSocketClass.md b/i18n/ja/docusaurus-plugin-content-docs/version-21/API/UDPSocketClass.md index 0c1dbad2f3a70f..b67c3948f52d7d 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21/API/UDPSocketClass.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21/API/UDPSocketClass.md @@ -48,7 +48,7 @@ UDPSocket オブジェクトは以下のプロパティと関数を提供しま | 引数 | 型 | | 説明 | | ------- | --------- | --------------------------- | ------------------------------------------------------------------------ | | port | Integer | -> | UDP ソケットに使用されるローカルのポート番号(0 または省略時には使用されていないポートを探して使用) | -| options | Object | -> | ソケットの接続[オプション](#options引数) | +| options | Object | -> | ソケットの接続[オプション](#options-引数) | | 戻り値 | UDPSocket | <- | 新規UDPSocket オブジェクト | diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21/API/WebSocketServerClass.md b/i18n/ja/docusaurus-plugin-content-docs/version-21/API/WebSocketServerClass.md index 46c9869c156df3..6a2aee10041f99 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21/API/WebSocketServerClass.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21/API/WebSocketServerClass.md @@ -37,7 +37,7 @@ WebSocketプロトコルは、WebSocketサーバーとクライアント (Webブ - サーバー接続を処理するためのユーザークラス - メッセージを処理するためのユーザークラス -接続を維持するため、[WebSocketサーバーの作成](#4dwebsocketservernew) は [ワーカー](../Develop/processes.md#worker-プロセス) 内にて行う必要があります。 +接続を維持するため、[WebSocketサーバーの作成](#4dwebsocketservernew) は [ワーカー](../Develop/processes.md#ワーカープロセス) 内にて行う必要があります。 [4D Webサーバー](WebServerClass.md) を起動しておく必要があります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21/Desktop/labels.md b/i18n/ja/docusaurus-plugin-content-docs/version-21/Desktop/labels.md index 4c5a8115de97f9..75f7b2d1352b2f 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21/Desktop/labels.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21/Desktop/labels.md @@ -164,7 +164,7 @@ title: ラベル var myVar+=1 ``` -3. プロジェクトメソッドに対して["コンポーネントとホストデータベース間で共有"](../Project/project-method-properties.md#コンポーネントとホストデータベース間で共有) オプションを設定します。 +3. プロジェクトメソッドに対して["コンポーネントとホストデータベース間で共有"](../Project/project-method-properties.md#コンポーネントとホストプロジェクト間で共有) オプションを設定します。 4. ラベルエディターを表示する前に、以下のコードを実行してプロジェクトメソッドが確実に許可されているようにします: diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21/Develop/preemptive.md b/i18n/ja/docusaurus-plugin-content-docs/version-21/Develop/preemptive.md index 2b352f5da304cc..e2b1bc924d9740 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21/Develop/preemptive.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21/Develop/preemptive.md @@ -41,7 +41,7 @@ title: プリエンプティブプロセス 要素毎の "スレッドセーフティ" プロパティは、その要素自身によります: -- 4Dコマンド: スレッドセーフティは内部プロパティです。 4D ドキュメンテーション内においては、スレッドセーフなコマンドには ![](../assets/en/Develop/thread-safe.png) アイコンが表示されています。 [`Command name`](../commands/command-name.md) コマンドを使用して、コマンドがスレッドセーフであるかどうかを知ることもできます。 4Dコマンドの大部分はプリエンプティブモードで実行可能です。 +- 4Dコマンド: スレッドセーフティは内部プロパティです。 The 4D documentation indicates whether each command is thread-safe or not in the Properties section. [`Command name`](../commands/command-name.md) コマンドを使用して、コマンドがスレッドセーフであるかどうかを知ることもできます。 4Dコマンドの大部分はプリエンプティブモードで実行可能です。 - プロジェクトメソッド: スレッドセーフであるための条件は [こちらの段落](#スレッドセーフなメソッドの書き方) にまとめられています。 原則として、プリエンプティブスレッド内で実行されるコードは外部との相互作用する部分、たとえばプラグインコードやインタープロセス変数などを呼び出すことはできません。しかしながら、4Dデータサーバーと ORDA はプリエンプティブ実行をサポートしていることから、データアクセスは可能です。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21/Develop/processes.md b/i18n/ja/docusaurus-plugin-content-docs/version-21/Develop/processes.md index 0d09a30c963552..50ddcc5854fde2 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21/Develop/processes.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21/Develop/processes.md @@ -50,7 +50,7 @@ title: プロセスとワーカー ### インターフェース要素 -インターフェース要素は、[デスクトップアプリケーション](../category/desktop-applications) で使用されます。 以下のものがあります: 以下のものがあります: +インターフェース要素は、[デスクトップアプリケーション](../category/desktop-applications) で使用されます。以下のものがあります: - [メニューバー](../Menus/creating.md): 各プロセスは、独自のカレントメニューバーを持つことができます。最前面のプロセスのメニューバーがアプリケーションのカレントメニューバーになります。 - 1つ以上のウィンドウ: 各プロセスは、1つまたは複数のウィンドウを同時に開くことができます。他方、ウィンドウをまったく持たないプロセスもあります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-21/FormEditor/createStylesheet.md b/i18n/ja/docusaurus-plugin-content-docs/version-21/FormEditor/createStylesheet.md index a9f7e82321de26..bec2c9ab9fb1cd 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-21/FormEditor/createStylesheet.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-21/FormEditor/createStylesheet.md @@ -126,7 +126,7 @@ text.center { } ``` -4D フォームの詳細では、[CSSクラス](../FormObjects/properties_Object.md#cssクラス) 属性を使用してクラス名を割り当てます。この属性には一つ以上のクラス名を指定することができます。 複数の場合はクラス名を半角スペースで区切ります: +4D フォームの詳細では、[CSSクラス](../FormObjects/properties_Object.md#cssクラス) 属性を使用してクラス名を割り当てます。この属性には一つ以上のクラス名を指定することができます。複数の場合はクラス名を半角スペースで区切ります: ``` class: "okButtons important"