docs: improve fallbacks vignette

Author: maelle

vignettes/fallback.Rmd

@@ -45,10 +45,10 @@ conflict_prefer("filter", "dplyr")
 ## Introduction
 
 The duckplyr package aims at providing a fully compatible drop-in replacement for dplyr.
-To achieve this, only a carefully selected subset of dplyr's operations, R functions, and R data types are implemented.
+Currently, only a carefully selected subset of dplyr's operations, R functions, and R data types are implemented (see `vignette("limits")`).
 Whenever a request cannot be handled by DuckDB, duckplyr falls back to dplyr.
 
-## DuckDB operation
+## A pipeline directly supported by duckplyr
 
 The following operation is supported by duckplyr:
 
@@ -67,13 +67,18 @@ duckdb %>%
   explain()
 ```
 
-The plan shows three operations: a data frame scan (the input), a sort operation, and a projection (adding the `b` column and removing the `a` column).
-Because each operation is supported by DuckDB, the resulting object contains a plan for the entire pipeline.
-The plan is only executed when the data is needed.
+The plan shows three **operations**: 
 
-## Relation objects
+- a data frame scan (the input), 
+- a sort operation,
+- a projection (adding the `b` column and removing the `a` column).
 
-DuckDB accepts a tree of interconnected _relation objects_ as input.
+Because each operation is supported by DuckDB, the resulting object contains a **plan for the entire pipeline**.
+The plan is only executed when the data is needed, i.e. lazily (see `vignette("prudence")`).
+
+### Relation objects
+
+DuckDB accepts a tree of interconnected *relation objects* as input.
 Each relation object represents a logical step of the execution plan.
 The duckplyr package translates dplyr verbs into relation objects.
 
@@ -93,7 +98,7 @@ duckplyr::last_rel()
 
 The `last_rel()` function now shows a relation that describes logical plan for executing the whole pipeline.
 
-## Functionality not supported by DuckDB
+## A pipeline with functionality not directly supported by duckplyr
 
 Using a custom function with a side effect is not supported by DuckDB and triggers a dplyr fallback:
 
@@ -110,7 +115,7 @@ fallback <-
   select(-a)
 ```
 
-The `verbose_plus_one()` function is not supported by DuckDB, so the `mutate()` step is handled by dplyr and already executed when the pipeline is defined.
+The `verbose_plus_one()` function is not supported by DuckDB, so the `mutate()` step is handled by dplyr and already executed when the pipeline is defined, i.e. eagerly.
 This is confirmed by the `last_rel()` function:
 
 ```{r}
@@ -140,10 +145,26 @@ duckplyr::last_rel()
 
 The `last_rel()` function confirms that only the final `select()` is handled by DuckDB again.
 
+## Configure fallbacks
+
+Using the `fallback_sitrep()` and `fallback_config()` functions you can examine and change settings related to fallbacks.
+
+- You can choose to make fallbacks verbose with `fallback_config(info = TRUE)`.
+
+- You can change settings related to logging and reporting fallback to duckplyr development team to inform their work. See `vignette("telemetry")`.
+
+### Enforcing DuckDB operation
+
+For any duck frame, one can control the automatic materialization.
+For fallbacks to dplyr, automatic materialization must be allowed for the frame at hand, as dplyr necessitate eager evaluation.
+
+Therefore, by making a data frame frugal, one can ensure a pipeline will error when a fallback to dplyr would have normally happened. See `vignette("prudence")`.
+
+By using operations supported by duckplyr and avoiding fallbacks as much as possible, your pipelines will be executed by DuckDB in an optimized way.
+
 ## Conclusion
 
 The fallback mechanism in duckplyr allows for a seamless integration of dplyr verbs and R functions that are not supported by DuckDB.
 It is transparent to the user and only triggers when necessary.
 With small or medium-sized data sets, it will not even be noticeable in most settings.
 
-See `vignette("large")` for techniques for working with large data, `vignette("limits")` for the currently implementated translations, `vignette("prudence")` for details on controlling fallback behavior, and `vignette("telemetry")` for the automatic reporting of fallback situations.