Customize Index action

docs/preparing-data.md

@@ -34,3 +34,19 @@ public function prepare(array $searchable): array
     return $searchable;
 }
 ```
+
+# Preparing Index Action
+Sometimes may you want to [route your documents](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-routing-field.html) to a specific shard.
+
+To achieve this, Explorer provides the `prepareIndexAction` method, which allows you to [add metadata to the Bulk action](https://www.elastic.co/guide/en/elasticsearch/reference/8.6/docs-bulk.html#bulk-routing). To utilize this feature, you need to implement the `JeroenG\Explorer\Application\BeIndexed` interface in your model and add the `prepareIndexAction(array $action)` function. The data passed to the prepare function is the index action that will be used when the document is sent to Elasticsearch.
+
+If you have a multi-tenant system and know that the queries will always include a filter condition for a given tenant, you might want to instruct Elasticsearch to group the documents for the same tenant on the same shard. Here's an example:
+
+```php
+public function prepareIndexAction(array $action): array
+{
+    $action['index']['_routing'] = $this->tenant_id;
+
+    return $action;
+}
+```

src/Application/BeIndexed.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace JeroenG\Explorer\Application;
+
+interface BeIndexed
+{
+    public function prepareIndexAction(array $indexAction): array;
+}

src/Application/Operations/Bulk/BulkUpdateOperation.php

@@ -4,6 +4,7 @@
 
 namespace JeroenG\Explorer\Application\Operations\Bulk;
 
+use JeroenG\Explorer\Application\BeIndexed;
 use JeroenG\Explorer\Application\BePrepared;
 use JeroenG\Explorer\Application\Explored;
 
@@ -49,12 +50,18 @@ public function build(): array
 
     private static function bulkActionSettings(Explored $model): array
     {
-        return [
+        $action = [
             'index' => [
                 '_index' => self::$indexName,
                 '_id' => $model->getScoutKey(),
             ]
         ];
+
+        if ($model instanceof BeIndexed) {
+            $action = $model->prepareIndexAction($action);
+        }
+
+        return $action;
     }
 
     private static function modelToData(Explored $model): array

tests/Support/Models/TestModelWithIndexed.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace JeroenG\Explorer\Tests\Support\Models;
+
+use JeroenG\Explorer\Application\BeIndexed;
+use JeroenG\Explorer\Application\Explored;
+
+class TestModelWithIndexed implements Explored, BeIndexed
+{
+    public function getScoutKey(): string
+    {
+        return ':scout_key:';
+    }
+
+    public function searchableAs(): string
+    {
+        return ':searchable_as:';
+    }
+
+    public function toSearchableArray(): array
+    {
+        return [ 'data' => true ];
+    }
+
+    public function mappableAs(): array
+    {
+        return [
+            'data' => [ 'type' => 'boolean' ]
+        ];
+    }
+
+    public function prepareIndexAction(array $action): array
+    {
+        $action['index']['_routing'] = ':routing_key:';
+
+        return $action;
+    }
+}

tests/Unit/Operations/Bulk/BulkUpdateOperationTest.php

@@ -6,6 +6,7 @@
 
 use JeroenG\Explorer\Application\Operations\Bulk\BulkUpdateOperation;
 use JeroenG\Explorer\Tests\Support\Models\TestModelWithoutSettings;
+use JeroenG\Explorer\Tests\Support\Models\TestModelWithIndexed;
 use JeroenG\Explorer\Tests\Support\Models\TestModelWithPrepare;
 use JeroenG\Explorer\Tests\Support\Models\TestModelWithSettings;
 use PHPUnit\Framework\TestCase;
@@ -73,4 +74,14 @@ public function test_it_builds_with_preparation_of_model(): void
             [ 'data' => true, 'extra' => true ]
         ], $operation->build());
     }
+
+    public function test_it_builds_with_preparation_of_index_action(): void
+    {
+        $operation = new BulkUpdateOperation(':searchable_as:');
+        $operation->add(new TestModelWithIndexed());
+        self::assertEquals([
+            ['index' => [ '_index' => ':searchable_as:', '_id' => ':scout_key:', '_routing' => ':routing_key:' ]],
+            [ 'data' => true ]
+        ], $operation->build());
+    }
 }