Merge branch 'main' into 5.x-dev

Author: pdphilip

CHANGELOG.md

@@ -2,6 +2,143 @@
 
 All notable changes to this `laravel-elasticsearch` package will be documented in this file.
 
+## v5.2.0 - 2025-10-24
+
+This release is compatible with Laravel 10, 11 & 12
+
+### New Feature: Query String Queries
+
+This release introduces Query String Queries, bringing full Elasticsearch `query_string` syntax support directly into your Eloquent-style queries.
+
+- Method: `searchQueryString(query, $fields = null, $options = [])` and related methods (`orSearchQueryString`, `searchNotQueryString`, etc.)
+- Supports all `query_string` features — logical operators, wildcards, fuzziness, ranges, regex, boosting, field scoping, and more
+- Includes a dedicated `QueryStringOptions` class for fluent option configuration or array-based parameters
+- [See Tests](https://github.com/pdphilip/laravel-elasticsearch/blob/main/tests/QueryStringTest.php)
+- [Full documentation](https://elasticsearch.pdphilip.com/eloquent/query-string-queries/)
+
+Example:
+
+```php
+Product::searchQueryString('status:(active OR pending) name:(full text search)^2')->get();
+Product::searchQueryString('price:[5 TO 19}')->get();
+
+// vanilla optional, +pizza required, -ice forbidden
+Product::searchQueryString('vanilla +pizza -ice', function (QueryStringOptions $options) {
+    $options->type('cross_fields')->fuzziness(2);
+})->get();
+
+//etc
+
+```
+### Ordering enhancement: unmapped_type
+
+- You can now add an `unmapped_type` flag to your ordering query #88
+
+```php
+Product::query()->orderBy('name', 'desc', ['unmapped_type' => 'keyword'])->get();
+
+```
+### Bugfix
+
+- Fixed issue where limit values were being reset on bucket aggregations #84
+
+**Full Changelog**: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.1.0...v5.2.0
+
+## v5.1.0 - 2025-08-20
+
+This release is compatible with Laravel 10, 11 & 12
+
+#### 1. New feature, `withTrackTotalHits(bool|int|null $val = true)`
+
+Appends the `track_total_hits` parameter to the DSL query, setting value to `true` will count all the hits embedded in the query meta not capping to Elasticsearch default of 10k hits
+
+```php
+$products = Product::limit(5)->withTrackTotalHits(true)->get();
+$totalHits = $products->getQueryMeta()->getTotalHits();
+
+
+```
+This can be set by default for all queries by updating the connection config in `database.php`:
+
+```php
+'elasticsearch' => [
+    'driver' => 'elasticsearch',
+    .....
+    'options' => [
+        'track_total_hits' => env('ES_TRACK_TOTAL_HITS', null),
+        ....
+    ],
+],
+
+
+```
+#### 2. New feature, `createOrFail(array $attributes)`
+
+By default, when using `create($attributes)` where `$attributes `has an `id` that exists, the operation will upsert. `createOrFail` will throw a `BulkInsertQueryException` with status code `409` if the `id` exists
+
+```php
+Product::createOrFail([
+    'id' => 'some-existing-id',
+    'name' => 'Blender',
+    'price' => 30,
+]);
+
+
+```
+#### 3. New feature `withRefresh(bool|string $refresh)`
+
+By default, inserting documents will wait for the shards to refresh, ie: `withRefresh(true)`, you can set the refresh flag with the following (as per ES docs):
+
+- `true` (default)
+  Refresh the relevant primary and replica shards (not the whole index) immediately after the operation occurs, so that the updated document appears in search results immediately.
+- `wait_for`
+  Wait for the changes made by the request to be made visible by a refresh before replying. This doesn’t force an immediate refresh, rather, it waits for a refresh to happen.
+- `false`
+  Take no refresh-related actions. The changes made by this request will be made visible at some point after the request returns.
+
+```php
+Product::withRefresh('wait_for')->create([
+    'name' => 'Blender',
+    'price' => 30,
+]);
+
+
+```
+### PRS
+
+* Add withTrackTotalHits method to Builder class to add track_total_hits by @caufab in https://github.com/pdphilip/laravel-elasticsearch/pull/76
+* feat(query): add op_type=create support and dedupe helpers by @abkrim in https://github.com/pdphilip/laravel-elasticsearch/pull/79
+
+### Bugfix
+
+* Laravel ^12.23 Compatibility - close [#81](https://github.com/pdphilip/laravel-elasticsearch/issues/81)
+
+### New Contributors
+
+* @caufab made their first contribution in https://github.com/pdphilip/laravel-elasticsearch/pull/76
+
+**Full Changelog**: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.7...v5.1.0
+
+## v5.0.7 - 2025-07-13
+
+This release is compatible with Laravel 10, 11 & 12
+
+### What's Changed
+
+* Connection bug fix by @pdphilip in https://github.com/pdphilip/laravel-elasticsearch/pull/75 - close #70
+
+**Full Changelog**: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.6...v5.0.7
+
+## v5.0.6 - 2025-06-04
+
+This release is compatible with Laravel 10, 11 & 12
+
+### What's Changed
+
+* Bug fix: Chunking `$count` value fixed for setting query limit correctly, via #68
+
+**Full Changelog**: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.5...v5.0.6
+
 ## v5.0.5 - 2025-05-19
 
 This release is compatible with Laravel 10, 11 & 12
@@ -71,6 +208,10 @@ People::bulkInsert([
 
 
 
+
+
+
+
 ```
 Returns:
 
@@ -93,6 +234,10 @@ Returns:
 }
 
 
+
+
+
+
 ```
 #### 2. Bug fix: `distinct()` aggregation now appends `searchAfter` key in meta
 
@@ -130,6 +275,10 @@ with Laravel’s Eloquent. It lays a solid, future-proof foundation for everythi
 "pdphilip/elasticsearch": "^5",
 
 
+
+
+
+
 ```
 ### Breaking Changes
 
@@ -159,6 +308,10 @@ with Laravel’s Eloquent. It lays a solid, future-proof foundation for everythi
   }
 
 
+  
+  
+  
+  
   ```
 
 #### 3. Queries
@@ -175,6 +328,10 @@ with Laravel’s Eloquent. It lays a solid, future-proof foundation for everythi
   Product::where('name', 'John')->get();      // term query
 
 
+  
+  
+  
+  
   ```
 - `orderByRandom()` Removed
 
@@ -192,6 +349,10 @@ with Laravel’s Eloquent. It lays a solid, future-proof foundation for everythi
   })->get();
 
 
+  
+  
+  
+  
   ```
 - Legacy Search Methods Removed
   All `{xx}->search()` methods been removed. Use `{multi_match}->get()` instead.
@@ -214,6 +375,10 @@ with Laravel’s Eloquent. It lays a solid, future-proof foundation for everythi
   use PDPhilip\Elasticsearch\Schema\Blueprint;
 
 
+  
+  
+  
+  
   ```
 - `Schema::hasIndex` has been removed. Use `Schema::hasTable` or `Schema::indexExists` instead.
 
@@ -280,6 +445,10 @@ with Laravel’s Eloquent. It lays a solid, future-proof foundation for everythi
 Connection::on('elasticsearch')->elastic()->{clientMethod}();
 
 
+
+
+
+
 ```
 ### What's Changed
 

src/Connection.php

@@ -123,6 +123,7 @@ private function sanitizeConfig(): void
                     'cert_password' => null,
                 ],
                 'options' => [
+                    'track_total_hits' => null, // null -> skips - max 10k by default; true -> full values; false -> no hit tracking, returns -1; int -> max hit tracking val, ex 20000
                     'bypass_map_validation' => false, // This skips the safety checks for Elastic Specific queries.
                     'logging' => false,
                     'ssl_verification' => true,
@@ -162,22 +163,24 @@ public function setOptions(): void
     {
         $this->allowIdSort = $this->config['options']['allow_id_sort'] ?? false;
 
+        $this->options()->add('track_total_hits', $this->config['options']['track_total_hits'] ?? null);
+
         $this->options()->add('bypass_map_validation', $this->config['options']['bypass_map_validation'] ?? null);
 
         if (isset($this->config['options']['ssl_verification'])) {
             $this->options()->add('ssl_verification', $this->config['options']['ssl_verification']);
         }
 
         if (! empty($this->config['options']['retires'])) {
-            $this->options()->add('retires', $this->config['options']['retires']);
+            $this->options()->add('retires', (int) $this->config['options']['retires']);
         }
 
         if (isset($this->config['options']['meta_header'])) {
             $this->options()->add('meta_header', $this->config['options']['meta_header']);
         }
 
         if (isset($this->config['options']['default_limit'])) {
-            $this->defaultQueryLimit = $this->config['options']['default_limit'];
+            $this->defaultQueryLimit = (int) $this->config['options']['default_limit'];
         }
     }
 

src/Eloquent/Builder.php

@@ -71,6 +71,7 @@ class Builder extends BaseEloquentBuilder
         'bucketaggregation',
         'openpit',
         'bulkinsert',
+        'createonly',
     ];
 
     /**
@@ -95,7 +96,7 @@ public function setModel($model): static
     public function newModelInstance($attributes = [])
     {
         $model = $this->model->newInstance($attributes)->setConnection(
-            $this->query->getConnection()->getName()
+            $this->query->connection->getName()
         );
 
         // Merge in our options.
@@ -216,7 +217,7 @@ public function hydrate(array $items)
         $instance = $this->newModelInstance();
 
         return $instance->newCollection(array_map(function ($item) use ($instance) {
-            return $instance->newFromBuilder($item, $this->getConnection()->getName());
+            return $instance->newFromBuilder($item, $this->query->connection->getName());
         }, $items));
     }
 
@@ -275,6 +276,7 @@ public function orderedChunkById($count, callable $callback, $column = null, $al
     public function chunkByPit($count, callable $callback, $keepAlive = '1m'): bool
     {
         $this->query->keepAlive = $keepAlive;
+        $this->query->limit = $count;
         $pitId = $this->query->openPit();
 
         $searchAfter = null;
@@ -386,9 +388,25 @@ public function findOrNew($id, $columns = ['*']): Model
         return $model;
     }
 
-    public function withoutRefresh()
+    public function withoutRefresh(): Model
     {
-        $this->model->options()->add('refresh', false);
+        return $this->withRefresh(false);
+    }
+
+    /**
+     * Explicitly control the Elasticsearch refresh behavior for write ops.
+     * Accepts: true, false, or 'wait_for'.
+     */
+    public function withRefresh(bool|string $refresh): Model
+    {
+        $this->model->options()->add('refresh', $refresh);
+
+        return $this->model;
+    }
+
+    public function withOpType(string $value)
+    {
+        $this->model->options()->add('op_type', $value);
 
         return $this->model;
     }
@@ -643,6 +661,27 @@ public function rawDsl($dsl): array
         return $this->query->raw($dsl)->asArray();
     }
 
+    /**
+     * Force insert operations to use op_type=create for dedupe semantics.
+     * When set, attempts to create an existing _id will fail with a 409 from Elasticsearch.
+     */
+    public function createOnly(): Model
+    {
+        // mark insert op type on the underlying query options
+        $this->withOpType('create');
+
+        return $this->model;
+    }
+
+    /**
+     * Convenience method to perform a create-only insert and surface 409s as exceptions.
+     * Accepts single document attributes or an array of documents.
+     */
+    public function createOrFail(array $attributes)
+    {
+        return $this->createOnly()->create($attributes);
+    }
+
     // ----------------------------------------------------------------------
     // Protected
     // ----------------------------------------------------------------------

src/Eloquent/Docs/ModelDocs.php

@@ -14,7 +14,7 @@
 /**
  * Query Builder Methods ---------------------------------
  *
- * @method static Builder query()
+ * @method static $this query()
  *-----------------------------------
  * @method static $this where($column, $operator = null, $value = null, $boolean = 'and', $options = [])
  * @method static $this whereNot($column, $operator = null, $value = null, $boolean = 'and', $options = [])
@@ -127,6 +127,11 @@
  * @method static $this orSearchFuzzyPrefix($term, $fields = ['*'], $options = [])
  * @method static $this searchNotFuzzyPrefix($term, $fields = ['*'], $options = [])
  * @method static $this orSearchNotFuzzyPrefix($term, $fields = ['*'], $options = [])
+ *                                                                                    -----------------------------------
+ * @method static $this searchQueryString($query, $fields = null, $options = [])
+ * @method static $this orSearchQueryString($query, $fields = null, $options = [])
+ * @method static $this searchNotQueryString($query, $fields = null, $options = [])
+ * @method static $this orSearchNotQueryString($query, $fields = null, $options = [])
  *===========================================
  * Speciality methods
  *===========================================
@@ -181,6 +186,8 @@
  * @method static array getModels($columns = ['*'])
  * @method static ElasticCollection get($columns = ['*'])
  * @method static ElasticCollection insert($values, $returnData = null)
+ * @method static self createOnly()
+ * @method static self createOrFail(array $attributes)
  *-----------------------------------
  * @method static array toDsl($columns = ['*'])
  * @method static array toSql($columns = ['*'])