Server-side caching

The Airplane API can optionally return a cached result when a task is executed instead of re-running the task. This feature is useful for non-mutating tasks that are expensive to run and/or accessed in performance-sensitive settings like views.

To allow runs of a particular task to return cached results by default, set the allowCachedMaxAge or allow_cached_max_age field in the task definition to a number of seconds between 0 and 172800, inclusive:

typescript
Copied
1
export default airplane.task(
2
  {
3
    slug: "task_with_caching",
4
    name: "Task with caching",
5
    allowCachedMaxAge: 600,
6
  }),
7
  async (params) => {
8
    // Task code
9
  },

python
Copied
1
@airplane.task(
2
    slug="task_with_caching",
3
    name="Task with caching",
4
    allow_cached_max_age=600,
5
)
6
def task_with_caching():
7
    # Task code

yaml
Copied
1
slug: task_with_caching
2
name: Task with caching
3

4
allowCachedMaxAge: 600
5

6
# Rest of task definition

When this task is executed by an Airplane SDK or view query, the Airplane API will look for a recent run with the same inputs that successfully finished no more than the max age ago. If such a run is found, then the API will return that run ID to the client instead of creating a new task run. See the Cachability section below for more details on this process.

Setting the max age to 0 effectively disables caching (which is the default behavior if this field isn't specified), whereas larger values allow for increasingly older runs to be used. The optimal number to set here will depend on the specific freshness vs. performance tradeoffs for the users of the task. To be safe, it's probably best to start low (e.g., 600) and then increase this value after more testing.

The Airplane JavaScript and Python SDKs allow overriding the value of the cache max age for a particular task execution. Setting this value to 0, for instance, allows a client to turn off caching even if it's configured in the task definition:

typescript
Copied
1
export default airplane.task(
2
  {
3
    slug: "task_with_cache_override",
4
  }),
5
  async (params) => {
6
    const result = await airplane.execute(
7
      "my_other_task",
8
      { nameParam: "my name" },
9
      { allowCachedMaxAge: 0 },
10
    );
11
  },

python
Copied
1
@airplane.task(slug="task_with_cache_override")
2
def task_with_cache_override():
3
    result = airplane.execute(
4
        "my_other_task",
5
        {"nameParam": "my name"},
6
        allow_cached_max_age=0,
7
    )

Similarly, this value can be overriden for queries made by task-backed view components. See the views documentation for more details.

All task runs can serve as cache sources, but only executions from an Airplane SDK or view query will possibly return a cached result. In particular, this means that clicking the "Execute" button in the Airplane UI will always trigger a new run, although it's possible for child runs called by this one to use cached results.

When matching an eligible execution request to previous runs, the Airplane API will pick the most recent, successful run within the max age window that matches on all of the following dimensions:

If such a run is found and the executor has permissions to see it, then the API will return the cached run to the client. Otherwise, a new run will be created and the API will return that one instead.