Index Blueprint

This guide walks you through defining Elasticsearch index schemas using Laravel, including field types, parameters, and advanced settings.

Eloquent Column Types

Elasticsearch integration in Laravel maps Eloquent column types to Elasticsearch fields, allowing for seamless schema definitions with custom parameters for specific Elasticsearch functionalities.

Schema::create('new_index', function (Blueprint $index) {
    $index->longText('description', parameters: ['similarity' => 'boolean']);
});

This example sets the scoring algorithm of a text field to boolean, customizing how Elasticsearch handles the field’s relevance scoring.

Note that certain Eloquent types are not supported due to the nature of Elasticsearch:

Increment types (bigIncrements, increments, etc.)—Elasticsearch does not support auto-incrementing fields.
Set types (set)—No direct equivalent in Elasticsearch.
JSON types (json, jsonb)—Redundant as Elasticsearch inherently supports JSON.

Elasticsearch Column Types

Elasticsearch-specific field types are also available to cater to specialized data structures and queries:

//Basic types
$index->text('first_name')->copyTo('full_name');
$index->text('last_name')->copyTo('full_name');
$index->text('full_name');
$index->text('text', hasKeyword: true); // Adds a text field with a keyword subfield for exact matching.
$index->keyword('my_keyword_field'); // For exact text matches.
$index->boolean('is_active');

// Facilitates nested object queries
$index->nested('my_nested_field');
// Define nested object fields with their own properties
$index->nested('comments')->properties(function (Blueprint $nested) {
    $nested->keyword('name');
    $nested->text('comment');
    $nested->keyword('country');
    $nested->integer('likes');
    $nested->date('created_at');
});
//flattened array
$index->flattened('purchase_history');

// Define parent-child relationships
$index->join('question', 'answer'); // 'question' is the parent, 'answer' is the child

//Alias Example
$index->text('notes');
$index->aliasField('comments', 'notes'); // 'comments' is an alias for 'notes'

//Date
$index->date('first_contact', 'epoch_second');
$index->dateRange('date_range');

//Geo
$index->geoPoint('geo_point'); // Stores and queries geographical locations.
$index->geoShape('geo_shape'); // For complex geographical shapes.

//Ips
$index->ip('ip'); // Dedicated for IP addresses.
$index->ipRange('ip_range');

//Numbers
$index->integer('some_int');
$index->integerRange('integer_range');
$index->float('some_float');
$index->floatRange('float_range');
$index->double('some_double');
$index->doubleRange('double_range');
$index->long('long');
$index->longRange('long_range');
$index->short('some_short');
$index->byte('some_byte');
$index->halfFloat('some_half_float');
$index->scaledFloat('some_scaled_float',140);
$index->unsignedLong('some_unsigned_long');
$index->range('integer_range', 'integer_range_2');

// Specialized for percolate queries.
// Used for percolate queries (match stored queries against new docs)
$index->percolator('percolator');

//Custom types
$index->property('text', 'custom_property');

//Multiple types => Order matters ::
//Top level `email` will be a searchable text field
//Sub Property will be a keyword type which can be sorted using orderBy('email.keyword')
$index->text('email');
$index->keyword('email');

Column Parameters

Modify field behaviors with parameters to enhance indexing and querying capabilities:

Schema::create('contacts', function (IndexBlueprint $index) {
    $index->text('first_name', parameters: ['copy_to' => 'full_name']);
    $index->text('full_name');
});

addColumn() / property()

If the built-in helpers for mapping fields do not meet your needs, you can use the $table->addColumn($type, $field, array $parameters = []) (this method is also aliased with property()) method to define custom mappings.

Schema::create('contacts', function (Blueprint $index) {
    $table->addColumn('date', 'last_seen', [
        'format' => 'epoch_second||yyyy-MM-dd HH:mm:ss||yyyy-MM-dd',
        'ignore_malformed' => true,
    ]);
});

addColumn() is aliased as property().

properties()

Define nested properties within an index to facilitate complex queries and data structures.

Schema::create('contacts', function (Blueprint $index) {
    $index->nested('comments')->properties(function (Blueprint $nested) {
        $nested->keyword('name');
        $nested->text('comment');
        $nested->keyword('country');
        $nested->integer('likes');
        $nested->date('created_at');
    });
});

boost()

Boost specific fields at query time to influence relevance scores more significantly.

Schema::create('contacts', function (Blueprint $index) {
    $index->text('test')->boost(2);
});

nullValue()

Allows indexing of explicit null values by replacing them with a specified non-null value.

Schema::create('contacts', function (Blueprint $index) {
    $index->keyword('token')->nullValue('NULL');
});

format()

Customize the format of date fields using standard date formatting syntax.

Schema::create('contacts', function (Blueprint $index) {
    $index->date('date')->format('yyyy');
});

Other Index Modifications

Enhance your Elasticsearch indices with additional settings and functionalities:

withSetting()

Adjust core index settings such as the number of shards.

Schema::create('contacts', function (Blueprint $index) {
    $index->withSetting('number_of_shards', 3);
});

withMapping()

Adjust core index settings such as the number of shards.

Schema::create('contacts', function (Blueprint $index) {
    $index->withMapping('dynamic', false);
});

meta()

Attach metadata to the index for enhanced identification and management.

Schema::create('contacts', function (Blueprint $index) {
    $index->meta(['class' => 'MyApp2::User3']);
});

alias()

Create an alias for the index to facilitate easier access and management.

Schema::create('contacts', function (Blueprint $index) {
    $index->alias('bar_foo');
});

routingRequired()

Make routing a mandatory requirement for the index to ensure efficient data placement and retrieval.

Schema::create('contacts', function (Blueprint $index) {
    $index->routingRequired('bar_foo');
});

addAnalyzer()

Configures or revises analyzers specific to an index, crucial for managing text tokenization and analysis.

Schema::create('contacts', function (Blueprint $index) {
    $index->addAnalyzer('my_custom_analyzer')
        ->type('custom')
        ->tokenizer('punctuation')
        ->filter(['lowercase', 'english_stop'])
        ->charFilter(['emoticons']);
});

addTokenizer()

Configures or revises tokenizers specific to an index, essential for text tokenization.

Schema::create('contacts', function (Blueprint $index) {
    $index->addTokenizer('punctuation')
        ->type('pattern')
        ->pattern('[ .,!?]');
});

addCharFilter()

Configures or revises character filters specific to an index, crucial for text normalization and analysis.

Schema::create('contacts', function (Blueprint $index) {
    $index->addCharFilter('emoticons')
        ->type('mapping')
        ->mappings([":) => _happy_", ":( => _sad_"]);
});

addFilter()

Configures or revises filters specific to an index, essential for text normalization and analysis.

Schema::create('contacts', function (Blueprint $index) {
    $index->addFilter('english_stop')
        ->type('stop')
        ->stopwords('_english_');
});

addNormalizer()

Configures or revises normalizers specific to an index, crucial for text normalization and analysis.

Schema::create('contacts', function (Blueprint $index) {
    $index->addNormalizer('my_normalizer')
        ->type('custom')
        ->charFilter([])
        ->filter(['lowercase', 'asciifolding']);
});