Skip to content
Laravel-Elasticsearch

What's New in V5

V5 represents a near-complete rewrite of the Laravel-Elasticsearch package. This update delivers a more seamless integration with Laravel’s Models, Eloquent, and Query Builders while providing greater access to Elasticsearch’s advanced features.

5.1 New features

Section titled “5.1 New features”

Track Total Hits

Section titled “Track Total Hits”

New query method withTrackTotalHits(bool|int|null $val = true) - Docs

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

Create or Fail

Section titled “Create or Fail”

New query model method createOrFail(array $attributes) - Docs

  • 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

Set refresh flag

Section titled “Set refresh flag”
  • New query method withRefresh(bool|string $refresh) - Docs

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):

  1. 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.
  2. 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.
  3. false: Take no refresh-related actions. The changes made by this request will be made visible at some point after the request returns.

5.0 New features

Section titled “5.0 New features”

Laravel generated IDs:

Section titled “Laravel generated IDs:”
  • Ids can be generated on the Laravel side by using the GeneratesUuids or the GeneratesElasticIds trait. Docs

Query field map

Section titled “Query field map”
  • Field Maps can be defined in the model to map text to keyword fields, boosting performance Docs

Fluent query options as a callback

Section titled “Fluent query options as a callback”
  • All clauses in the query builder now accept an optional callback of Elasticsearch options to be applied to the clause. Docs

BelongsToMany Relationships

Section titled “BelongsToMany Relationships”
  • BelongsToMany relationships are now supported. Docs

New queries

Section titled “New queries”

Three powerful new query methods have been added to simplify expressive search:

New aggregations

Section titled “New aggregations”
  • Boxplot Aggregations Docs
  • Stats Aggregations Docs
  • Extended Stats Aggregations - Docs
  • Cardinality Aggregations - Docs
  • Median Absolute Deviation Aggregations - Docs
  • Percentiles Aggregations - Docs
  • String Stats Aggregations - Docs

Migrations: Add Normalizer

Section titled “Migrations: Add Normalizer”
  • Normalizers can now be defined in migrations. Docs

Direct Access to Elasticsearch PHP client

Section titled “Direct Access to Elasticsearch PHP client”

For low-level operations, you can access the native Elasticsearch PHP client directly:

Connection::on('elasticsearch')->elastic()->{clientMethod}();

V5 Under the Hood

Section titled “V5 Under the Hood”

This release is a complete architectural overhaul designed to mirror Laravel’s Eloquent ORM more closely.
The internals have been refactored for better testability, performance, and future extensibility.

Diagram