Elasticsearch Dsl Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require ongr/elasticsearch-dsl elasticsearch/elasticsearch
   

   • The package requires elasticsearch/elasticsearch as a dependency.

2. Basic Setup:

   use ONGR\ElasticsearchDSL\Search;
   use ONGR\ElasticsearchDSL\Query\MatchAllQuery;
   use Elasticsearch\ClientBuilder;
   
   $client = ClientBuilder::create()->build();
   $search = new Search();
   $search->addQuery(new MatchAllQuery());
   
   $params = [
       'index' => 'your_index_name',
       'body'  => $search->toArray(),
   ];
   
   $response = $client->search($params);
   

3. First Use Case:

   • Search all documents:

     $search = new Search();
     $search->addQuery(new MatchAllQuery());
     

   • Search with a term query:

     $search = new Search();
     $search->addQuery(new TermQuery('title', 'Laravel'));
     

Where to Look First

• Documentation: Start with the official docs for query and aggregation examples.
• Query Builders: Explore the ONGR\ElasticsearchDSL\Query namespace for query types (e.g., TermQuery, BoolQuery, FunctionScoreQuery).
• Aggregations: Check the ONGR\ElasticsearchDSL\Aggregation namespace for aggregations like StatsAggregation, NestedAggregation, etc.

Implementation Patterns

Common Workflows

1. Building Queries:

   • Basic Queries:

     $search = new Search();
     $search->addQuery(new TermQuery('field_name', 'value'));
     

   • Compound Queries:

     $boolQuery = new BoolQuery();
     $boolQuery->addMust(new TermQuery('field1', 'value1'));
     $boolQuery->addShould(new TermQuery('field2', 'value2'));
     $search->addQuery($boolQuery);
     

   • Function Score Queries:

     $functionScoreQuery = new FunctionScoreQuery(new MatchAllQuery());
     $functionScoreQuery->addWeightFunction(2.0, new TermQuery('popular', true));
     $search->addQuery($functionScoreQuery);
     

2. Aggregations:

   • Simple Aggregation:

     $search = new Search();
     $search->addAggregation(new StatsAggregation('stats_agg', 'numeric_field'));
     

   • Nested Aggregations:

     $nestedAgg = new NestedAggregation('nested_agg', 'nested_field');
     $nestedAgg->addAggregation(new AvgAggregation('avg_agg', 'nested_field.value'));
     $search->addAggregation($nestedAgg);
     

3. Pagination and Sorting:

   $search = new Search();
   $search->setFrom(0)->setSize(10);
   $search->addSort(Sort::create()->field('created_at')->order(Sort::ORDER_DESC));
   

Integration Tips

1. Laravel Integration:

   • Use the package alongside ongr/elasticsearch-bundle for seamless integration with Laravel’s service container and configuration.
   • Example service provider setup:

     $this->app->bind('elasticsearch.dsl', function () {
         return new Search();
     });
     

2. Custom Parameters:

   $search = new Search();
   $search->setParameter('track_total_hits', true);
   $search->setParameter('typed_keys', false);
   

3. Reusing Queries:

   • Create reusable query builders in a service class:

     class ElasticsearchQueryBuilder
     {
         public function buildPopularProductsQuery()
         {
             $functionScoreQuery = new FunctionScoreQuery(new MatchAllQuery());
             $functionScoreQuery->addWeightFunction(2.0, new TermQuery('is_popular', true));
             return $functionScoreQuery;
         }
     }
     

4. Handling Aggregation Results:

   • Process aggregation results in Laravel:

     $response = $client->search($params);
     $aggregations = $response['aggregations'];
     $stats = $aggregations['stats_agg']['avg'];
     

Gotchas and Tips

Pitfalls

1. Version Compatibility:

   • Ensure your Elasticsearch server version matches the supported version of ongr/elasticsearch-dsl (e.g., Elasticsearch 7.x requires DSL 7.x).
   • Check the version matrix in the README.

2. Nested Objects:

   • Nested aggregations require the path parameter to correctly reference nested fields. Forgetting this will result in errors:

     $nestedAgg = new NestedAggregation('nested_agg', 'nested_field'); // Correct
     // vs
     $nestedAgg = new NestedAggregation('nested_agg'); // Incorrect (missing path)
     

3. Boolean Query Logic:

   • The BoolQuery in this DSL automatically wraps added queries in a bool query. If you need explicit control, use BoolQuery directly:

     $boolQuery = new BoolQuery();
     $boolQuery->addMust(new TermQuery('field', 'value')); // Explicit bool query
     

4. Aggregation Field References:

   • Ensure field names in aggregations match the Elasticsearch mapping. Typos or incorrect paths will return empty or incorrect results.

5. Performance:

   • Avoid overly complex queries or aggregations in production without testing. Use explain: true in queries to debug scoring issues:

     $search->setParameter('explain', true);
     

Debugging Tips

1. Inspect Raw Query:

   • Use toArray() to debug the generated query before sending it to Elasticsearch:

     $queryArray = $search->toArray();
     dd($queryArray); // Debug the query structure
     

2. Error Handling:

   • Wrap Elasticsearch calls in try-catch blocks to handle exceptions gracefully:

     try {
         $response = $client->search($params);
     } catch (\Exception $e) {
         Log::error('Elasticsearch error: ' . $e->getMessage());
         throw $e;
     }
     

3. Logging:

   • Enable logging for the Elasticsearch client to debug connection issues:

     $client = ClientBuilder::create()
         ->setLogger(new \Psr\Log\NullLogger()) // Replace with your logger
         ->build();
     

Extension Points

1. Custom Query Classes:

   • Extend existing query classes to add domain-specific logic:

     class CustomRangeQuery extends RangeQuery
     {
         public function setCustomRange($min, $max)
         {
             $this->addParameter('gte', $min);
             $this->addParameter('lte', $max);
         }
     }
     

2. Query Builders:

   • Create fluent interfaces for complex queries:

     class ProductQueryBuilder
     {
         public static function create()
         {
             return new static();
         }
     
         public function inStock()
         {
             $this->query->addMust(new TermQuery('stock', true));
             return $this;
         }
     
         public function priceRange($min, $max)
         {
             $rangeQuery = new RangeQuery('price');
             $rangeQuery->addParameter('gte', $min);
             $rangeQuery->addParameter('lte', $max);
             $this->query->addMust($rangeQuery);
             return $this;
         }
     
         public function build()
         {
             return $this->query;
         }
     }
     

3. Aggregation Pipelines:

   • Use aggregation pipelines for advanced analytics:

     $bucketScript = new BucketScriptAggregation('avg_price_per_category', 'avg_price');
     $bucketScript->setScript('params.category_avg / params.category_count');
     $bucketScript->addMetric(new AvgAggregation('avg_price', 'price'));
     $bucketScript->addMetric(new CardinalityAggregation('category_count', 'category'));
     $search->addAggregation($bucketScript);
     

4. Dynamic Field Mapping:

   • Dynamically adjust field names or paths based on runtime conditions:

     $field = $dynamicField ? 'dynamic_field' : 'static_field';
     $search->addAggregation(new StatsAggregation('stats', $field));
     

Configuration Quirks

1. Elasticsearch Client Configuration:

   • Configure the Elasticsearch client with host, port, and authentication:

     $client = ClientBuilder::create()
         ->setHosts(['http://localhost:9200'])
         ->setBasicAuthentication('username', 'password')
         ->build();
     

2. Search Parameters:

   • Set global search parameters like track_total_hits or typed_keys:

     $