v2.0.2 upgrades

agg() method, phrase() method, wherePhrasePrefix() method, toDsl() method, Error logging, Bug fix of saving _meta data,

Author: pdphilip

README.md

@@ -2,34 +2,44 @@
 
 # Laravel-OpenSearch
 
-
 > **This package has been built off the back of the original [Elasticsearch version](https://github.com/pdphilip/laravel-elasticsearch) of this package**
-> 
+>
 > **The starting point of this package was forked from `v4.0.1` with over 2 years of development**
 
-[OpenSearch](https://opensearch.net/) is a distributed, community-driven, Apache 2.0-licensed, 100% open-source search and analytics suite used for a broad set of use cases like real-time application monitoring, log analytics, and website search.
+[OpenSearch](https://opensearch.net/) is a distributed, community-driven, Apache 2.0-licensed, 100% open-source search and analytics suite used for a broad set of use cases like real-time application monitoring, log analytics, and website
+search.
 
 ### An OpenSearch implementation of Laravel's Eloquent ORM
 
 This package extends Laravel's Eloquent model and query builder with seamless integration of OpenSearch functionalities. Designed to feel native to Laravel, this package enables you to work with Eloquent models while leveraging the
 powerful search and analytics capabilities of OpenSearch.
 
-Example:
+Examples:
+
 ```php
 $logs = UserLog::where('created_at','>=',Carbon::now()->subDays(30))->get();
 ```
+
 ```php
 $updates = UserLog::where('status', 1)->update(['status' => 4]);
 ```
+
+```php
+$updates = UserLog::where('status', 1)->paginate(50);
+```
+
 ```php
 $profiles = UserProfile::whereIn('country_code',['US','CA'])->orderByDesc('last_login')->take(10)->get();
 ```
+
 ```php
-$deleted = UserProfile::where('state','unsubscribed')->where('updated_at','<=',Carbon::now()->subDays(90)->delete();
+$deleted = UserProfile::where('state','unsubscribed')->where('updated_at','<=',Carbon::now()->subDays(90))->delete();
 ```
+
 ```php
-$search = UserProfile::term('loves espressos')->minShouldMatch(2)->highlight()->search();
+$search = UserProfile::phrase('loves espressos')->highlight()->search();
 ```
+
 ---
 > ### Read the [Documentation](https://opensearch.pdphilip.com/)
 ---
@@ -42,8 +52,8 @@ $search = UserProfile::term('loves espressos')->minShouldMatch(2)->highlight()->
 composer require pdphilip/opensearch
 ```
 
-| Laravel Version | Command                                       | Maintained |
-|-----------------|-----------------------------------------------|------------|
+| Laravel Version | Command                                    | Maintained |
+|-----------------|--------------------------------------------|------------|
 | Laravel 10 & 11 | `composer require pdphilip/opensearch:~2 ` | ✅          |
 | Laravel 8 & 9   | `composer require pdphilip/opensearch:~1`  | ✅          |
 
@@ -70,6 +80,7 @@ OS_OPT_VERIFY_SSL=true
 OS_OPT_RETRIES=
 OS_OPT_SNIFF_ON_START=
 OS_OPT_PORT_HOST_HEADERS=
+OS_ERROR_INDEX=
 ```
 
 For multiple nodes, pass in as comma-separated:
@@ -106,10 +117,7 @@ OS_HOSTS="http://opensearch-node1:9200,http://opensearch-node2:9200,http://opens
         'sniff_on_start'      => env('OS_OPT_SNIFF_ON_START'),
         'port_in_host_header' => env('OS_OPT_PORT_HOST_HEADERS'),
     ],
-    'query_log'    => [
-        'index'      => false, //Or provide a name for the logging index ex: 'laravel_query_logs'
-        'error_only' => true, //If false, then all queries are logged if the query_log index is set
-    ],
+    'error_log_index' => env('OS_ERROR_INDEX', false),
 ],
 ```
 

src/Connection.php

@@ -25,6 +25,7 @@ class Connection extends BaseConnection
     protected $portInHeaders = null;
     protected $rebuild = false;
     protected $allowIdSort = true;
+    protected $errorLoggingIndex = false;
 
     public function __construct(array $config)
     {
@@ -59,6 +60,13 @@ public function setOptions($config)
         if (isset($config['options']['port_in_host_header'])) {
             $this->portInHeaders = $config['options']['port_in_host_header'];
         }
+        if (!empty($config['error_log_index'])) {
+            if ($this->indexPrefix) {
+                $this->errorLoggingIndex = $this->indexPrefix.'_'.$config['error_log_index'];
+            } else {
+                $this->errorLoggingIndex = $config['error_log_index'];
+            }
+        }
     }
 
     public function getIndexPrefix(): string|null
@@ -89,6 +97,11 @@ public function setIndex($index): string
         return $this->getIndex();
     }
 
+    public function getErrorLoggingIndex(): string|bool
+    {
+        return $this->errorLoggingIndex;
+    }
+
     public function getSchemaGrammar()
     {
         return new Schema\Grammar($this);

src/DSL/Bridge.php

@@ -21,11 +21,9 @@ class Bridge
 
     protected Client $client;
 
-    protected mixed $queryLogger = false;
+    protected string|bool $errorLogger = false;
 
-    protected mixed $queryLoggerOnErrorOnly = true;
-
-    protected int|null $maxSize = 10; //ES default
+    protected int|null $maxSize = 10; //OS default
 
     private string|null $index;
 
@@ -38,11 +36,7 @@ public function __construct(Connection $connection)
         $this->index = $this->connection->getIndex();
         $this->maxSize = $this->connection->getMaxSize();
         $this->indexPrefix = $this->connection->getIndexPrefix();
-
-        if (!empty(config('database.connections.elasticsearch.logging.index'))) {
-            $this->queryLogger = config('database.connections.elasticsearch.logging.index');
-            $this->queryLoggerOnErrorOnly = config('database.connections.elasticsearch.logging.errorOnly');
-        }
+        $this->errorLogger = $this->connection->getErrorLoggingIndex();
 
     }
 
@@ -191,6 +185,20 @@ public function processIndicesDsl($method, $params): Results
         }
     }
 
+    //----------------------------------------------------------------------
+    // To DSL
+    //----------------------------------------------------------------------
+
+    public function processToDsl($wheres, $options, $columns)
+    {
+        return $this->buildParams($this->index, $wheres, $options, $columns);
+    }
+
+    public function processToDslForSearch($searchParams, $searchOptions, $wheres, $opts, $fields, $cols)
+    {
+        return $this->buildSearchParams($this->index, $searchParams, $searchOptions, $wheres, $opts, $fields, $cols);
+    }
+
 
     //----------------------------------------------------------------------
     // Read Queries
@@ -314,7 +322,9 @@ public function processSave($data, $refresh): Results
         if (isset($data['_index'])) {
             unset($data['_index']);
         }
-
+        if (isset($data['_meta'])) {
+            unset($data['_meta']);
+        }
         $params = [
             'index' => $this->index,
             'body'  => $data,
@@ -665,6 +675,21 @@ public function processIndexAnalyzerSettings($settings): bool
     // Aggregates
     //----------------------------------------------------------------------
 
+    public function processMultipleAggregate($functions, $wheres, $options, $column)
+    {
+        $params = $this->buildParams($this->index, $wheres, $options);
+        try {
+            $params['body']['aggs'] = ParameterBuilder::multipleAggregations($functions, $column);
+            $process = $this->client->search($params);
+
+            return $this->_return($process['aggregations'] ?? [], $process, $params, $this->_queryTag(__FUNCTION__));
+
+        } catch (Exception $e) {
+
+            $this->throwError($e, $params, $this->_queryTag(__FUNCTION__));
+        }
+    }
+
     /**
      *  Aggregate entry point
      *
@@ -1193,9 +1218,6 @@ private function _return($data, $meta, $params, $queryTag): Results
             $results = new Results($data, $meta, $params, $queryTag);
         }
 
-        if ($this->queryLogger && !$this->queryLoggerOnErrorOnly) {
-            $this->_logQuery($results);
-        }
 
         return $results;
     }
@@ -1213,9 +1235,7 @@ private function throwError(Exception $exception, $params, $queryTag): QueryExce
         $this->connection->rebuildConnection();
         $error = new Results([], [], $params, $queryTag);
         $error->setError($errorMsg, $errorCode);
-        if ($this->queryLogger) {
-            $this->_logQuery($error);
-        }
+
         $meta = $error->getMetaData();
         $details = [
             'error'     => $meta['error']['msg'],
@@ -1226,15 +1246,22 @@ private function throwError(Exception $exception, $params, $queryTag): QueryExce
             'params'    => $params,
             'original'  => $errorMsg,
         ];
+        if ($this->errorLogger) {
+            $this->_logQuery($error, $details);
+        }
         // For details catch $exception then $exception->getDetails()
         throw new QueryException($meta['error']['msg'], $errorCode, new $previous, $details);
     }
 
-    private function _logQuery($results)
+    private function _logQuery(Results $results, $details)
     {
+        $body = $results->getLogFormattedMetaData();
+        if ($details) {
+            $body['details'] = (array)$details;
+        }
         $params = [
-            'index' => $this->queryLogger,
-            'body'  => $results->getLogFormattedMetaData(),
+            'index' => $this->errorLogger,
+            'body'  => $body,
         ];
         try {
             $this->client->index($params);

src/DSL/ParameterBuilder.php

@@ -140,5 +140,38 @@ public static function matrixAggregation(array $fields): array
         ];
     }
 
+    public static function multipleAggregations($aggregations, $field)
+    {
+        $aggs = [];
+        foreach ($aggregations as $aggregation) {
+            switch ($aggregation) {
+                case 'max':
+                    $aggs['max_'.$field] = self::maxAggregation($field);
+                    break;
+                case 'min':
+                    $aggs['min_'.$field] = self::minAggregation($field);
+                    break;
+                case 'avg':
+                    $aggs['avg_'.$field] = self::avgAggregation($field);
+                    break;
+                case 'sum':
+                    $aggs['sum_'.$field] = self::sumAggregation($field);
+                    break;
+                case 'matrix':
+                    $aggs['matrix_'.$field] = self::matrixAggregation([$field]);
+                    break;
+                case 'count':
+                    $aggs['count_'.$field] = [
+                        'value_count' => [
+                            'field' => $field,
+                        ],
+                    ];
+                    break;
+            }
+        }
+
+        return $aggs;
+
+    }
 
 }

src/DSL/QueryBuilder.php

@@ -352,6 +352,9 @@ private function _parseCondition($condition, $parentField = null): array
                 case 'phrase':
                     $queryPart = ['match_phrase' => [$field => $operand]];
                     break;
+                case 'phrase_prefix':
+                    $queryPart = ['match_phrase_prefix' => [$field => ['query' => $operand]]];
+                    break;
                 case 'exact':
                     $keywordField = $this->parseRequiredKeywordMapping($field);
                     if (!$keywordField) {

src/Eloquent/Builder.php

@@ -40,7 +40,7 @@ class Builder extends BaseEloquentBuilder
         'push',
         'raw',
         'sum',
-        'toSql',
+        'tosql',
         //ES only:
         'matrix',
         'query',
@@ -54,6 +54,8 @@ class Builder extends BaseEloquentBuilder
         'indexexists',
         'createindex',
         'search',
+        'todsl',
+        'agg',
     ];
 
 
@@ -392,6 +394,28 @@ public function orRegEx(string $regEx, int $boostFactor = null)
         return $this;
     }
 
+
+    public function phrase(string $term, int $boostFactor = null)
+    {
+        $this->query->searchQuery($term, $boostFactor, null, 'phrase');
+
+        return $this;
+    }
+
+    public function andPhrase(string $term, int $boostFactor = null)
+    {
+        $this->query->searchQuery($term, $boostFactor, 'AND', 'phrase');
+
+        return $this;
+    }
+
+    public function orPhrase(string $term, int $boostFactor = null)
+    {
+        $this->query->searchQuery($term, $boostFactor, 'OR', 'phrase');
+
+        return $this;
+    }
+
     /**
      * @param $value
      *

src/Eloquent/Docs/ModelDocs.php

@@ -12,18 +12,24 @@
  * @method static $this regEx(string $term, $boostFactor = null)
  * @method $this andRegEx(string $term, $boostFactor = null)
  * @method $this orRegEx(string $term, $boostFactor = null)
+ * @method static $this phrase(string $term, $boostFactor = null)
+ * @method $this andPhrase(string $term, $boostFactor = null)
+ * @method $this orPhrase(string $term, $boostFactor = null)
  * @method $this minShouldMatch(int $value)
  * @method $this minScore(float $value)
  * @method $this field(string $field, int $boostFactor = null)
  * @method $this fields(array $fields)
  * @method search(array $columns = '*')
  * @method query(array $columns = '*')
+ * @method toDsl(array $columns = '*')
+ * @method agg(array $functions, $column)
  *
  * @method  $this WhereDate($column, $operator = null, $value = null, $boolean = 'and')
  * @method  $this WhereTimestamp($column, $operator = null, $value = null, $boolean = 'and')
  * @method  $this whereIn(string $column, array $values)
  * @method  $this whereExact(string $column, string $value)
  * @method  $this wherePhrase(string $column, string $value)
+ * @method  $this wherePhrasePrefix(string $column, string $value)
  * @method  $this filterGeoBox(string $column, array $topLeftCoords, array $bottomRightCoords)
  * @method  $this filterGeoPoint(string $column, string $distance, array $point)
  * @method  $this whereRegex(string $column, string $regex)