Fix #311: Added support for runtime mappings in Elasticsearch 7.11+

Author: mabentley85

.github/workflows/build.yml

@@ -25,6 +25,7 @@ jobs:
           - "7.4"
 
         es-version:
+          - "7.14.0"
           - "7.7.0"
           - "6.8.9"
           - "5.6.16"
@@ -67,7 +68,7 @@ jobs:
       - name: Get composer cache directory
         id: composer-cache
         run: echo "::set-output name=dir::$(composer config cache-files-dir)"
-        
+
       - name: Cache dependencies installed with composer
         uses: actions/cache@v1
         with:

CHANGELOG.md

@@ -4,7 +4,7 @@ Yii Framework 2 Elasticsearch extension Change Log
 2.1.3 under development
 -----------------------
 
-- no changes in this release.
+- Enh #311: Added support for runtime mappings in Elasticsearch 7.11+ (mabentley85)
 
 
 2.1.2 August 09, 2021

Query.php

@@ -103,6 +103,38 @@ class Query extends Component implements QueryInterface
      * @see source
      */
     public $scriptFields;
+    /**
+     * @var array An array of runtime fields evaluated at query time
+     * Example:
+     * ```php
+     * $query->$runtimeMappings = [
+     *     'value_times_two' => [
+     *         'type' => 'double',
+     *         'script' => "emit(doc['my_field_name'].value * 2)",
+     *     ],
+     *     'value_times_factor' => [
+     *         'type' => 'double',
+     *         'script' => "emit(doc['my_field_name'].value * factor)",
+     *         'params' => [
+     *             'factor' => 2.0
+     *         ],
+     *     ],
+     * ]
+     * ```
+     *
+     * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/runtime-mapping-fields.html
+     * @see runtimeMappings()
+     * @see source
+     */
+    public $runtimeMappings;
+    /**
+     * @var array Use the fields parameter to retrieve the values of runtime fields.  Runtime fields won’t display in
+     * _source, but the fields API works for all fields, even those that were not sent as part of the original _source.
+     * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/runtime-retrieving-fields.html
+     * @see fields()
+     * @see fields
+     */
+    public $fields;
     /**
      * @var array this option controls how the `_source` field is returned from
      * the documents. For example, `['id', 'name']` means that only the `id`
@@ -450,7 +482,7 @@ public function count($q = '*', $db = null)
         if ($this->emulateExecution) {
             return 0;
         }
-        
+
         $command = $this->createCommand($db);
 
         // performing a query with return size of 0, is equal to getting result stats such as count
@@ -732,6 +764,38 @@ public function scriptFields($fields)
         return $this;
     }
 
+    /**
+     * Sets the runtime mappings for this query
+     * @param $mappings
+     * @return $this the query object itself
+     * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/runtime.html
+     */
+    public function runtimeMappings($mappings)
+    {
+        if (is_array($mappings) || $mappings === null) {
+            $this->runtimeMappings = $mappings;
+        } else {
+            $this->runtimeMappings = func_get_args();
+        }
+        return $this;
+    }
+
+    /**
+     * Sets the runtime fields to retrieve from the documents.
+     * @param array $fields the fields to be selected.
+     * @return $this the query object itself
+     * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/runtime-retrieving-fields.html
+     */
+    public function fields($fields)
+    {
+        if (is_array($fields) || $fields === null) {
+            $this->fields = $fields;
+        } else {
+            $this->fields = func_get_args();
+        }
+        return $this;
+    }
+
     /**
      * Sets the source filtering, specifying how the `_source` field of the
      * document should be returned.

QueryBuilder.php

@@ -53,6 +53,12 @@ public function build($query)
         if ($query->scriptFields !== null) {
             $parts['script_fields'] = $query->scriptFields;
         }
+        if ($query->runtimeMappings !== null) {
+            $parts['runtime_mappings'] = $query->runtimeMappings;
+        }
+        if ($query->fields !== null) {
+            $parts['fields'] = $query->fields;
+        }
 
         if ($query->source !== null) {
             $parts['_source'] = $query->source;

docs/guide/usage-query.md

@@ -94,3 +94,30 @@ $query->from('customer');
 // Note the literal string 'true', not a boolean value!
 $query->addOptions(['track_total_hits' => 'true']);
 ```
+
+## Runtime Fields/Mappings in ES >= 7.11
+
+Runtime Fields are fields that can be dynamically generated at query time by supplying a script similar to `script_fields`.
+The major difference being that the value of a Runtime Field can be used in search queries, aggregations, filtering, and 
+sorting.
+
+Any Runtime Field values that you want to be included in the search results must be added to the `field` array by passing
+an array of field names using the `fields()` method. 
+
+Example for fetching users' full names by concatenating the `first_name` and `last_name` fields from the index and 
+sorting them alphabetically.
+```php
+$results = (new yii\elasticsearch\Query())
+    ->from('users')
+    ->runtimeMappings([
+        'full_name' => [
+            'type' => 'keyword',
+            'script' => "emit(doc['first_name'].value + ' ' + doc['last_name'].value)",
+        ],
+    ])
+    ->fields(['full_name'])
+    ->orderBy(['full_name' => SORT_ASC])
+    ->search($connection);
+```
+
+For more information concerning `type` and `script` please see [Elastic's Runtime Field Documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/runtime.html)

tests/QueryTest.php

@@ -451,4 +451,36 @@ public function testSuggest()
 
         $this->assertCount(5, $result['customer_name'][0]['options']);
     }
+
+    public function testRuntimeMappings()
+    {
+        // Check that Elasticsearch is version 7.11.0 or later before running this test
+        $elasticsearchInfo = $this->getConnection()->get('/');
+        if(!version_compare($elasticsearchInfo['version']['number'], '7.11.0', '>=')) {
+            return;
+        }
+
+        $query = new Query();
+        $query->from('query-test', 'user');
+
+        $query->runtimeMappings([
+            'name_email' => [
+                'type' => 'keyword',
+                'script' => "emit(doc['name'].value + ':' + doc['email'].value)",
+            ],
+        ]);
+        $this->assertEquals([
+            'name_email' => [
+                'type' => 'keyword',
+                'script' => "emit(doc['name'].value + ':' + doc['email'].value)",
+            ],
+        ], $query->runtimeMappings);
+
+        $query->fields(['name_email']);
+        $this->assertEquals(['name_email'], $query->fields);
+
+        $result = $query->search($this->getConnection());
+        $this->assertArrayHasKey('name_email', $result['hits']['hits'][0]['fields']);
+        $this->assertEquals($result['hits']['hits'][0]['fields']['name_email'][0], 'user1:user1@example.com');
+    }
 }