Index Blueprint

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

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

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

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 opensearch 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']);
});