From d4ad6be838481095514b403179c28753e496a9f7 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Sat, 14 Nov 2026 10:36:48 +0000 Subject: [PATCH 1/4] Document published Server visibility query language --- docs/features/search-attributes.md | 2 + docs/polyglot/server-api-reference.md | 4 +- docs/polyglot/visibility-query-language.md | 143 +++++++++++++++++++++ sidebars.js | 1 + 4 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 docs/polyglot/visibility-query-language.md diff --git a/docs/features/search-attributes.md b/docs/features/search-attributes.md index 5c0db55bb4a..3fde78a57ad 100644 --- a/docs/features/search-attributes.md +++ b/docs/features/search-attributes.md @@ -139,6 +139,8 @@ Search attributes appear in: - **History timeline** — each `SearchAttributesUpserted` event appears as a typed entry in the run timeline - **History export** — search attributes are included in JSON history exports +For Server-side typed comparisons, time ranges, membership, quoting and HTTP pagination, use the [Visibility Query Language](../polyglot/visibility-query-language.md). Current embedded listing and Waterline saved-view filters do not implement that full grammar. Shared parity remains pending in [the visibility-query feature](https://github.com/durable-workflow/.github/issues/224). + ### Parent and child list filters {#parent-child-list-filters} Children [inherit search attributes and memo at creation](./child-workflows.md#child-metadata-inheritance), then can upsert their own values independently. Filtering an inherited attribute does not implicitly exclude children. For a registered keyword attribute, the Server query `customer = 'customer-42'` can return the parent and every child still carrying that value. Memo remains unindexed metadata; it is not another search-attribute filter. diff --git a/docs/polyglot/server-api-reference.md b/docs/polyglot/server-api-reference.md index 9ba5b802165..80c23e89ae2 100644 --- a/docs/polyglot/server-api-reference.md +++ b/docs/polyglot/server-api-reference.md @@ -422,7 +422,7 @@ admin role and `X-Durable-Workflow-Control-Plane-Version: 2`. | Method | Path | Purpose | | --- | --- | --- | -| `GET` | `/api/workflows` | List workflow instances. Supports filters such as status, type, query text, and limit. | +| `GET` | `/api/workflows` | List workflow runs in the namespace, with status, type, visibility query, `page_size` and `next_page_token`. | | `POST` | `/api/workflows` | Start a workflow instance. | | `GET` | `/api/workflows/{workflowId}` | Describe the current run for one workflow id. | | `GET` | `/api/workflows/{workflowId}/debug` | Return bounded diagnostic facts for stuck-run investigation. | @@ -432,6 +432,8 @@ admin role and `X-Durable-Workflow-Control-Plane-Version: 2`. | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history` | Page through run history events. | | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history/export` | Export the archival replay bundle for a run. | +For supported fields, typed comparisons, quoting, precedence, errors and paging examples, see the [Visibility Query Language](./visibility-query-language.md). This listing grammar differs from a workflow's named query handlers and from schedule-list filters. + Start requests use the language-neutral control-plane shape: diff --git a/docs/polyglot/visibility-query-language.md b/docs/polyglot/visibility-query-language.md new file mode 100644 index 00000000000..fbdda4d52c6 --- /dev/null +++ b/docs/polyglot/visibility-query-language.md @@ -0,0 +1,143 @@ +--- +title: Visibility Query Language +description: Filter Server workflow runs by status, time, identity and typed search attributes, with HTTP examples and pagination. +--- + +# Visibility Query Language + +Use `GET /api/workflows?query=...` to find runs in one Server namespace. This reference describes the published native Server selected in the [compatibility manifest](../compatibility.md#last-qualified-reproducible-tuple), currently `%%artifact.serverVersion%%`. Listing reads stored visibility facts. It does not execute a workflow's named query handler. + +The request needs an operator or admin bearer token, `X-Namespace` and `X-Durable-Workflow-Control-Plane-Version: 2`. See [namespace authorization](./namespace-auth-workers.md). Results include matching runs, including earlier runs of an instance and children whose attributes match. There is no built-in roots-only predicate. + +## Make a request {#make-a-request} + +Set `DURABLE_WORKFLOW_SERVER_URL` to your Server base URL and `DURABLE_WORKFLOW_AUTH_TOKEN` to an operator or admin token. This example needs Bash, curl and jq. Replace the fixed UTC interval with the interval you want to inspect. + +```bash +query='Status = failed AND CloseTime >= "2026-11-14T00:00:00Z" AND CloseTime < "2026-11-15T00:00:00Z"' +page=$(curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50') +printf '%s\n' "$page" | jq '{workflow_count, workflows, next_page_token}' +``` + +`Status = failed` selects a bucket that also includes cancelled and terminated runs. Use `Status = cancelled` or `Status = terminated` for those exact statuses. `running` includes pending, running and waiting. `completed` selects completed runs. Status values are case-insensitive. + +Use `--data-urlencode` for the query and page token. Shell quoting, query-string escaping and URL encoding are separate steps. A successful response with `workflows: []` means no runs matched this request. + +## Fields {#fields} + +Field names are case-sensitive. Built-in names take precedence over custom attributes. + +| Field | Value | Operators | +| --- | --- | --- | +| `WorkflowType`, `WorkflowId`, `RunId`, `TaskQueue` | Run type, instance ID, run ID or task queue | `=`, `!=`, `IN`, negated `IN` | +| `Status`, `ExecutionStatus` | Status or status bucket, as above | `=`, `!=` | +| `StartTime`, `ExecutionTime` | The run's start instant. These names are aliases. | Scalar comparisons, `IN`, negated `IN` | +| `CloseTime` | The run's close instant | Scalar comparisons, `IN`, negated `IN` | +| `BuildId`, `BuildIds` | Aliases for the run's compatibility value, not a worker-fleet lookup | Keyword operators, subject to the native refusal below | + +Scalar comparisons are `=`, `!=`, `<`, `<=`, `>` and `>=`. A missing start or close instant never matches a comparison, including a negated one. Native listing refuses a returned run with non-null compatibility as HTTP `409` / `unqualified_build_visibility`. A parsed build predicate does not establish qualified build-based listing. + +Other fields must be registered search attributes in this namespace. Use `GET /api/search-attributes` to inspect definitions and `POST /api/search-attributes` with a JSON body such as `{"name":"OrderTotal","type":"double"}` to register one. Registration needs an admin token. An inferred stored type alone does not make an unregistered key queryable. Deleting a definition leaves stored values but makes queries on that key invalid. + +Identifiers start with an ASCII letter and continue with ASCII letters, digits or `_`. Use the registered name exactly. Memos, visibility labels, business keys and parent/root relationship names are not additional built-in structured fields. Plain search can still find a business key as described below. + +## Types and comparisons {#types-and-comparisons} + +| Registered type | Literal and comparison behavior | +| --- | --- | +| `keyword` | Whole-value text equality or inequality, `IN` and negated `IN`. No ordering. | +| `string`, `text` | Whole-value text comparisons, with the same operators as `keyword`. No substring, full-text or `LIKE` operator. | +| `int` | Unquoted integer, such as `42` or `-3`. Scalar comparisons, `IN` and negated `IN`. A quoted number or a decimal is not an integer literal. | +| `double` | Unquoted integer or decimal, including exponent notation such as `1.5e3`. Scalar comparisons, `IN` and negated `IN`. | +| `bool` | Unquoted `true` or `false`, case-insensitive. Scalar comparisons, `IN` and negated `IN`; `false` sorts before `true`. `1` and `"true"` are not boolean literals. | +| `datetime` | Quoted datetime. Scalar comparisons, `IN` and negated `IN` compare instants. Use explicit UTC or offset timestamps, such as `"2026-11-14T12:34:56.123456Z"`. | +| `keyword_list` | `Tags = "urgent"` tests membership. `Tags IN ("urgent", "review")` matches any listed member. Inequality, ordering and negated membership are refused. | + +A run without a queried attribute never matches that predicate, including `!=` and negated `IN`. There is no existence or `IS NULL` predicate. A value retained under an earlier, different registered type is not automatically converted to the new type. + +Keyword, text and built-in text comparisons follow the database's equality rules. The published MySQL/MariaDB schema uses `utf8mb4_unicode_ci`, which ignores case, accents and trailing spaces. SQLite and the native PostgreSQL comparison are exact. Keyword-list membership is exact. Do not assume identical text results across these backends. + +Datetimes accept ISO dates and timestamps, with fractions retained to microseconds. A date alone means midnight UTC; an omitted timezone is UTC. Use explicit timestamps for portable queries. Relative dates such as `tomorrow` and timezone names such as `Europe/Paris` are not accepted datetime values. Calculate a rolling interval in the caller and send fixed boundaries. + +## Syntax, precedence and escaping {#syntax-and-escaping} + +- Write comparisons as `Field operator literal`. Separate predicates with `AND` or `OR`. Keywords are case-insensitive. +- `NOT` applies to the next predicate, before `AND`; `AND` binds more tightly than `OR`. `A = 1 OR B = 2 AND C = 3` means `A = 1 OR (B = 2 AND C = 3)`. +- Parentheses delimit a nonempty, comma-separated `IN` list. They do not group boolean expressions. Repeat predicates across `OR` branches when necessary. +- Negated membership is **`NOT Region IN ("eu", "us")`**. The SQL spelling `Region NOT IN (...)` is not supported. `Status IN (...)` is also unsupported; use `Status = running OR Status = completed`. +- Use single or double quotes for strings. Escape the chosen quote and a literal backslash with `\`. For example, `Customer = 'O\'Brien'` and `Path = "C:\\orders"`. The parser also decodes C-style escapes such as `\n`, `\t` and `\r`; JSON's `\uXXXX` syntax is not a Unicode escape here. Write Unicode characters directly. +- Bare text literals allow ASCII letters, digits, `_`, `.`, `:`, and `-`. Prefer quoted text so booleans and numbers are not inferred accidentally. There is no SQL `SELECT`, `ORDER BY` or `LIMIT` clause. + +In an expression, a bare registered boolean field can mean `Flag = true`, and `NOT Flag` means `Flag = false`. A lone `Flag` is instead plain search text. Explicit comparisons avoid this ambiguity. + +The Server recognizes an expression from comparison syntax, `IN (...)` or a leading `NOT` predicate. Other text is a substring search over workflow ID and business key. For example, `query=order-1001` is plain search. Unsupported SQL-like text can therefore fall back to plain search rather than produce a syntax error. Use the documented grammar and inspect `query` errors when a recognized expression is invalid. + +## Query examples {#query-examples} + +Pass any expression below as the `query` value in the curl request above. Custom examples assume `OrderTotal: double`, `Attempt: int`, `Region: keyword`, `Tags: keyword_list`, `Approved: bool`, and `DueAt: datetime` are registered and populated in the selected namespace. + +| Task | Query | +| --- | --- | +| Orders over a numeric threshold | `WorkflowType = "orders.fulfillment" AND OrderTotal > 1000` | +| Attempts within an inclusive range | `Attempt >= 2 AND Attempt <= 5` | +| Either region | `Region IN ("eu", "us")` | +| Other recorded regions | `NOT Region IN ("eu", "us")` | +| A tag from either set | `Tags IN ("urgent", "review")` | +| Explicit false | `Approved = false` | +| A time window | `DueAt >= "2026-11-14T00:00:00Z" AND DueAt < "2026-11-15T00:00:00Z"` | +| Two queues under the same type | `WorkflowType = "orders.fulfillment" AND TaskQueue = "orders" OR WorkflowType = "orders.fulfillment" AND TaskQueue = "priority"` | + +## Pagination and limits {#pagination-and-limits} + +| Parameter | Behavior | +| --- | --- | +| `workflow_type` | Optional exact type filter, combined with `query` and `status` using `AND`. | +| `status` | Optional filter. Prefer canonical buckets `running`, `completed` or `failed`. The current list endpoint also accepts exact `cancelled` and `terminated`; `pending` and `waiting` are not accepted here. | +| `page_size` | Integer from `1` to `200`, default `50`. Use this parameter, not `limit`. | +| `next_page_token` | Copy the previous response's token without decoding or constructing it. Stop when it is null. | + +`workflow_count` is the number in this page, not the total number of matching runs. Results are ordered by descending start/sort time, then descending run ID. Paging reads live data using an offset. Keep namespace, query, filters and page size unchanged. Inserts, closures or attribute updates between requests can move matches and cause repeats or omissions; this is not a snapshot export. An invalid token currently restarts at the first page rather than returning an error. + +Fetch the next page from the first example, if present: + +```bash +next=$(printf '%s\n' "$page" | jq -r '.next_page_token // empty') +if [ -n "$next" ]; then + curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50' \ + --data-urlencode "next_page_token=$next" | jq . +fi +``` + +Page size limits returned rows, not query evaluation work. Keep expressions and `IN` lists small and use selective type, status or attribute predicates. The workflow parser does not define the schedule API's 2048-character query limit. HTTP servers and proxies can impose their own request-URI limits. [Schedule listing](./server-api-reference.md#schedule-list-filters) has a different, equality-and-`AND` grammar. + +## Invalid queries {#invalid-queries} + +A recognized expression that fails parsing, field lookup or type checking returns HTTP `422` with `reason: "validation_failed"`, a `message`, and arrays in `errors.query` and `validation_errors.query`. An invalid page size or status uses that parameter's key instead. + +| Invalid expression | Correction | +| --- | --- | +| `Unknown = 1` | Register the attribute in this namespace or correct the field name. | +| `OrderTotal = "1000"` | Use the numeric literal `1000`. | +| `Approved = 1` | Use `true` or `false`. | +| `Region > "eu"` | Keywords support equality and membership, not ordering. | +| `Tags != "urgent"` or `NOT Tags IN ("urgent")` | Negative membership is not supported for keyword lists. | +| `Attempt IN ()`, `Attempt = 1 AND` | Supply a nonempty list or complete predicate. | +| `DueAt > "tomorrow"` | Send a concrete timestamp. | + +## Embedded mode and Waterline {#mode-support} + +This language is available through the Server workflow-list API. Current embedded listing and Waterline saved-view filters do not implement this full grammar. Their existing exact `key=value` metadata filters and substring fields do not establish range, `IN`, `!=` or boolean-expression support. Service-mode Waterline also needs explicit UI/API support before a saved view can be treated as this query language. Shared parity work remains open in [the visibility-query feature](https://github.com/durable-workflow/.github/issues/224). + +The reference follows the [published native parser and its unit tests](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility_query.rs), [HTTP pagination implementation](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility.rs), and [listing API tests](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/tests/execution/visibility.rs). These describe the published Server behavior, not completion of embedded or Waterline parity. diff --git a/sidebars.js b/sidebars.js index df8c65dd940..1d3705c4b33 100644 --- a/sidebars.js +++ b/sidebars.js @@ -52,6 +52,7 @@ const sidebars = { 'polyglot/cli-python-parity', 'polyglot/server-config-reference', 'polyglot/server-api-reference', + 'polyglot/visibility-query-language', 'polyglot/server-role-topology', 'polyglot/namespace-auth-workers', 'polyglot/worker-compatibility-routing', From b9cfa8e4c875a72d26cc11de7badd7b236d5f633 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Sat, 14 Nov 2026 10:53:32 +0000 Subject: [PATCH 2/4] Translate visibility query reference into all seven locales --- .../current/features/search-attributes.md | 2 + .../current/polyglot/server-api-reference.md | 4 +- .../polyglot/visibility-query-language.md | 143 ++++++++++++++++++ i18n/de/source-hashes.json | 5 +- .../current/features/search-attributes.md | 2 + .../current/polyglot/server-api-reference.md | 4 +- .../polyglot/visibility-query-language.md | 143 ++++++++++++++++++ i18n/es/source-hashes.json | 5 +- .../current/features/search-attributes.md | 2 + .../current/polyglot/server-api-reference.md | 4 +- .../polyglot/visibility-query-language.md | 143 ++++++++++++++++++ i18n/fr/source-hashes.json | 5 +- .../current/features/search-attributes.md | 2 + .../current/polyglot/server-api-reference.md | 4 +- .../polyglot/visibility-query-language.md | 143 ++++++++++++++++++ i18n/ja/source-hashes.json | 5 +- .../current/features/search-attributes.md | 2 + .../current/polyglot/server-api-reference.md | 4 +- .../polyglot/visibility-query-language.md | 143 ++++++++++++++++++ i18n/pt-BR/source-hashes.json | 5 +- .../current/features/search-attributes.md | 2 + .../current/polyglot/server-api-reference.md | 4 +- .../polyglot/visibility-query-language.md | 143 ++++++++++++++++++ i18n/uk/source-hashes.json | 5 +- .../current/features/search-attributes.md | 2 + .../current/polyglot/server-api-reference.md | 4 +- .../polyglot/visibility-query-language.md | 143 ++++++++++++++++++ i18n/zh-Hans/source-hashes.json | 5 +- 28 files changed, 1057 insertions(+), 21 deletions(-) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md create mode 100644 i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md create mode 100644 i18n/uk/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/features/search-attributes.md b/i18n/de/docusaurus-plugin-content-docs/current/features/search-attributes.md index 3751bea1038..e19961a0147 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/features/search-attributes.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/features/search-attributes.md @@ -155,6 +155,8 @@ Suchattribute erscheinen in: - **Historienzeitleiste**: Jedes `SearchAttributesUpserted`-Ereignis erscheint als typisierter Eintrag in der Laufzeitleiste. - **Historienexport**: Suchattribute sind in JSON-Historienexporten enthalten. +Für typisierte Vergleiche, Zeitbereiche, Mitgliedschaft, Anführungszeichen und HTTP-Seitennavigation auf dem Server verwenden Sie die [Visibility-Abfragesprache](../polyglot/visibility-query-language.md). Aktuelle Embedded-Listen und gespeicherte Waterline-Ansichtsfilter implementieren nicht die vollständige Grammatik. Die gemeinsame Parität bleibt im [Visibility-Query-Feature](https://github.com/durable-workflow/.github/issues/224) offen. + ### Listenfilter für Eltern und Kinder {#parent-child-list-filters} Kinder [erben Suchattribute und Memo bei der Erstellung](./child-workflows.md#child-metadata-inheritance) und können ihre Werte danach unabhängig ändern. Das Filtern eines geerbten Attributs schließt Kinder nicht automatisch aus. Bei einem registrierten Keyword-Attribut kann die Server-Abfrage `customer = 'customer-42'` den Elternlauf und jedes Kind mit diesem Wert zurückgeben. Memo bleibt nicht indizierte Metadaten und ist kein weiterer Suchattributfilter. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md index 30a705db1a9..5ce48c5bb52 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md @@ -407,7 +407,7 @@ Operator oder Admin und `X-Durable-Workflow-Control-Plane-Version: 2`. | Methode | Pfad | Zweck | | --- | --- | --- | -| `GET` | `/api/workflows` | Workflow-Instanzen auflisten. Unterstützt Filter wie Status, Typ, Abfragetext und Grenze. | +| `GET` | `/api/workflows` | Workflow-Ausführungen im Namespace mit Status, Typ, Visibility-Abfrage, `page_size` und `next_page_token` auflisten. | | `POST` | `/api/workflows` | Workflow-Instanz starten. | | `GET` | `/api/workflows/{workflowId}` | Aktuellen Lauf einer Workflow-ID beschreiben. | | `GET` | `/api/workflows/{workflowId}/debug` | Begrenzte Diagnoseangaben für festhängende Läufe liefern. | @@ -417,6 +417,8 @@ Operator oder Admin und `X-Durable-Workflow-Control-Plane-Version: 2`. | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history` | Laufhistorienereignisse seitenweise lesen. | | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history/export` | Replay-Archivpaket eines Laufs exportieren. | +Felder, typisierte Vergleiche, Anführungszeichen, Rangfolge, Fehler und Seitenbeispiele beschreibt die [Visibility-Abfragesprache](./visibility-query-language.md). Diese Listengrammatik unterscheidet sich von benannten Workflow-Abfrage-Handlern und Schedule-Listenfiltern. + Startanfragen verwenden die sprachneutrale Control-Plane-Struktur: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md new file mode 100644 index 00000000000..42ff73cf0a4 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -0,0 +1,143 @@ +--- +title: Visibility-Abfragesprache +description: Server-Ausführungen nach Status, Zeit, Identität und typisierten Suchattributen filtern, mit HTTP-Beispielen und Seitennavigation. +--- + +# Visibility-Abfragesprache + +Mit `GET /api/workflows?query=...` finden Sie Ausführungen in einem Server-Namespace. Diese Referenz beschreibt den veröffentlichten nativen Server aus dem [Kompatibilitätsmanifest](../compatibility.md#last-qualified-reproducible-tuple), derzeit `%%artifact.serverVersion%%`. Die Auflistung liest gespeicherte Sichtbarkeitsdaten. Sie führt keinen benannten Abfrage-Handler eines Workflows aus. + +Die Anfrage benötigt ein Bearer-Token mit Operator- oder Admin-Rolle, `X-Namespace` und `X-Durable-Workflow-Control-Plane-Version: 2`. Siehe [Namespace-Autorisierung](./namespace-auth-workers.md). Ergebnisse enthalten passende Ausführungen, auch frühere Ausführungen einer Instanz und Kinder mit passenden Attributen. Ein eingebautes Prädikat nur für Wurzeln gibt es nicht. + +## Anfrage senden {#make-a-request} + +Setzen Sie `DURABLE_WORKFLOW_SERVER_URL` auf die Basis-URL Ihres Servers und `DURABLE_WORKFLOW_AUTH_TOKEN` auf ein Operator- oder Admin-Token. Das Beispiel benötigt Bash, curl und jq. Ersetzen Sie das feste UTC-Intervall durch den gewünschten Zeitraum. + +```bash +query='Status = failed AND CloseTime >= "2026-11-14T00:00:00Z" AND CloseTime < "2026-11-15T00:00:00Z"' +page=$(curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50') +printf '%s\n' "$page" | jq '{workflow_count, workflows, next_page_token}' +``` + +`Status = failed` wählt einen Statusbereich, der auch abgebrochene und terminierte Ausführungen enthält. `Status = cancelled` und `Status = terminated` wählen diese Status exakt. `running` umfasst pending, running und waiting. `completed` wählt abgeschlossene Ausführungen. Bei Statuswerten spielt die Groß-/Kleinschreibung keine Rolle. + +Verwenden Sie `--data-urlencode` für Abfrage und Seitentoken. Shell-Anführungszeichen, Escape-Sequenzen der Abfragesprache und URL-Kodierung sind getrennte Schritte. Eine erfolgreiche Antwort mit `workflows: []` bedeutet, dass keine Ausführung zu dieser Anfrage passt. + +## Felder {#fields} + +Feldnamen unterscheiden Groß- und Kleinschreibung. Eingebaute Namen haben Vorrang vor benutzerdefinierten Attributen. + +| Feld | Wert | Operatoren | +| --- | --- | --- | +| `WorkflowType`, `WorkflowId`, `RunId`, `TaskQueue` | Ausführungstyp, Instanz-ID, Ausführungs-ID oder Task-Queue | `=`, `!=`, `IN`, negiertes `IN` | +| `Status`, `ExecutionStatus` | Status oder Statusbereich wie oben | `=`, `!=` | +| `StartTime`, `ExecutionTime` | Startzeitpunkt der Ausführung. Die Namen sind Aliasse. | Skalarvergleiche, `IN`, negiertes `IN` | +| `CloseTime` | Abschlusszeitpunkt der Ausführung | Skalarvergleiche, `IN`, negiertes `IN` | +| `BuildId`, `BuildIds` | Aliasse für den Kompatibilitätswert der Ausführung, keine Suche in der Worker-Flotte | Keyword-Operatoren, mit der unten beschriebenen nativen Ablehnung | + +Skalarvergleiche sind `=`, `!=`, `<`, `<=`, `>` und `>=`. Ein fehlender Start- oder Abschlusszeitpunkt erfüllt keinen Vergleich, auch keinen negierten. Die native Auflistung verweigert eine zurückzugebende Ausführung mit einem nicht-null Kompatibilitätswert mit HTTP `409` / `unqualified_build_visibility`. Ein geparstes Build-Prädikat belegt keine qualifizierte Build-basierte Auflistung. + +Andere Felder müssen registrierte Suchattribute in diesem Namespace sein. Lesen Sie Definitionen mit `GET /api/search-attributes` und registrieren Sie ein Attribut mit `POST /api/search-attributes` und einem JSON-Body wie `{"name":"OrderTotal","type":"double"}`. Die Registrierung benötigt ein Admin-Token. Ein abgeleiteter gespeicherter Typ allein macht einen unregistrierten Schlüssel nicht abfragbar. Das Löschen einer Definition erhält gespeicherte Werte, macht Abfragen dieses Schlüssels aber ungültig. + +Bezeichner beginnen mit einem ASCII-Buchstaben, gefolgt von ASCII-Buchstaben, Ziffern oder `_`. Verwenden Sie den registrierten Namen exakt. Memos, Sichtbarkeitslabels, Geschäftsschlüssel und Namen für Eltern-/Wurzelbeziehungen sind keine zusätzlichen eingebauten strukturierten Felder. Die einfache Suche kann einen Geschäftsschlüssel weiterhin wie unten beschrieben finden. + +## Typen und Vergleiche {#types-and-comparisons} + +| Registrierter Typ | Literale und Vergleichsverhalten | +| --- | --- | +| `keyword` | Gleichheit oder Ungleichheit des gesamten Textwerts, `IN` und negiertes `IN`. Keine Ordnung. | +| `string`, `text` | Vergleich des gesamten Textwerts mit denselben Operatoren wie `keyword`. Keine Teilstring-, Volltext- oder `LIKE`-Suche. | +| `int` | Ganzzahl ohne Anführungszeichen, etwa `42` oder `-3`. Skalarvergleiche, `IN` und negiertes `IN`. Eine Zahl in Anführungszeichen oder eine Dezimalzahl ist kein Ganzzahlliteral. | +| `double` | Ganz- oder Dezimalzahl ohne Anführungszeichen, auch Exponentialschreibweise wie `1.5e3`. Skalarvergleiche, `IN` und negiertes `IN`. | +| `bool` | `true` oder `false` ohne Anführungszeichen, unabhängig von Groß-/Kleinschreibung. Skalarvergleiche, `IN` und negiertes `IN`; `false` liegt vor `true`. `1` und `"true"` sind keine booleschen Literale. | +| `datetime` | Datum/Zeit in Anführungszeichen. Skalarvergleiche, `IN` und negiertes `IN` vergleichen Zeitpunkte. Verwenden Sie explizite UTC- oder Offset-Zeitstempel, etwa `"2026-11-14T12:34:56.123456Z"`. | +| `keyword_list` | `Tags = "urgent"` prüft die Mitgliedschaft. `Tags IN ("urgent", "review")` trifft bei mindestens einem aufgeführten Element zu. Ungleichheit, Ordnung und negierte Mitgliedschaft werden abgelehnt. | + +Fehlt einer Ausführung das abgefragte Attribut, erfüllt sie das Prädikat nie, auch bei `!=` und negiertem `IN`. Es gibt kein Existenz- oder `IS NULL`-Prädikat. Ein Wert mit einem früheren, anderen registrierten Typ wird nicht automatisch in den neuen Typ umgewandelt. + +Keyword-, Text- und eingebaute Textvergleiche folgen den Gleichheitsregeln der Datenbank. Das veröffentlichte MySQL-/MariaDB-Schema nutzt `utf8mb4_unicode_ci` und ignoriert Groß-/Kleinschreibung, Akzente und nachgestellte Leerzeichen. SQLite und der native PostgreSQL-Vergleich sind exakt. Mitgliedschaft in Keyword-Listen ist exakt. Gehen Sie nicht von identischen Textergebnissen auf diesen Backends aus. + +Datum/Zeit akzeptiert ISO-Daten und Zeitstempel mit Bruchteilen bis zu Mikrosekunden. Ein Datum allein bedeutet Mitternacht UTC; ohne Zeitzone gilt UTC. Verwenden Sie für portable Abfragen explizite Zeitstempel. Relative Angaben wie `tomorrow` und Zeitzonennamen wie `Europe/Paris` werden nicht als Datum/Zeit akzeptiert. Berechnen Sie gleitende Intervalle im Aufrufer und senden Sie feste Grenzen. + +## Syntax, Rangfolge und Escape-Sequenzen {#syntax-and-escaping} + +- Schreiben Sie Vergleiche als `Field operator literal`. Verbinden Sie Prädikate mit `AND` oder `OR`. Schlüsselwörter sind unabhängig von Groß-/Kleinschreibung. +- `NOT` gilt für das nächste Prädikat vor `AND`; `AND` bindet stärker als `OR`. `A = 1 OR B = 2 AND C = 3` bedeutet `A = 1 OR (B = 2 AND C = 3)`. +- Klammern begrenzen eine nichtleere, kommagetrennte `IN`-Liste. Sie gruppieren keine booleschen Ausdrücke. Wiederholen Sie nötigenfalls Prädikate in den `OR`-Zweigen. +- Negierte Mitgliedschaft lautet **`NOT Region IN ("eu", "us")`**. Die SQL-Schreibweise `Region NOT IN (...)` wird nicht unterstützt. Auch `Status IN (...)` wird nicht unterstützt; verwenden Sie `Status = running OR Status = completed`. +- Verwenden Sie einfache oder doppelte Anführungszeichen für Strings. Maskieren Sie das gewählte Anführungszeichen und einen literalen Backslash mit `\`. Beispiele: `Customer = 'O\'Brien'` und `Path = "C:\\orders"`. Der Parser dekodiert auch C-Escapes wie `\n`, `\t` und `\r`; JSONs `\uXXXX` ist hier kein Unicode-Escape. Schreiben Sie Unicode-Zeichen direkt. +- Textliterale ohne Anführungszeichen erlauben ASCII-Buchstaben, Ziffern, `_`, `.`, `:` und `-`. Bevorzugen Sie Anführungszeichen, damit nicht versehentlich boolesche Werte oder Zahlen abgeleitet werden. SQL-Klauseln `SELECT`, `ORDER BY` und `LIMIT` gibt es nicht. + +In einem Ausdruck kann ein bloßer registrierter boolescher Feldname `Flag = true` bedeuten; `NOT Flag` bedeutet `Flag = false`. Ein alleinstehendes `Flag` ist dagegen einfacher Suchtext. Explizite Vergleiche vermeiden diese Mehrdeutigkeit. + +Der Server erkennt einen Ausdruck an Vergleichssyntax, `IN (...)` oder einem führenden `NOT`-Prädikat. Anderer Text sucht Teilstrings in Workflow-ID und Geschäftsschlüssel. Zum Beispiel ist `query=order-1001` eine einfache Suche. Nicht unterstützter SQL-ähnlicher Text kann daher als einfache Suche behandelt werden, statt einen Syntaxfehler zu liefern. Verwenden Sie die dokumentierte Grammatik und prüfen Sie `query`-Fehler bei ungültigen erkannten Ausdrücken. + +## Abfragebeispiele {#query-examples} + +Übergeben Sie jeden folgenden Ausdruck als `query`-Wert der obigen curl-Anfrage. Die benutzerdefinierten Beispiele setzen voraus, dass `OrderTotal: double`, `Attempt: int`, `Region: keyword`, `Tags: keyword_list`, `Approved: bool` und `DueAt: datetime` im gewählten Namespace registriert und befüllt sind. + +| Aufgabe | Abfrage | +| --- | --- | +| Bestellungen über einem numerischen Schwellenwert | `WorkflowType = "orders.fulfillment" AND OrderTotal > 1000` | +| Versuche in einem inklusiven Bereich | `Attempt >= 2 AND Attempt <= 5` | +| Eine von zwei Regionen | `Region IN ("eu", "us")` | +| Andere gespeicherte Regionen | `NOT Region IN ("eu", "us")` | +| Ein Tag aus der Liste | `Tags IN ("urgent", "review")` | +| Explizites false | `Approved = false` | +| Ein Zeitfenster | `DueAt >= "2026-11-14T00:00:00Z" AND DueAt < "2026-11-15T00:00:00Z"` | +| Zwei Queues unter demselben Typ | `WorkflowType = "orders.fulfillment" AND TaskQueue = "orders" OR WorkflowType = "orders.fulfillment" AND TaskQueue = "priority"` | + +## Seitennavigation und Grenzen {#pagination-and-limits} + +| Parameter | Verhalten | +| --- | --- | +| `workflow_type` | Optionaler exakter Typfilter, mit `query` und `status` durch `AND` kombiniert. | +| `status` | Optionaler Filter. Bevorzugen Sie die kanonischen Bereiche `running`, `completed` oder `failed`. Der aktuelle Listenendpunkt akzeptiert auch exakt `cancelled` und `terminated`; `pending` und `waiting` sind hier nicht erlaubt. | +| `page_size` | Ganzzahl von `1` bis `200`, Standard `50`. Verwenden Sie diesen Parameter statt `limit`. | +| `next_page_token` | Kopieren Sie das Token der vorherigen Antwort, ohne es zu dekodieren oder selbst zu erzeugen. Stoppen Sie bei null. | + +`workflow_count` zählt die Elemente dieser Seite, nicht alle passenden Ausführungen. Ergebnisse sind nach absteigender Start-/Sortierzeit, dann absteigender Ausführungs-ID geordnet. Die Seitennavigation liest Live-Daten mit einem Offset. Behalten Sie Namespace, Abfrage, Filter und Seitengröße bei. Neue Einträge, Abschlüsse oder Attributänderungen können Treffer zwischen Anfragen verschieben und zu Wiederholungen oder Auslassungen führen; dies ist kein Snapshot-Export. Ein ungültiges Token startet derzeit bei der ersten Seite neu, statt einen Fehler zu liefern. + +Rufen Sie die nächste Seite des ersten Beispiels ab, falls vorhanden: + +```bash +next=$(printf '%s\n' "$page" | jq -r '.next_page_token // empty') +if [ -n "$next" ]; then + curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50' \ + --data-urlencode "next_page_token=$next" | jq . +fi +``` + +Die Seitengröße begrenzt zurückgegebene Zeilen, nicht den Aufwand der Abfrageauswertung. Halten Sie Ausdrücke und `IN`-Listen klein und verwenden Sie selektive Typ-, Status- oder Attributprädikate. Der Workflow-Parser definiert nicht die 2048-Zeichen-Grenze der Schedule-API. HTTP-Server und Proxys können eigene URI-Grenzen setzen. [Schedule-Listen](./server-api-reference.md#schedule-list-filters) verwenden eine andere Grammatik mit Gleichheit und `AND`. + +## Ungültige Abfragen {#invalid-queries} + +Ein erkannter Ausdruck mit Parser-, Feld- oder Typfehler liefert HTTP `422` mit `reason: "validation_failed"`, einer `message` und Arrays in `errors.query` und `validation_errors.query`. Bei ungültiger Seitengröße oder ungültigem Status wird stattdessen der jeweilige Parameterschlüssel verwendet. + +| Ungültiger Ausdruck | Korrektur | +| --- | --- | +| `Unknown = 1` | Registrieren Sie das Attribut in diesem Namespace oder korrigieren Sie den Feldnamen. | +| `OrderTotal = "1000"` | Verwenden Sie das numerische Literal `1000`. | +| `Approved = 1` | Verwenden Sie `true` oder `false`. | +| `Region > "eu"` | Keywords unterstützen Gleichheit und Mitgliedschaft, keine Ordnung. | +| `Tags != "urgent"` oder `NOT Tags IN ("urgent")` | Negative Mitgliedschaft wird für Keyword-Listen nicht unterstützt. | +| `Attempt IN ()`, `Attempt = 1 AND` | Geben Sie eine nichtleere Liste oder ein vollständiges Prädikat an. | +| `DueAt > "tomorrow"` | Senden Sie einen konkreten Zeitstempel. | + +## Embedded-Modus und Waterline {#mode-support} + +Diese Sprache ist über die Workflow-Listen-API des Servers verfügbar. Aktuelle Embedded-Listen und Filter gespeicherter Waterline-Ansichten implementieren nicht die vollständige Grammatik. Ihre exakten Metadatenfilter `key=value` und Teilstringfelder belegen keine Unterstützung für Bereiche, `IN`, `!=` oder boolesche Ausdrücke. Auch Waterline im Service-Modus benötigt explizite UI-/API-Unterstützung, bevor eine gespeicherte Ansicht als diese Abfragesprache gelten kann. Die gemeinsame Paritätsarbeit bleibt im [Visibility-Query-Feature](https://github.com/durable-workflow/.github/issues/224) offen. + +Diese Referenz folgt dem [veröffentlichten nativen Parser mit Unit-Tests](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility_query.rs), der [HTTP-Seitennavigation](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility.rs) und den [Listen-API-Tests](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/tests/execution/visibility.rs). Sie beschreiben veröffentlichtes Server-Verhalten, keinen Abschluss der Embedded- oder Waterline-Parität. diff --git a/i18n/de/source-hashes.json b/i18n/de/source-hashes.json index 8f81228c72e..d34df5c591d 100644 --- a/i18n/de/source-hashes.json +++ b/i18n/de/source-hashes.json @@ -45,7 +45,7 @@ "features/queries.md": "c66dd9542a062edd8158a46cebc9f1bf926aaf3599dca4a3122bd9860df6e2a2", "features/sagas.md": "046ba5661ccb5ac71a236356d243b021d9830123e3798afce491118434e83820", "features/schedules.md": "40d30b2767e7ed043e2b0c7180915c256accea3e7a3401c38d1bf75bfe1c2213", - "features/search-attributes.md": "bb66d83f64e0098354d86ac237e6867b9819098044101ba9a60a6a00a3961dd1", + "features/search-attributes.md": "034ce80ef59a1ba460e41ebf7d7e2d72cfa272bdce609ef5a696c7c8877aeaa5", "features/service-operations.md": "912131c0a8ef393040a933fb4a66e68abcb9d475a3ebd47c85287d4032f45a0e", "features/side-effects.md": "abdccab8d6fc1a12b3eff8a4ccc58730ac36f523559b4ad89c5c2a8d201a3b86", "features/signal+timer.md": "a05fc480544fa71f6c9b215ad3417f71b8475dd81f9de8ee18d7a3b69ac33a23", @@ -88,13 +88,14 @@ "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", - "polyglot/server-api-reference.md": "ecd6d358d6e5bde442ebf0e1ec8a072779089e2a5c4427e31eef646f42c6c03c", + "polyglot/server-api-reference.md": "d3f148fc8a12a315d695d47108ce658c80dea78c314b650a3b86f08727a20aee", "polyglot/server-config-reference.md": "aec241c0046f12a9d6efe2d6c1de443d7753bdf34135e06a6f83b3904ed1d429", "polyglot/server-role-topology.md": "3d048f0c6b5f179399622508f51e67fff8aa5a6d5b2492533fc720eeec2c27f2", "polyglot/server.md": "f24fd7ff4eebcc768ec8105e8689ab1a14cc08d98167090ebb84e3e26631132a", "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", + "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/es/docusaurus-plugin-content-docs/current/features/search-attributes.md b/i18n/es/docusaurus-plugin-content-docs/current/features/search-attributes.md index d18d2b5ba04..db76e3b2d2c 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/features/search-attributes.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/features/search-attributes.md @@ -139,6 +139,8 @@ Los atributos aparecen en: - **Cronología de historial**: cada `SearchAttributesUpserted` aparece como entrada tipada. - **Exportación del historial**: se incluyen en las exportaciones JSON. +Para comparaciones tipadas, rangos temporales, pertenencia, comillas y paginación HTTP del Server, use el [Lenguaje de consultas de visibilidad](../polyglot/visibility-query-language.md). El listado embedded actual y los filtros de vistas guardadas de Waterline no implementan toda esa gramática. La paridad sigue pendiente en la [función de consultas de visibilidad](https://github.com/durable-workflow/.github/issues/224). + ### Filtros de lista de padres e hijos {#parent-child-list-filters} Los hijos [heredan atributos de búsqueda y memo al crearse](./child-workflows.md#child-metadata-inheritance) y luego pueden actualizar sus valores de forma independiente. Filtrar un atributo heredado no excluye implícitamente a los hijos. Para un atributo keyword registrado, la consulta del Server `customer = 'customer-42'` puede devolver al padre y a cada hijo que aún conserve ese valor. El memo sigue siendo metadatos sin índice; no es otro filtro de atributos de búsqueda. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md index b60afd3b235..fc73846eac4 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md @@ -277,7 +277,7 @@ Las rutas de workflow son de operador/plano de control. Requieren rol operator o | Método | Ruta | Finalidad | | --- | --- | --- | -| `GET` | `/api/workflows` | Listar instancias. Admite filtros por estado, tipo, texto de consulta y límite. | +| `GET` | `/api/workflows` | Listar ejecuciones de workflow del namespace, con estado, tipo, consulta de visibilidad, `page_size` y `next_page_token`. | | `POST` | `/api/workflows` | Iniciar una instancia. | | `GET` | `/api/workflows/{workflowId}` | Describir la ejecución actual de un ID de workflow. | | `GET` | `/api/workflows/{workflowId}/debug` | Devolver diagnósticos acotados de una ejecución atascada. | @@ -287,6 +287,8 @@ Las rutas de workflow son de operador/plano de control. Requieren rol operator o | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history` | Paginar eventos de historial. | | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history/export` | Exportar el paquete de reproducción para archivo. | +Consulte campos, comparaciones tipadas, comillas, precedencia, errores y ejemplos de paginación en el [Lenguaje de consultas de visibilidad](./visibility-query-language.md). Esta gramática difiere de los manejadores de consultas con nombre del workflow y de los filtros de schedules. + Las solicitudes de inicio utilizan la estructura independiente del lenguaje: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md new file mode 100644 index 00000000000..ca58339dd9c --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -0,0 +1,143 @@ +--- +title: Lenguaje de consultas de visibilidad +description: Filtre ejecuciones del Server por estado, tiempo, identidad y atributos de búsqueda tipados, con ejemplos HTTP y paginación. +--- + +# Lenguaje de consultas de visibilidad + +Use `GET /api/workflows?query=...` para encontrar ejecuciones en un namespace del Server. Esta referencia describe el Server nativo publicado elegido en el [manifiesto de compatibilidad](../compatibility.md#last-qualified-reproducible-tuple), actualmente `%%artifact.serverVersion%%`. El listado lee datos de visibilidad almacenados. No ejecuta el manejador de una consulta con nombre del workflow. + +La petición necesita un token bearer de operador o administrador, `X-Namespace` y `X-Durable-Workflow-Control-Plane-Version: 2`. Consulte la [autorización del namespace](./namespace-auth-workers.md). Los resultados incluyen ejecuciones coincidentes, también ejecuciones anteriores de una instancia e hijos cuyos atributos coinciden. No hay un predicado integrado para seleccionar solo raíces. + +## Hacer una petición {#make-a-request} + +Defina `DURABLE_WORKFLOW_SERVER_URL` con la URL base del Server y `DURABLE_WORKFLOW_AUTH_TOKEN` con un token de operador o administrador. El ejemplo requiere Bash, curl y jq. Sustituya el intervalo UTC fijo por el período que quiera inspeccionar. + +```bash +query='Status = failed AND CloseTime >= "2026-11-14T00:00:00Z" AND CloseTime < "2026-11-15T00:00:00Z"' +page=$(curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50') +printf '%s\n' "$page" | jq '{workflow_count, workflows, next_page_token}' +``` + +`Status = failed` selecciona un grupo que incluye ejecuciones canceladas y terminadas. Use `Status = cancelled` o `Status = terminated` para esos estados exactos. `running` incluye pending, running y waiting. `completed` selecciona ejecuciones completadas. Los valores de estado no distinguen mayúsculas de minúsculas. + +Use `--data-urlencode` para la consulta y el token de página. Las comillas del shell, los escapes del lenguaje y la codificación URL son pasos distintos. Una respuesta correcta con `workflows: []` significa que ninguna ejecución coincidió con la petición. + +## Campos {#fields} + +Los nombres de campo distinguen mayúsculas de minúsculas. Los nombres integrados tienen prioridad sobre los atributos personalizados. + +| Campo | Valor | Operadores | +| --- | --- | --- | +| `WorkflowType`, `WorkflowId`, `RunId`, `TaskQueue` | Tipo de ejecución, ID de instancia, ID de ejecución o cola de tareas | `=`, `!=`, `IN`, `IN` negado | +| `Status`, `ExecutionStatus` | Estado o grupo de estados descrito arriba | `=`, `!=` | +| `StartTime`, `ExecutionTime` | Instante de inicio de la ejecución. Los nombres son alias. | Comparaciones escalares, `IN`, `IN` negado | +| `CloseTime` | Instante de cierre de la ejecución | Comparaciones escalares, `IN`, `IN` negado | +| `BuildId`, `BuildIds` | Alias del valor de compatibilidad de la ejecución, no una búsqueda de la flota de workers | Operadores de keyword, sujetos al rechazo nativo indicado abajo | + +Las comparaciones escalares son `=`, `!=`, `<`, `<=`, `>` y `>=`. Si falta el instante de inicio o cierre, ninguna comparación coincide, ni siquiera una negada. El listado nativo rechaza una ejecución que devolvería con compatibilidad no nula mediante HTTP `409` / `unqualified_build_visibility`. Que un predicado de build se analice no acredita el listado por build. + +Los demás campos deben ser atributos de búsqueda registrados en este namespace. Consulte las definiciones con `GET /api/search-attributes` y registre un atributo con `POST /api/search-attributes` y un cuerpo JSON como `{"name":"OrderTotal","type":"double"}`. El registro requiere un token de administrador. Un tipo almacenado inferido no vuelve consultable una clave sin registrar. Borrar una definición conserva los valores, pero invalida las consultas sobre esa clave. + +Los identificadores empiezan por una letra ASCII y continúan con letras ASCII, dígitos o `_`. Use exactamente el nombre registrado. Los memos, las etiquetas de visibilidad, las claves de negocio y los nombres de relaciones padre/raíz no son campos estructurados integrados adicionales. La búsqueda simple aún puede encontrar una clave de negocio como se explica abajo. + +## Tipos y comparaciones {#types-and-comparisons} + +| Tipo registrado | Literales y comportamiento de comparación | +| --- | --- | +| `keyword` | Igualdad o desigualdad del texto completo, `IN` e `IN` negado. Sin ordenación. | +| `string`, `text` | Comparación del texto completo con los mismos operadores que `keyword`. Sin subcadenas, búsqueda de texto completo ni operador `LIKE`. | +| `int` | Entero sin comillas, como `42` o `-3`. Comparaciones escalares, `IN` e `IN` negado. Un número entre comillas o decimal no es un literal entero. | +| `double` | Entero o decimal sin comillas, incluida notación exponencial como `1.5e3`. Comparaciones escalares, `IN` e `IN` negado. | +| `bool` | `true` o `false` sin comillas, sin distinguir mayúsculas. Comparaciones escalares, `IN` e `IN` negado; `false` precede a `true`. `1` y `"true"` no son literales booleanos. | +| `datetime` | Fecha y hora entre comillas. Las comparaciones escalares, `IN` e `IN` negado comparan instantes. Use marcas explícitas UTC o con desplazamiento, como `"2026-11-14T12:34:56.123456Z"`. | +| `keyword_list` | `Tags = "urgent"` comprueba pertenencia. `Tags IN ("urgent", "review")` coincide con cualquiera de los miembros indicados. Se rechazan desigualdad, ordenación y pertenencia negada. | + +Una ejecución sin el atributo consultado nunca coincide con ese predicado, tampoco con `!=` ni `IN` negado. No hay predicado de existencia ni `IS NULL`. Un valor conservado con otro tipo registrado anteriormente no se convierte automáticamente al tipo nuevo. + +Las comparaciones de keyword, texto y campos de texto integrados siguen las reglas de igualdad de la base de datos. El esquema publicado de MySQL/MariaDB usa `utf8mb4_unicode_ci`, que ignora mayúsculas, acentos y espacios finales. SQLite y la comparación nativa de PostgreSQL son exactos. La pertenencia en listas de keywords es exacta. No presuponga resultados textuales idénticos entre estos backends. + +Las fechas aceptan fechas ISO y marcas de tiempo con fracciones conservadas hasta microsegundos. Una fecha sola significa medianoche UTC; si se omite la zona, es UTC. Use marcas explícitas para consultas portables. Fechas relativas como `tomorrow` y zonas con nombre como `Europe/Paris` no son valores de fecha válidos. Calcule el intervalo móvil en el llamador y envíe límites fijos. + +## Sintaxis, precedencia y escapes {#syntax-and-escaping} + +- Escriba comparaciones como `Field operator literal`. Separe predicados con `AND` u `OR`. Las palabras clave no distinguen mayúsculas. +- `NOT` se aplica al siguiente predicado antes de `AND`; `AND` tiene mayor precedencia que `OR`. `A = 1 OR B = 2 AND C = 3` significa `A = 1 OR (B = 2 AND C = 3)`. +- Los paréntesis delimitan una lista `IN` no vacía separada por comas. No agrupan expresiones booleanas. Repita predicados en las ramas `OR` cuando sea necesario. +- La pertenencia negada se escribe **`NOT Region IN ("eu", "us")`**. No se admite la forma SQL `Region NOT IN (...)`. Tampoco se admite `Status IN (...)`; use `Status = running OR Status = completed`. +- Use comillas simples o dobles para cadenas. Escape la comilla elegida y una barra inversa literal con `\`. Por ejemplo, `Customer = 'O\'Brien'` y `Path = "C:\\orders"`. El parser también decodifica escapes de C como `\n`, `\t` y `\r`; `\uXXXX` de JSON no es un escape Unicode aquí. Escriba los caracteres Unicode directamente. +- Los literales de texto sin comillas permiten letras ASCII, dígitos, `_`, `.`, `:` y `-`. Prefiera texto entre comillas para evitar inferir booleanos o números por accidente. No hay cláusulas SQL `SELECT`, `ORDER BY` ni `LIMIT`. + +Dentro de una expresión, un campo booleano registrado sin operador puede significar `Flag = true`, y `NOT Flag` significa `Flag = false`. Un `Flag` aislado es texto de búsqueda simple. Las comparaciones explícitas evitan esta ambigüedad. + +El Server reconoce expresiones mediante sintaxis de comparación, `IN (...)` o un predicado `NOT` inicial. El resto del texto busca subcadenas en ID de workflow y clave de negocio. Por ejemplo, `query=order-1001` es búsqueda simple. Un texto similar a SQL no admitido puede tratarse como búsqueda simple en lugar de devolver un error sintáctico. Use la gramática documentada e inspeccione los errores de `query` cuando una expresión reconocida sea inválida. + +## Ejemplos de consultas {#query-examples} + +Pase cualquiera de estas expresiones como valor de `query` en la petición curl anterior. Los ejemplos personalizados suponen que `OrderTotal: double`, `Attempt: int`, `Region: keyword`, `Tags: keyword_list`, `Approved: bool` y `DueAt: datetime` están registrados y tienen valores en el namespace seleccionado. + +| Tarea | Consulta | +| --- | --- | +| Pedidos por encima de un umbral numérico | `WorkflowType = "orders.fulfillment" AND OrderTotal > 1000` | +| Intentos en un rango inclusivo | `Attempt >= 2 AND Attempt <= 5` | +| Cualquiera de dos regiones | `Region IN ("eu", "us")` | +| Otras regiones registradas | `NOT Region IN ("eu", "us")` | +| Cualquier etiqueta de la lista | `Tags IN ("urgent", "review")` | +| False explícito | `Approved = false` | +| Una ventana temporal | `DueAt >= "2026-11-14T00:00:00Z" AND DueAt < "2026-11-15T00:00:00Z"` | +| Dos colas bajo el mismo tipo | `WorkflowType = "orders.fulfillment" AND TaskQueue = "orders" OR WorkflowType = "orders.fulfillment" AND TaskQueue = "priority"` | + +## Paginación y límites {#pagination-and-limits} + +| Parámetro | Comportamiento | +| --- | --- | +| `workflow_type` | Filtro opcional de tipo exacto, combinado con `query` y `status` mediante `AND`. | +| `status` | Filtro opcional. Prefiera los grupos canónicos `running`, `completed` o `failed`. El endpoint actual también acepta `cancelled` y `terminated` exactos; aquí no acepta `pending` ni `waiting`. | +| `page_size` | Entero de `1` a `200`, por defecto `50`. Use este parámetro, no `limit`. | +| `next_page_token` | Copie el token de la respuesta anterior sin decodificarlo ni construirlo. Termine cuando sea null. | + +`workflow_count` es el número de esta página, no el total de ejecuciones coincidentes. Se ordenan por instante de inicio/ordenación descendente y después por ID de ejecución descendente. La paginación lee datos vivos con un offset. Mantenga namespace, consulta, filtros y tamaño de página. Inserciones, cierres y cambios de atributos pueden mover coincidencias entre peticiones y causar repeticiones u omisiones; no es una exportación instantánea. Un token inválido actualmente vuelve a la primera página en vez de producir un error. + +Obtenga la siguiente página del primer ejemplo, si existe: + +```bash +next=$(printf '%s\n' "$page" | jq -r '.next_page_token // empty') +if [ -n "$next" ]; then + curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50' \ + --data-urlencode "next_page_token=$next" | jq . +fi +``` + +El tamaño de página limita las filas devueltas, no el trabajo de evaluar la consulta. Mantenga pequeñas las expresiones y listas `IN`, y use predicados selectivos de tipo, estado o atributos. El parser de workflows no define el límite de 2048 caracteres de la API de schedules. Servidores HTTP y proxies pueden imponer límites de URI propios. El [listado de schedules](./server-api-reference.md#schedule-list-filters) tiene otra gramática, de igualdad y `AND`. + +## Consultas inválidas {#invalid-queries} + +Una expresión reconocida que falla al analizarse, resolver campos o comprobar tipos devuelve HTTP `422` con `reason: "validation_failed"`, un `message` y arrays en `errors.query` y `validation_errors.query`. Un tamaño de página o estado inválido usa la clave de ese parámetro. + +| Expresión inválida | Corrección | +| --- | --- | +| `Unknown = 1` | Registre el atributo en este namespace o corrija el nombre del campo. | +| `OrderTotal = "1000"` | Use el literal numérico `1000`. | +| `Approved = 1` | Use `true` o `false`. | +| `Region > "eu"` | Los keywords admiten igualdad y pertenencia, no ordenación. | +| `Tags != "urgent"` o `NOT Tags IN ("urgent")` | Las listas de keywords no admiten pertenencia negativa. | +| `Attempt IN ()`, `Attempt = 1 AND` | Proporcione una lista no vacía o un predicado completo. | +| `DueAt > "tomorrow"` | Envíe una marca de tiempo concreta. | + +## Modo embedded y Waterline {#mode-support} + +Este lenguaje está disponible mediante la API de listado de workflows del Server. El listado embedded actual y los filtros de vistas guardadas de Waterline no implementan toda esta gramática. Sus filtros exactos de metadatos `key=value` y campos de subcadena no acreditan rangos, `IN`, `!=` ni expresiones booleanas. Waterline en modo servicio también necesita soporte explícito de interfaz/API antes de tratar una vista guardada como este lenguaje. El trabajo de paridad sigue abierto en la [función de consultas de visibilidad](https://github.com/durable-workflow/.github/issues/224). + +La referencia sigue el [parser nativo publicado y sus pruebas unitarias](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility_query.rs), la [implementación de paginación HTTP](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility.rs) y las [pruebas de la API de listado](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/tests/execution/visibility.rs). Describen el comportamiento publicado del Server, no la finalización de la paridad embedded o Waterline. diff --git a/i18n/es/source-hashes.json b/i18n/es/source-hashes.json index 8f81228c72e..d34df5c591d 100644 --- a/i18n/es/source-hashes.json +++ b/i18n/es/source-hashes.json @@ -45,7 +45,7 @@ "features/queries.md": "c66dd9542a062edd8158a46cebc9f1bf926aaf3599dca4a3122bd9860df6e2a2", "features/sagas.md": "046ba5661ccb5ac71a236356d243b021d9830123e3798afce491118434e83820", "features/schedules.md": "40d30b2767e7ed043e2b0c7180915c256accea3e7a3401c38d1bf75bfe1c2213", - "features/search-attributes.md": "bb66d83f64e0098354d86ac237e6867b9819098044101ba9a60a6a00a3961dd1", + "features/search-attributes.md": "034ce80ef59a1ba460e41ebf7d7e2d72cfa272bdce609ef5a696c7c8877aeaa5", "features/service-operations.md": "912131c0a8ef393040a933fb4a66e68abcb9d475a3ebd47c85287d4032f45a0e", "features/side-effects.md": "abdccab8d6fc1a12b3eff8a4ccc58730ac36f523559b4ad89c5c2a8d201a3b86", "features/signal+timer.md": "a05fc480544fa71f6c9b215ad3417f71b8475dd81f9de8ee18d7a3b69ac33a23", @@ -88,13 +88,14 @@ "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", - "polyglot/server-api-reference.md": "ecd6d358d6e5bde442ebf0e1ec8a072779089e2a5c4427e31eef646f42c6c03c", + "polyglot/server-api-reference.md": "d3f148fc8a12a315d695d47108ce658c80dea78c314b650a3b86f08727a20aee", "polyglot/server-config-reference.md": "aec241c0046f12a9d6efe2d6c1de443d7753bdf34135e06a6f83b3904ed1d429", "polyglot/server-role-topology.md": "3d048f0c6b5f179399622508f51e67fff8aa5a6d5b2492533fc720eeec2c27f2", "polyglot/server.md": "f24fd7ff4eebcc768ec8105e8689ab1a14cc08d98167090ebb84e3e26631132a", "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", + "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/features/search-attributes.md b/i18n/fr/docusaurus-plugin-content-docs/current/features/search-attributes.md index 7603835bbbf..8c49ddc3f9f 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/features/search-attributes.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/features/search-attributes.md @@ -139,6 +139,8 @@ Les attributs apparaissent dans : - la **chronologie d’historique** : chaque `SearchAttributesUpserted` apparaît comme une entrée typée - l’**export d’historique** : les attributs sont inclus dans les exports JSON +Pour les comparaisons typées, intervalles temporels, appartenance, guillemets et pagination HTTP côté Server, utilisez le [Langage de requêtes de visibilité](../polyglot/visibility-query-language.md). Les listes embedded actuelles et les filtres de vues enregistrées de Waterline n’implémentent pas toute cette grammaire. La parité reste en attente dans la [fonction de requêtes de visibilité](https://github.com/durable-workflow/.github/issues/224). + ### Filtres de liste parent/enfant {#parent-child-list-filters} Les enfants [héritent des attributs de recherche et du memo à la création](./child-workflows.md#child-metadata-inheritance), puis peuvent modifier leurs valeurs indépendamment. Filtrer un attribut hérité n’exclut pas implicitement les enfants. Pour un attribut keyword enregistré, la requête Server `customer = 'customer-42'` peut renvoyer le parent et tous les enfants conservant cette valeur. Le memo reste une métadonnée non indexée, pas un autre filtre d’attribut de recherche. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md index 691c00d7930..be8f2c49774 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md @@ -422,7 +422,7 @@ exigent un rôle operator ou admin et `X-Durable-Workflow-Control-Plane-Version: | Méthode | Chemin | Rôle | | --- | --- | --- | -| `GET` | `/api/workflows` | Lister les instances de workflow. Accepte les filtres d'état, de type, de texte de requête et de limite. | +| `GET` | `/api/workflows` | Lister les exécutions du namespace, avec état, type, requête de visibilité, `page_size` et `next_page_token`. | | `POST` | `/api/workflows` | Démarrer une instance de workflow. | | `GET` | `/api/workflows/{workflowId}` | Décrire l'exécution actuelle d'un identifiant de workflow. | | `GET` | `/api/workflows/{workflowId}/debug` | Renvoyer des diagnostics bornés pour examiner une exécution bloquée. | @@ -432,6 +432,8 @@ exigent un rôle operator ou admin et `X-Durable-Workflow-Control-Plane-Version: | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history` | Parcourir par pages les événements d'historique d'une exécution. | | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history/export` | Exporter l'ensemble de relecture archivable d'une exécution. | +Pour les champs, comparaisons typées, guillemets, priorités, erreurs et exemples de pagination, voir le [Langage de requêtes de visibilité](./visibility-query-language.md). Cette grammaire diffère des gestionnaires de requêtes nommés du workflow et des filtres de liste des schedules. + Les requêtes de démarrage suivent la forme du plan de contrôle indépendante du langage : diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md new file mode 100644 index 00000000000..bee66b223fe --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -0,0 +1,143 @@ +--- +title: Langage de requêtes de visibilité +description: Filtrer les exécutions du Server par état, temps, identité et attributs de recherche typés, avec exemples HTTP et pagination. +--- + +# Langage de requêtes de visibilité + +Utilisez `GET /api/workflows?query=...` pour trouver des exécutions dans un espace de noms du Server. Cette référence décrit le Server natif publié sélectionné dans le [manifeste de compatibilité](../compatibility.md#last-qualified-reproducible-tuple), actuellement `%%artifact.serverVersion%%`. La liste lit les données de visibilité stockées. Elle ne lance pas le gestionnaire de requête de lecture nommé du workflow. + +La demande nécessite un jeton bearer avec le rôle opérateur ou administrateur, `X-Namespace` et `X-Durable-Workflow-Control-Plane-Version: 2`. Voir [les autorisations des espaces de noms](./namespace-auth-workers.md). Les résultats incluent les exécutions correspondantes, y compris les anciennes exécutions d’une instance et les enfants dont les attributs correspondent. Aucun prédicat intégré ne sélectionne uniquement les racines. + +## Envoyer une demande {#make-a-request} + +Définissez `DURABLE_WORKFLOW_SERVER_URL` avec l’URL de base du Server et `DURABLE_WORKFLOW_AUTH_TOKEN` avec un jeton opérateur ou administrateur. Cet exemple nécessite Bash, curl et jq. Remplacez l’intervalle UTC fixe par la période à inspecter. + +```bash +query='Status = failed AND CloseTime >= "2026-11-14T00:00:00Z" AND CloseTime < "2026-11-15T00:00:00Z"' +page=$(curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50') +printf '%s\n' "$page" | jq '{workflow_count, workflows, next_page_token}' +``` + +`Status = failed` sélectionne un groupe qui inclut aussi les exécutions annulées et terminées de force. Utilisez `Status = cancelled` ou `Status = terminated` pour ces états exacts. `running` inclut pending, running et waiting. `completed` sélectionne les exécutions achevées. Les valeurs d’état sont insensibles à la casse. + +Utilisez `--data-urlencode` pour la requête et le jeton de page. Les guillemets du shell, les échappements du langage et l’encodage URL sont des étapes distinctes. Une réponse réussie avec `workflows: []` indique qu’aucune exécution ne correspond à cette demande. + +## Champs {#fields} + +Les noms de champs sont sensibles à la casse. Les noms intégrés priment sur les attributs personnalisés. + +| Champ | Valeur | Opérateurs | +| --- | --- | --- | +| `WorkflowType`, `WorkflowId`, `RunId`, `TaskQueue` | Type d’exécution, ID d’instance, ID d’exécution ou file de tâches | `=`, `!=`, `IN`, `IN` nié | +| `Status`, `ExecutionStatus` | État ou groupe d’états décrit ci-dessus | `=`, `!=` | +| `StartTime`, `ExecutionTime` | Instant de début de l’exécution. Ces noms sont des alias. | Comparaisons scalaires, `IN`, `IN` nié | +| `CloseTime` | Instant de clôture de l’exécution | Comparaisons scalaires, `IN`, `IN` nié | +| `BuildId`, `BuildIds` | Alias de la valeur de compatibilité de l’exécution, pas une recherche dans la flotte de workers | Opérateurs de keyword, soumis au refus natif ci-dessous | + +Les comparaisons scalaires sont `=`, `!=`, `<`, `<=`, `>` et `>=`. Un instant de début ou de clôture absent ne satisfait jamais une comparaison, même niée. La liste native refuse une exécution qu’elle devrait renvoyer avec une compatibilité non nulle par HTTP `409` / `unqualified_build_visibility`. L’analyse d’un prédicat de build n’établit pas une qualification de la liste par build. + +Les autres champs doivent être des attributs de recherche enregistrés dans cet espace de noms. Consultez les définitions avec `GET /api/search-attributes` et enregistrez un attribut avec `POST /api/search-attributes` et un corps JSON comme `{"name":"OrderTotal","type":"double"}`. L’enregistrement exige un jeton administrateur. Un type stocké inféré ne rend pas une clé non enregistrée interrogeable. Supprimer la définition conserve les valeurs mais invalide les requêtes sur cette clé. + +Les identifiants commencent par une lettre ASCII, puis contiennent des lettres ASCII, chiffres ou `_`. Respectez exactement le nom enregistré. Memos, labels de visibilité, clés métier et noms de relations parent/racine ne sont pas des champs structurés intégrés supplémentaires. La recherche simple peut toujours trouver une clé métier comme décrit plus bas. + +## Types et comparaisons {#types-and-comparisons} + +| Type enregistré | Littéraux et comportement de comparaison | +| --- | --- | +| `keyword` | Égalité ou inégalité du texte entier, `IN` et `IN` nié. Aucun ordre. | +| `string`, `text` | Comparaison du texte entier avec les mêmes opérateurs que `keyword`. Aucun opérateur de sous-chaîne, de plein texte ou `LIKE`. | +| `int` | Entier sans guillemets, comme `42` ou `-3`. Comparaisons scalaires, `IN` et `IN` nié. Un nombre entre guillemets ou décimal n’est pas un littéral entier. | +| `double` | Entier ou décimal sans guillemets, y compris la notation exponentielle telle que `1.5e3`. Comparaisons scalaires, `IN` et `IN` nié. | +| `bool` | `true` ou `false` sans guillemets, insensibles à la casse. Comparaisons scalaires, `IN` et `IN` nié ; `false` précède `true`. `1` et `"true"` ne sont pas des littéraux booléens. | +| `datetime` | Date/heure entre guillemets. Comparaisons scalaires, `IN` et `IN` nié comparent les instants. Utilisez un horodatage UTC ou à décalage explicite, tel que `"2026-11-14T12:34:56.123456Z"`. | +| `keyword_list` | `Tags = "urgent"` teste l’appartenance. `Tags IN ("urgent", "review")` correspond à au moins un élément cité. Inégalité, ordre et appartenance niée sont refusés. | + +Une exécution sans l’attribut interrogé ne satisfait jamais ce prédicat, même avec `!=` ou `IN` nié. Il n’existe pas de prédicat d’existence ni `IS NULL`. Une valeur conservée sous un ancien type enregistré différent n’est pas convertie automatiquement vers le nouveau type. + +Les comparaisons de keyword, texte et champs textuels intégrés suivent les règles d’égalité de la base. Le schéma MySQL/MariaDB publié utilise `utf8mb4_unicode_ci`, qui ignore la casse, les accents et les espaces finaux. SQLite et la comparaison native PostgreSQL sont exacts. L’appartenance aux listes de keywords est exacte. Ne supposez pas des résultats textuels identiques sur ces backends. + +Les dates acceptent les dates ISO et les horodatages, avec des fractions conservées à la microseconde. Une date seule signifie minuit UTC ; sans fuseau, UTC s’applique. Utilisez des horodatages explicites pour les requêtes portables. Les dates relatives comme `tomorrow` et les fuseaux nommés comme `Europe/Paris` ne sont pas acceptés. Calculez l’intervalle glissant dans l’appelant et envoyez des bornes fixes. + +## Syntaxe, priorité et échappement {#syntax-and-escaping} + +- Écrivez les comparaisons sous la forme `Field operator literal`. Séparez les prédicats avec `AND` ou `OR`. Les mots-clés sont insensibles à la casse. +- `NOT` s’applique au prédicat suivant avant `AND` ; `AND` est prioritaire sur `OR`. `A = 1 OR B = 2 AND C = 3` signifie `A = 1 OR (B = 2 AND C = 3)`. +- Les parenthèses délimitent une liste `IN` non vide séparée par des virgules. Elles ne regroupent pas les expressions booléennes. Répétez si nécessaire les prédicats dans les branches `OR`. +- L’appartenance niée s’écrit **`NOT Region IN ("eu", "us")`**. La forme SQL `Region NOT IN (...)` n’est pas prise en charge. `Status IN (...)` non plus ; utilisez `Status = running OR Status = completed`. +- Utilisez des guillemets simples ou doubles pour les chaînes. Échappez le guillemet choisi et une barre oblique inverse littérale avec `\`. Exemples : `Customer = 'O\'Brien'` et `Path = "C:\\orders"`. Le parseur décode aussi les échappements C tels que `\n`, `\t` et `\r` ; `\uXXXX` de JSON n’est pas un échappement Unicode ici. Écrivez directement les caractères Unicode. +- Les littéraux textuels sans guillemets acceptent les lettres ASCII, chiffres, `_`, `.`, `:` et `-`. Préférez les guillemets pour éviter une inférence accidentelle de booléens ou de nombres. Aucune clause SQL `SELECT`, `ORDER BY` ou `LIMIT` n’est disponible. + +Dans une expression, un champ booléen enregistré seul peut signifier `Flag = true`, et `NOT Flag` signifie `Flag = false`. Un `Flag` isolé est en revanche du texte de recherche simple. Les comparaisons explicites évitent cette ambiguïté. + +Le Server reconnaît une expression par une syntaxe de comparaison, `IN (...)` ou un prédicat `NOT` initial. Le reste est une recherche de sous-chaîne dans l’ID de workflow et la clé métier. Par exemple, `query=order-1001` est une recherche simple. Un texte ressemblant à du SQL non pris en charge peut donc être traité comme recherche simple au lieu de produire une erreur de syntaxe. Utilisez la grammaire documentée et inspectez les erreurs de `query` lorsqu’une expression reconnue est invalide. + +## Exemples de requêtes {#query-examples} + +Passez une expression ci-dessous comme valeur de `query` dans la demande curl précédente. Les exemples personnalisés supposent que `OrderTotal: double`, `Attempt: int`, `Region: keyword`, `Tags: keyword_list`, `Approved: bool` et `DueAt: datetime` sont enregistrés et renseignés dans l’espace de noms choisi. + +| Tâche | Requête | +| --- | --- | +| Commandes au-dessus d’un seuil numérique | `WorkflowType = "orders.fulfillment" AND OrderTotal > 1000` | +| Tentatives dans un intervalle inclusif | `Attempt >= 2 AND Attempt <= 5` | +| Une des deux régions | `Region IN ("eu", "us")` | +| Autres régions renseignées | `NOT Region IN ("eu", "us")` | +| Une des étiquettes citées | `Tags IN ("urgent", "review")` | +| False explicite | `Approved = false` | +| Une fenêtre temporelle | `DueAt >= "2026-11-14T00:00:00Z" AND DueAt < "2026-11-15T00:00:00Z"` | +| Deux files sous le même type | `WorkflowType = "orders.fulfillment" AND TaskQueue = "orders" OR WorkflowType = "orders.fulfillment" AND TaskQueue = "priority"` | + +## Pagination et limites {#pagination-and-limits} + +| Paramètre | Comportement | +| --- | --- | +| `workflow_type` | Filtre facultatif de type exact, combiné avec `query` et `status` par `AND`. | +| `status` | Filtre facultatif. Préférez les groupes canoniques `running`, `completed` ou `failed`. Le point de terminaison actuel accepte aussi `cancelled` et `terminated` exacts ; `pending` et `waiting` ne sont pas acceptés ici. | +| `page_size` | Entier de `1` à `200`, par défaut `50`. Utilisez ce paramètre, pas `limit`. | +| `next_page_token` | Copiez le jeton de la réponse précédente sans le décoder ni en construire un. Arrêtez-vous lorsqu’il est null. | + +`workflow_count` compte les éléments de cette page, pas toutes les exécutions correspondantes. Les résultats sont triés par date de début/tri décroissante, puis ID d’exécution décroissant. La pagination lit des données vivantes avec un décalage. Conservez espace de noms, requête, filtres et taille de page. Des insertions, clôtures ou mises à jour d’attributs entre demandes peuvent déplacer les résultats et créer doublons ou omissions ; ce n’est pas un export figé. Un jeton invalide repart actuellement de la première page au lieu de produire une erreur. + +Récupérez la page suivante du premier exemple, si elle existe : + +```bash +next=$(printf '%s\n' "$page" | jq -r '.next_page_token // empty') +if [ -n "$next" ]; then + curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50' \ + --data-urlencode "next_page_token=$next" | jq . +fi +``` + +La taille de page limite les lignes renvoyées, pas le coût d’évaluation. Gardez expressions et listes `IN` petites et utilisez des prédicats sélectifs de type, état ou attribut. Le parseur de workflows ne définit pas la limite de 2048 caractères de l’API des schedules. Serveurs HTTP et proxys peuvent imposer leurs limites d’URI. La [liste des schedules](./server-api-reference.md#schedule-list-filters) utilise une autre grammaire, fondée sur l’égalité et `AND`. + +## Requêtes invalides {#invalid-queries} + +Une expression reconnue qui échoue à l’analyse, à la résolution des champs ou au contrôle des types renvoie HTTP `422` avec `reason: "validation_failed"`, un `message`, et des tableaux dans `errors.query` et `validation_errors.query`. Une taille de page ou un état invalide utilise la clé de ce paramètre. + +| Expression invalide | Correction | +| --- | --- | +| `Unknown = 1` | Enregistrez l’attribut dans cet espace de noms ou corrigez le nom du champ. | +| `OrderTotal = "1000"` | Utilisez le littéral numérique `1000`. | +| `Approved = 1` | Utilisez `true` ou `false`. | +| `Region > "eu"` | Les keywords acceptent égalité et appartenance, pas l’ordre. | +| `Tags != "urgent"` ou `NOT Tags IN ("urgent")` | L’appartenance négative n’est pas prise en charge pour les listes de keywords. | +| `Attempt IN ()`, `Attempt = 1 AND` | Fournissez une liste non vide ou un prédicat complet. | +| `DueAt > "tomorrow"` | Envoyez un horodatage concret. | + +## Mode embedded et Waterline {#mode-support} + +Ce langage est disponible via l’API de liste des workflows du Server. La liste embedded actuelle et les filtres des vues enregistrées de Waterline n’implémentent pas toute cette grammaire. Leurs filtres exacts de métadonnées `key=value` et champs de sous-chaîne ne prouvent pas la prise en charge des intervalles, de `IN`, de `!=` ou des expressions booléennes. Waterline en mode service a aussi besoin d’un support explicite dans l’interface/API avant de traiter une vue enregistrée comme ce langage. Le travail de parité reste ouvert dans la [fonction de requêtes de visibilité](https://github.com/durable-workflow/.github/issues/224). + +La référence suit le [parseur natif publié et ses tests unitaires](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility_query.rs), l’[implémentation de pagination HTTP](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility.rs) et les [tests de l’API de liste](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/tests/execution/visibility.rs). Ils décrivent le comportement publié du Server, pas l’achèvement de la parité embedded ou Waterline. diff --git a/i18n/fr/source-hashes.json b/i18n/fr/source-hashes.json index 8f81228c72e..d34df5c591d 100644 --- a/i18n/fr/source-hashes.json +++ b/i18n/fr/source-hashes.json @@ -45,7 +45,7 @@ "features/queries.md": "c66dd9542a062edd8158a46cebc9f1bf926aaf3599dca4a3122bd9860df6e2a2", "features/sagas.md": "046ba5661ccb5ac71a236356d243b021d9830123e3798afce491118434e83820", "features/schedules.md": "40d30b2767e7ed043e2b0c7180915c256accea3e7a3401c38d1bf75bfe1c2213", - "features/search-attributes.md": "bb66d83f64e0098354d86ac237e6867b9819098044101ba9a60a6a00a3961dd1", + "features/search-attributes.md": "034ce80ef59a1ba460e41ebf7d7e2d72cfa272bdce609ef5a696c7c8877aeaa5", "features/service-operations.md": "912131c0a8ef393040a933fb4a66e68abcb9d475a3ebd47c85287d4032f45a0e", "features/side-effects.md": "abdccab8d6fc1a12b3eff8a4ccc58730ac36f523559b4ad89c5c2a8d201a3b86", "features/signal+timer.md": "a05fc480544fa71f6c9b215ad3417f71b8475dd81f9de8ee18d7a3b69ac33a23", @@ -88,13 +88,14 @@ "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", - "polyglot/server-api-reference.md": "ecd6d358d6e5bde442ebf0e1ec8a072779089e2a5c4427e31eef646f42c6c03c", + "polyglot/server-api-reference.md": "d3f148fc8a12a315d695d47108ce658c80dea78c314b650a3b86f08727a20aee", "polyglot/server-config-reference.md": "aec241c0046f12a9d6efe2d6c1de443d7753bdf34135e06a6f83b3904ed1d429", "polyglot/server-role-topology.md": "3d048f0c6b5f179399622508f51e67fff8aa5a6d5b2492533fc720eeec2c27f2", "polyglot/server.md": "f24fd7ff4eebcc768ec8105e8689ab1a14cc08d98167090ebb84e3e26631132a", "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", + "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/features/search-attributes.md b/i18n/ja/docusaurus-plugin-content-docs/current/features/search-attributes.md index d607c9bcbb8..1f27c1f0c71 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/features/search-attributes.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/features/search-attributes.md @@ -139,6 +139,8 @@ upsertSearchAttributes(['temporary_flag' => null]); - **履歴タイムライン**: 各 `SearchAttributesUpserted` を型付き項目として表示。 - **履歴エクスポート**: JSON 履歴に含む。 +Server 側の型付き比較、時間範囲、所属、引用符、HTTP ページングには[可視性クエリ言語](../polyglot/visibility-query-language.md)を使います。現在の embedded 一覧と Waterline の保存ビュー用フィルターは文法全体を実装していません。共通の同等性対応は[可視性クエリ機能](https://github.com/durable-workflow/.github/issues/224)で未完了です。 + ### 親子の一覧フィルター {#parent-child-list-filters} 子は[作成時に検索属性と memo を継承](./child-workflows.md#child-metadata-inheritance)し、その後は独立して値を更新できます。継承属性でフィルターしても、子が自動的に除外されることはありません。登録済み keyword 属性の Server クエリ `customer = 'customer-42'` は、親と、その値を保持するすべての子を返す場合があります。Memo は引き続きインデックスのないメタデータであり、検索属性のフィルターではありません。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md index 5b63e1b1caf..178c3b379e4 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md @@ -277,7 +277,7 @@ curl -sS "$DURABLE_WORKFLOW_SERVER_URL/api/system/health" \ | メソッド | パス | 用途 | | --- | --- | --- | -| `GET` | `/api/workflows` | インスタンスを一覧。状態、型、クエリテキスト、件数などでフィルター可能。 | +| `GET` | `/api/workflows` | 名前空間内のワークフロー実行を、状態、型、可視性クエリ、`page_size`、`next_page_token` で一覧します。 | | `POST` | `/api/workflows` | インスタンスを開始。 | | `GET` | `/api/workflows/{workflowId}` | ワークフロー ID の現在の実行を説明。 | | `GET` | `/api/workflows/{workflowId}/debug` | 停滞した実行調査のための範囲付き診断情報を返す。 | @@ -287,6 +287,8 @@ curl -sS "$DURABLE_WORKFLOW_SERVER_URL/api/system/health" \ | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history` | 履歴イベントをページ単位で読む。 | | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history/export` | 実行のアーカイブ用リプレイバンドルをエクスポート。 | +フィールド、型付き比較、引用符、優先順位、エラー、ページング例は[可視性クエリ言語](./visibility-query-language.md)を参照してください。この一覧の文法はワークフローの名前付きクエリハンドラーや schedule 一覧フィルターとは異なります。 + 開始要求は言語中立のコントロールプレーン構造を使います。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md new file mode 100644 index 00000000000..c0be7ab3305 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -0,0 +1,143 @@ +--- +title: 可視性クエリ言語 +description: 状態、時刻、識別情報、型付き検索属性で Server の実行を絞り込む HTTP 例とページングのリファレンス。 +--- + +# 可視性クエリ言語 + +`GET /api/workflows?query=...` で Server の一つの名前空間にある実行を検索します。このリファレンスは[互換性マニフェスト](../compatibility.md#last-qualified-reproducible-tuple)で選択された公開済みネイティブ Server、現在の `%%artifact.serverVersion%%` を説明します。一覧は保存された可視性情報を読みます。ワークフローの名前付きクエリハンドラーは実行しません。 + +リクエストには operator または admin の bearer トークン、`X-Namespace`、`X-Durable-Workflow-Control-Plane-Version: 2` が必要です。[名前空間の認可](./namespace-auth-workers.md)を参照してください。結果にはインスタンスの以前の実行や、属性が一致する子の実行も含まれます。ルートだけを選ぶ組み込み述語はありません。 + +## リクエストを送る {#make-a-request} + +`DURABLE_WORKFLOW_SERVER_URL` に Server のベース URL、`DURABLE_WORKFLOW_AUTH_TOKEN` に operator または admin トークンを設定します。例には Bash、curl、jq が必要です。固定の UTC 区間を調べたい期間に置き換えてください。 + +```bash +query='Status = failed AND CloseTime >= "2026-11-14T00:00:00Z" AND CloseTime < "2026-11-15T00:00:00Z"' +page=$(curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50') +printf '%s\n' "$page" | jq '{workflow_count, workflows, next_page_token}' +``` + +`Status = failed` はキャンセル済みと強制終了済みも含む状態グループを選びます。その状態だけを選ぶには `Status = cancelled` または `Status = terminated` を使います。`running` は pending、running、waiting を含みます。`completed` は完了した実行を選びます。状態値は大文字と小文字を区別しません。 + +クエリとページトークンには `--data-urlencode` を使います。シェルの引用符、クエリ文字列のエスケープ、URL エンコードは別の処理です。成功したレスポンスの `workflows: []` は、このリクエストに一致する実行がないことを意味します。 + +## フィールド {#fields} + +フィールド名は大文字と小文字を区別します。組み込み名はカスタム属性より優先されます。 + +| フィールド | 値 | 演算子 | +| --- | --- | --- | +| `WorkflowType`, `WorkflowId`, `RunId`, `TaskQueue` | 実行の型、インスタンス ID、実行 ID、タスクキュー | `=`、`!=`、`IN`、否定した `IN` | +| `Status`, `ExecutionStatus` | 上記の状態または状態グループ | `=`, `!=` | +| `StartTime`, `ExecutionTime` | 実行開始時刻。二つの名前は別名です。 | スカラー比較、`IN`、否定した `IN` | +| `CloseTime` | 実行終了時刻 | スカラー比較、`IN`、否定した `IN` | +| `BuildId`, `BuildIds` | 実行の互換性値の別名。Worker フリートの検索ではありません。 | keyword 演算子。ただし以下のネイティブ拒否制約があります。 | + +スカラー比較は `=`、`!=`、`<`、`<=`、`>`、`>=` です。開始時刻または終了時刻がない場合、否定を含むどの比較にも一致しません。返す実行の compatibility が非 null なら、ネイティブ一覧は HTTP `409` / `unqualified_build_visibility` で拒否します。build 述語を解析できても build による一覧が資格検証済みとは限りません。 + +他のフィールドは、この名前空間に登録された検索属性である必要があります。`GET /api/search-attributes` で定義を確認し、`POST /api/search-attributes` と `{"name":"OrderTotal","type":"double"}` などの JSON 本文で登録します。登録には admin トークンが必要です。保存時に型を推論しただけでは未登録キーを検索できません。定義を削除しても保存値は残りますが、そのキーのクエリは無効になります。 + +識別子は ASCII 英字で始まり、ASCII 英字、数字、`_` が続きます。登録名を正確に使ってください。memo、可視性ラベル、ビジネスキー、親やルートの関係名は追加の組み込み構造化フィールドではありません。ビジネスキーは後述の単純検索で検索できます。 + +## 型と比較 {#types-and-comparisons} + +| 登録された型 | リテラルと比較の動作 | +| --- | --- | +| `keyword` | 文字列全体の等値、不等値、`IN`、否定した `IN`。順序比較はできません。 | +| `string`, `text` | `keyword` と同じ演算子で文字列全体を比較します。部分文字列、全文検索、`LIKE` 演算子はありません。 | +| `int` | `42`、`-3` など引用符なしの整数。スカラー比較、`IN`、否定した `IN`。引用符付き数値や小数は整数リテラルではありません。 | +| `double` | 引用符なしの整数または小数。`1.5e3` など指数表記も使えます。スカラー比較、`IN`、否定した `IN`。 | +| `bool` | 引用符なしの `true` または `false`。大文字と小文字は区別しません。スカラー比較、`IN`、否定した `IN` が使え、`false` は `true` より小さい値です。`1` と `"true"` は真偽値リテラルではありません。 | +| `datetime` | 引用符付き日時。スカラー比較、`IN`、否定した `IN` は時点を比較します。`"2026-11-14T12:34:56.123456Z"` のように UTC またはオフセットを明示してください。 | +| `keyword_list` | `Tags = "urgent"` は要素の所属を検査します。`Tags IN ("urgent", "review")` は列挙した要素のいずれかに一致します。不等値、順序比較、所属の否定は拒否されます。 | + +対象の属性がない実行は、`!=` や否定した `IN` を含め、その述語に一致しません。存在検査や `IS NULL` 述語はありません。以前の別の登録型で残った値は、新しい型へ自動変換されません。 + +keyword、テキスト、組み込みテキストフィールドの比較はデータベースの等値規則に従います。公開された MySQL/MariaDB スキーマは `utf8mb4_unicode_ci` を使い、大文字と小文字、アクセント、末尾の空白を無視します。SQLite とネイティブ PostgreSQL の比較は完全一致です。keyword_list の所属も完全一致です。これらのバックエンドで同じテキスト結果になるとは想定しないでください。 + +日時には ISO 日付とタイムスタンプを使え、小数部はマイクロ秒まで保持されます。日付だけなら UTC の午前零時で、タイムゾーンの省略時も UTC です。移植可能なクエリには明示的なタイムスタンプを使います。`tomorrow` のような相対日付や `Europe/Paris` のようなゾーン名は使えません。呼び出し側で移動区間を計算して固定境界を送ってください。 + +## 構文、優先順位、エスケープ {#syntax-and-escaping} + +- 比較は `Field operator literal` と書きます。述語を `AND` または `OR` で区切ります。キーワードは大文字と小文字を区別しません。 +- `NOT` は `AND` より先に次の述語へ適用され、`AND` は `OR` より強く結合します。`A = 1 OR B = 2 AND C = 3` は `A = 1 OR (B = 2 AND C = 3)` を意味します。 +- 括弧は空でないカンマ区切りの `IN` リストに使います。真偽式をグループ化することはできません。必要なら各 `OR` 分岐に述語を繰り返します。 +- 所属の否定は **`NOT Region IN ("eu", "us")`** です。SQL 形式の `Region NOT IN (...)` は未対応です。`Status IN (...)` も未対応なので、`Status = running OR Status = completed` を使います。 +- 文字列には単一引用符か二重引用符を使います。選んだ引用符とリテラルのバックスラッシュを `\` でエスケープします。例は `Customer = 'O\'Brien'` と `Path = "C:\\orders"` です。パーサーは `\n`、`\t`、`\r` などの C 形式もデコードします。JSON の `\uXXXX` はここでは Unicode エスケープではありません。Unicode 文字を直接記述してください。 +- 引用符なしテキストには ASCII 英字、数字、`_`、`.`、`:`、`-` を使えます。意図せず真偽値や数値に推論されないよう、テキストには引用符を推奨します。SQL の `SELECT`、`ORDER BY`、`LIMIT` 句はありません。 + +式の中では、演算子のない登録済み真偽値フィールドが `Flag = true` を意味することがあり、`NOT Flag` は `Flag = false` を意味します。一方、単独の `Flag` は単純検索テキストです。明示的な比較で曖昧さを避けてください。 + +Server は比較構文、`IN (...)`、先頭の `NOT` 述語から式を認識します。他のテキストはワークフロー ID とビジネスキーの部分文字列検索になります。例えば `query=order-1001` は単純検索です。そのため未対応の SQL 風テキストは構文エラーではなく単純検索になる場合があります。記載された文法を使い、認識された式が無効な場合は `query` エラーを確認してください。 + +## クエリ例 {#query-examples} + +以下の式を上記 curl リクエストの `query` 値として渡せます。カスタム例では、選択した名前空間に `OrderTotal: double`、`Attempt: int`、`Region: keyword`、`Tags: keyword_list`、`Approved: bool`、`DueAt: datetime` が登録され、値が設定されていることを前提とします。 + +| 目的 | クエリ | +| --- | --- | +| 数値しきい値を超える注文 | `WorkflowType = "orders.fulfillment" AND OrderTotal > 1000` | +| 両端を含む範囲の試行回数 | `Attempt >= 2 AND Attempt <= 5` | +| 二つの地域のいずれか | `Region IN ("eu", "us")` | +| それ以外の記録済み地域 | `NOT Region IN ("eu", "us")` | +| リスト内のいずれかのタグ | `Tags IN ("urgent", "review")` | +| 明示的な false | `Approved = false` | +| 時間ウィンドウ | `DueAt >= "2026-11-14T00:00:00Z" AND DueAt < "2026-11-15T00:00:00Z"` | +| 同じ型の二つのキュー | `WorkflowType = "orders.fulfillment" AND TaskQueue = "orders" OR WorkflowType = "orders.fulfillment" AND TaskQueue = "priority"` | + +## ページングと制限 {#pagination-and-limits} + +| パラメーター | 動作 | +| --- | --- | +| `workflow_type` | 任意の完全一致型フィルター。`query` と `status` と `AND` で組み合わせます。 | +| `status` | 任意のフィルター。正規の状態グループ `running`、`completed`、`failed` を推奨します。現在の一覧エンドポイントは正確な状態 `cancelled`、`terminated` も受け付けますが、ここでは `pending`、`waiting` は使えません。 | +| `page_size` | `1` から `200` の整数。既定は `50`。`limit` ではなくこのパラメーターを使います。 | +| `next_page_token` | 前のレスポンスのトークンをデコードや自作せずコピーします。null になったら終了します。 | + +`workflow_count` はこのページの件数であり、全一致実行の総数ではありません。開始/ソート時刻の降順、次に実行 ID の降順で並びます。ページングはオフセットでライブデータを読みます。名前空間、クエリ、フィルター、ページサイズを固定してください。リクエスト間の挿入、終了、属性更新で一致項目が移動し、重複や欠落が起こり得ます。スナップショットのエクスポートではありません。現在、無効なトークンはエラーではなく最初のページに戻ります。 + +最初の例に次ページがある場合は取得します。 + +```bash +next=$(printf '%s\n' "$page" | jq -r '.next_page_token // empty') +if [ -n "$next" ]; then + curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50' \ + --data-urlencode "next_page_token=$next" | jq . +fi +``` + +ページサイズは返却行数を制限し、評価処理量は制限しません。式と `IN` リストは小さくし、選択性の高い型、状態、属性の述語を使います。ワークフローパーサーは schedule API の 2048 文字制限を定義していません。HTTP サーバーやプロキシが独自の URI 制限を設ける場合があります。[Schedule 一覧](./server-api-reference.md#schedule-list-filters)は等値と `AND` の別の文法を使います。 + +## 無効なクエリ {#invalid-queries} + +認識した式が解析、フィールド検索、型検査で失敗すると、HTTP `422`、`reason: "validation_failed"`、`message`、`errors.query` と `validation_errors.query` の配列が返ります。無効なページサイズや状態では、代わりにそのパラメーターのキーを使います。 + +| 無効な式 | 修正 | +| --- | --- | +| `Unknown = 1` | この名前空間に属性を登録するか、フィールド名を修正します。 | +| `OrderTotal = "1000"` | 数値リテラル `1000` を使います。 | +| `Approved = 1` | `true` または `false` を使います。 | +| `Region > "eu"` | keyword は等値と所属をサポートし、順序比較はできません。 | +| `Tags != "urgent"` または `NOT Tags IN ("urgent")` | keyword_list では所属の否定は未対応です。 | +| `Attempt IN ()`, `Attempt = 1 AND` | 空でないリスト、または完全な述語を指定します。 | +| `DueAt > "tomorrow"` | 具体的なタイムスタンプを送ります。 | + +## Embedded モードと Waterline {#mode-support} + +この言語は Server のワークフロー一覧 API で利用できます。現在の embedded 一覧と Waterline の保存ビュー用フィルターは、この文法全体を実装していません。既存の完全一致メタデータ `key=value` フィルターや部分文字列フィールドは、範囲、`IN`、`!=`、真偽式の対応を意味しません。サービスモード Waterline も、保存ビューをこの言語として扱うには明示的な UI/API 対応が必要です。共通の同等性対応は[可視性クエリ機能](https://github.com/durable-workflow/.github/issues/224)で未完了です。 + +この参考は[公開済みネイティブパーサーと単体テスト](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility_query.rs)、[HTTP ページング実装](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility.rs)、[一覧 API テスト](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/tests/execution/visibility.rs)に基づきます。これらは公開 Server の動作であり、embedded や Waterline の同等性対応の完了を示しません。 diff --git a/i18n/ja/source-hashes.json b/i18n/ja/source-hashes.json index 8f81228c72e..d34df5c591d 100644 --- a/i18n/ja/source-hashes.json +++ b/i18n/ja/source-hashes.json @@ -45,7 +45,7 @@ "features/queries.md": "c66dd9542a062edd8158a46cebc9f1bf926aaf3599dca4a3122bd9860df6e2a2", "features/sagas.md": "046ba5661ccb5ac71a236356d243b021d9830123e3798afce491118434e83820", "features/schedules.md": "40d30b2767e7ed043e2b0c7180915c256accea3e7a3401c38d1bf75bfe1c2213", - "features/search-attributes.md": "bb66d83f64e0098354d86ac237e6867b9819098044101ba9a60a6a00a3961dd1", + "features/search-attributes.md": "034ce80ef59a1ba460e41ebf7d7e2d72cfa272bdce609ef5a696c7c8877aeaa5", "features/service-operations.md": "912131c0a8ef393040a933fb4a66e68abcb9d475a3ebd47c85287d4032f45a0e", "features/side-effects.md": "abdccab8d6fc1a12b3eff8a4ccc58730ac36f523559b4ad89c5c2a8d201a3b86", "features/signal+timer.md": "a05fc480544fa71f6c9b215ad3417f71b8475dd81f9de8ee18d7a3b69ac33a23", @@ -88,13 +88,14 @@ "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", - "polyglot/server-api-reference.md": "ecd6d358d6e5bde442ebf0e1ec8a072779089e2a5c4427e31eef646f42c6c03c", + "polyglot/server-api-reference.md": "d3f148fc8a12a315d695d47108ce658c80dea78c314b650a3b86f08727a20aee", "polyglot/server-config-reference.md": "aec241c0046f12a9d6efe2d6c1de443d7753bdf34135e06a6f83b3904ed1d429", "polyglot/server-role-topology.md": "3d048f0c6b5f179399622508f51e67fff8aa5a6d5b2492533fc720eeec2c27f2", "polyglot/server.md": "f24fd7ff4eebcc768ec8105e8689ab1a14cc08d98167090ebb84e3e26631132a", "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", + "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/features/search-attributes.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/features/search-attributes.md index 41e505cb286..e3e7fb8ee7d 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/features/search-attributes.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/features/search-attributes.md @@ -139,6 +139,8 @@ Atributos de busca aparecem em: - **Linha do tempo do histórico**: cada evento `SearchAttributesUpserted` aparece como entrada tipada na linha do tempo da execução - **Exportação de histórico**: os atributos de busca são incluídos nas exportações de histórico em JSON +Para comparações tipadas, intervalos de tempo, pertencimento, aspas e paginação HTTP no Server, use a [Linguagem de consultas de visibilidade](../polyglot/visibility-query-language.md). A listagem embedded atual e os filtros de vistas salvas do Waterline não implementam toda essa gramática. A paridade continua pendente no [recurso de consultas de visibilidade](https://github.com/durable-workflow/.github/issues/224). + ### Filtros de lista de pais e filhos {#parent-child-list-filters} Filhos [herdam atributos de busca e memo na criação](./child-workflows.md#child-metadata-inheritance) e depois podem atualizar os valores de forma independente. Filtrar um atributo herdado não exclui filhos implicitamente. Para um atributo keyword registrado, a consulta do Server `customer = 'customer-42'` pode retornar o pai e cada filho que ainda mantenha esse valor. Memo continua sendo metadado não indexado, não outro filtro de atributos de busca. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md index 536425c464a..7e5111db3fd 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md @@ -404,7 +404,7 @@ operator ou admin e `X-Durable-Workflow-Control-Plane-Version: 2`. | Método | Caminho | Finalidade | | --- | --- | --- | -| `GET` | `/api/workflows` | Lista instâncias de workflow. Suporta filtros como status, tipo, texto de consulta e limite. | +| `GET` | `/api/workflows` | Lista execuções de workflow no namespace, com estado, tipo, consulta de visibilidade, `page_size` e `next_page_token`. | | `POST` | `/api/workflows` | Inicia uma instância de workflow. | | `GET` | `/api/workflows/{workflowId}` | Descreve a execução atual de um ID de workflow. | | `GET` | `/api/workflows/{workflowId}/debug` | Retorna diagnósticos limitados para investigar execução presa. | @@ -414,6 +414,8 @@ operator ou admin e `X-Durable-Workflow-Control-Plane-Version: 2`. | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history` | Pagina eventos do histórico da execução. | | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history/export` | Exporta o pacote de replay de arquivo da execução. | +Veja campos, comparações tipadas, aspas, precedência, erros e exemplos de paginação na [Linguagem de consultas de visibilidade](./visibility-query-language.md). Essa gramática difere dos handlers de consultas nomeadas do workflow e dos filtros de schedules. + Requisições de início usam o formato de controle independente de linguagem: diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md new file mode 100644 index 00000000000..9df79fde555 --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -0,0 +1,143 @@ +--- +title: Linguagem de consultas de visibilidade +description: Filtre execuções do Server por estado, tempo, identidade e atributos de busca tipados, com exemplos HTTP e paginação. +--- + +# Linguagem de consultas de visibilidade + +Use `GET /api/workflows?query=...` para encontrar execuções em um namespace do Server. Esta referência descreve o Server nativo publicado selecionado no [manifesto de compatibilidade](../compatibility.md#last-qualified-reproducible-tuple), atualmente `%%artifact.serverVersion%%`. A listagem lê fatos de visibilidade armazenados. Ela não executa o handler de uma consulta nomeada do workflow. + +A requisição precisa de um token bearer de operador ou administrador, `X-Namespace` e `X-Durable-Workflow-Control-Plane-Version: 2`. Consulte a [autorização de namespace](./namespace-auth-workers.md). Os resultados incluem execuções correspondentes, também execuções anteriores de uma instância e filhos cujos atributos correspondam. Não existe predicado integrado para selecionar apenas raízes. + +## Fazer uma requisição {#make-a-request} + +Defina `DURABLE_WORKFLOW_SERVER_URL` como a URL base do Server e `DURABLE_WORKFLOW_AUTH_TOKEN` como um token de operador ou administrador. O exemplo exige Bash, curl e jq. Substitua o intervalo UTC fixo pelo período que deseja inspecionar. + +```bash +query='Status = failed AND CloseTime >= "2026-11-14T00:00:00Z" AND CloseTime < "2026-11-15T00:00:00Z"' +page=$(curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50') +printf '%s\n' "$page" | jq '{workflow_count, workflows, next_page_token}' +``` + +`Status = failed` seleciona um grupo que também inclui execuções canceladas e terminadas. Use `Status = cancelled` ou `Status = terminated` para esses estados exatos. `running` inclui pending, running e waiting. `completed` seleciona execuções concluídas. Valores de estado não diferenciam maiúsculas de minúsculas. + +Use `--data-urlencode` para a consulta e o token de página. Aspas do shell, escapes da linguagem e codificação URL são etapas separadas. Uma resposta bem-sucedida com `workflows: []` significa que nenhuma execução correspondeu à requisição. + +## Campos {#fields} + +Nomes de campo diferenciam maiúsculas de minúsculas. Nomes integrados têm precedência sobre atributos personalizados. + +| Campo | Valor | Operadores | +| --- | --- | --- | +| `WorkflowType`, `WorkflowId`, `RunId`, `TaskQueue` | Tipo de execução, ID da instância, ID da execução ou fila de tarefas | `=`, `!=`, `IN`, `IN` negado | +| `Status`, `ExecutionStatus` | Estado ou grupo de estados descrito acima | `=`, `!=` | +| `StartTime`, `ExecutionTime` | Instante de início da execução. Os nomes são aliases. | Comparações escalares, `IN`, `IN` negado | +| `CloseTime` | Instante de encerramento da execução | Comparações escalares, `IN`, `IN` negado | +| `BuildId`, `BuildIds` | Aliases do valor de compatibilidade da execução, não uma busca na frota de workers | Operadores de keyword, sujeitos à recusa nativa abaixo | + +Comparações escalares são `=`, `!=`, `<`, `<=`, `>` e `>=`. Um instante de início ou encerramento ausente nunca corresponde a uma comparação, mesmo negada. A listagem nativa recusa uma execução que seria retornada com compatibilidade não nula usando HTTP `409` / `unqualified_build_visibility`. Um predicado de build analisado não comprova listagem qualificada por build. + +Outros campos precisam ser atributos de busca registrados neste namespace. Consulte definições com `GET /api/search-attributes` e registre um atributo com `POST /api/search-attributes` e um corpo JSON como `{"name":"OrderTotal","type":"double"}`. O registro exige token de administrador. Um tipo inferido armazenado, sozinho, não torna consultável uma chave não registrada. Excluir a definição preserva os valores, mas invalida consultas sobre a chave. + +Identificadores começam com uma letra ASCII e continuam com letras ASCII, dígitos ou `_`. Use exatamente o nome registrado. Memos, rótulos de visibilidade, chaves de negócio e nomes de relações pai/raiz não são campos estruturados integrados adicionais. A busca simples ainda pode encontrar uma chave de negócio como explicado abaixo. + +## Tipos e comparações {#types-and-comparisons} + +| Tipo registrado | Literais e comportamento de comparação | +| --- | --- | +| `keyword` | Igualdade ou desigualdade do texto completo, `IN` e `IN` negado. Sem ordenação. | +| `string`, `text` | Comparação do texto completo, com os mesmos operadores de `keyword`. Sem substring, busca de texto completo ou operador `LIKE`. | +| `int` | Inteiro sem aspas, como `42` ou `-3`. Comparações escalares, `IN` e `IN` negado. Um número entre aspas ou decimal não é um literal inteiro. | +| `double` | Inteiro ou decimal sem aspas, incluindo notação exponencial como `1.5e3`. Comparações escalares, `IN` e `IN` negado. | +| `bool` | `true` ou `false` sem aspas, sem diferenciar maiúsculas. Comparações escalares, `IN` e `IN` negado; `false` vem antes de `true`. `1` e `"true"` não são literais booleanos. | +| `datetime` | Data/hora entre aspas. Comparações escalares, `IN` e `IN` negado comparam instantes. Use timestamps UTC ou com offset explícito, como `"2026-11-14T12:34:56.123456Z"`. | +| `keyword_list` | `Tags = "urgent"` testa pertencimento. `Tags IN ("urgent", "review")` corresponde a qualquer membro listado. Desigualdade, ordenação e pertencimento negado são recusados. | + +Uma execução sem o atributo consultado nunca corresponde ao predicado, inclusive `!=` e `IN` negado. Não há predicado de existência nem `IS NULL`. Um valor mantido com outro tipo registrado anteriormente não é convertido automaticamente para o tipo novo. + +Comparações de keyword, texto e campos de texto integrados seguem as regras de igualdade do banco. O esquema publicado de MySQL/MariaDB usa `utf8mb4_unicode_ci`, que ignora maiúsculas, acentos e espaços finais. SQLite e a comparação nativa de PostgreSQL são exatos. O pertencimento a listas de keywords é exato. Não presuma resultados textuais idênticos entre esses backends. + +Datas aceitam datas ISO e timestamps, preservando frações até microssegundos. Uma data sozinha significa meia-noite UTC; sem fuso explícito, usa UTC. Use timestamps explícitos para consultas portáveis. Datas relativas como `tomorrow` e fusos nomeados como `Europe/Paris` não são valores válidos. Calcule o intervalo móvel no chamador e envie limites fixos. + +## Sintaxe, precedência e escapes {#syntax-and-escaping} + +- Escreva comparações como `Field operator literal`. Separe predicados com `AND` ou `OR`. Palavras-chave não diferenciam maiúsculas. +- `NOT` aplica-se ao próximo predicado antes de `AND`; `AND` tem precedência sobre `OR`. `A = 1 OR B = 2 AND C = 3` significa `A = 1 OR (B = 2 AND C = 3)`. +- Parênteses delimitam uma lista `IN` não vazia, separada por vírgulas. Não agrupam expressões booleanas. Repita predicados nos ramos `OR` quando necessário. +- Pertencimento negado é **`NOT Region IN ("eu", "us")`**. A forma SQL `Region NOT IN (...)` não é suportada. `Status IN (...)` também não é suportado; use `Status = running OR Status = completed`. +- Use aspas simples ou duplas para strings. Escape a aspa escolhida e uma barra invertida literal com `\`. Exemplos: `Customer = 'O\'Brien'` e `Path = "C:\\orders"`. O parser também decodifica escapes de C como `\n`, `\t` e `\r`; `\uXXXX` de JSON não é um escape Unicode aqui. Escreva os caracteres Unicode diretamente. +- Literais de texto sem aspas permitem letras ASCII, dígitos, `_`, `.`, `:` e `-`. Prefira texto entre aspas para evitar a inferência acidental de booleanos ou números. Não há cláusulas SQL `SELECT`, `ORDER BY` ou `LIMIT`. + +Dentro de uma expressão, um campo booleano registrado sem operador pode significar `Flag = true`; `NOT Flag` significa `Flag = false`. Um `Flag` isolado é texto de busca simples. Comparações explícitas evitam essa ambiguidade. + +O Server reconhece uma expressão pela sintaxe de comparação, `IN (...)` ou um predicado `NOT` inicial. O restante do texto busca substrings no ID do workflow e na chave de negócio. Por exemplo, `query=order-1001` é busca simples. Texto semelhante a SQL não suportado pode virar busca simples em vez de erro de sintaxe. Use a gramática documentada e inspecione erros de `query` quando uma expressão reconhecida for inválida. + +## Exemplos de consultas {#query-examples} + +Passe qualquer expressão abaixo como valor de `query` na requisição curl acima. Os exemplos personalizados pressupõem `OrderTotal: double`, `Attempt: int`, `Region: keyword`, `Tags: keyword_list`, `Approved: bool` e `DueAt: datetime` registrados e preenchidos no namespace selecionado. + +| Tarefa | Consulta | +| --- | --- | +| Pedidos acima de um limite numérico | `WorkflowType = "orders.fulfillment" AND OrderTotal > 1000` | +| Tentativas em um intervalo inclusivo | `Attempt >= 2 AND Attempt <= 5` | +| Qualquer uma das regiões | `Region IN ("eu", "us")` | +| Outras regiões registradas | `NOT Region IN ("eu", "us")` | +| Qualquer tag da lista | `Tags IN ("urgent", "review")` | +| False explícito | `Approved = false` | +| Uma janela de tempo | `DueAt >= "2026-11-14T00:00:00Z" AND DueAt < "2026-11-15T00:00:00Z"` | +| Duas filas sob o mesmo tipo | `WorkflowType = "orders.fulfillment" AND TaskQueue = "orders" OR WorkflowType = "orders.fulfillment" AND TaskQueue = "priority"` | + +## Paginação e limites {#pagination-and-limits} + +| Parâmetro | Comportamento | +| --- | --- | +| `workflow_type` | Filtro opcional de tipo exato, combinado com `query` e `status` por `AND`. | +| `status` | Filtro opcional. Prefira os grupos canônicos `running`, `completed` ou `failed`. O endpoint atual também aceita `cancelled` e `terminated` exatos; não aceita `pending` e `waiting` aqui. | +| `page_size` | Inteiro de `1` a `200`, padrão `50`. Use este parâmetro, não `limit`. | +| `next_page_token` | Copie o token da resposta anterior sem decodificar ou construir um. Pare quando for null. | + +`workflow_count` é o número nesta página, não o total de execuções correspondentes. A ordem é por instante de início/ordenação decrescente e depois ID da execução decrescente. A paginação lê dados vivos usando offset. Mantenha namespace, consulta, filtros e tamanho de página. Inserções, encerramentos ou atualizações de atributos entre requisições podem mover resultados e causar repetições ou omissões; não é uma exportação de snapshot. Um token inválido atualmente reinicia na primeira página, em vez de retornar erro. + +Busque a próxima página do primeiro exemplo, se houver: + +```bash +next=$(printf '%s\n' "$page" | jq -r '.next_page_token // empty') +if [ -n "$next" ]; then + curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50' \ + --data-urlencode "next_page_token=$next" | jq . +fi +``` + +O tamanho de página limita as linhas retornadas, não o trabalho de avaliação. Mantenha expressões e listas `IN` pequenas e use predicados seletivos de tipo, estado ou atributos. O parser de workflows não define o limite de 2048 caracteres da API de schedules. Servidores HTTP e proxies podem impor limites próprios de URI. A [listagem de schedules](./server-api-reference.md#schedule-list-filters) tem outra gramática, de igualdade e `AND`. + +## Consultas inválidas {#invalid-queries} + +Uma expressão reconhecida que falha no parsing, na resolução de campos ou na checagem de tipos retorna HTTP `422` com `reason: "validation_failed"`, uma `message` e arrays em `errors.query` e `validation_errors.query`. Tamanho de página ou estado inválido usa a chave do respectivo parâmetro. + +| Expressão inválida | Correção | +| --- | --- | +| `Unknown = 1` | Registre o atributo neste namespace ou corrija o nome do campo. | +| `OrderTotal = "1000"` | Use o literal numérico `1000`. | +| `Approved = 1` | Use `true` ou `false`. | +| `Region > "eu"` | Keywords suportam igualdade e pertencimento, não ordenação. | +| `Tags != "urgent"` ou `NOT Tags IN ("urgent")` | Listas de keywords não suportam pertencimento negativo. | +| `Attempt IN ()`, `Attempt = 1 AND` | Forneça uma lista não vazia ou um predicado completo. | +| `DueAt > "tomorrow"` | Envie um timestamp concreto. | + +## Modo embedded e Waterline {#mode-support} + +Esta linguagem está disponível pela API de listagem de workflows do Server. A listagem embedded atual e os filtros de vistas salvas do Waterline não implementam toda essa gramática. Os filtros exatos de metadados `key=value` e campos de substring existentes não comprovam suporte a intervalos, `IN`, `!=` ou expressões booleanas. Waterline em modo serviço também precisa de suporte explícito na interface/API antes de tratar uma vista salva como essa linguagem. O trabalho de paridade continua aberto no [recurso de consultas de visibilidade](https://github.com/durable-workflow/.github/issues/224). + +A referência segue o [parser nativo publicado e seus testes unitários](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility_query.rs), a [implementação de paginação HTTP](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility.rs) e os [testes da API de listagem](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/tests/execution/visibility.rs). Eles descrevem o comportamento publicado do Server, não a conclusão da paridade embedded ou Waterline. diff --git a/i18n/pt-BR/source-hashes.json b/i18n/pt-BR/source-hashes.json index 8f81228c72e..d34df5c591d 100644 --- a/i18n/pt-BR/source-hashes.json +++ b/i18n/pt-BR/source-hashes.json @@ -45,7 +45,7 @@ "features/queries.md": "c66dd9542a062edd8158a46cebc9f1bf926aaf3599dca4a3122bd9860df6e2a2", "features/sagas.md": "046ba5661ccb5ac71a236356d243b021d9830123e3798afce491118434e83820", "features/schedules.md": "40d30b2767e7ed043e2b0c7180915c256accea3e7a3401c38d1bf75bfe1c2213", - "features/search-attributes.md": "bb66d83f64e0098354d86ac237e6867b9819098044101ba9a60a6a00a3961dd1", + "features/search-attributes.md": "034ce80ef59a1ba460e41ebf7d7e2d72cfa272bdce609ef5a696c7c8877aeaa5", "features/service-operations.md": "912131c0a8ef393040a933fb4a66e68abcb9d475a3ebd47c85287d4032f45a0e", "features/side-effects.md": "abdccab8d6fc1a12b3eff8a4ccc58730ac36f523559b4ad89c5c2a8d201a3b86", "features/signal+timer.md": "a05fc480544fa71f6c9b215ad3417f71b8475dd81f9de8ee18d7a3b69ac33a23", @@ -88,13 +88,14 @@ "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", - "polyglot/server-api-reference.md": "ecd6d358d6e5bde442ebf0e1ec8a072779089e2a5c4427e31eef646f42c6c03c", + "polyglot/server-api-reference.md": "d3f148fc8a12a315d695d47108ce658c80dea78c314b650a3b86f08727a20aee", "polyglot/server-config-reference.md": "aec241c0046f12a9d6efe2d6c1de443d7753bdf34135e06a6f83b3904ed1d429", "polyglot/server-role-topology.md": "3d048f0c6b5f179399622508f51e67fff8aa5a6d5b2492533fc720eeec2c27f2", "polyglot/server.md": "f24fd7ff4eebcc768ec8105e8689ab1a14cc08d98167090ebb84e3e26631132a", "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", + "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/uk/docusaurus-plugin-content-docs/current/features/search-attributes.md b/i18n/uk/docusaurus-plugin-content-docs/current/features/search-attributes.md index c23cd25961b..6dc7b4ada46 100644 --- a/i18n/uk/docusaurus-plugin-content-docs/current/features/search-attributes.md +++ b/i18n/uk/docusaurus-plugin-content-docs/current/features/search-attributes.md @@ -139,6 +139,8 @@ upsertSearchAttributes(['temporary_flag' => null]); - **Хронологія історії** — кожна подія `SearchAttributesUpserted` відображається як типізований запис у хронології запуску - **Експорт історії** — атрибути пошуку входять до експорту історії у JSON +Для типізованих порівнянь, часових діапазонів, належності, лапок і HTTP-пагінації на Server використовуйте [мову запитів видимості](../polyglot/visibility-query-language.md). Поточні embedded-списки та фільтри збережених подань Waterline не реалізують усю граматику. Спільний паритет залишається незавершеним у [функції запитів видимості](https://github.com/durable-workflow/.github/issues/224). + ### Фільтри списку батьків і дітей {#parent-child-list-filters} Діти [успадковують search attributes і memo під час створення](./child-workflows.md#child-metadata-inheritance), а потім можуть незалежно оновлювати власні значення. Фільтрація успадкованого атрибута не виключає дітей автоматично. Для зареєстрованого keyword-атрибута запит Server `customer = 'customer-42'` може повернути батька й кожну дитину з цим значенням. Memo залишається неіндексованими метаданими, а не ще одним фільтром search attributes. diff --git a/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md index 9a9d706a9e2..9d52b280854 100644 --- a/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md +++ b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md @@ -380,7 +380,7 @@ curl -sS "$DURABLE_WORKFLOW_SERVER_URL/api/system/health" \ | Метод | Шлях | Призначення | | --- | --- | --- | -| `GET` | `/api/workflows` | Показати екземпляри workflow з фільтрами статусу, типу, тексту query й ліміту. | +| `GET` | `/api/workflows` | Показати запуски workflow в namespace зі станом, типом, query видимості, `page_size` і `next_page_token`. | | `POST` | `/api/workflows` | Запустити екземпляр workflow. | | `GET` | `/api/workflows/{workflowId}` | Описати поточне виконання ID workflow. | | `GET` | `/api/workflows/{workflowId}/debug` | Повернути обмежену діагностику застряглого виконання. | @@ -390,6 +390,8 @@ curl -sS "$DURABLE_WORKFLOW_SERVER_URL/api/system/health" \ | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history` | Прочитати події історії сторінками. | | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history/export` | Експортувати архівний набір replay виконання. | +Поля, типізовані порівняння, лапки, пріоритет, помилки й приклади пагінації описує [мова запитів видимості](./visibility-query-language.md). Ця граматика списків відрізняється від іменованих query-обробників workflow і фільтрів списку schedule. + Запити запуску використовують незалежну від мови форму control-plane: diff --git a/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md new file mode 100644 index 00000000000..930fdf40fd6 --- /dev/null +++ b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -0,0 +1,143 @@ +--- +title: Мова запитів видимості +description: Фільтрування запусків Server за станом, часом, ідентичністю та типізованими атрибутами пошуку, з HTTP-прикладами й пагінацією. +--- + +# Мова запитів видимості + +Використовуйте `GET /api/workflows?query=...`, щоб знайти запуски в одному namespace Server. Цей довідник описує опублікований native Server, вибраний у [маніфесті сумісності](../compatibility.md#last-qualified-reproducible-tuple), зараз `%%artifact.serverVersion%%`. Список читає збережені дані видимості. Він не виконує іменований query-обробник workflow. + +Запит потребує bearer-токена оператора або адміністратора, `X-Namespace` та `X-Durable-Workflow-Control-Plane-Version: 2`. Див. [авторизацію namespace](./namespace-auth-workers.md). Результати містять відповідні запуски, зокрема попередні запуски екземпляра й дочірні запуски з відповідними атрибутами. Вбудованого предиката лише для кореневих workflow немає. + +## Надсилання запиту {#make-a-request} + +Задайте `DURABLE_WORKFLOW_SERVER_URL` як базову URL-адресу Server, а `DURABLE_WORKFLOW_AUTH_TOKEN` як токен оператора або адміністратора. Приклад потребує Bash, curl і jq. Замініть фіксований UTC-інтервал на потрібний період. + +```bash +query='Status = failed AND CloseTime >= "2026-11-14T00:00:00Z" AND CloseTime < "2026-11-15T00:00:00Z"' +page=$(curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50') +printf '%s\n' "$page" | jq '{workflow_count, workflows, next_page_token}' +``` + +`Status = failed` вибирає групу, яка також охоплює скасовані й примусово завершені запуски. Використовуйте `Status = cancelled` або `Status = terminated` для цих точних станів. `running` охоплює pending, running і waiting. `completed` вибирає завершені запуски. Значення стану не залежать від регістру. + +Використовуйте `--data-urlencode` для query і токена сторінки. Лапки оболонки, екранування мови запитів і URL-кодування є окремими кроками. Успішна відповідь із `workflows: []` означає, що жоден запуск не відповідає запиту. + +## Поля {#fields} + +Назви полів чутливі до регістру. Вбудовані назви мають пріоритет над користувацькими атрибутами. + +| Поле | Значення | Оператори | +| --- | --- | --- | +| `WorkflowType`, `WorkflowId`, `RunId`, `TaskQueue` | Тип запуску, ID екземпляра, ID запуску або черга завдань | `=`, `!=`, `IN`, заперечений `IN` | +| `Status`, `ExecutionStatus` | Стан або група станів, описана вище | `=`, `!=` | +| `StartTime`, `ExecutionTime` | Момент початку запуску. Назви є псевдонімами. | Скалярні порівняння, `IN`, заперечений `IN` | +| `CloseTime` | Момент закриття запуску | Скалярні порівняння, `IN`, заперечений `IN` | +| `BuildId`, `BuildIds` | Псевдоніми значення сумісності запуску, а не пошук у парку worker | Оператори keyword з урахуванням native-відмови нижче | + +Скалярні порівняння: `=`, `!=`, `<`, `<=`, `>` і `>=`. Відсутній момент початку чи закриття не відповідає жодному порівнянню, навіть запереченому. Native-список відмовляє HTTP `409` / `unqualified_build_visibility`, якщо запуск, який слід повернути, має не-null значення сумісності. Розбір build-предиката не доводить кваліфіковану підтримку списків за build. + +Інші поля мають бути атрибутами пошуку, зареєстрованими в цьому namespace. Переглядайте визначення через `GET /api/search-attributes` і реєструйте атрибут через `POST /api/search-attributes` із JSON-тілом на кшталт `{"name":"OrderTotal","type":"double"}`. Реєстрація потребує токена адміністратора. Самого виведеного збереженого типу недостатньо, щоб запитувати незареєстрований ключ. Видалення визначення зберігає значення, але робить запити за цим ключем недійсними. + +Ідентифікатор починається з ASCII-літери й продовжується ASCII-літерами, цифрами або `_`. Використовуйте точну зареєстровану назву. Memo, мітки видимості, бізнес-ключі та назви батьківських/кореневих зв’язків не є додатковими вбудованими структурованими полями. Простий пошук усе ще знаходить бізнес-ключ, як описано нижче. + +## Типи й порівняння {#types-and-comparisons} + +| Зареєстрований тип | Літерали й поведінка порівняння | +| --- | --- | +| `keyword` | Рівність або нерівність усього текстового значення, `IN` і заперечений `IN`. Без порівняння порядку. | +| `string`, `text` | Порівняння всього тексту тими самими операторами, що й `keyword`. Немає підрядкового, повнотекстового пошуку чи `LIKE`. | +| `int` | Ціле число без лапок, як-от `42` або `-3`. Скалярні порівняння, `IN` і заперечений `IN`. Число в лапках або десяткове число не є цілим літералом. | +| `double` | Ціле або десяткове число без лапок, зокрема експоненційний запис `1.5e3`. Скалярні порівняння, `IN` і заперечений `IN`. | +| `bool` | `true` або `false` без лапок, незалежно від регістру. Скалярні порівняння, `IN` і заперечений `IN`; `false` менше за `true`. `1` і `"true"` не є булевими літералами. | +| `datetime` | Дата й час у лапках. Скалярні порівняння, `IN` і заперечений `IN` порівнюють моменти. Задавайте UTC або явний зсув, наприклад `"2026-11-14T12:34:56.123456Z"`. | +| `keyword_list` | `Tags = "urgent"` перевіряє належність. `Tags IN ("urgent", "review")` відповідає будь-якому з наведених елементів. Нерівність, порядок і заперечена належність відхиляються. | + +Запуск без запитуваного атрибута ніколи не відповідає предикату, навіть для `!=` і запереченого `IN`. Немає предиката існування або `IS NULL`. Значення зі старим іншим зареєстрованим типом не перетворюється автоматично на новий тип. + +Порівняння keyword, тексту й вбудованих текстових полів дотримуються правил рівності бази даних. Опублікована схема MySQL/MariaDB використовує `utf8mb4_unicode_ci`, що ігнорує регістр, діакритику й кінцеві пробіли. SQLite та native-порівняння PostgreSQL є точними. Належність у keyword_list також точна. Не припускайте однакових текстових результатів між цими бекендами. + +Дата й час приймають ISO-дати та часові позначки зі збереженням часток до мікросекунд. Дата без часу означає північ UTC; пропущений часовий пояс також означає UTC. Для переносних запитів задавайте явні часові позначки. Відносні дати на кшталт `tomorrow` і назви поясів на кшталт `Europe/Paris` не приймаються. Обчисліть рухомий інтервал у викликача й надішліть фіксовані межі. + +## Синтаксис, пріоритет і екранування {#syntax-and-escaping} + +- Пишіть порівняння як `Field operator literal`. Розділяйте предикати через `AND` або `OR`. Ключові слова не залежать від регістру. +- `NOT` застосовується до наступного предиката перед `AND`; `AND` має вищий пріоритет за `OR`. `A = 1 OR B = 2 AND C = 3` означає `A = 1 OR (B = 2 AND C = 3)`. +- Дужки обмежують непорожній список `IN` з елементами через кому. Вони не групують булеві вирази. За потреби повторіть предикати в гілках `OR`. +- Заперечена належність записується як **`NOT Region IN ("eu", "us")`**. SQL-форма `Region NOT IN (...)` не підтримується. `Status IN (...)` також не підтримується; використовуйте `Status = running OR Status = completed`. +- Для рядків використовуйте одинарні або подвійні лапки. Екрануйте вибрані лапки та буквальну зворотну скісну риску через `\`. Наприклад, `Customer = 'O\'Brien'` і `Path = "C:\\orders"`. Парсер також декодує C-послідовності `\n`, `\t` і `\r`; JSON-запис `\uXXXX` тут не є Unicode-екрануванням. Пишіть Unicode-символи безпосередньо. +- Текстові літерали без лапок допускають ASCII-літери, цифри, `_`, `.`, `:` і `-`. Краще брати текст у лапки, щоб випадково не вивести булевий або числовий тип. SQL-конструкцій `SELECT`, `ORDER BY` і `LIMIT` немає. + +У виразі окреме зареєстроване булеве поле може означати `Flag = true`, а `NOT Flag` означає `Flag = false`. Натомість самотній `Flag` є простим пошуковим текстом. Явні порівняння усувають цю неоднозначність. + +Server розпізнає вираз за синтаксисом порівняння, `IN (...)` або початковим предикатом `NOT`. Інший текст шукається як підрядок у workflow ID та бізнес-ключі. Наприклад, `query=order-1001` є простим пошуком. Тому непідтримуваний SQL-подібний текст може стати простим пошуком, а не синтаксичною помилкою. Використовуйте задокументовану граматику й перевіряйте помилки `query`, коли розпізнаний вираз недійсний. + +## Приклади запитів {#query-examples} + +Передайте будь-який вираз нижче як значення `query` у наведеному curl-запиті. Приклади користувацьких атрибутів передбачають, що `OrderTotal: double`, `Attempt: int`, `Region: keyword`, `Tags: keyword_list`, `Approved: bool` і `DueAt: datetime` зареєстровано й заповнено у вибраному namespace. + +| Завдання | Запит | +| --- | --- | +| Замовлення понад числовий поріг | `WorkflowType = "orders.fulfillment" AND OrderTotal > 1000` | +| Спроби у включному діапазоні | `Attempt >= 2 AND Attempt <= 5` | +| Один із двох регіонів | `Region IN ("eu", "us")` | +| Інші збережені регіони | `NOT Region IN ("eu", "us")` | +| Будь-яка мітка зі списку | `Tags IN ("urgent", "review")` | +| Явне false | `Approved = false` | +| Часове вікно | `DueAt >= "2026-11-14T00:00:00Z" AND DueAt < "2026-11-15T00:00:00Z"` | +| Дві черги з тим самим типом | `WorkflowType = "orders.fulfillment" AND TaskQueue = "orders" OR WorkflowType = "orders.fulfillment" AND TaskQueue = "priority"` | + +## Пагінація й обмеження {#pagination-and-limits} + +| Параметр | Поведінка | +| --- | --- | +| `workflow_type` | Необов’язковий точний фільтр типу, поєднується з `query` і `status` через `AND`. | +| `status` | Необов’язковий фільтр. Краще використовувати канонічні групи `running`, `completed` або `failed`. Поточний endpoint списку також приймає точні `cancelled` і `terminated`; `pending` та `waiting` тут не приймаються. | +| `page_size` | Ціле від `1` до `200`, типово `50`. Використовуйте цей параметр, а не `limit`. | +| `next_page_token` | Копіюйте токен попередньої відповіді, не декодуйте й не створюйте його самостійно. Завершіть, коли він null. | + +`workflow_count` є кількістю на цій сторінці, а не загальною кількістю відповідних запусків. Результати сортуються за спаданням часу початку/сортування, потім ID запуску. Пагінація читає живі дані зі зміщенням. Не змінюйте namespace, query, фільтри й розмір сторінки. Вставки, закриття або зміни атрибутів між запитами можуть зсувати збіги та спричиняти повтори чи пропуски; це не експорт знімка. Недійсний токен зараз повертає до першої сторінки замість помилки. + +Отримайте наступну сторінку першого прикладу, якщо вона є: + +```bash +next=$(printf '%s\n' "$page" | jq -r '.next_page_token // empty') +if [ -n "$next" ]; then + curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50' \ + --data-urlencode "next_page_token=$next" | jq . +fi +``` + +Розмір сторінки обмежує повернуті рядки, а не роботу з обчислення query. Зберігайте вирази й списки `IN` невеликими та використовуйте вибіркові предикати типу, стану чи атрибута. Парсер workflow не визначає schedule-ліміт у 2048 символів. HTTP-сервери та проксі можуть мати власні обмеження URI. [Список schedule](./server-api-reference.md#schedule-list-filters) використовує іншу граматику: рівність і `AND`. + +## Недійсні запити {#invalid-queries} + +Розпізнаний вираз із помилкою розбору, пошуку поля чи перевірки типу повертає HTTP `422` з `reason: "validation_failed"`, `message` та масивами в `errors.query` і `validation_errors.query`. Для недійсного розміру сторінки або стану використовується ключ відповідного параметра. + +| Недійсний вираз | Виправлення | +| --- | --- | +| `Unknown = 1` | Зареєструйте атрибут у цьому namespace або виправте назву поля. | +| `OrderTotal = "1000"` | Використовуйте числовий літерал `1000`. | +| `Approved = 1` | Використовуйте `true` або `false`. | +| `Region > "eu"` | Keywords підтримують рівність і належність, а не порядок. | +| `Tags != "urgent"` або `NOT Tags IN ("urgent")` | Заперечена належність не підтримується для keyword_list. | +| `Attempt IN ()`, `Attempt = 1 AND` | Задайте непорожній список або повний предикат. | +| `DueAt > "tomorrow"` | Надішліть конкретну часову позначку. | + +## Embedded-режим і Waterline {#mode-support} + +Ця мова доступна через Server API списку workflow. Поточні embedded-списки та фільтри збережених подань Waterline не реалізують усю граматику. Їхні точні метадані-фільтри `key=value` та підрядкові поля не доводять підтримку діапазонів, `IN`, `!=` чи булевих виразів. Service-mode Waterline також потребує явної підтримки UI/API, перш ніж збережене подання можна буде вважати цією мовою запитів. Спільна робота над паритетом залишається відкритою у [функції запитів видимості](https://github.com/durable-workflow/.github/issues/224). + +Довідник спирається на [опублікований native-парсер та unit-тести](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility_query.rs), [реалізацію HTTP-пагінації](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility.rs) і [тести API списків](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/tests/execution/visibility.rs). Вони описують поведінку опублікованого Server, а не завершення паритету embedded або Waterline. diff --git a/i18n/uk/source-hashes.json b/i18n/uk/source-hashes.json index 8f81228c72e..d34df5c591d 100644 --- a/i18n/uk/source-hashes.json +++ b/i18n/uk/source-hashes.json @@ -45,7 +45,7 @@ "features/queries.md": "c66dd9542a062edd8158a46cebc9f1bf926aaf3599dca4a3122bd9860df6e2a2", "features/sagas.md": "046ba5661ccb5ac71a236356d243b021d9830123e3798afce491118434e83820", "features/schedules.md": "40d30b2767e7ed043e2b0c7180915c256accea3e7a3401c38d1bf75bfe1c2213", - "features/search-attributes.md": "bb66d83f64e0098354d86ac237e6867b9819098044101ba9a60a6a00a3961dd1", + "features/search-attributes.md": "034ce80ef59a1ba460e41ebf7d7e2d72cfa272bdce609ef5a696c7c8877aeaa5", "features/service-operations.md": "912131c0a8ef393040a933fb4a66e68abcb9d475a3ebd47c85287d4032f45a0e", "features/side-effects.md": "abdccab8d6fc1a12b3eff8a4ccc58730ac36f523559b4ad89c5c2a8d201a3b86", "features/signal+timer.md": "a05fc480544fa71f6c9b215ad3417f71b8475dd81f9de8ee18d7a3b69ac33a23", @@ -88,13 +88,14 @@ "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", - "polyglot/server-api-reference.md": "ecd6d358d6e5bde442ebf0e1ec8a072779089e2a5c4427e31eef646f42c6c03c", + "polyglot/server-api-reference.md": "d3f148fc8a12a315d695d47108ce658c80dea78c314b650a3b86f08727a20aee", "polyglot/server-config-reference.md": "aec241c0046f12a9d6efe2d6c1de443d7753bdf34135e06a6f83b3904ed1d429", "polyglot/server-role-topology.md": "3d048f0c6b5f179399622508f51e67fff8aa5a6d5b2492533fc720eeec2c27f2", "polyglot/server.md": "f24fd7ff4eebcc768ec8105e8689ab1a14cc08d98167090ebb84e3e26631132a", "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", + "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/features/search-attributes.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/features/search-attributes.md index 285447a7ab0..52480a30eda 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/features/search-attributes.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/features/search-attributes.md @@ -139,6 +139,8 @@ upsertSearchAttributes(['temporary_flag' => null]); - **历史时间线**：每个 `SearchAttributesUpserted` 事件作为类型化条目展示 - **历史导出**：JSON 历史导出包含搜索属性 +Server 端的带类型比较、时间范围、成员关系、引号和 HTTP 分页请使用[可见性查询语言](../polyglot/visibility-query-language.md)。当前嵌入模式列表和 Waterline 已保存视图筛选器没有实现完整语法。共享一致性工作仍在[可见性查询功能](https://github.com/durable-workflow/.github/issues/224)中进行。 + ### 父子运行列表筛选 {#parent-child-list-filters} 子运行[在创建时继承搜索属性和 memo](./child-workflows.md#child-metadata-inheritance)，随后可以独立更新自己的值。按继承属性筛选不会自动排除子运行。对于已注册的 keyword 属性，Server 查询 `customer = 'customer-42'` 可能返回父运行及所有仍保留该值的子运行。Memo 仍是未索引的元数据，不是另一种搜索属性筛选条件。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md index bf0ba807bc5..47d345be764 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/server-api-reference.md @@ -277,7 +277,7 @@ curl -sS "$DURABLE_WORKFLOW_SERVER_URL/api/system/health" \ | 方法 | 路径 | 用途 | | --- | --- | --- | -| `GET` | `/api/workflows` | 列出工作流实例。支持状态、类型、查询文本和数量上限等过滤。 | +| `GET` | `/api/workflows` | 列出命名空间内的工作流运行，支持状态、类型、可见性查询、`page_size` 和 `next_page_token`。 | | `POST` | `/api/workflows` | 启动工作流实例。 | | `GET` | `/api/workflows/{workflowId}` | 描述某个工作流 ID 的当前运行。 | | `GET` | `/api/workflows/{workflowId}/debug` | 返回有限诊断信息，用于调查卡住的运行。 | @@ -287,6 +287,8 @@ curl -sS "$DURABLE_WORKFLOW_SERVER_URL/api/system/health" \ | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history` | 分页读取运行历史事件。 | | `GET` | `/api/workflows/{workflowId}/runs/{runId}/history/export` | 导出某次运行的归档重放包。 | +支持的字段、带类型比较、引号、优先级、错误和分页示例见[可见性查询语言](./visibility-query-language.md)。该列表语法不同于工作流的命名查询处理程序，也不同于 schedule 列表筛选器。 + 启动请求使用语言中立的控制平面结构： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md new file mode 100644 index 00000000000..243a84eb57c --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -0,0 +1,143 @@ +--- +title: 可见性查询语言 +description: 按状态、时间、标识和带类型的搜索属性筛选 Server 工作流运行，包含 HTTP 示例和分页说明。 +--- + +# 可见性查询语言 + +使用 `GET /api/workflows?query=...` 查找 Server 某个命名空间中的运行。本参考描述[兼容性清单](../compatibility.md#last-qualified-reproducible-tuple)选定的已发布原生 Server，当前为 `%%artifact.serverVersion%%`。列表读取已存储的可见性数据，不执行工作流的命名查询处理程序。 + +请求需要 operator 或 admin 角色的 bearer 令牌、`X-Namespace` 和 `X-Durable-Workflow-Control-Plane-Version: 2`。请参阅[命名空间授权](./namespace-auth-workers.md)。结果包含所有匹配的运行，包括实例较早的运行和属性匹配的子工作流运行。没有内置的仅筛选根工作流的谓词。 + +## 发送请求 {#make-a-request} + +将 `DURABLE_WORKFLOW_SERVER_URL` 设为 Server 基础 URL，将 `DURABLE_WORKFLOW_AUTH_TOKEN` 设为 operator 或 admin 令牌。示例需要 Bash、curl 和 jq。请将固定 UTC 区间替换为要检查的时间范围。 + +```bash +query='Status = failed AND CloseTime >= "2026-11-14T00:00:00Z" AND CloseTime < "2026-11-15T00:00:00Z"' +page=$(curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50') +printf '%s\n' "$page" | jq '{workflow_count, workflows, next_page_token}' +``` + +`Status = failed` 选择的状态组还包含已取消和已终止的运行。使用 `Status = cancelled` 或 `Status = terminated` 精确选择这些状态。`running` 包括 pending、running 和 waiting。`completed` 选择已完成的运行。状态值不区分大小写。 + +对查询和分页令牌使用 `--data-urlencode`。Shell 引号、查询字符串转义和 URL 编码是不同步骤。成功响应中的 `workflows: []` 表示没有运行匹配此次请求。 + +## 字段 {#fields} + +字段名区分大小写。内置名称优先于自定义属性。 + +| 字段 | 值 | 运算符 | +| --- | --- | --- | +| `WorkflowType`, `WorkflowId`, `RunId`, `TaskQueue` | 运行类型、实例 ID、运行 ID 或任务队列 | `=`、`!=`、`IN`、否定 `IN` | +| `Status`, `ExecutionStatus` | 上述状态或状态组 | `=`, `!=` | +| `StartTime`, `ExecutionTime` | 运行的开始时刻，两个名称互为别名。 | 标量比较、`IN`、否定 `IN` | +| `CloseTime` | 运行的关闭时刻 | 标量比较、`IN`、否定 `IN` | +| `BuildId`, `BuildIds` | 运行兼容性值的别名，不是 Worker 集群查询 | keyword 运算符，但受下述原生拒绝限制 | + +标量比较为 `=`、`!=`、`<`、`<=`、`>` 和 `>=`。开始或关闭时刻缺失时，任何比较都不匹配，包括否定比较。若待返回运行的 compatibility 非 null，原生列表返回 HTTP `409` / `unqualified_build_visibility` 拒绝。能解析 build 谓词不代表按 build 列表查询已通过资格验证。 + +其他字段必须是在本命名空间注册的搜索属性。用 `GET /api/search-attributes` 查看定义，用 `POST /api/search-attributes` 和 JSON 请求体（例如 `{"name":"OrderTotal","type":"double"}`）注册属性。注册需要 admin 令牌。仅有推断出的存储类型并不使未注册键可查询。删除定义会保留存储值，但该键的查询将无效。 + +标识符必须以 ASCII 字母开头，后续为 ASCII 字母、数字或 `_`。请精确使用注册名称。Memo、可见性标签、业务键和父级/根关系名称不是额外的内置结构化字段。普通搜索仍可按下文说明查找业务键。 + +## 类型和比较 {#types-and-comparisons} + +| 注册类型 | 字面量和比较行为 | +| --- | --- | +| `keyword` | 比较整个文本值的相等或不等，支持 `IN` 和否定 `IN`，不支持排序比较。 | +| `string`, `text` | 比较整个文本值，运算符与 `keyword` 相同。不支持子串、全文或 `LIKE` 运算符。 | +| `int` | 不加引号的整数，例如 `42` 或 `-3`。支持标量比较、`IN` 和否定 `IN`。带引号的数字或小数不是整数字面量。 | +| `double` | 不加引号的整数或小数，也支持 `1.5e3` 等指数记法。支持标量比较、`IN` 和否定 `IN`。 | +| `bool` | 不加引号的 `true` 或 `false`，不区分大小写。支持标量比较、`IN` 和否定 `IN`；`false` 小于 `true`。`1` 和 `"true"` 不是布尔字面量。 | +| `datetime` | 加引号的日期时间。标量比较、`IN` 和否定 `IN` 按时刻比较。使用明确的 UTC 或带偏移量的时间戳，例如 `"2026-11-14T12:34:56.123456Z"`。 | +| `keyword_list` | `Tags = "urgent"` 检查成员关系。`Tags IN ("urgent", "review")` 匹配任一列出的成员。不等、排序和否定成员关系会被拒绝。 | + +运行缺少被查询属性时，永远不匹配该谓词，包括 `!=` 和否定 `IN`。没有存在性或 `IS NULL` 谓词。按旧的其他注册类型保留的值不会自动转换为新类型。 + +keyword、文本和内置文本字段的比较遵循数据库的相等规则。已发布 MySQL/MariaDB 模式使用 `utf8mb4_unicode_ci`，忽略大小写、重音和尾随空格。SQLite 和原生 PostgreSQL 比较是精确比较。keyword_list 的成员匹配也是精确比较。不要假定这些后端的文本查询结果相同。 + +日期时间接受 ISO 日期和时间戳，小数部分保留到微秒。仅有日期表示 UTC 午夜；省略时区时使用 UTC。可移植查询应使用明确时间戳。`tomorrow` 等相对日期和 `Europe/Paris` 等时区名称不是有效的日期时间值。请在调用方计算滚动区间，再发送固定边界。 + +## 语法、优先级和转义 {#syntax-and-escaping} + +- 比较写作 `Field operator literal`，用 `AND` 或 `OR` 分隔谓词。关键字不区分大小写。 +- `NOT` 先于 `AND` 作用于下一个谓词；`AND` 的优先级高于 `OR`。`A = 1 OR B = 2 AND C = 3` 的含义是 `A = 1 OR (B = 2 AND C = 3)`。 +- 括号仅用于非空、逗号分隔的 `IN` 列表，不用于布尔表达式分组。必要时在不同 `OR` 分支中重复谓词。 +- 否定成员关系写作 **`NOT Region IN ("eu", "us")`**。不支持 SQL 写法 `Region NOT IN (...)`。也不支持 `Status IN (...)`；请用 `Status = running OR Status = completed`。 +- 字符串可用单引号或双引号。用 `\` 转义所选引号和字面的反斜杠，例如 `Customer = 'O\'Brien'` 和 `Path = "C:\\orders"`。解析器也解码 `\n`、`\t`、`\r` 等 C 风格转义；这里 JSON 的 `\uXXXX` 不是 Unicode 转义。请直接写 Unicode 字符。 +- 不加引号的文本字面量允许 ASCII 字母、数字、`_`、`.`、`:` 和 `-`。建议给文本加引号，避免意外推断为布尔值或数字。不支持 SQL 的 `SELECT`、`ORDER BY` 或 `LIMIT` 子句。 + +表达式中的独立已注册布尔字段可表示 `Flag = true`，`NOT Flag` 表示 `Flag = false`。但单独的 `Flag` 会作为普通搜索文本。使用显式比较可避免歧义。 + +Server 通过比较语法、`IN (...)` 或开头的 `NOT` 谓词识别表达式。其他文本按工作流 ID 和业务键进行子串搜索，例如 `query=order-1001` 是普通搜索。因此，不受支持的类 SQL 文本可能退回普通搜索，而不是返回语法错误。请使用已记录的语法，并在已识别表达式无效时检查 `query` 错误。 + +## 查询示例 {#query-examples} + +将下列任一表达式作为上述 curl 请求中的 `query` 值。自定义示例假定在所选命名空间中已注册并填充 `OrderTotal: double`、`Attempt: int`、`Region: keyword`、`Tags: keyword_list`、`Approved: bool` 和 `DueAt: datetime`。 + +| 任务 | 查询 | +| --- | --- | +| 超过数值阈值的订单 | `WorkflowType = "orders.fulfillment" AND OrderTotal > 1000` | +| 闭区间内的尝试次数 | `Attempt >= 2 AND Attempt <= 5` | +| 任一地区 | `Region IN ("eu", "us")` | +| 其他已记录地区 | `NOT Region IN ("eu", "us")` | +| 列表中的任一标签 | `Tags IN ("urgent", "review")` | +| 明确的 false | `Approved = false` | +| 时间窗口 | `DueAt >= "2026-11-14T00:00:00Z" AND DueAt < "2026-11-15T00:00:00Z"` | +| 同一类型下的两个队列 | `WorkflowType = "orders.fulfillment" AND TaskQueue = "orders" OR WorkflowType = "orders.fulfillment" AND TaskQueue = "priority"` | + +## 分页和限制 {#pagination-and-limits} + +| 参数 | 行为 | +| --- | --- | +| `workflow_type` | 可选的精确类型筛选，与 `query`、`status` 通过 `AND` 结合。 | +| `status` | 可选筛选。建议使用规范状态组 `running`、`completed` 或 `failed`。当前列表端点还接受精确的 `cancelled`、`terminated`；此处不接受 `pending`、`waiting`。 | +| `page_size` | 从 `1` 到 `200` 的整数，默认 `50`。使用此参数，不要使用 `limit`。 | +| `next_page_token` | 原样复制前一响应的令牌，不要解码或自行构造。令牌为 null 时停止。 | + +`workflow_count` 是本页数量，不是全部匹配运行的总数。结果先按开始/排序时间降序，再按运行 ID 降序排列。分页使用偏移量读取实时数据。应保持命名空间、查询、筛选和页大小不变。请求之间的插入、关闭或属性更新可能移动匹配项，造成重复或遗漏；它不是快照导出。无效令牌当前会从第一页重新开始，而不是返回错误。 + +如果第一页包含后续令牌，用以下方式获取下一页： + +```bash +next=$(printf '%s\n' "$page" | jq -r '.next_page_token // empty') +if [ -n "$next" ]; then + curl --fail-with-body --silent --show-error --get \ + "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \ + -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \ + -H 'X-Namespace: default' \ + -H 'X-Durable-Workflow-Control-Plane-Version: 2' \ + --data-urlencode "query=$query" \ + --data-urlencode 'page_size=50' \ + --data-urlencode "next_page_token=$next" | jq . +fi +``` + +页大小限制返回行数，不限制查询求值工作量。请控制表达式和 `IN` 列表大小，并使用选择性较高的类型、状态或属性谓词。工作流解析器没有采用 schedule API 的 2048 字符查询限制。HTTP 服务器和代理可以施加自己的请求 URI 限制。[Schedule 列表](./server-api-reference.md#schedule-list-filters)使用不同的语法，仅支持相等与 `AND`。 + +## 无效查询 {#invalid-queries} + +已识别表达式若在解析、字段查找或类型检查时失败，返回 HTTP `422`，包含 `reason: "validation_failed"`、`message`，以及 `errors.query` 和 `validation_errors.query` 数组。页大小或状态无效时，改用相应参数键。 + +| 无效表达式 | 修正方式 | +| --- | --- | +| `Unknown = 1` | 在当前命名空间注册属性，或修正字段名。 | +| `OrderTotal = "1000"` | 使用数值字面量 `1000`。 | +| `Approved = 1` | 使用 `true` 或 `false`。 | +| `Region > "eu"` | keyword 支持相等和成员关系，不支持排序比较。 | +| `Tags != "urgent"` 或 `NOT Tags IN ("urgent")` | keyword_list 不支持否定成员关系。 | +| `Attempt IN ()`, `Attempt = 1 AND` | 提供非空列表或完整谓词。 | +| `DueAt > "tomorrow"` | 发送具体时间戳。 | + +## 嵌入模式和 Waterline {#mode-support} + +Server 的工作流列表 API 提供此语言。当前嵌入模式列表和 Waterline 已保存视图筛选器没有实现完整语法。现有精确 `key=value` 元数据筛选和子串字段不代表支持范围、`IN`、`!=` 或布尔表达式。服务模式 Waterline 也需要明确的 UI/API 支持，才能将已保存视图视为此查询语言。共享一致性工作仍在[可见性查询功能](https://github.com/durable-workflow/.github/issues/224)中跟踪。 + +本参考依据[已发布的原生解析器及其单元测试](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility_query.rs)、[HTTP 分页实现](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/src/runtime/visibility.rs)和[列表 API 测试](https://github.com/durable-workflow/server/blob/b6e04ce7e679464e91f6ceae83310d3bb3204092/rust/tests/execution/visibility.rs)。它们描述已发布 Server 的行为，不表示嵌入模式或 Waterline 一致性工作已完成。 diff --git a/i18n/zh-Hans/source-hashes.json b/i18n/zh-Hans/source-hashes.json index 8f81228c72e..d34df5c591d 100644 --- a/i18n/zh-Hans/source-hashes.json +++ b/i18n/zh-Hans/source-hashes.json @@ -45,7 +45,7 @@ "features/queries.md": "c66dd9542a062edd8158a46cebc9f1bf926aaf3599dca4a3122bd9860df6e2a2", "features/sagas.md": "046ba5661ccb5ac71a236356d243b021d9830123e3798afce491118434e83820", "features/schedules.md": "40d30b2767e7ed043e2b0c7180915c256accea3e7a3401c38d1bf75bfe1c2213", - "features/search-attributes.md": "bb66d83f64e0098354d86ac237e6867b9819098044101ba9a60a6a00a3961dd1", + "features/search-attributes.md": "034ce80ef59a1ba460e41ebf7d7e2d72cfa272bdce609ef5a696c7c8877aeaa5", "features/service-operations.md": "912131c0a8ef393040a933fb4a66e68abcb9d475a3ebd47c85287d4032f45a0e", "features/side-effects.md": "abdccab8d6fc1a12b3eff8a4ccc58730ac36f523559b4ad89c5c2a8d201a3b86", "features/signal+timer.md": "a05fc480544fa71f6c9b215ad3417f71b8475dd81f9de8ee18d7a3b69ac33a23", @@ -88,13 +88,14 @@ "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", - "polyglot/server-api-reference.md": "ecd6d358d6e5bde442ebf0e1ec8a072779089e2a5c4427e31eef646f42c6c03c", + "polyglot/server-api-reference.md": "d3f148fc8a12a315d695d47108ce658c80dea78c314b650a3b86f08727a20aee", "polyglot/server-config-reference.md": "aec241c0046f12a9d6efe2d6c1de443d7753bdf34135e06a6f83b3904ed1d429", "polyglot/server-role-topology.md": "3d048f0c6b5f179399622508f51e67fff8aa5a6d5b2492533fc720eeec2c27f2", "polyglot/server.md": "f24fd7ff4eebcc768ec8105e8689ab1a14cc08d98167090ebb84e3e26631132a", "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", + "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", From bca68960fdf4fd5ec7794161effa98a972e79983 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Sat, 14 Nov 2026 10:59:37 +0000 Subject: [PATCH 3/4] Use explicit document navigation for visibility reference --- sidebars.js | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/sidebars.js b/sidebars.js index 1d3705c4b33..6f417f1ffe5 100644 --- a/sidebars.js +++ b/sidebars.js @@ -52,7 +52,10 @@ const sidebars = { 'polyglot/cli-python-parity', 'polyglot/server-config-reference', 'polyglot/server-api-reference', - 'polyglot/visibility-query-language', + { + type: 'doc', + id: 'polyglot/visibility-query-language', + }, 'polyglot/server-role-topology', 'polyglot/namespace-auth-workers', 'polyglot/worker-compatibility-routing', From df8dd7973eafb5eefe73deab875c54c47a6538f5 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Sat, 14 Nov 2026 11:03:21 +0000 Subject: [PATCH 4/4] Link visibility reference through existing API navigation --- docs/polyglot/visibility-query-language.md | 1 + .../current/polyglot/visibility-query-language.md | 1 + i18n/de/source-hashes.json | 2 +- .../current/polyglot/visibility-query-language.md | 1 + i18n/es/source-hashes.json | 2 +- .../current/polyglot/visibility-query-language.md | 1 + i18n/fr/source-hashes.json | 2 +- .../current/polyglot/visibility-query-language.md | 1 + i18n/ja/source-hashes.json | 2 +- .../current/polyglot/visibility-query-language.md | 1 + i18n/pt-BR/source-hashes.json | 2 +- .../current/polyglot/visibility-query-language.md | 1 + i18n/uk/source-hashes.json | 2 +- .../current/polyglot/visibility-query-language.md | 1 + i18n/zh-Hans/source-hashes.json | 2 +- sidebars.js | 4 ---- 16 files changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/polyglot/visibility-query-language.md b/docs/polyglot/visibility-query-language.md index fbdda4d52c6..068a9472695 100644 --- a/docs/polyglot/visibility-query-language.md +++ b/docs/polyglot/visibility-query-language.md @@ -1,4 +1,5 @@ --- +displayed_sidebar: tutorialSidebar title: Visibility Query Language description: Filter Server workflow runs by status, time, identity and typed search attributes, with HTTP examples and pagination. --- diff --git a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md index 42ff73cf0a4..9a1b0a7f69d 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -1,4 +1,5 @@ --- +displayed_sidebar: tutorialSidebar title: Visibility-Abfragesprache description: Server-Ausführungen nach Status, Zeit, Identität und typisierten Suchattributen filtern, mit HTTP-Beispielen und Seitennavigation. --- diff --git a/i18n/de/source-hashes.json b/i18n/de/source-hashes.json index d34df5c591d..7ef1a28e1e1 100644 --- a/i18n/de/source-hashes.json +++ b/i18n/de/source-hashes.json @@ -95,7 +95,7 @@ "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", - "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", + "polyglot/visibility-query-language.md": "15790074c904c6cdbb1de8dfade95ea9ca6391f2f16412db517a2fb84ef08334", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/es/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md index ca58339dd9c..c5026064201 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -1,4 +1,5 @@ --- +displayed_sidebar: tutorialSidebar title: Lenguaje de consultas de visibilidad description: Filtre ejecuciones del Server por estado, tiempo, identidad y atributos de búsqueda tipados, con ejemplos HTTP y paginación. --- diff --git a/i18n/es/source-hashes.json b/i18n/es/source-hashes.json index d34df5c591d..7ef1a28e1e1 100644 --- a/i18n/es/source-hashes.json +++ b/i18n/es/source-hashes.json @@ -95,7 +95,7 @@ "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", - "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", + "polyglot/visibility-query-language.md": "15790074c904c6cdbb1de8dfade95ea9ca6391f2f16412db517a2fb84ef08334", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md index bee66b223fe..eed3ad249a2 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -1,4 +1,5 @@ --- +displayed_sidebar: tutorialSidebar title: Langage de requêtes de visibilité description: Filtrer les exécutions du Server par état, temps, identité et attributs de recherche typés, avec exemples HTTP et pagination. --- diff --git a/i18n/fr/source-hashes.json b/i18n/fr/source-hashes.json index d34df5c591d..7ef1a28e1e1 100644 --- a/i18n/fr/source-hashes.json +++ b/i18n/fr/source-hashes.json @@ -95,7 +95,7 @@ "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", - "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", + "polyglot/visibility-query-language.md": "15790074c904c6cdbb1de8dfade95ea9ca6391f2f16412db517a2fb84ef08334", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md index c0be7ab3305..c0b6e280cee 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -1,4 +1,5 @@ --- +displayed_sidebar: tutorialSidebar title: 可視性クエリ言語 description: 状態、時刻、識別情報、型付き検索属性で Server の実行を絞り込む HTTP 例とページングのリファレンス。 --- diff --git a/i18n/ja/source-hashes.json b/i18n/ja/source-hashes.json index d34df5c591d..7ef1a28e1e1 100644 --- a/i18n/ja/source-hashes.json +++ b/i18n/ja/source-hashes.json @@ -95,7 +95,7 @@ "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", - "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", + "polyglot/visibility-query-language.md": "15790074c904c6cdbb1de8dfade95ea9ca6391f2f16412db517a2fb84ef08334", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md index 9df79fde555..b0139c7a8f0 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -1,4 +1,5 @@ --- +displayed_sidebar: tutorialSidebar title: Linguagem de consultas de visibilidade description: Filtre execuções do Server por estado, tempo, identidade e atributos de busca tipados, com exemplos HTTP e paginação. --- diff --git a/i18n/pt-BR/source-hashes.json b/i18n/pt-BR/source-hashes.json index d34df5c591d..7ef1a28e1e1 100644 --- a/i18n/pt-BR/source-hashes.json +++ b/i18n/pt-BR/source-hashes.json @@ -95,7 +95,7 @@ "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", - "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", + "polyglot/visibility-query-language.md": "15790074c904c6cdbb1de8dfade95ea9ca6391f2f16412db517a2fb84ef08334", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md index 930fdf40fd6..728fe1a4b9f 100644 --- a/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md +++ b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -1,4 +1,5 @@ --- +displayed_sidebar: tutorialSidebar title: Мова запитів видимості description: Фільтрування запусків Server за станом, часом, ідентичністю та типізованими атрибутами пошуку, з HTTP-прикладами й пагінацією. --- diff --git a/i18n/uk/source-hashes.json b/i18n/uk/source-hashes.json index d34df5c591d..7ef1a28e1e1 100644 --- a/i18n/uk/source-hashes.json +++ b/i18n/uk/source-hashes.json @@ -95,7 +95,7 @@ "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", - "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", + "polyglot/visibility-query-language.md": "15790074c904c6cdbb1de8dfade95ea9ca6391f2f16412db517a2fb84ef08334", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md index 243a84eb57c..bb0207ab464 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/visibility-query-language.md @@ -1,4 +1,5 @@ --- +displayed_sidebar: tutorialSidebar title: 可见性查询语言 description: 按状态、时间、标识和带类型的搜索属性筛选 Server 工作流运行，包含 HTTP 示例和分页说明。 --- diff --git a/i18n/zh-Hans/source-hashes.json b/i18n/zh-Hans/source-hashes.json index d34df5c591d..7ef1a28e1e1 100644 --- a/i18n/zh-Hans/source-hashes.json +++ b/i18n/zh-Hans/source-hashes.json @@ -95,7 +95,7 @@ "polyglot/service-operations.md": "a2ee46ac8d2e4f18aed4e3cb47a4f0b36f51ccc67f1e841efb99f0297391cf27", "polyglot/task-matching-dispatch.md": "9c8ffbbee16b5da48e7882721d7ba8eac209a374a6ca766d93d2b17e825b203d", "polyglot/task-queue-admission.md": "efcf934876a27c153dd3ecd1a995e7c08b37452c79dfcbba1ae7fa0a8cbad327", - "polyglot/visibility-query-language.md": "5ea156e9764b3d1061f3e527dbf884dc9d2c4d71c33d30f8af294b88acd45106", + "polyglot/visibility-query-language.md": "15790074c904c6cdbb1de8dfade95ea9ca6391f2f16412db517a2fb84ef08334", "polyglot/worker-build-id-rollout.md": "62ddf1ca054cf4b83de2fa020f313a153ece00519f804c4f8f30aca53c979af0", "polyglot/worker-compatibility-routing.md": "ef58f23c112f0e6b968927ba861177903adca21ed33b6b9371681e23a18b2994", "polyglot/worker-protocol.md": "007e844b0a7ab284b7cd343e79f01a27a0dabee3fe4cf19064170581bb897b85", diff --git a/sidebars.js b/sidebars.js index 6f417f1ffe5..df8c65dd940 100644 --- a/sidebars.js +++ b/sidebars.js @@ -52,10 +52,6 @@ const sidebars = { 'polyglot/cli-python-parity', 'polyglot/server-config-reference', 'polyglot/server-api-reference', - { - type: 'doc', - id: 'polyglot/visibility-query-language', - }, 'polyglot/server-role-topology', 'polyglot/namespace-auth-workers', 'polyglot/worker-compatibility-routing',