Index Blueprint
This guide walks you through defining OpenSearch index schemas using Laravel, including field types, parameters, and advanced settings.
Eloquent Column Types
Section titled “Eloquent Column Types”opensearch integration in Laravel maps Eloquent column types to OpenSearch fields, allowing for seamless schema definitions with custom parameters for specific OpenSearch 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 OpenSearch handles the field’s relevance scoring.
Note that certain Eloquent types are not supported due to the nature of OpenSearch:
- Increment types (
bigIncrements
,increments
, etc.) - OpenSearch does not support auto-incrementing fields. - Set types (
set
)—No direct equivalent in OpenSearch. - JSON types (
json
,jsonb
)—Redundant as OpenSearch inherently supports JSON.
OpenSearch Column Types
Section titled “OpenSearch Column Types”OpenSearch-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 opensearch 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']);});