nested query builder

Author: pdphilip

src/Eloquent/Builder.php

@@ -72,6 +72,7 @@ class Builder extends BaseEloquentBuilder
         'todsl',
         'bucket',
         'bucketaggregation',
+        'nestedquery',
         'openpit',
         'bulkinsert',
         'createonly',

src/Eloquent/Docs/ModelDocs.php

@@ -77,6 +77,7 @@
  * @method static $this orWhereGeoDistance($field, $distance, $location, $distanceType = null, $validationMethod = null)
  * @method static $this orWhereNotGeoDistance($field, $distance, $location, $distanceType = null, $validationMethod = null)
  *-----------------------------------
+ * @method static \PDPhilip\Elasticsearch\Query\Builder nestedQuery(string $column)
  * @method static $this whereNestedObject($column, $query, $filterInnerHits = false, $options = [], $boolean = 'and', $not = false)
  * @method static $this whereNotNestedObject($column, $query, $filterInnerHits = false, $options = [])
  * @method static $this orWhereNestedObject($column, $query, $filterInnerHits = false, $options = [])

src/Query/Concerns/BuildsNestedQueries.php

@@ -6,17 +6,43 @@
 
 use Closure;
 use Illuminate\Support\Str;
+use PDPhilip\Elasticsearch\Exceptions\BuilderException;
 use PDPhilip\Elasticsearch\Exceptions\RuntimeException;
+use PDPhilip\Elasticsearch\Query\Builder;
 
 /**
  * Nested object and parent/child relationship queries.
  * For when your docs have docs inside docs.
  */
 trait BuildsNestedQueries
 {
+    /**
+     * Return a Builder pre-configured for a nested path.
+     *
+     * Use this when you need to build the inner nested query programmatically
+     * (across functions, conditionals, loops) rather than inside a closure.
+     * The returned Builder can be passed straight to whereNestedObject():
+     *
+     *     $inner = BlogPost::nestedQuery('comments');
+     *     $inner->where('country', 'Peru');
+     *     if ($minLikes) $inner->where('likes', '>=', $minLikes);
+     *
+     *     BlogPost::whereNestedObject('comments', $inner)->get();
+     */
+    public function nestedQuery(string $column): Builder
+    {
+        $query = $this->newQuery($this->from);
+        $query->options()->add('parentField', $column);
+
+        return $query;
+    }
+
     /**
      * Query nested objects within a document.
      * https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-nested-query.html
+     *
+     * The $query argument may be a Closure (most common), a pre-built Builder
+     * returned by nestedQuery(), or a raw DSL string.
      */
     public function whereNestedObject($column, $query, $filterInnerHits = false, $options = [], $boolean = 'and', $not = false): self
     {
@@ -28,16 +54,39 @@ public function whereNestedObject($column, $query, $filterInnerHits = false, $op
         }
         $options = $options->toArray();
 
-        if (! is_string($query) && is_callable($query)) {
+        $query = $this->resolveNestedQuery($column, $query);
+
+        $this->wheres[] = compact('column', 'query', 'type', 'boolean', 'not', 'options');
+
+        return $this;
+    }
+
+    /**
+     * Normalize the $query argument accepted by whereNestedObject / filterNested.
+     * Accepts a Closure, a pre-built Builder, or a raw DSL string.
+     */
+    protected function resolveNestedQuery(string $column, mixed $query): mixed
+    {
+        if ($query instanceof Builder) {
+            return $query;
+        }
+
+        if (is_string($query)) {
+            return $query;
+        }
+
+        if (is_callable($query)) {
             $callback = $query;
-            $query = $this->newQuery($from);
+            $query = $this->newQuery($this->from);
             $query->options()->add('parentField', $column);
             call_user_func($callback, $query);
-        }
 
-        $this->wheres[] = compact('column', 'query', 'type', 'boolean', 'not', 'options');
+            return $query;
+        }
 
-        return $this;
+        throw new BuilderException(
+            'Nested query must be a Closure, a Builder from nestedQuery(), or a raw DSL string. Got '.get_debug_type($query).'.'
+        );
     }
 
     public function orWhereNestedObject($column, $query, $filterInnerHits = false, $options = []): self
@@ -74,12 +123,7 @@ public function filterNested($column, $query, $options = [])
         $options = $this->setOptions($options, 'nested');
         $options = $options->toArray();
 
-        if (! is_string($query) && is_callable($query)) {
-            $callback = $query;
-            $query = $this->newQuery($from);
-            $query->options()->add('parentField', $column);
-            call_user_func($callback, $query);
-        }
+        $query = $this->resolveNestedQuery($column, $query);
 
         $this->wheres[] = compact('column', 'query', 'type', 'boolean', 'not', 'options');
 

tests/QueryElasticsearchSpecificTest.php

@@ -141,6 +141,57 @@
     expect($count)->toBe(2);
 });
 
+it('accepts a pre-built Builder from nestedQuery()', function () {
+    $inner = Post::nestedQuery('comments');
+    expect($inner)->toBeInstanceOf(Builder::class);
+
+    $inner->where('country', 'USA')->where('likes', '>=', 15);
+
+    $posts = Post::whereNestedObject('comments', $inner)->get();
+    expect($posts)->toHaveCount(1)
+        ->and($posts[0]['title'])->toBe('Getting Started with Laravel');
+});
+
+it('produces identical results for closure and pre-built Builder forms', function () {
+    $closureForm = Post::whereNestedObject('comments', function (Builder $q) {
+        $q->where('country', 'USA');
+    })->get()->pluck('title')->sort()->values()->all();
+
+    $inner = Post::nestedQuery('comments')->where('country', 'USA');
+    $builderForm = Post::whereNestedObject('comments', $inner)->get()->pluck('title')->sort()->values()->all();
+
+    expect($builderForm)->toBe($closureForm);
+});
+
+it('builds nested query programmatically across conditionals', function () {
+    $filters = ['country' => 'USA'];
+    $minLikes = 15;
+
+    $inner = Post::nestedQuery('comments');
+    foreach ($filters as $field => $value) {
+        $inner->where($field, $value);
+    }
+    if ($minLikes) {
+        $inner->where('likes', '>=', $minLikes);
+    }
+
+    $count = Post::whereNestedObject('comments', $inner)->count();
+    expect($count)->toBe(1);
+});
+
+it('supports pre-built Builder with filterInnerHits', function () {
+    $inner = Post::nestedQuery('comments')->where('country', 'USA');
+
+    $posts = Post::whereNestedObject('comments', $inner, true)->get();
+    expect($posts)->toHaveCount(2)
+        ->and($posts[0]['comments'])->toHaveCount(1)
+        ->and($posts[1]['comments'])->toHaveCount(1);
+});
+
+it('throws BuilderException for invalid nested query argument', function () {
+    Post::whereNestedObject('comments', 12345);
+})->throws(\PDPhilip\Elasticsearch\Exceptions\BuilderException::class);
+
 it('can search with field boosting', function () {
     $users = User::search('John', 'best_fields', ['name' => 5, 'description' => 1])->get();
     expect($users)->toHaveCount(2)