In Prefect, what does setting cache_key_fn on a task do?

## The problem caching solves A Prefect task is a Python function decorated with `@task`. By default the body runs every time the task is called inside a flow. When the body is expensive — a wide warehouse query, a model fit, a metered API call — you want the second invocation with the same inputs to reuse the first one's answer instead of paying again. `cache_key_fn` is how you tell Prefect when two runs count as "the same work". ## The signature `cache_key_fn` is an ordinary function that Prefect calls *before* the task body, passing the run context and a dict of the task's resolved parameters: ```python def key_from_day(context, parameters): return f"load-orders-{parameters['day']}" ``` Whatever string it returns is the task run's **cache key**. Returning `None` means "do not cache this particular run" — the task simply executes. ## What Prefect does with the key Before transitioning the run to `Running`, Prefect asks its backend (a local server, a self-hosted server, or Prefect Cloud) whether a completed task run already carries that key. If one exists and the configured expiration has not passed, the new run is set to `Cached` instead. `Cached` is a *state name* whose *state type* is Completed, so downstream tasks treat it as success and receive the previous run's return value. Your function body never executes — which is the whole point, and also the whole hazard when the body has side effects. ## cache_expiration `cache_expiration` takes a `datetime.timedelta` and bounds how long an entry is considered valid: ```python @task(cache_key_fn=task_input_hash, cache_expiration=timedelta(hours=1)) def fetch(day: str): ... ``` Omit it and the entry has no expiry — the key is good for as long as the record survives in the backend. Set it when the upstream data can change underneath a key that would otherwise stay identical (for example a "today" partition that is still being appended to). ## A cache hit needs a reachable result A Prefect state does not carry your data; it carries a *reference* to a result. So a cache hit can only hand back a value if that value was written to result storage that the reading run can actually open. Locally this works by default because results land under the Prefect home directory on the same machine. Across containers or workers on different hosts it does not, unless you configure shared `result_storage`. In Prefect 3, declaring a cache policy turns result persistence on for you, precisely because caching without persistence is meaningless. ## Cache keys are global, not per-task The key is a string in a shared table. Nothing stops two different tasks from producing the same string, and if they do they will share results — a genuinely confusing bug where a task "returns" another task's output. Defend against it by folding something task-identifying into the key (the task name, a version constant), or by using the built-in policies that already include task identity. ## Prefect 3: cache policies Prefect 3 keeps `cache_key_fn` but adds composable `cache_policy` values — `INPUTS`, `TASK_SOURCE`, `RUN_ID`, `FLOW_PARAMETERS`, `NO_CACHE` — which you combine with `+`: ```python @task(cache_policy=INPUTS + TASK_SOURCE) def transform(rows): ... ``` The default policy is scoped to the flow run, so repeat calls inside one flow run are reused while a later flow run recomputes. `TASK_SOURCE` folds the function's source into the key, so editing the body invalidates old entries — a common expectation that a pure inputs hash does not satisfy. An explicit `cache_key_fn` takes precedence over the policy. ## Forcing a recompute Set `refresh_cache=True` on the task (or via `.with_options(refresh_cache=True)`) to make a run ignore any existing entry, execute, and overwrite the stored result under the same key. That is the tool for "the upstream was wrong, recompute this one". ## When not to cache Do not cache tasks whose value is the side effect — sending mail, publishing a message, writing a file with a run-specific name — because a hit silently skips the effect while reporting success. Do not cache non-deterministic reads unless the key encodes the thing that varies. And be wary of caching very large return values: every hit and miss is an object round-tripped through your result storage, which can cost more than recomputing something cheap.