diff --git a/docs/3.0/develop/results.mdx b/docs/3.0/develop/results.mdx index 7777978e60e97..493800a64949c 100644 --- a/docs/3.0/develop/results.mdx +++ b/docs/3.0/develop/results.mdx @@ -33,6 +33,7 @@ keyword and the `PREFECT_DEFAULT_RESULT_STORAGE_BLOCK` setting. the `result_serializer` keyword and the `PREFECT_RESULTS_DEFAULT_SERIALIZER` setting. - [what filename to use](/3.0/develop/results#result-filenames): this is configured through one of `result_storage_key`, `cache_policy`, or `cache_key_fn`. + ### Default persistence configuration Once result persistence is enabled - whether through the `PREFECT_RESULTS_PERSIST_BY_DEFAULT` setting or @@ -50,7 +51,10 @@ prefect config set PREFECT_LOCAL_STORAGE_PATH='~/.my-results/' ### Enabling result persistence -In addition to the `PREFECT_RESULTS_PERSIST_BY_DEFAULT` and `PREFECT_TASKS_DEFAULT_PERSIST_RESULT` settings, result persistence can also be enabled or disabled on both individual flows and individual tasks. Specifying a non-null value for any of the following keywords on the task decorator will enable result persistence for that task: +In addition to the `PREFECT_RESULTS_PERSIST_BY_DEFAULT` and `PREFECT_TASKS_DEFAULT_PERSIST_RESULT` settings, +result persistence can also be enabled or disabled on both individual flows and individual tasks. +Specifying a non-null value for any of the following keywords on the task decorator will enable result +persistence for that task: - `persist_result`: a boolean that allows you to explicitly enable or disable result persistence. - `result_storage`: accepts either a string reference to a storage block or a storage block class that specifies where results should be stored. - `result_storage_key`: a string that specifies the filename of the result within the task's result storage. @@ -58,17 +62,20 @@ In addition to the `PREFECT_RESULTS_PERSIST_BY_DEFAULT` and `PREFECT_TASKS_DEFAU - `cache_policy`: a [cache policy](/3.0/develop/task-caching#cache-policies) specifying the behavior of the task's cache. - `cache_key_fn`: [a function](/3.0/develop/task-caching#cache-key-functions) that configures a custom cache policy. -Similarly, setting `persist_result=True`, `result_storage`, or `result_serializer` on a flow will enable persistence for that flow. +Similarly, setting `persist_result=True`, `result_storage`, or `result_serializer` on a flow will enable +persistence for that flow. **Enabling persistence on a flow enables persistence by default for its tasks** -Enabling result persistence on a flow through any of the above keywords will also enable it for all tasks called within that flow by default. +Enabling result persistence on a flow through any of the above keywords will also enable it for all +tasks called within that flow by default. Any settings _explicitly_ set on a task take precedence over the flow settings. Additionally, the `PREFECT_TASKS_DEFAULT_PERSIST_RESULT` environment variable can be used to globally control the default persistence behavior for tasks, overriding the default behavior set by a parent flow or task. + ### Result storage You can configure the system of record for your results through the `result_storage` keyword argument. @@ -162,6 +169,7 @@ def my_flow(): If a result exists at a given storage key in the storage location, the task will load it without running. To learn more about caching mechanics in Prefect, see the [caching documentation](/3.0/develop/task-caching). + ### Result serialization You can configure how results are serialized to storage using result serializers. diff --git a/docs/3.0/develop/settings-ref.mdx b/docs/3.0/develop/settings-ref.mdx index db4aad9ef5ee5..66dfd3be373ed 100644 --- a/docs/3.0/develop/settings-ref.mdx +++ b/docs/3.0/develop/settings-ref.mdx @@ -3,7 +3,7 @@ title: Settings reference description: Reference for all available settings for Prefect. --- {/* This page is generated by `scripts/generate_settings_ref.py`. Update the generation script to update this page. */} -## Root Settings +## Root Settings ### `home` The path to the Prefect home directory. Defaults to ~/.prefect @@ -176,17 +176,28 @@ If `True`, warn on usage of experimental features. **Supported environment variables**: `PREFECT_EXPERIMENTAL_WARN` -### `default_persist_result` -If `True`, results will be persisted by default for all tasks. Set to `False` to disable persistence by default. Note that setting to `False` will override the behavior set by a parent flow or task. +### `async_fetch_state_result` -**Type**: `boolean | None` + Determines whether `State.result()` fetches results automatically or not. + In Prefect 2.6.0, the `State.result()` method was updated to be async + to facilitate automatic retrieval of results from storage which means when + writing async code you must `await` the call. For backwards compatibility, + the result is not retrieved by default for async users. You may opt into this + per call by passing `fetch=True` or toggle this setting to change the behavior + globally. -**Default**: `None` -**TOML dotted key path**: `tasks.default_persist_result` +**Type**: `boolean` + +**Default**: `False` + +**TOML dotted key path**: `async_fetch_state_result` **Supported environment variables**: -`PREFECT_TASKS_DEFAULT_PERSIST_RESULT` +`PREFECT_ASYNC_FETCH_STATE_RESULT` + +--- + ## APISettings Settings for interacting with the Prefect API ### `url` @@ -698,7 +709,6 @@ The maximum size in bytes for a single log. --- ## ResultsSettings Settings for controlling result storage behavior - ### `default_serializer` The default serializer to use when not otherwise specified. @@ -747,17 +757,7 @@ The path to a directory to store results in. **Supported environment variables**: `PREFECT_RESULTS_LOCAL_STORAGE_PATH`, `PREFECT_LOCAL_STORAGE_PATH` -### `default_persist_result` -If `True`, results will be persisted by default for all tasks. Set to `False` to disable persistence by default. Note that setting to `False` will override the behavior set by a parent flow or task. - -**Type**: `boolean | None` - -**Default**: `None` - -**TOML dotted key path**: `tasks.default_persist_result` - -**Supported environment variables**: -`PREFECT_TASKS_DEFAULT_PERSIST_RESULT` +--- ## RunnerServerSettings Settings for controlling runner server behavior ### `enable` @@ -2198,7 +2198,6 @@ Whether or not to delete failed task submissions from the database. --- ## TasksSettings - ### `refresh_cache` If `True`, enables a refresh of cached results: re-executing the task will refresh the cached results. @@ -2238,18 +2237,6 @@ This value sets the default retry delay seconds for all tasks. **Supported environment variables**: `PREFECT_TASKS_DEFAULT_RETRY_DELAY_SECONDS`, `PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS` -### `default_persist_result` -If `True`, results will be persisted by default for all tasks. Set to `False` to disable persistence by default. Note that setting to `False` will override the behavior set by a parent flow or task. - -**Type**: `boolean | None` - -**Default**: `None` - -**TOML dotted key path**: `tasks.default_persist_result` - -**Supported environment variables**: -`PREFECT_TASKS_DEFAULT_PERSIST_RESULT` - ### `runner` Settings for controlling task runner behavior @@ -2263,6 +2250,8 @@ Settings for controlling client-side task scheduling behavior **Type**: [TasksSchedulingSettings](#tasksschedulingsettings) **TOML dotted key path**: `tasks.scheduling` + +--- ## TestingSettings ### `test_mode` If `True`, places the API in test mode. This may modify behavior to facilitate testing.