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 cache entries based on specific criteria. This option allows you to evict multiple entries that match the query.

  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. This is useful when the query depends on function arguments or needs to be built dynamically.

  • A direct query value - Any term that is a valid query supported by the cache adapter. This is suitable for static queries that don't depend on runtime values.

  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 allows you to provide a query (or a function that returns a query at runtime) to evict multiple cache entries based on specific criteria. The query must be supported by the cache adapter.

To explain how this works, let's use an example. Imagine you have a function delete_objects_by_tag that receives a tag as an argument and deletes all records matching the given tag from the system of record (SoR). You want to evict those entries from the cache as well. This can be accomplished by using a query to identify and evict all matching entries. However, writing the query directly in the decorator can be verbose and hard to maintain, especially for complex queries. Instead, you can use a function that receives the decorator context and returns the required query to evict all cached entries matching the given tag.

@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

However, using a function is recommended for better readability and maintainability, especially when the query depends on function arguments.

Combining :key and :query

You can use both :key and :query options together to evict both specific entries and entries matching a query pattern. When both options are provided, the decorator executes the eviction in the following order:

1. Query-based eviction - First, entries matching the query are evicted.
2. Key-based eviction - Then, the specific key(s) are evicted.

This is useful when you need to evict a primary entry along with related entries. For example, when logging out a user, you might want to evict the user's cache entry and all their active session entries (the examples below assume you are using 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 for reusability and cleaner code.
• Test queries independently before using them in decorators to ensure they match the expected entries.
• Document query behavior and the expected match criteria for future maintainability.
• Consider performance implications when querying large datasets, as some queries may require full cache scans.
• Use both :key and :query when evicting hierarchical data where you need to remove both a parent entry and its related child entries.

Eviction of references

When the cache_evict decorator annotates a key (or keys) to evict, it removes only the entry associated with that key. Therefore, if the key has references (as created by the :references option in cacheable), those are not automatically removed, which results in dangling keys. However, there are multiple ways to evict references and avoid dangling keys:

• 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.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 - You can combine the previous approaches to create a more robust solution:

  • 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 layered approach provides both automatic cleanup through TTL expiration and manual control when you have access to all the necessary keys in your function arguments.

Local Adapter: Advanced Reference Eviction

The Nebulex.Adapters.Local adapter provides powerful strategies for automatic reference cleanup using QueryHelper, without needing to specify each reference key individually.

Strategy 1: Tag-based reference grouping

Tag both the main key and its references with the same tag, then evict all entries with that tag in one 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),
              opts: [tag: {:user, &(&1.id)}]
            )
  def get_user_account_by_email(email) do
    # your logic ...
  end

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

  defp evict_by_user_tag(%{args: [user]}) do
    match_spec tag: t, where: t == {:user, user.id}
  end
end

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 strategies provide automatic cleanup of all references without manually specifying each reference key. Choose based on your needs:

• Tag-based: Best when you control reference creation upfront and want a simple, declarative approach. Requires planning tags during caching.
• Query-based: More flexible for cases where references may exist across different decorators or when references are created conditionally.

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

Eviction of external references

As mentioned in the cacheable decorator's "External referenced keys" section, an external reference is a key (or reference) that lives in another cache store. For example, you might have one cache to store only the references and another to store the actual values. In these cases, when you annotate the eviction function, you want to remove both the cached value and any references to it that may exist. Therefore, you can use {:in, keys} in the :key option, adding the references to be removed 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.

In contrast to the cacheable decorator, this decorator does not cause the decorated function to be skipped. Instead, it always causes the function to be invoked and its result to be stored in the associated cache if the condition given by the :match option matches accordingly.

Use Cases

The cache_put decorator is ideal for scenarios where:

• Updating or modifying data - After writing changes to the SoR, update the cache with the new value.
• Write-through caching - Maintain consistency between SoR and cache by updating the cache after successful writes.

Key Differences from cacheable

Options

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

Match Function Behavior

The :match option is crucial for controlling 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).

This is useful for:

• Caching only successful operations (e.g., {:ok, result})
• Transforming the cached value
• Applying different cache options based 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(Product, id)
  Repo.update(product, attrs)
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 real-world integration examples and comprehensive patterns, see the Declarative Caching Guide.

As the name implies, the cacheable decorator indicates storing in cache the result of invoking a function.

Each time a decorated function is invoked, the caching behavior will be applied, checking whether the function has already been invoked for the given arguments. A default algorithm uses the function arguments to compute the key. Still, a custom key can be provided through the :key option, or a custom key-generator function can replace the default one (See "Key Generation" section in the module documentation).

If no value is found in the cache for the computed key, the target function will be invoked, and the returned value will be stored in the associated cache. Note that what is cached can be handled with the :match option.

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 handy when multiple keys keep the same value. For example, let's imagine we have a schema User with multiple unique fields, like :id, :email, and :token. We may have a module with functions retrieving the user account by any of those fields, like so:

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

As you notice, all three functions will store the same user record under a different key. It could be more efficient in terms of memory space. Besides, when the user record is updated, we have to invalidate the previously cached entries, which means we have to specify in the cache_evict decorator all the different keys associated with the cached user account.

Using the referenced keys, we can address it better and more simply. The module will look like this:

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 the option :references, we are indicating to the cacheable decorator to store the user id under the key email and the key token (assuming the function returns a user record), and the user record itself under the user id, which is the referenced key; if the function returns nil, the decorator will cache nothing. This time, instead of storing the same object three times, the decorator will cache it only once under the user ID, and the other entries will keep a reference to it. When the functions get_user_account_by_email/1 or get_user_account_by_token/1 are are executed, the decorator will automatically handle it; under the hood, it will fetch the referenced key given by email or token first, and then get the user record under the referenced key.

On the other hand, in the eviction function update_user_account/1, since the user record is stored only once under the user's ID, we could set the option :key to the user's ID, without specifying multiple keys like in the previous case. However, there is a caveat:

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 should have removed the user schema associated with the user.id key (decorated with cache_evict) but not the references. Therefore, if we call get_user_account_by_email again, we will get 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", ...}

However, here we have an inconsistency because we are requesting a user with the email "me@test.com" and we got a user with a different email "updated@test.com" (the updated one). How can we avoid this? The answer is to leverage the :match option to ensure consistency and correctness. Let's provide a match function that helps us with it:

@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

With the solution above, the cacheable decorator only caches the user's value if the email matches the one in the arguments. Otherwise, nothing is cached, and the decorator evaluates the function's block. Previously, the decorator was caching the user regardless of the requested email value. With this fix, if we try the previous call:

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

Since there is an email mismatch in the previous call, the decorator removes the mismatch reference from the cache (eliminating the inconsistency) and executes the function body, assuming it uses MyApp.Repo.get_by/2, nil is returned because there is no such user in the database.

External referenced keys

Previously, we saw how to work with referenced keys but on the same cache, like "internal references." Despite this being the typical case scenario, there could be situations where you may want to reference a key stored in a different or external cache. Why would I want to reference a key located in a separate cache? There may be multiple reasons, but let's give a few examples.

• One example is when you have a Redis cache; in such case, you likely want to optimize the calls to Redis as much as possible. Therefore, you should store the referenced keys in a local cache and the values in Redis. This way, we only hit Redis to access the keys with the actual values, and the decorator resolves the referenced keys locally.

• Another example is for keeping the cache key references isolated, preferably locally. Then, apply a different eviction (or garbage collection) policy for the references; one may want to expire the references more often to avoid having dangling keys since the cache_evict decorator doesn't remove the references automatically, just the defined key (or keys). 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/2 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 cache key references. Then, with the option references: &(&1 && keyref(&1.id, cache: RedisCache)) we are telling the cacheable decorator the referenced key given by &1.id is located in the cache RedisCache; the macro keyref/2 builds the required reference tuple for the external cache reference underneath.