Nested Field Aggs

Author: pdphilip

src/Query/Grammar/Concerns/CompilesAggregations.php

@@ -91,6 +91,13 @@ protected function compileBucketAggregations(Builder $builder, $sorts = null): a
             }
 
             $result = $this->compileAggregation($builder, $aggregation);
+
+            // Wrap in nested agg if bucket targets nested fields
+            $nestedPath = $this->detectNestedPathFromBucketAgg($builder, $aggregation);
+            if ($nestedPath) {
+                $result = $this->wrapInNestedAgg($result, $nestedPath, $builder);
+            }
+
             $aggregations = $aggregations->mergeRecursive($result);
         }
 
@@ -264,4 +271,130 @@ protected function compileFilterAggregation(mixed $args): array
 
         return DslFactory::filterAggregation(array_merge($filter['query'] ?? [], $filter['filter'] ?? []));
     }
+
+    // ----------------------------------------------------------------------
+    // Nested field aggregation support
+    // ES requires aggregations on nested fields to be wrapped in a nested agg context.
+    // ----------------------------------------------------------------------
+
+    /**
+     * Wrap compiled aggregations in a nested agg when targeting nested fields.
+     * If a whereNestedObject filter exists on the same path, injects it as a
+     * filter agg inside the nested wrapper for accurate sub-document filtering.
+     */
+    protected function wrapInNestedAgg(array $aggs, ?string $nestedPath, ?Builder $builder = null): array
+    {
+        if (! $nestedPath) {
+            return $aggs;
+        }
+
+        $key = 'nested_'.str_replace('.', '_', $nestedPath);
+
+        // Check for a whereNestedObject filter on the same path
+        $nestedFilter = $builder ? $this->extractNestedFilter($nestedPath, $builder) : null;
+
+        if ($nestedFilter) {
+            return [
+                $key => [
+                    'nested' => ['path' => $nestedPath],
+                    'aggs' => [
+                        'filtered' => [
+                            'filter' => $nestedFilter,
+                            'aggs' => $aggs,
+                        ],
+                    ],
+                ],
+            ];
+        }
+
+        return [
+            $key => [
+                'nested' => ['path' => $nestedPath],
+                'aggs' => $aggs,
+            ],
+        ];
+    }
+
+    /**
+     * Find the common nested path shared by all fields.
+     * Returns null if any field is non-nested or paths differ.
+     */
+    protected function resolveCommonNestedPath(array $fields, Builder $builder): ?string
+    {
+        $nestedPath = null;
+
+        foreach ($fields as $field) {
+            $fieldPath = $this->getNestedPath($field, $builder);
+
+            if ($fieldPath === null) {
+                return null;
+            }
+
+            if ($nestedPath === null) {
+                $nestedPath = $fieldPath;
+            } elseif ($nestedPath !== $fieldPath) {
+                return null;
+            }
+        }
+
+        return $nestedPath;
+    }
+
+    /**
+     * Detect the nested path from a bucket aggregation's arguments.
+     * Inspects composite sources and terms field references.
+     */
+    protected function detectNestedPathFromBucketAgg(Builder $builder, array $aggregation): ?string
+    {
+        $type = $aggregation['type'];
+        $args = $aggregation['args'];
+
+        if ($type === 'composite' && is_array($args)) {
+            foreach ($args as $source) {
+                if (! is_array($source)) {
+                    continue;
+                }
+                foreach (array_keys($source) as $field) {
+                    $path = $this->getNestedPath($field, $builder);
+                    if ($path) {
+                        return $path;
+                    }
+                }
+            }
+        }
+
+        if ($type === 'terms') {
+            $field = is_array($args) ? ($args['field'] ?? $aggregation['key']) : $aggregation['key'];
+
+            return $this->getNestedPath($field, $builder);
+        }
+
+        return null;
+    }
+
+    /**
+     * Extract the filter condition from a whereNestedObject on the same path.
+     * Returns a compiled ES filter body, or null if no matching filter exists.
+     */
+    protected function extractNestedFilter(string $nestedPath, Builder $builder): ?array
+    {
+        if (empty($builder->wheres)) {
+            return null;
+        }
+
+        foreach ($builder->wheres as $where) {
+            if (($where['type'] ?? null) !== 'NestedObject' || ($where['column'] ?? null) !== $nestedPath) {
+                continue;
+            }
+
+            $compiled = $this->compileWheres($where['query']);
+            $filter = array_merge($compiled['query'] ?? [], $compiled['filter'] ?? []);
+
+            if (! empty($filter)) {
+                return $filter;
+            }
+        }
+
+        return null;
+    }
 }

src/Query/Grammar/Concerns/FieldUtilities.php

@@ -9,6 +9,7 @@
 use Illuminate\Support\Facades\Config;
 use PDPhilip\Elasticsearch\Exceptions\BuilderException;
 use PDPhilip\Elasticsearch\Query\Builder;
+use PDPhilip\Elasticsearch\Schema\Schema;
 
 /**
  * Field mapping, value conversion, and other utility methods.
@@ -120,6 +121,63 @@ public function getIndexableField(string $textField, Builder $builder): string
         throw new BuilderException("{$textField} does not have a keyword field.");
     }
 
+    /**
+     * Get the nested mapping path for a dotted field.
+     * For 'tags.key', returns 'tags' if tags is mapped as nested.
+     * Supports multi-level nesting: 'a.b.c' checks 'a' then 'a.b'.
+     *
+     * Uses the index mapping API (getMappings) rather than the field mapping API,
+     * because the field mapping API doesn't return nested parent entries.
+     */
+    public function getNestedPath(string $field, Builder $builder): ?string
+    {
+        if (! str_contains($field, '.')) {
+            return null;
+        }
+
+        $nestedPaths = $this->resolveNestedPaths($builder);
+
+        $segments = explode('.', $field);
+        $path = '';
+        for ($i = 0; $i < count($segments) - 1; $i++) {
+            $path = $path ? $path.'.'.$segments[$i] : $segments[$i];
+            if (in_array($path, $nestedPaths)) {
+                return $path;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Resolve all nested field paths for the builder's index.
+     * Cached per index to avoid repeated API calls.
+     */
+    protected function resolveNestedPaths(Builder $builder): array
+    {
+        $cacheKey = $builder->from.'_nested_paths';
+        $cached = $builder->options()->get($cacheKey);
+        if ($cached !== null) {
+            return $cached;
+        }
+
+        $nestedPaths = [];
+        try {
+            $mapping = Schema::connection($builder->connection->getName())->getMappings($builder->getFrom());
+            foreach ($mapping as $field => $details) {
+                if (is_array($details) && ($details['type'] ?? null) === 'nested') {
+                    $nestedPaths[] = $field;
+                }
+            }
+        } catch (\Exception) {
+            // Index may not exist yet — no nested paths to detect
+        }
+
+        $builder->options()->add($cacheKey, $nestedPaths);
+
+        return $nestedPaths;
+    }
+
     /**
      * Date format from config.
      */

src/Query/Grammar/Grammar.php

@@ -268,7 +268,15 @@ private function compileSelectAggregations(Builder $query, DslBuilder $dsl): voi
                     $aggs[$aggregation['key']]['key'] = $aggregation['type'].'_'.$aggregation['key'];
                 }
 
-                $dsl->setBody(['aggs'], $this->compileNestedTermAggregations($fields, $query, $aggs));
+                $compiledAggs = $this->compileNestedTermAggregations($fields, $query, $aggs);
+
+                // Wrap in nested agg if all fields share a nested path
+                $nestedPath = $this->resolveCommonNestedPath($fields, $query);
+                if ($nestedPath) {
+                    $compiledAggs = $this->wrapInNestedAgg($compiledAggs, $nestedPath, $query);
+                }
+
+                $dsl->setBody(['aggs'], $compiledAggs);
                 $dsl->setBody(['size'], $query->getSetLimit() ?? 0);
                 $dsl->unsetBody(['sort']);
             } else {
@@ -279,10 +287,30 @@ private function compileSelectAggregations(Builder $query, DslBuilder $dsl): voi
                 $fields = Arr::wrap($query->columns);
                 $aggs = [];
 
+                // Group fields by nested path to share one wrapper per path
+                $nestedGroups = [];
+                $plainFields = [];
                 foreach ($fields as $field) {
+                    $nestedPath = $this->getNestedPath($field, $query);
+                    if ($nestedPath) {
+                        $nestedGroups[$nestedPath][] = $field;
+                    } else {
+                        $plainFields[] = $field;
+                    }
+                }
+
+                foreach ($plainFields as $field) {
                     $aggs = [...$aggs, ...$this->compileNestedTermAggregations([$field], $query)];
                 }
 
+                foreach ($nestedGroups as $nestedPath => $groupFields) {
+                    $innerAggs = [];
+                    foreach ($groupFields as $field) {
+                        $innerAggs = [...$innerAggs, ...$this->compileNestedTermAggregations([$field], $query)];
+                    }
+                    $aggs = [...$aggs, ...$this->wrapInNestedAgg($innerAggs, $nestedPath, $query)];
+                }
+
                 $dsl->setBody(['aggs'], $aggs);
                 $dsl->setBody(['size'], $query->getSetLimit() ?? 0);
                 $dsl->unsetBody(['sort']);

src/Query/Processor/Concerns/ProcessesBucketAggregations.php

@@ -21,8 +21,13 @@ protected function parseBucket($bucketAggregation, $rawAggs)
         $key = $bucketAggregation['key'];
         $type = $bucketAggregation['type'] ?? null;
 
+        // Unwrap nested/filter agg wrappers if the bucket key isn't at the top level
+        if (! isset($rawAggs[$key])) {
+            $rawAggs = $this->unwrapNestedAggregation($rawAggs, $key);
+        }
+
         if (! isset($rawAggs[$key]['buckets'])) {
-            return $rawAggs[$key];
+            return $rawAggs[$key] ?? [];
         }
         $result = collect($rawAggs[$key]['buckets'])->map(function ($bucket) use ($key, $type) {
             $metricAggs = $this->appendMetricsToBucket($bucket);

src/Query/Processor/Concerns/ProcessesDistinctAggregations.php

@@ -15,7 +15,14 @@ public function processDistinctAggregations($index, $result, $columns, $withCoun
         foreach ($columns as $column) {
             $keys[] = 'by_'.$column;
         }
-        $aggregations = $this->parseDistinctBucket($columns, $keys, $result['aggregations'], 0, $withCount);
+
+        // Unwrap nested/filter agg wrappers if the expected key isn't at the top level
+        $aggs = $result['aggregations'];
+        if (! empty($keys[0]) && ! isset($aggs[$keys[0]])) {
+            $aggs = $this->unwrapNestedAggregation($aggs, $keys[0]);
+        }
+
+        $aggregations = $this->parseDistinctBucket($columns, $keys, $aggs, 0, $withCount);
         $aggregations = collect($aggregations);
 
         return $aggregations->map(function ($aggregation) use ($index) {
@@ -29,9 +36,16 @@ public function processBulkDistinctAggregations($index, $result, $columns, $with
         $aggregations = [];
         foreach ($columns as $column) {
             $keys = ['by_'.$column];
+
+            // Each column's agg may be inside its own nested wrapper
+            $aggs = $result['aggregations'];
+            if (! isset($aggs[$keys[0]])) {
+                $aggs = $this->unwrapNestedAggregation($aggs, $keys[0]);
+            }
+
             $aggregations = [
                 ...$aggregations,
-                ...$this->parseDistinctBucket([$column], $keys, $result['aggregations'], 0, $withCount),
+                ...$this->parseDistinctBucket([$column], $keys, $aggs, 0, $withCount),
             ];
         }
         $aggregations = collect($aggregations);

src/Query/Processor/Processor.php

@@ -66,8 +66,11 @@ public function processAggregations(Builder $query, $result)
         $this->query = $query;
         $response = $this->getRawResponse();
         $this->rawAggregations = $response['aggregations'] ?? [];
-        if (! empty($response['aggregations']['group_by']['after_key'])) {
-            $this->query->getMetaTransfer()->set('after_key', $response['aggregations']['group_by']['after_key']);
+
+        // Extract after_key — may be inside a nested agg wrapper
+        $groupByAggs = $this->unwrapNestedAggregation($this->rawAggregations, 'group_by');
+        if (! empty($groupByAggs['group_by']['after_key'])) {
+            $this->query->getMetaTransfer()->set('after_key', $groupByAggs['group_by']['after_key']);
         }
 
         if (! empty($this->query->bucketAggregations)) {
@@ -319,4 +322,36 @@ public function processRaw($query, $response)
 
         return $documents->all();
     }
+
+    /**
+     * Drill into nested/filter agg wrappers to find the expected aggregation key.
+     * Returns the aggregation array containing $expectedKey at the top level.
+     * Handles: nested_* → filtered → expected_key (up to 3 levels deep).
+     */
+    protected function unwrapNestedAggregation(array $aggregations, string $expectedKey, int $depth = 0): array
+    {
+        if (isset($aggregations[$expectedKey]) || $depth > 3) {
+            return $aggregations;
+        }
+
+        foreach ($aggregations as $key => $value) {
+            if (! is_array($value)) {
+                continue;
+            }
+
+            if (isset($value[$expectedKey])) {
+                return $value;
+            }
+
+            // Drill into nested/filter wrappers (they always have doc_count)
+            if (isset($value['doc_count'])) {
+                $inner = $this->unwrapNestedAggregation($value, $expectedKey, $depth + 1);
+                if (isset($inner[$expectedKey])) {
+                    return $inner;
+                }
+            }
+        }
+
+        return $aggregations;
+    }
 }