#
View Source Ash.Resource.Change.Builtins (ash v2.14.2)

Built in changes that are available to all resources

The functions in this module are imported by default in the actions section.

# Link to this section Summary

## Functions

after_action(callback, opts \\ [])

Directly attach an `after_action` function to the current change.

after_transaction(callback, opts \\ [])

Directly attach an `after_transaction` function to the current change.

before_action(callback, opts \\ [])

Directly attach a `before_action` function to the current change.

before_transaction(callback, opts \\ [])

Directly attach a `before_transaction` function to the current change.

ensure_selected(value)

Passes the provided value into `Ash.Changeset.ensure_selected/2`

get_and_lock(lock)

Re-fetches the record being updated and locks it with the given type.

get_and_lock_for_update()

Re-fetches the record being updated and locks it for update.

increment(attribute, opts \\ [])

Increments an attribute's value by the amount specified, which defaults to 1.

load(value)

Passes the provided value into `changeset.api.load()`, after the action has completed.

manage_relationship(argument, relationship_name \\ nil, opts)

Calls `Ash.Changeset.manage_relationship/4` with the changeset and relationship provided, using the value provided for the named argument.

optimistic_lock(attribute)

Apply an "optimistic lock" on a record being updated or destroyed.

prevent_change(attribute)

Clears a change off of the changeset before the action runs.

relate_actor(relationship, opts \\ [])
relate_actor_opts()

Relates the actor to the data being changed, as the provided relationship.

select(value)

Passes the provided value into `Ash.Changeset.select/3`

set_attribute(attribute, value, opts \\ [])
set_attribute_opts()

Sets the attribute to the value provided.

set_context(context)

Merges the given query context.

set_new_attribute(attribute, value)

Sets the attribute to the value provided if the attribute is not already being changed.

# Link to this section Functions

Link to this macro

# after_action(callback, opts \\ [])

View Source (macro)

Directly attach an `after_action` function to the current change.

See `Ash.Changeset.after_action/3` for more information.

Provide the option `prepend?: true` to place the hook before all other hooks instead of after.

##

example

Example

    change after_action(fn changeset, record ->
      Logger.debug("Successfully executed action #{changeset.action.name} on #{inspect(changeset.resource)}")
      {:ok, record}
    end)

Link to this macro

# after_transaction(callback, opts \\ [])

View Source (macro)

Directly attach an `after_transaction` function to the current change.

See `Ash.Changeset.after_transaction/3` for more information.

Provide the option `prepend?: true` to place the hook before all other hooks instead of after.

##

example

Example

    change after_transaction(fn
      changeset, {:ok, record} ->
        Logger.debug("Successfully executed transaction for action #{changeset.action.name} on #{inspect(changeset.resource)}")
        {:ok, record}
      changeset, {:error, reason} ->
        Logger.debug("Failed to execute transaction for action #{changeset.action.name} on #{inspect(changeset.resource)}, reason: #{inspect(reason)}")
        {:error, reason}
    end)

Link to this macro

# before_action(callback, opts \\ [])

View Source (macro)

Directly attach a `before_action` function to the current change.

See `Ash.Changeset.before_action/3` for more information.

Provide the option `append?: true` to place the hook after all other hooks instead of before.

##

example

Example

    change before_action(fn changeset ->
      Logger.debug("About to execute #{changeset.action.name} on #{inspect(changeset.resource)})

      changeset
    end)

Link to this macro

# before_transaction(callback, opts \\ [])

View Source (macro)

Directly attach a `before_transaction` function to the current change.

See `Ash.Changeset.before_transaction/3` for more information.

Provide the option `append?: true` to place the hook after all other hooks instead of before.

##

example

Example

    change before_transaction(fn changeset ->
      Logger.debug("About to execute transaction for #{changeset.action.name} on #{inspect(changeset.resource)})

      changeset
    end)

Link to this function

# ensure_selected(value)

View Source

    @spec ensure_selected(select :: atom() | [atom()]) :: Ash.Resource.Change.ref()

Passes the provided value into `Ash.Changeset.ensure_selected/2`

If the value is not already selected, this makes sure it is. Does not deselect anything else.

##

example

Example

change ensure_selected([:necessary_field])

Link to this function

# get_and_lock(lock)

View Source

    @spec get_and_lock(lock :: Ash.DataLayer.lock_type()) :: Ash.Resource.Change.ref()

Re-fetches the record being updated and locks it with the given type.

This happens in a `before_action` hook (so that it is done as part of the transaction).

If your resource has global validations (in the top level `validations` block), you may want to add `delay_global_validations? true` to your action to ensure they happen on the locked record.

Link to this function

# get_and_lock_for_update()

View Source

    @spec get_and_lock_for_update() :: Ash.Resource.Change.ref()

Re-fetches the record being updated and locks it for update.

Only usable with data layers that support locking `:for_update`.

This happens in a `before_action` hook (so that it is done as part of the transaction).

If your resource has global validations (in the top level `validations` block), you may want to add `delay_global_validations? true` to your action to ensure they happen on the locked record.

Link to this function

# increment(attribute, opts \\ [])

View Source

    @spec increment(attribute :: atom(), opts :: Keyword.t()) :: Ash.Resource.Change.ref()

Increments an attribute's value by the amount specified, which defaults to 1.

Options:

- `:amount` - Defaults to 1
- `:overflow_limit` - Defaults to `nil`. If the value is over the overflow limit it will roll-over to the amount being incremented by (for common database limit support)

Link to this function

# load(value)

View Source

    @spec load(load :: term()) :: Ash.Resource.Change.ref()

Passes the provided value into `changeset.api.load()`, after the action has completed.

##

example

Example

    change load(:comments)
    change load([:friend_count, :friends])

Link to this function

# manage_relationship(argument, relationship_name \\ nil, opts)

View Source

    @spec manage_relationship(
      argument :: atom(),
      relationship_name :: atom() | nil,
      opts :: Keyword.t()
    ) :: Ash.Resource.Change.ref()

Calls `Ash.Changeset.manage_relationship/4` with the changeset and relationship provided, using the value provided for the named argument.

If relationship_name is not specified, it is assumed to be the same as the argument.

For information on the available options, see `Ash.Changeset.manage_relationship/4`.

##

examples

Examples

    change manage_relationship(:comments, type: :append)
    change manage_relationship(:remove_comments, :comments, type: :remove)

Link to this function

# optimistic_lock(attribute)

View Source

Apply an "optimistic lock" on a record being updated or destroyed.

This is modeled after ecto's implementation of optimistic locking, so to read more, see their documentation: https://hexdocs.pm/ecto/Ecto.Changeset.html#optimistic_lock/3

The primary difference is that we leave it to you to increment the field being used for optimistic locking yourself. So in ecto you might do `Changeset.optimistic_lock(changeset, :foo)` and that would add 1 to the `:foo` attribute automatically. In Ash, you would combine this with the `increment/1` change.

    change optimistic_lock(:foo)
    change increment(:foo)

Link to this function

# prevent_change(attribute)

View Source

    @spec prevent_change(attribute :: atom()) :: Ash.Resource.Change.ref()

Clears a change off of the changeset before the action runs.

Does not fail if it is being changed, but ensures it is cleared just before the action.

Can be useful if a change is only used in validations but shouldn't ultimately be written to the data layer.

##

examples

Examples

    change prevent_change(:email)

Link to this function

# relate_actor(relationship, opts \\ [])

View Source

    @spec relate_actor(relationship :: atom(), opts :: Keyword.t()) ::
      Ash.Resource.Change.ref()

Link to this function

# relate_actor_opts()

View Source

Relates the actor to the data being changed, as the provided relationship.

##

options

Options

- `:relationship` (`atom/0`) - Required. The relationship to set the actor to.

- `:allow_nil?` (`boolean/0`) - Whether or not to allow the actor to be nil, in which case nothing will happen. The default value is `false`.

- `:field` (`atom/0`) - The field of the actor to set the relationship to

##

examples

Examples

    change relate_actor(:owner, allow_nil?: true)

Link to this function

# select(value)

View Source

    @spec select(select :: atom() | [atom()]) :: Ash.Resource.Change.ref()

Passes the provided value into `Ash.Changeset.select/3`

Keep in mind, this will limit the fields that are selected. You may want `ensure_selected/1` if you want to make sure that something is selected, without deselecting anything else.

Selecting in changesets does not actually do a select in the data layer. It nils out any fields that were not selected after completing the action. This can be useful if you are writing policies that have to do with specific fields being selected.

##

example

Example

    change select([:name])

Link to this function

# set_attribute(attribute, value, opts \\ [])

View Source

    @spec set_attribute(
      relationship :: atom(),
      (-> term()) | {:_arg, :status} | term(),
      opts :: Keyword.t()
    ) :: Ash.Resource.Change.ref()

Link to this function

# set_attribute_opts()

View Source

Sets the attribute to the value provided.

If a zero argument function is provided, it is called to determine the value.

Use `arg(:argument_name)` to use the value of the given argument. If the argument is not supplied then nothing happens.

##

options

Options

- `:set_when_nil?` (`boolean/0`) - When false, decline setting the attribute if it is nil. The default value is `true`.

- `:new?` (`boolean/0`) - When true, sets the attribute to the value provided if the attribute is not already being changed. The default value is `false`.

##

examples

Examples

    change set_attribute(:active, false)
    change set_attribute(:opened_at, &DateTime.utc_now/0)
    change set_attribute(:status, arg(:status))
    change set_attribute(:encrypted_data, arg(:data), set_when_nil?: false)

Link to this function

# set_context(context)

View Source

    @spec set_context(context :: map() | mfa()) :: Ash.Resource.Change.ref()

Merges the given query context.

If an MFA is provided, it will be called with the changeset. The MFA should return `{:ok, context_to_be_merged}` or `{:error, term}`

##

examples

Examples

    change set_context(%{something_used_internally: true})
    change set_context({MyApp.Context, :set_context, []})

Link to this function

# set_new_attribute(attribute, value)

View Source

    @spec set_new_attribute(
      relationship :: atom(),
      (-> term()) | {:_arg, :status} | term()
    ) ::
      Ash.Resource.Change.ref()

Sets the attribute to the value provided if the attribute is not already being changed.

If a zero argument function is provided, it is called to determine the value.

Use `arg(:argument_name)` to use the value of the given argument. If the argument is not supplied then nothing happens.

##

examples

Examples

    change set_new_attribute(:active, false)
    change set_new_attribute(:opened_at, &DateTime.utc_now/0)
    change set_new_attribute(:status, arg(:status))