scout:sync-index-settings

Sync your configured index settings with your search engine (Meilisearch).

Synopsis

php artisan scout:sync-index-settings

Description

This command synchronizes the index configuration defined in your Laravel Scout models with Meilisearch. It updates:

Searchable attributes
Filterable attributes
Sortable attributes
Ranking rules
Stop words
Synonyms
Typo tolerance settings

Use this command after modifying search configuration in your models to apply the changes to Meilisearch.

Usage Examples

Basic Usage

Sync all index settings:

php artisan scout:sync-index-settings

Output:

Syncing index settings for [games]...
Syncing index settings for [dialogue]...
Syncing index settings for [reviews]...
Syncing index settings for [tags]...
All indexes synced!

DDEV Environment

Run in DDEV:

ddev artisan scout:sync-index-settings

When to Use

Required Scenarios

Use scout:sync-index-settings when you:

Modify Searchable Fields: Change which fields are searchable
Update Filterable Fields: Add or remove filterable attributes
Change Sortable Fields: Modify which fields can be sorted
Adjust Ranking Rules: Update search result ranking
Configure Stop Words: Add or remove stop words
Update Synonyms: Modify synonym lists
Change Typo Tolerance: Adjust typo tolerance settings

After Model Changes

After modifying the toSearchableArray() method or Scout configuration in models:

// Before
public function toSearchableArray()
{
    return [
        'id' => $this->id,
        'title' => $this->title,
    ];
}

// After - added description
public function toSearchableArray()
{
    return [
        'id' => $this->id,
        'title' => $this->title,
        'description' => $this->description, // New field
    ];
}

// Run sync to apply changes
// php artisan scout:sync-index-settings

Configuration

Model Configuration

Index settings are defined in Scout models using the searchableAs() and configuration methods:

use Laravel\Scout\Searchable;

class Game extends Model
{
    use Searchable;

    /**
     * Get the indexable data array for the model.
     */
    public function toSearchableArray(): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'description' => $this->description,
            'author' => $this->author,
            'tags' => $this->tags->pluck('name'),
            'languages' => $this->languages->pluck('code'),
            'rating' => $this->rating,
            'release_date' => $this->release_date,
        ];
    }

    /**
     * Get the name of the index associated with the model.
     */
    public function searchableAs(): string
    {
        return 'games';
    }
}

Meilisearch Settings

Configure Meilisearch-specific settings in config/scout.php:

'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
    'key' => env('MEILISEARCH_KEY'),
    'index-settings' => [
        'games' => [
            'filterableAttributes' => ['tags', 'languages', 'platforms', 'rating'],
            'sortableAttributes' => ['rating', 'release_date', 'created_at'],
            'rankingRules' => [
                'words',
                'typo',
                'proximity',
                'attribute',
                'sort',
                'exactness',
            ],
        ],
    ],
],

What It Syncs

Searchable Attributes

Fields that can be searched:

// Defined in toSearchableArray()
'title' => $this->title,
'description' => $this->description,
'author' => $this->author,

Filterable Attributes

Fields that can be used in filters:

'filterableAttributes' => [
    'tags',
    'languages',
    'platforms',
    'content_flags',
    'rating',
    'release_date',
],

Sortable Attributes

Fields that can be used for sorting:

'sortableAttributes' => [
    'rating',
    'release_date',
    'created_at',
    'updated_at',
],

Ranking Rules

Order of ranking criteria:

'rankingRules' => [
    'words',      // Number of matched words
    'typo',       // Typo tolerance
    'proximity',  // Word proximity
    'attribute',  // Attribute ranking
    'sort',       // Custom sort
    'exactness',  // Exact matches
],

Performance Impact

Sync Time

Small indexes (< 1,000 docs): < 1 second
Medium indexes (1,000-100,000 docs): 1-5 seconds
Large indexes (> 100,000 docs): 5-30 seconds

No Reindexing

This command only updates settings, not data. It does not trigger reindexing.

Zero Downtime

Settings are updated without downtime. Search continues to work during sync.

Verification

Check Settings Applied

Verify settings in Meilisearch:

# Check games index settings
curl http://localhost:7700/indexes/games/settings

Test Filters

Verify filterable attributes work:

php artisan tinker
>>> App\Models\Game::search('visual novel')
       ->where('rating', '>', 4.0)
       ->get()

Test Sorting

Verify sortable attributes work:

php artisan tinker
>>> App\Models\Game::search('visual novel')
       ->orderBy('rating', 'desc')
       ->get()

Troubleshooting

Settings Not Applied

Problem: Settings don't seem to apply

Solutions:

Check Meilisearch is running
Verify configuration in config/scout.php
Clear config cache: php artisan config:clear
Check Meilisearch logs for errors
Manually verify settings via API

Filter Not Working

Problem: Cannot filter by a field

Solutions:

Ensure field is in filterableAttributes
Run scout:sync-index-settings
Verify field exists in toSearchableArray()
Check field data type matches filter

Sort Not Working

Problem: Cannot sort by a field

Solutions:

Ensure field is in sortableAttributes
Run scout:sync-index-settings
Verify field exists in toSearchableArray()
Check field contains sortable data

Connection Error

Problem: Cannot connect to Meilisearch

Solutions:

Check Meilisearch is running: ddev describe
Verify MEILISEARCH_HOST in .env
Check network connectivity
Restart Meilisearch: ddev restart

Best Practices

After Config Changes: Always run after modifying search configuration
Version Control: Track configuration changes in git
Test Thoroughly: Verify filters and sorting work after sync
Document Changes: Note what settings were changed and why
Staging First: Test on staging before production

Common Scenarios

Adding a New Filterable Field

Add field to model's toSearchableArray()
Add field to filterableAttributes in config
Run scout:sync-index-settings
Test filtering works

Changing Ranking Rules

Modify rankingRules in config
Run scout:sync-index-settings
Test search result ordering

Adding Synonyms

Add synonyms to config
Run scout:sync-index-settings
Test synonym search works

meilisearch:setup - Initial Meilisearch setup
meilisearch:reindex - Reindex content

FVN.li Documentation Help

scout:sync-index-settings

Synopsis

Description

Usage Examples

Basic Usage

DDEV Environment

When to Use

Required Scenarios

After Model Changes

Configuration

Model Configuration

Meilisearch Settings

What It Syncs

Searchable Attributes

Filterable Attributes

Sortable Attributes

Ranking Rules

Performance Impact

Sync Time

No Reindexing

Zero Downtime

Verification

Check Settings Applied

Test Filters

Test Sorting

Troubleshooting

Settings Not Applied

Filter Not Working

Sort Not Working

Connection Error

Best Practices

Common Scenarios

Adding a New Filterable Field

Changing Ranking Rules

Adding Synonyms

See Also

scout:sync-index-settings

Synopsis

Description

Usage Examples

Basic Usage

DDEV Environment

When to Use

Required Scenarios

After Model Changes

Configuration

Model Configuration

Meilisearch Settings

What It Syncs

Searchable Attributes

Filterable Attributes

Sortable Attributes

Ranking Rules

Performance Impact

Sync Time

No Reindexing

Zero Downtime

Verification

Check Settings Applied

Test Filters

Test Sorting

Troubleshooting

Settings Not Applied

Filter Not Working

Sort Not Working

Connection Error

Best Practices

Common Scenarios

Adding a New Filterable Field

Changing Ranking Rules

Adding Synonyms

Related Commands

See Also