Index Blueprint
This guide walks you through defining Elasticsearch index schemas using Laravel, including field types, parameters, and advanced settings.
Eloquent Column Types
Section titled “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
Section titled “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
Section titled “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()
Section titled “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()
Section titled “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()
Section titled “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()
Section titled “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()
Section titled “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
Section titled “Other Index Modifications”Enhance your Elasticsearch indices with additional settings and functionalities:
withSetting()
Section titled “withSetting()”Adjust core index settings such as the number of shards.
Schema::create('contacts', function (Blueprint $index) { $index->withSetting('number_of_shards', 3);});
withMapping()
Section titled “withMapping()”Adjust core index settings such as the number of shards.
Schema::create('contacts', function (Blueprint $index) { $index->withMapping('dynamic', false);});
meta()
Section titled “meta()”Attach metadata to the index for enhanced identification and management.
Schema::create('contacts', function (Blueprint $index) { $index->meta(['class' => 'MyApp2::User3']);});
alias()
Section titled “alias()”Create an alias for the index to facilitate easier access and management.
Schema::create('contacts', function (Blueprint $index) { $index->alias('bar_foo');});
routingRequired()
Section titled “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()
Section titled “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()
Section titled “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()
Section titled “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()
Section titled “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()
Section titled “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']);});