Decorator indicating that a function triggers a cache evict operation (delete or delete_all).

Options

• :all_entries (boolean/0) - When set to true, the decorator removes all entries from the cache, ignoring the :key and :query options.

  Default: false

  The default value is false.

• :before_invocation (boolean/0) - When set to true, the cache eviction occurs before the decorated function is invoked. When false, the eviction occurs after the function completes successfully.

  Default: false

  The default value is false.

• :query (query/0) - The query to use for evicting all cache entries that match it.

  When both :query and :key are provided, the decorator will:

  1. First execute the query-based eviction to remove matching entries.
  2. Then execute the key-based eviction to remove the specified key(s).

  This is useful when you need to evict both a specific entry and related entries. For example, when deleting a user, you might want to evict both the user's cache entry and all their session entries.

  The :query option accepts the following values:

  • An anonymous function - A function that generates the query at runtime. The function can optionally receive the decorator context as an argument and must return a query supported by the cache adapter. Use it when the query depends on the function arguments.

  • A direct query value - Any term that is a valid query supported by the cache adapter. Use it for static queries.

  See the "Eviction with a query" section for more details and examples.

See the "Shared options" section in the module documentation for more options.

Examples

defmodule MyApp.Example do
  use Nebulex.Caching, cache: MyApp.Cache

  @decorate cache_evict(key: id)
  def delete(id) do
    # your logic (maybe write/delete data to the SoR)
  end

  @decorate cache_evict(key: {:in, [object.name, object.id]})
  def delete_object(object) do
    # your logic (maybe write/delete data to the SoR)
  end

  @decorate cache_evict(all_entries: true)
  def delete_all do
    # your logic (maybe write/delete data to the SoR)
  end

  @decorate cache_evict(key: user_id, query: &query_for_user_sessions/1)
  def logout_user(user_id) do
    # Evicts both the user entry and all their session entries
    # your logic (maybe write/delete data to the SoR)
  end

  def query_for_user_sessions(%{args: [user_id]}) do
    # Return a query that matches user sessions
    # (implementation depends on your adapter)
  end
end

Eviction with a query

The :query option takes a query (or a function that returns one at runtime) and evicts every entry that matches it. The query must be supported by the cache adapter.

For example, say delete_objects_by_tag receives a tag and deletes all records with that tag from the system of record (SoR). You want those entries gone from the cache too, so you evict them with a query. Writing the query inline in the decorator gets long, so use a function that receives the decorator context and returns the query:

@decorate cache_evict(query: &query_for_tag/1)
def delete_objects_by_tag(tag) do
  # your logic to delete data from the SoR
end

defp query_for_tag(%{args: [tag]} = _context) do
  # Assuming we are using the `Nebulex.Adapters.Local` adapter and the
  # cached entry value is a map with a `tag` field, the match spec
  # would look like this:
  [
    {
      {:entry, :"$1", %{tag: :"$2"}, :_, :_, :_},
      [{:"=:=", :"$2", tag}],
      [true]
    }
  ]
end

More examples

Evicting entries by user ID

If you need to evict all cached entries associated with a specific user:

@decorate cache_evict(query: &query_for_user/1)
def delete_user_data(user_id) do
  # your logic to delete user data from the SoR
end

defp query_for_user(%{args: [user_id]} = _context) do
  [
    {
      {:entry, :"$1", %{user_id: :"$2"}, :_, :_, :_},
      [{:"=:=", :"$2", user_id}],
      [true]
    }
  ]
end

Evicting entries with multiple criteria

You can build more complex queries that match multiple conditions:

@decorate cache_evict(query: &query_for_category_and_status/1)
def delete_products(category, status) do
  # your logic to delete products from the SoR
end

defp query_for_category_and_status(%{args: [category, status]}) do
  [
    {
      {:entry, :"$1", %{category: :"$2", status: :"$3"}, :_, :_, :_},
      [{:andalso, {:"=:=", :"$2", category}, {:"=:=", :"$3", status}}],
      [true]
    }
  ]
end

Direct query without a function

For simpler cases, you can provide the query directly:

@decorate cache_evict(
  query: [
    {
      {:entry, :"$1", %{archived: true}, :_, :_, :_},
      [],
      [true]
    }
  ]
)
def cleanup_archived_entries do
  # your logic to cleanup archived data from the SoR
end

A function is still the better choice when the query depends on the function arguments.

Combining :key and :query

You can use :key and :query together to evict specific entries and the entries matching a query. When both are given, the decorator evicts in this order:

1. Query-based eviction: entries matching the query are evicted first.
2. Key-based eviction: then the given key (or keys).

Use it to evict a main entry along with related entries. For example, when logging out a user you may want to evict the user's entry and all their session entries (the examples below assume the Nebulex.Adapters.Local adapter):

@decorate cache_evict(key: user_id, query: &query_for_user_sessions/1)
def logout_user(user_id) do
  # Evicts the user entry and all session entries for this user
  UserSessions.delete_all_for_user(user_id)
end

defp query_for_user_sessions(%{args: [user_id]} = _context) do
  # Return a query that matches all session entries for the given user
  [
    {
      {:entry, :"$1", %{user_id: :"$2", type: "session"}, :_, :_, :_},
      [{:"=:=", :"$2", user_id}],
      [true]
    }
  ]
end

Another common use case is evicting multiple specific keys along with a query:

@decorate cache_evict(
  key: {:in, [category.id, category.slug]},
  query: &query_for_category_products/1
)
def delete_category(category) do
  # Evicts both category cache entries (by id and slug) and all
  # product entries within that category
  Products.delete_all_for_category(category.id)
end

defp query_for_category_products(%{args: [category]} = _context) do
  [
    {
      {:entry, :"$1", %{category_id: :"$2"}, :_, :_, :_},
      [{:"=:=", :"$2", category.id}],
      [true]
    }
  ]
end

Best Practices

• Keep query logic in separate functions so it can be reused and read on its own.
• Test queries on their own before using them in decorators, to check they match the entries you expect.
• Document what each query matches.
• Mind the cost on large caches; some queries scan the whole cache.
• Use both :key and :query for hierarchical data, where a parent entry and its children must go together.

Eviction of references

The cache_evict decorator removes only the entry for the given key (or keys). References to that key (created by the :references option of cacheable) are not removed, so they become dangling keys. There are several ways to evict references and avoid this:

• Specify the key and its references explicitly - Use the key: {:in, keys} option to specify both a key and its references. For example, if you have:

  @decorate cacheable(key: email, references: &(&1 && &1.id))
  def get_user_by_email(email) do
    # get the user from the database ...
  end

  The eviction may look like this:

  @decorate cache_evict(key: {:in, [user.id, user.email]})
  def delete_user(user) do
    # delete the user from the database ...
  end

  However, to make this work, you need access to both the key and references in the function arguments, which is not always possible. Consider the previous example: what if the delete_user function receives only the ID? You won't be able to evict the reference since you don't have access to the email in the arguments.

• Set a TTL for the reference - Configure a time-to-live value so references expire automatically. For example:

  @decorate cacheable(
              key: email,
              references: &(&1 && &1.id),
              opts: [ttl: @ttl]
            )
  def get_user_by_email(email) do
    # get the user from the database ...
  end

  You can also specify a different TTL for the referenced key:

  @decorate cacheable(
              key: email,
              references: &(&1 && keyref(&1.id, ttl: @another_ttl)),
              opts: [ttl: @ttl]
            )
  def get_user_by_email(email) do
    # get the user from the database ...
  end

• Use a separate cache for references - Maintain a dedicated cache for references only (e.g., a cache using the local adapter). This allows you to provide a different eviction or garbage collection configuration to run the GC more frequently and keep the references cache clean. See the "External referenced keys" section below.

• Combine multiple strategies - The approaches above can be combined:

  • Use key: {:in, keys} together with a TTL configuration to explicitly evict keys when possible while having automatic cleanup as a fallback.

  • Use a separate cache for references with its own TTL and eviction configuration, then explicitly evict keys from both caches when you have access to all necessary arguments.

  This way you get automatic cleanup through TTL expiration plus explicit eviction whenever the function arguments give you all the keys.

Local Adapter: Advanced Reference Eviction

The Nebulex.Adapters.Local adapter has two ways to clean up references automatically using QueryHelper, without naming each reference key.

Strategy 1: Tag-based reference grouping

Tag the main entries and their references with the same tag, then evict every entry with that tag in one operation. A tag is set when the entry is written, so it can only come from the function arguments or a constant; a lookup by email cannot tag its entry with the user ID. Use a group tag for bulk cleanup:

defmodule MyApp.UserAccounts do
  use Nebulex.Caching, cache: MyApp.Cache
  use Nebulex.Adapters.Local.QueryHelper

  @decorate cacheable(key: id, opts: [tag: :users])
  def get_user_account(id) do
    # your logic ...
  end

  @decorate cacheable(
              key: email,
              references: &(&1 && &1.id),
              opts: [tag: :users]
            )
  def get_user_account_by_email(email) do
    # your logic ...
  end

  @decorate cache_evict(query: &evict_all_users/1)
  def reload_user_accounts do
    # reload the users from the source of record ...
  end

  defp evict_all_users(_context) do
    match_spec tag: t, where: t == :users, select: true
  end
end

To evict a single user and its references, use Strategy 2.

Strategy 2: Direct reference queries with keyref_match_spec

Evict the main key explicitly and use keyref_match_spec/2 to find and remove all associated references in the same operation:

defmodule MyApp.UserAccounts do
  use Nebulex.Caching, cache: MyApp.Cache
  use Nebulex.Adapters.Local.QueryHelper

  @decorate cacheable(key: id)
  def get_user_account(id) do
    # your logic ...
  end

  @decorate cacheable(key: email, references: &(&1 && &1.id))
  def get_user_account_by_email(email) do
    # your logic ...
  end

  @decorate cacheable(key: token, references: &(&1 && &1.id))
  def get_user_account_by_token(token) do
    # your logic ...
  end

  @decorate cache_evict(key: user.id, query: &evict_user_refs/1)
  def delete_user(user) do
    # delete the user from the database ...
  end

  defp evict_user_refs(%{args: [user]}) do
    keyref_match_spec(user.id)
  end
end

Both clean up all references without naming each one. Choose based on your needs:

• Tag-based: Best when you control how references are created. Requires planning the tags up front.
• Query-based: Better when references are created by different decorators or only under some conditions.

For more details on QueryHelper and available query builders, see the Nebulex.Adapters.Local.QueryHelper documentation.

Eviction of external references

As described in the cacheable decorator's "External referenced keys" section, an external reference is a reference that lives in another cache, for example when one cache holds only references and another holds the values. To evict both the value and its references, use {:in, keys} in the :key option and add the references to the list. For example:

@decorate cache_evict(
            key: {:in, [user.id, keyref(user.email, cache: ExtCache)]}
          )
def delete_user(user) do
  # your logic to delete data from the SoR
end

Assuming there is a reference under the key user.email in ExtCache, the decorator will remove the cached value under the key user.id and the reference under the key user.email from ExtCache.

Decorator indicating that a function triggers a cache put operation.

Unlike cacheable, this decorator never skips the function. The function always runs, and its result is stored in the cache when the :match option says so.

Use Cases

Use cache_put when:

• Updating data - After writing changes to the SoR, put the new value in the cache.
• Write-through caching - Keep the cache in sync with the SoR by updating it after each successful write.

Key Differences from cacheable

Options

See the "Shared options" section in the module documentation for more options.

Match Function Behavior

The :match option controls when results are cached. The match function can return:

• true - Cache the result as-is.
• false - Don't cache anything.
• {true, value} - Cache the modified value instead of the function result.
• {true, value, opts} - Cache the value with additional cache options (e.g., different TTL).

Use it to:

• Cache only successful results (e.g., {:ok, result})
• Change what gets cached
• Set different cache options depending on the result

Examples

Basic Cache Update

Always execute and cache the result:

@decorate cache_put(key: id, opts: [ttl: :timer.hours(1)])
def update_product(id, attrs) do
  Product
  |> Repo.get!(id)
  |> Product.changeset(attrs)
  |> Repo.update()
end

Conditional Caching

Only cache successful operations:

@decorate cache_put(
            key: id,
            match: &match_ok/1,
            opts: [ttl: :timer.hours(1)]
          )
def update_product(id, attrs) do
  Repo.get(Product, id)
  |> Product.changeset(attrs)
  |> Repo.update()
end

defp match_ok({:ok, product}), do: {true, product}
defp match_ok({:error, _}), do: false

Multiple Keys

Update the cache with multiple keys (e.g., by ID and slug):

@decorate cache_put(
            key: {:in, [product.id, product.slug]},
            match: &match_ok/1,
            opts: [ttl: :timer.hours(1)]
          )
def update_product(product, attrs) do
  product
  |> Product.changeset(attrs)
  |> Repo.update()
end

defp match_ok({:ok, product}), do: {true, product}
defp match_ok({:error, _}), do: false

Transform Before Caching

Use the match function to transform what gets cached:

@decorate cache_put(
            key: id,
            match: &extract_result/1,
            opts: [ttl: :timer.hours(1)]
          )
def fetch_and_cache(id) do
  case external_api.fetch(id) do
    {:ok, data} -> data
    {:error, reason} -> {:error, reason}
  end
end

# Extract and cache only the data, not the error
defp extract_result({:error, _}), do: false
defp extract_result(data), do: {true, data}

Different TTL Based on Result

Apply different cache durations based on the result:

@decorate cache_put(
            key: id,
            match: &__MODULE__.match_with_ttl/1,
            opts: [ttl: :timer.hours(1)]
          )
def fetch_data(id) do
  case external_api.fetch(id) do
    {:ok, data} -> data
    {:error, _reason} = error -> error
  end
end

# Cache errors for a shorter time (5 minutes)
def match_with_ttl({:error, _reason}) do
  {true, nil, [ttl: :timer.minutes(5)]}
end

# Cache success for longer (1 hour, from opts)
def match_with_ttl(data) do
  {true, data}
end

See Also

For more examples, see the Declarative Caching Guide.

The cacheable decorator stores the result of a function in the cache.

Each time the decorated function is called, the decorator checks whether the function has already run for the given arguments. By default the key is computed from the function arguments; you can provide your own key with the :key option or replace the default key generator (see "Key Generation" in the module documentation).

If there is no value in the cache for the key, the function runs and its result is stored in the cache. The :match option controls what gets cached.

Options

• :references (references/0) - Indicates that the key specified by the :key option references another key provided by this option. When present, the cacheable decorator stores the decorated function's result under both the referenced key (provided by :references) and the primary key (provided by :key).

  See references/0 for possible values.

  For more information and examples, see the "Referenced keys" section.

See the "Shared options" section in the module documentation for more options.

Examples

defmodule MyApp.Example do
  use Nebulex.Caching, cache: MyApp.Cache

  @ttl :timer.hours(1)

  @decorate cacheable(key: id, opts: [ttl: @ttl])
  def get_by_id(id) do
    # your logic (maybe the loader to retrieve the value from the SoR)
  end

  @decorate cacheable(key: email, references: &(&1 && &1.id))
  def get_by_email(email) do
    # your logic (maybe the loader to retrieve the value from the SoR)
  end

  @decorate cacheable(key: clauses, match: &match_fun/1)
  def all(clauses) do
    # your logic (maybe the loader to retrieve the value from the SoR)
  end

  defp match_fun([]), do: false
  defp match_fun(_), do: true
end

Referenced keys

Referenced keys are for when several keys hold the same value. Say we have a User schema with several unique fields: :id, :email, and :token. A module may fetch the user account by any of them:

defmodule MyApp.UserAccounts do
  use Nebulex.Caching, cache: MyApp.Cache

  @decorate cacheable(key: id)
  def get_user_account(id) do
    # your logic ...
  end

  @decorate cacheable(key: email)
  def get_user_account_by_email(email) do
    # your logic ...
  end

  @decorate cacheable(key: token)
  def get_user_account_by_token(token) do
    # your logic ...
  end

  @decorate cache_evict(key: {:in, [user.id, user.email, user.token]})
  def update_user_account(user, attrs) do
    # your logic ...
  end
end

All three functions store the same user record under a different key, which wastes memory. And when the user record is updated, every cached copy has to be invalidated, so the cache_evict decorator has to list all the keys associated with the user account.

Referenced keys solve both problems. The module becomes:

defmodule MyApp.UserAccounts do
  use Nebulex.Caching, cache: MyApp.Cache

  @decorate cacheable(key: id)
  def get_user_account(id) do
    # your logic ...
  end

  @decorate cacheable(key: email, references: &(&1 && &1.id))
  def get_user_account_by_email(email) do
    # your logic ...
  end

  @decorate cacheable(key: token, references: &(&1 && &1.id))
  def get_user_account_by_token(token) do
    # your logic ...
  end

  @decorate cache_evict(key: user.id)
  def update_user_account(user, attrs) do
    # your logic ...
  end
end

With :references, the cacheable decorator stores the user record once, under the user ID (the referenced key), and stores the user ID under the email and token keys as references (assuming the function returns a user record; if it returns nil, nothing is cached). When get_user_account_by_email/1 or get_user_account_by_token/1 runs, the decorator first fetches the reference under email or token, then fetches the user record under the referenced key.

Since the user record is stored only once, update_user_account/2 can evict just the user ID instead of listing every key. There is a caveat, though:

The match function on references

The cacheable decorator also evaluates the :match option's function on cache key references to ensure consistency and correctness. Let's give an example to understand what this is about.

Using the previous "user accounts" example, here is the first call to get a user by email:

iex> user = MyApp.UserAccounts.get_user_account_by_email("me@test.com")
#=> %MyApp.UserAccounts.User{id: 1, email: "me@test.com", ...}

The user is now available in the cache for subsequent calls. Now, let's suppose we update the user's email by calling:

iex> MyApp.UserAccounts.update_user_account(user, %{
...>   email: "updated@test.com", ...
...> })
#=> %MyApp.UserAccounts.User{id: 1, email: "updated@test.com", ...}

The update_user_account function evicts the user schema stored under the user.id key (it is decorated with cache_evict) but not the reference stored under "me@test.com". Next, something re-caches the user under its ID, for example a lookup by ID:

iex> MyApp.UserAccounts.get_user_account(1)
#=> %MyApp.UserAccounts.User{id: 1, email: "updated@test.com", ...}

The old reference now points at a fresh entry again. (Without this step the reference would point at a missing entry, and the decorator would run the function body instead.) If we call get_user_account_by_email with the old email, the decorator follows the reference and returns the user with the updated email:

iex> user = MyApp.UserAccounts.get_user_account_by_email("me@test.com")
#=> %MyApp.UserAccounts.User{id: 1, email: "updated@test.com", ...}

This is inconsistent: we asked for the user with email "me@test.com" and got a user with a different email, "updated@test.com". The fix is a :match function:

@decorate cacheable(
            key: email,
            references: &(&1 && &1.id),
            match: &match(&1, email)
          )
def get_user_account_by_email(email) do
  # your logic ...
end

defp match(%{email: email}, email), do: true
defp match(_, _), do: false

Now the cacheable decorator caches the user only if the email matches the argument. Otherwise nothing is cached and the function body runs. With this fix, the previous call gives:

iex> MyApp.UserAccounts.get_user_account_by_email("me@test.com")
#=> nil

Because the email does not match, the decorator removes the stale reference from the cache and runs the function body; assuming it uses MyApp.Repo.get_by/2, it returns nil because there is no such user in the database.

External referenced keys

So far the references lived in the same cache as the values. Sometimes you want a reference to point at a key in a different cache. Two common reasons:

• You have a Redis cache and want to reduce the calls to Redis. Store the references in a local cache and the values in Redis; then Redis is hit only for the actual values, and the references are resolved locally.

• You want the references in their own cache (preferably local) so you can give them a different eviction or garbage collection policy, for example expiring them more often to avoid dangling keys, since the cache_evict decorator removes only the given key (or keys), not the references. See the "Eviction of references" section below.

Let us modify the previous "user accounts" example based on the Redis scenario:

defmodule MyApp.UserAccounts do
  use Nebulex.Caching

  alias MyApp.{LocalCache, RedisCache}

  @decorate cacheable(cache: RedisCache, key: id)
  def get_user_account(id) do
    # your logic ...
  end

  @decorate cacheable(
              cache: LocalCache,
              key: email,
              references: &(&1 && keyref(&1.id, cache: RedisCache))
            )
  def get_user_account_by_email(email) do
    # your logic ...
  end

  @decorate cacheable(
              cache: LocalCache,
              key: token,
              references: &(&1 && keyref(&1.id, cache: RedisCache))
            )
  def get_user_account_by_token(token) do
    # your logic ...
  end

  @decorate cache_evict(cache: RedisCache, key: user.id)
  def update_user_account(user) do
    # your logic ...
  end
end

The functions get_user_account/1 and update_user_account/1 use RedisCache to store the real value in Redis while get_user_account_by_email/1 and get_user_account_by_token/1 use LocalCache to store the references. The option references: &(&1 && keyref(&1.id, cache: RedisCache)) tells the cacheable decorator that the referenced key &1.id lives in RedisCache; the keyref/2 macro builds the reference tuple for it.