What's New in V4

ElasticLens v4 brings a cleaner search API, conditional indexing, and soft delete support.

viaIndex Scope Flag

The biggest change in v4: viaIndex() now returns Base Models by default.

Previously, viaIndex()->get() returned Index Models and you had to call getBase() or paginateBase() to get base models. In v4, get() and paginate() return base models automatically when called through viaIndex():

// v3 - had to use getBase()
User::viaIndex()->searchTerm('david')->getBase();

// v4 - get() returns base models through viaIndex()
User::viaIndex()->searchTerm('david')->get();

For explicit control, new methods are available:

• getIndex() / paginateIndex() - Always return Index Models
• getBase() / paginateBase() - Always return Base Models (still available, now just aliases)

Conditional Indexing

New excludeIndex() method on your Base Model lets you skip specific records during indexing:

class User extends Model
{
    use Indexable;

    public function excludeIndex(): bool
    {
        return $this->status === 'banned';
    }
}

Excluded records are tracked as skipped in build state and health checks. See Conditional Indexing for details.

Soft Delete Support

ElasticLens now handles soft deletes intelligently:

• Global config: index_soft_deletes in config/elasticlens.php
• Per-model override: $indexSoftDeletes property on your Index Model
• Restore detection: Automatically re-indexes when a model is restored

config/elasticlens.php

'index_soft_deletes' => true, // Keep index records when soft deleting

// Or per-model
class IndexedUser extends IndexModel
{
    protected ?bool $indexSoftDeletes = true;
}

See Soft Delete Support for the full configuration guide.

LensBuilder

Under the hood, ElasticLens now uses a dedicated LensBuilder that extends the Elasticsearch Builder. This powers the viaIndex scope flag and provides a cleaner architecture for the search API. The IndexModel::query() method now returns a LensBuilder instance.