Docs: Add Examples to Config Options page

datafusion/common/src/config.rs

@@ -1008,11 +1008,23 @@ impl ConfigOptions {
         e.0.set(key, value)
     }
 
-    /// Create new ConfigOptions struct, taking values from
-    /// environment variables where possible.
+    /// Create new [`ConfigOptions`], taking values from environment variables
+    /// where possible.
     ///
-    /// For example, setting `DATAFUSION_EXECUTION_BATCH_SIZE` will
-    /// control `datafusion.execution.batch_size`.
+    /// For example, to configure `datafusion.execution.batch_size`
+    /// ([`ExecutionOptions::batch_size`]) you would set the
+    /// `DATAFUSION_EXECUTION_BATCH_SIZE` environment variable.
+    ///
+    /// The name of the environment variable is the option's key, transformed to
+    /// uppercase and with periods replaced with underscores.
+    ///
+    /// Values are parsed according to the [same rules used in casts from
+    /// Utf8](https://docs.rs/arrow/latest/arrow/compute/kernels/cast/fn.cast.html).
+    ///
+    /// If the value in the environment variable cannot be cast to the type of
+    /// the configuration option, the default value will be used instead and a
+    /// warning emitted. Environment variables are read when this method is
+    /// called, and are not re-read later.
     pub fn from_env() -> Result<Self> {
         struct Visitor(Vec<String>);
 

datafusion/execution/src/config.rs

@@ -117,6 +117,9 @@ impl SessionConfig {
     }
 
     /// Create an execution config with config options read from the environment
+    ///
+    /// See [`ConfigOptions::from_env`] for details on how environment variables
+    /// are mapped to config options.
     pub fn from_env() -> Result<Self> {
         Ok(ConfigOptions::from_env()?.into())
     }

dev/update_config_docs.sh

@@ -50,22 +50,49 @@ cat <<'EOF' > "$TARGET_FILE"
 -->
 
 <!---
-This file was generated by the dev/update_config_docs.sh script.
+NOTE: This file was generated by the dev/update_config_docs.sh script.
 Do not edit it manually as changes will be overwritten.
 Instead, edit dev/update_config_docs.sh or the docstrings in datafusion/core/src/config.rs.
 -->
 
 # Configuration Settings
 
-The following configuration options can be passed to `SessionConfig` to control various aspects of query execution.
+DataFusion configurations control various aspects of DataFusion planning and execution
 
-For applications which do not expose `SessionConfig`, like `datafusion-cli`, these options may also be set via environment variables.
-To construct a session with options from the environment, use `SessionConfig::from_env`.
-The name of the environment variable is the option's key, transformed to uppercase and with periods replaced with underscores.
-For example, to configure `datafusion.execution.batch_size` you would set the `DATAFUSION_EXECUTION_BATCH_SIZE` environment variable.
-Values are parsed according to the [same rules used in casts from Utf8](https://docs.rs/arrow/latest/arrow/compute/kernels/cast/fn.cast.html).
-If the value in the environment variable cannot be cast to the type of the configuration option, the default value will be used instead and a warning emitted.
-Environment variables are read during `SessionConfig` initialisation so they must be set beforehand and will not affect running sessions.
+## Setting Configuration Options
+
+### Programmatically
+You can set the options programmatically via the [`ConfigOptions`] object. For
+example, to configure the `datafusion.execution.target_partitions` using the API:
+
+```rust
+use datafusion::common::config::ConfigOptions;
+let mut config = ConfigOptions::new();
+config.execution.target_partitions = 1;
+```
+
+### Via Environment Variables
+
+You can also set configuration options via environment variables using
+[`ConfigOptions::from_env`], for example
+
+```shell
+DATAFUSION_EXECUTION_TARGET_PARTITIONS=1 ./your_program
+```
+
+### Via SQL
+
+You can also set configuration options via SQL using the `SET` command. For
+example, to configure `datafusion.execution.target_partitions`:
+
+```sql
+SET datafusion.execution.target_partitions = '1';
+```
+
+[`ConfigOptions`]: https://docs.rs/datafusion/latest/datafusion/common/config/struct.ConfigOptions.html
+[`ConfigOptions::from_env`]: https://docs.rs/datafusion/latest/datafusion/common/config/struct.ConfigOptions.html#method.from_env
+
+The following configuration settings are available:
 
 EOF
 

docs/source/user-guide/configs.md

@@ -18,22 +18,50 @@
 -->
 
 <!---
-This file was generated by the dev/update_config_docs.sh script.
+NOTE: This file was generated by the dev/update_config_docs.sh script.
 Do not edit it manually as changes will be overwritten.
 Instead, edit dev/update_config_docs.sh or the docstrings in datafusion/core/src/config.rs.
 -->
 
 # Configuration Settings
 
-The following configuration options can be passed to `SessionConfig` to control various aspects of query execution.
+DataFusion configurations control various aspects of DataFusion planning and execution
 
-For applications which do not expose `SessionConfig`, like `datafusion-cli`, these options may also be set via environment variables.
-To construct a session with options from the environment, use `SessionConfig::from_env`.
-The name of the environment variable is the option's key, transformed to uppercase and with periods replaced with underscores.
-For example, to configure `datafusion.execution.batch_size` you would set the `DATAFUSION_EXECUTION_BATCH_SIZE` environment variable.
-Values are parsed according to the [same rules used in casts from Utf8](https://docs.rs/arrow/latest/arrow/compute/kernels/cast/fn.cast.html).
-If the value in the environment variable cannot be cast to the type of the configuration option, the default value will be used instead and a warning emitted.
-Environment variables are read during `SessionConfig` initialisation so they must be set beforehand and will not affect running sessions.
+## Setting Configuration Options
+
+### Programmatically
+
+You can set the options programmatically via the [`ConfigOptions`] object. For
+example, to configure the `datafusion.execution.target_partitions` using the API:
+
+```rust
+use datafusion::common::config::ConfigOptions;
+let mut config = ConfigOptions::new();
+config.execution.target_partitions = 1;
+```
+
+### Via Environment Variables
+
+You can also set configuration options via environment variables using
+[`ConfigOptions::from_env`], for example
+
+```shell
+DATAFUSION_EXECUTION_TARGET_PARTITIONS=1 ./your_program
+```
+
+### Via SQL
+
+You can also set configuration options via SQL using the `SET` command. For
+example, to configure `datafusion.execution.target_partitions`:
+
+```sql
+SET datafusion.execution.target_partitions = '1';
+```
+
+[`configoptions`]: https://docs.rs/datafusion/latest/datafusion/common/config/struct.ConfigOptions.html
+[`configoptions::from_env`]: https://docs.rs/datafusion/latest/datafusion/common/config/struct.ConfigOptions.html#method.from_env
+
+The following configuration settings are available:
 
 | key                                                                     | default                   | description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | ----------------------------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |