From ff0a9b262fb7bb1b27d789bb8428130ea414d6a6 Mon Sep 17 00:00:00 2001 From: bosd <5e2fd43-d292-4c90-9d1f-74ff3436329a@anonaddy.me> Date: Thu, 11 Jun 2026 11:36:05 +0200 Subject: [PATCH 1/2] docs: add 'Choosing the Right Options' feature-discovery guide The CLI reference (sphinx-click) documents every flag, but a user with a *problem* can't easily tell which feature solves it. Add a problem->feature map covering speed, relational data, idempotency, resilience, messy data, deadlocks, and hierarchies, linking to the in-depth guides. Wired early in the guides toctree. --- docs/guides/choosing_options.md | 79 +++++++++++++++++++++++++++++++++ docs/guides/index.md | 1 + 2 files changed, 80 insertions(+) create mode 100644 docs/guides/choosing_options.md diff --git a/docs/guides/choosing_options.md b/docs/guides/choosing_options.md new file mode 100644 index 00000000..9f977e37 --- /dev/null +++ b/docs/guides/choosing_options.md @@ -0,0 +1,79 @@ +# Guide: Choosing the Right Options + +`fluvo`'s `import` command has many options for performance, resilience, relational +data, and messy sources. This guide maps **common problems to the features that solve +them**, with links to the in-depth guides. For the complete, always-up-to-date option +list, see the [CLI reference](../usage.md). + +## "My import is slow" + +| Reach for | What it does | +|---|---| +| `--resolve-relation` | Resolve relation columns in Polars so Odoo runs **no `name_search`** ([Performance Tuning](performance_tuning.md)) | +| `--skip-unchanged` | On a re-import, send only new/changed rows via a vectorized anti-join | +| `--size` | Bigger batches (default 500) — fewer round-trips | +| `--worker` with `--groupby` | Parallel import without write deadlocks ([Performance Tuning](performance_tuning.md)) | +| JSON-RPC protocol | Faster transport than XML-RPC | + +## "I'm importing relational data" + +| Reach for | What it does | +|---|---| +| (automatic two-pass) | Relational fields are deferred to a second pass to avoid inverse-relation rewrites ([Performance Tuning](performance_tuning.md)) | +| `--deferred-fields` / `--auto-defer` | Manually or automatically defer specific relational fields | +| `--check-refs fail\|warn\|skip` | Pre-import validation that referenced XML IDs exist | +| `--auto-create-refs` | Auto-create missing related records for many2one fields | +| `--on-missing-ref field:action` | Per-field handling of a missing reference (create/skip/...) | +| `--set-empty-on-missing` | Set a relation to empty rather than failing when its target is missing | + +## "I'm re-running an import (idempotency)" + +| Reach for | What it does | +|---|---| +| `--skip-unchanged` | Send only rows whose values actually changed | +| `--skip-existing` | Skip records that already exist (by external id) | + +## "My server is unstable, or the import is huge" + +| Reach for | What it does | +|---|---| +| `--adaptive-throttle` | Auto-scale batch size to the server's health ([Performance Tuning](performance_tuning.md)) | +| `--resume` / `--no-checkpoint` | Resume an interrupted import from its checkpoint (or disable checkpointing) | +| `--max-batch-bytes` | Cap each batch's payload size | +| `--stream` | Stream very large CSVs without loading them fully into memory | + +## "My source data is messy" + +| Reach for | What it does | +|---|---| +| `--dry-run` | Validate the file against the model without importing | +| `--auto-clean` | Safe, type-aware coercions (whitespace, null tokens, booleans) before load | +| `--fallback-values field:value` | Defaults for invalid selection/boolean values | +| `--fail` | Route bad rows to a fail file instead of aborting the batch | + +## "I'm hitting concurrent-update deadlocks" + +| Reach for | What it does | +|---|---| +| `--groupby` | Partition work so workers never update the same parent concurrently ([Performance Tuning](performance_tuning.md)) | +| `--auto-groupby` | Let fluvo pick the partition column | + +## "I'm importing hierarchical / nested data" + +| Reach for | What it does | +|---|---| +| `--defer-parent-store` | Defer `parent_left`/`parent_right` recomputation for nested models | +| `--deferred-fields parent_id` | Defer the self-referencing field to a second pass | + +## Product-specific + +| Reach for | What it does | +|---|---| +| `--fix-missing-variants` | After a `product.template` import, create default variants for templates that have none (Odoo's `load()` doesn't) ([Odoo Workflows](odoo_workflows.md)) | +| `fluvo workflow create-missing-variants` | The same fix, runnable any time as a standalone command | + +--- + +Every option above is also documented in full in the [CLI reference](../usage.md), and +the [Performance Tuning](performance_tuning.md) guide explains the speed-related ones in +depth. diff --git a/docs/guides/index.md b/docs/guides/index.md index 9976a9a0..1ffad0fd 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -7,6 +7,7 @@ This section provides detailed, step-by-step guides for common tasks and advance :caption: "Guides" importing_data +choosing_options exporting_data exporting_data_for_modules data_transformations From 4fe7f0d6013da6bbfb5cb3897b5dbc7fdc298131 Mon Sep 17 00:00:00 2001 From: bosd <5e2fd43-d292-4c90-9d1f-74ff3436329a@anonaddy.me> Date: Thu, 11 Jun 2026 16:25:14 +0200 Subject: [PATCH 2/2] docs: use | HTML entity for pipes in table cells (review) Backslash-escaped pipes (\|) can render literally or break tables on some markdown engines; the HTML entity is portable. --- docs/guides/choosing_options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/choosing_options.md b/docs/guides/choosing_options.md index 9f977e37..9b1fdb2e 100644 --- a/docs/guides/choosing_options.md +++ b/docs/guides/choosing_options.md @@ -21,7 +21,7 @@ list, see the [CLI reference](../usage.md). |---|---| | (automatic two-pass) | Relational fields are deferred to a second pass to avoid inverse-relation rewrites ([Performance Tuning](performance_tuning.md)) | | `--deferred-fields` / `--auto-defer` | Manually or automatically defer specific relational fields | -| `--check-refs fail\|warn\|skip` | Pre-import validation that referenced XML IDs exist | +| `--check-refs fail|warn|skip` | Pre-import validation that referenced XML IDs exist | | `--auto-create-refs` | Auto-create missing related records for many2one fields | | `--on-missing-ref field:action` | Per-field handling of a missing reference (create/skip/...) | | `--set-empty-on-missing` | Set a relation to empty rather than failing when its target is missing |