# Collection override

{% hint style="success" %}
This is the official documentation of the `agent_ruby` Ruby agent.
{% endhint %}

Forest Admin allows customizing at a very low level the behavior of any given Collection via the usage of Collection Overrides.

{% hint style="info" %}
Collection Overrides provide a powerful means to completely replace the default behavior of CUD operations (`create`, `update`, `delete`) for your Collections. This feature should be used with caution, as it directly affects the core operations on your data.
{% endhint %}

### How it Works

In addition to the standard Collection functions:

* `create`
* `update`
* `delete`

Collection Overrides allow you to define custom behavior that will entirely replace the default implementation of the `create`, `update`, and `delete` operations.

To define an Override for a Collection, you must specify:

* The handler function that will be executed instead of the default operation.

The custom handler function will receive a context object containing relevant information for the operation, allowing for comprehensive control over the behavior of these CUD operations.

### Context object reference

All override contexts provide access to:

* `collection` - the current collection
* `datasource` - the composite data source containing all collections
* `caller` - information about the user performing the operation (see [Collection Hooks](/developer-guide-agents-ruby/agent-customization/hooks/collection-hook.md#the-caller-object) for details)

#### Override-specific context properties

| Override   | Properties                                                             |
| ---------- | ---------------------------------------------------------------------- |
| **Create** | `data` - Array of records to create                                    |
| **Update** | `filter` - Filter for records to update, `patch` - Partial update data |
| **Delete** | `filter` - Filter for records to delete                                |

### Setting Up Overrides

Overrides are declared similarly to hooks but are aimed at replacing an entire operation rather than augmenting its execution. However this can also be used to enrich the default behavior. Here's how to set up overrides in your Collection:

#### Custom Create Operation

To replace the default create operation, use `override_create` with your custom handler:

```ruby
collection.override_create do |context|
  # Custom logic to handle creation
  # context.data contains the data intended for creation
  # Return an array of created records
end
```

#### Custom Update Operation

To replace the default update operation, use with your custom handler:

```ruby
collection.override_update do |context|
  # Custom logic to handle update
  # context.filter to determine which records are targeted
  # context.patch contains the data for update
  # Perform update operation
end

```

#### Custom Delete Operation

To replace the default delete operation, use with your custom handler:

```ruby
collection.override_delete do |context|
  # Custom logic to handle deletion
  # context.filter to determine which records are targeted
  # Perform deletion operation
end
```

{% hint style="warning" %}
Overrides take precedence over the default operation. Ensure your custom handlers properly manage all necessary logic for the operation, as the default behavior will not be executed.
{% endhint %}

### Basic Use Cases

#### Create over API

You might want to create the record with your custom API:

```ruby
product.override_create do |context|
  response = HTTParty.post("https://my-product-api.com/products", body: context.data)
  response.parsed_response
end
```

#### Modify data before update

You might want to modify payload data before update your record:

```ruby
product.override_update do |context|
  # Execute data modification and validation only if one of name or slug was edited
  if context.patch.key?('name') || context.patch.key?('slug')
    name = context.patch['name'] || context.patch['slug'].split("-")[0]
    uuid = HTTParty.get('https://my-product-api.com/slug', body: { name: name }).parsed_response

    context.patch['name'] = name
    context.patch['slug'] = "#{name}-#{uuid}"
  end

  context.collection.update(context.filter, context.patch)
end
```

#### Implementing soft delete

Instead of actually deleting records, mark them as deleted:

```ruby
collection.override_delete do |context|
  # Get all records that would be deleted
  records = context.collection.list(context.filter, ['id'])

  # Mark them as deleted instead of actually deleting
  records.each do |record|
    context.collection.update(
      { field: 'id', operator: 'Equal', value: record['id'] },
      { 'deletedAt' => Time.now, 'deletedBy' => context.caller.id }
    )
  end
end
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forestadmin.com/developer-guide-agents-ruby/agent-customization/hooks/collection-override.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.