docs

docs/03-resources/07-managing-relationships.md

@@ -378,6 +378,33 @@ public function table(Table $table): Table
 }
 ```
 
+### Improving the performance of detach bulk actions
+
+By default, the `DetachBulkAction` will load all Eloquent records into memory, before looping over them and detaching them one by one.
+
+If you are detaching a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application:
+
+```php
+use Filament\Actions\DetachBulkAction;
+
+DetachBulkAction::make()
+    ->chunkSelectedRecords(250)
+```
+
+Filament loads Eloquent records into memory before detaching them for two reasons:
+
+- To allow individual records in the collection to be authorized with a model policy before detaching (using `authorizeIndividualRecords('delete')`, for example).
+- To ensure that model events are run when detaching records, such as the `deleting` and `deleted` events in a model observer.
+
+If you do not require individual record policy authorization and model events, you can use the `fetchSelectedRecords(false)` method, which will not fetch the records into memory before detaching them, and instead will detach them in a single query:
+
+```php
+use Filament\Actions\DetachBulkAction;
+
+DetachBulkAction::make()
+    ->fetchSelectedRecords(false)
+```
+
 ## Associating and dissociating records
 
 Filament is able to associate and dissociate records for `HasMany` and `MorphMany` relationships.
@@ -475,6 +502,33 @@ AssociateAction::make()
     )
 ```
 
+### Improving the performance of dissociate bulk actions
+
+By default, the `DissociateBulkAction` will load all Eloquent records into memory, before looping over them and dissociating them one by one.
+
+If you are dissociating a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application:
+
+```php
+use Filament\Actions\DissociateBulkAction;
+
+DissociateBulkAction::make()
+    ->chunkSelectedRecords(250)
+```
+
+Filament loads Eloquent records into memory before dissociating them for two reasons:
+
+- To allow individual records in the collection to be authorized with a model policy before dissociation (using `authorizeIndividualRecords('update')`, for example).
+- To ensure that model events are run when dissociating records, such as the `updating` and `updated` events in a model observer.
+
+If you do not require individual record policy authorization and model events, you can use the `fetchSelectedRecords(false)` method, which will not fetch the records into memory before dissociating them, and instead will dissociate them in a single query:
+
+```php
+use Filament\Actions\DissociateBulkAction;
+
+DissociateBulkAction::make()
+    ->fetchSelectedRecords(false)
+```
+
 ## Viewing related records
 
 When generating your relation manager, you may pass the `--view` flag to also add a `ViewAction` to the table:

packages/actions/docs/07-delete.md

@@ -99,3 +99,30 @@ DeleteAction::make()
 ```
 
 <UtilityInjection set="actions" version="4.x">These hook functions can inject various utilities as parameters.</UtilityInjection>
+
+## Improving the performance of delete bulk actions
+
+By default, the `DeleteBulkAction` will load all Eloquent records into memory, before looping over them and deleting them one by one.
+
+If you are deleting a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application:
+
+```php
+use Filament\Actions\DeleteBulkAction;
+
+DeleteBulkAction::make()
+    ->chunkSelectedRecords(250)
+```
+
+Filament loads Eloquent records into memory before deleting them for two reasons:
+
+- To allow individual records in the collection to be authorized with a model policy before deletion (using `authorizeIndividualRecords('delete')`, for example).
+- To ensure that model events are run when deleting records, such as the `deleting` and `deleted` events in a model observer.
+
+If you do not require individual record policy authorization and model events, you can use the `fetchSelectedRecords(false)` method, which will not fetch the records into memory before deleting them, and instead will delete them in a single query:
+
+```php
+use Filament\Actions\DeleteBulkAction;
+
+DeleteBulkAction::make()
+    ->fetchSelectedRecords(false)
+```

packages/actions/docs/09-force-delete.md

@@ -99,3 +99,30 @@ ForceDeleteAction::make()
 ```
 
 <UtilityInjection set="actions" version="4.x">These hook functions can inject various utilities as parameters.</UtilityInjection>
+
+## Improving the performance of force delete bulk actions
+
+By default, the `ForceDeleteBulkAction` will load all Eloquent records into memory, before looping over them and deleting them one by one.
+
+If you are deleting a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application:
+
+```php
+use Filament\Actions\ForceDeleteBulkAction;
+
+ForceDeleteBulkAction::make()
+    ->chunkSelectedRecords(250)
+```
+
+Filament loads Eloquent records into memory before deleting them for two reasons:
+
+- To allow individual records in the collection to be authorized with a model policy before deletion (using `authorizeIndividualRecords('forceDelete')`, for example).
+- To ensure that model events are run when deleting records, such as the `forceDeleting` and `forceDeleted` events in a model observer.
+
+If you do not require individual record policy authorization and model events, you can use the `fetchSelectedRecords(false)` method, which will not fetch the records into memory before deleting them, and instead will delete them in a single query:
+
+```php
+use Filament\Actions\ForceDeleteBulkAction;
+
+ForceDeleteBulkAction::make()
+    ->fetchSelectedRecords(false)
+```

packages/actions/docs/10-restore.md

@@ -99,3 +99,30 @@ RestoreAction::make()
 ```
 
 <UtilityInjection set="actions" version="4.x">These hook functions can inject various utilities as parameters.</UtilityInjection>
+
+## Improving the performance of restore bulk actions
+
+By default, the `RestoreBulkAction` will load all Eloquent records into memory, before looping over them and restoring them one by one.
+
+If you are restoring a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application:
+
+```php
+use Filament\Actions\RestoreBulkAction;
+
+RestoreBulkAction::make()
+    ->chunkSelectedRecords(250)
+```
+
+Filament loads Eloquent records into memory before restoring them for two reasons:
+
+- To allow individual records in the collection to be authorized with a model policy before restoration (using `authorizeIndividualRecords('restore')`, for example).
+- To ensure that model events are run when restoring records, such as the `restoring` and `restored` events in a model observer.
+
+If you do not require individual record policy authorization and model events, you can use the `fetchSelectedRecords(false)` method, which will not fetch the records into memory before restoring them, and instead will restore them in a single query:
+
+```php
+use Filament\Actions\RestoreBulkAction;
+
+RestoreBulkAction::make()
+    ->fetchSelectedRecords(false)
+```

packages/tables/docs/04-actions.md

@@ -367,6 +367,38 @@ public function table(Table $table): Table
 }
 ```
 
+### Improving the performance of bulk actions
+
+By default, a bulk action will load all Eloquent records into memory before passing them to the `action()` function.
+
+If you are processing a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application:
+
+```php
+use Filament\Actions\BulkAction;
+use Illuminate\Support\LazyCollection;
+
+BulkAction::make()
+    ->chunkSelectedRecords(250)
+    ->action(function (LazyCollection $records) {
+        // Process the records...
+    })
+```
+
+You can still loop through the `$records` collection as normal, but the collection will be a `LazyCollection` instead of a normal collection.
+
+You can also prevent Filament from fetching the Eloquent models in the first place, and instead just pass the IDs of the selected records to the `action()` function. This is useful if you are processing a large number of records, and you don't need to load them into memory:
+
+```php
+use Filament\Actions\BulkAction;
+use Illuminate\Support\Collection;
+
+BulkAction::make()
+    ->fetchSelectedRecords(false)
+    ->action(function (Collection $records) {
+        // Process the records...
+    })
+```
+
 ## Header actions
 
 Both [row actions](#row-actions) and [bulk actions](#bulk-actions) can be rendered in the header of the table. You can put them in the `$table->headerActions()` method: