Schema Builder

Create a Migration Class

You can create migration classes manually or generate them by using the php artisan make:migration command. If you generate them, you must make the following changes to perform the schema changes on your MongoDB database:

• Replace the Illuminate\Database\Schema\Blueprint import with MongoDB\Laravel\Schema\Blueprint if it is referenced in your migration

• Use only commands and syntax supported by the Laravel Integration

The following example migration class contains the following methods:

• up(), which creates a collection and an index when you run the migration

• down(), which drops the collection and all the indexes on it when you roll back the migration

<?php
declare(strict_types=1);
use Illuminate\Database\Migrations\Migration;
use Illuminate\Support\Facades\Schema;
use MongoDB\Laravel\Schema\Blueprint;
return new class extends Migration
{
    protected $connection = 'mongodb';
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('astronauts', function (Blueprint $collection) {
            $collection->index('name');
        });
    }
    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::drop('astronauts');
    }
};

Run or Roll Back a Migration

To run the database migration from a class file, run the following command after replacing the placeholder:

php artisan migrate --path=<path to your migration class file>

This command runs the up() function in the class file to create the collection and index in the database specified in the config/database.php file.

To roll back the migration, run the following command after replacing the placeholder:

php artisan migrate:rollback --path=<path to your migration class file>

This command runs the down() function in the class file to drop the collection and related indexes.

To learn more about Laravel migrations, see Database: Migrations in the Laravel documentation.

Create an Index

To create indexes, perform the following actions:

1. Call the create() method on the Schema facade in your migration file.

2. Pass it the collection name and a callback method with a MongoDB\Laravel\Schema\Blueprint parameter.

3. Specify the index creation details on the Blueprint instance.

The following example migration creates indexes on the following collection fields:

• Single field index on mission_type

• Compound index on launch_location and launch_date, specifying a descending sort order on launch_date

• Unique index on the mission_id field, specifying the index name "unique_mission_id_idx"

Click the VIEW OUTPUT button to see the indexes created by running the migration, including the default index on the _id field:

Schema::create('flights', function (Blueprint $collection) {
    $collection->index('mission_type');
    $collection->index(['launch_location' => 1, 'launch_date' => -1]);
    $collection->unique('mission_id', options: ['name' => 'unique_mission_id_idx']);
});

[
  { v: 2, key: { _id: 1 }, name: '_id_' },
  { v: 2, key: { mission_type: 1 }, name: 'mission_type_1' },
  {
    v: 2,
    key: { launch_location: 1, launch_date: -1 },
    name: 'launch_location_1_launch_date_-1'
  },
  {
    v: 2,
    key: { mission_id: 1 },
    name: 'unique_mission_id_idx',
    unique: true
  }
]

Specify Index Options

MongoDB index options determine how the indexes are used and stored. You can specify index options when calling an index creation method, such as index(), on a Blueprint instance.

The following migration code shows how to add a collation to an index as an index option. Click the VIEW OUTPUT button to see the indexes created by running the migration, including the default index on the _id field:

Schema::create('passengers', function (Blueprint $collection) {
    $collection->index(
        'last_name',
        name: 'passengers_collation_idx',
        options: [
            'collation' => [ 'locale' => 'de@collation=phonebook', 'numericOrdering' => true ],
        ],
    );
});

[
  { v: 2, key: { _id: 1 }, name: '_id_' },
  {
    v: 2,
    key: { last_name: 1 },
    name: 'passengers_collation_idx',
    collation: {
      locale: 'de@collation=phonebook',
      caseLevel: false,
      caseFirst: 'off',
      strength: 3,
      numericOrdering: true,
      alternate: 'non-ignorable',
      maxVariable: 'punct',
      normalization: false,
      backwards: false,
      version: '57.1'
    }
  }
]

To learn more about index options, see Options for All Index Types in the Server manual.

Create Sparse, TTL, and Unique Indexes

You can use Laravel MongoDB helper methods to create the following types of indexes:

• Sparse indexes, which allow index entries only for documents that contain the specified field

• Time-to-live (TTL) indexes, which expire after a set amount of time

• Unique indexes, which prevent inserting documents that contain duplicate values for the indexed field

To create these index types, perform the following actions:

1. Call the create() method on the Schema facade in your migration file.

2. Pass create() the collection name and a callback method with a MongoDB\Laravel\Schema\Blueprint parameter.

3. Call the appropriate helper method for the index type on the Blueprint instance and pass the index creation details.

The following migration code shows how to create a sparse and a TTL index by using the index helpers. Click the VIEW OUTPUT button to see the indexes created by running the migration, including the default index on the _id field:

Schema::create('planets', function (Blueprint $collection) {
    $collection->sparse('rings');
    $collection->expire('last_visible_dt', 86400);
});

[
  { v: 2, key: { _id: 1 }, name: '_id_' },
  { v: 2, key: { rings: 1 }, name: 'rings_1', sparse: true },
  {
    v: 2,
    key: { last_visible_dt: 1 },
    name: 'last_visible_dt_1',
    expireAfterSeconds: 86400
  }
]

You can specify sparse, TTL, and unique indexes on either a single field or compound index by specifying them in the index options.

The following migration code shows how to create all three types of indexes on a single field. Click the VIEW OUTPUT button to see the indexes created by running the migration, including the default index on the _id field:

Schema::create('planet_systems', function (Blueprint $collection) {
    $collection->index('last_visible_dt', options: ['sparse' => true, 'expireAfterSeconds' => 3600, 'unique' => true]);
});

[
  { v: 2, key: { _id: 1 }, name: '_id_' },
  {
    v: 2,
    key: { last_visible_dt: 1 },
    name: 'last_visible_dt_1',
    unique: true,
    sparse: true,
    expireAfterSeconds: 3600
  }
]

To learn more about these indexes, see Index Properties in the Server manual.

Create a Geospatial Index

In MongoDB, geospatial indexes let you query geospatial coordinate data for inclusion, intersection, and proximity.

To create geospatial indexes, perform the following actions:

1. Call the create() method on the Schema facade in your migration file.

2. Pass create() the collection name and a callback method with a MongoDB\Laravel\Schema\Blueprint parameter.

3. Specify the geospatial index creation details on the Blueprint instance.

The following example migration creates a 2d and 2dsphere geospatial index on the spaceports collection. Click the VIEW OUTPUT button to see the indexes created by running the migration, including the default index on the _id field:

Schema::create('spaceports', function (Blueprint $collection) {
    $collection->geospatial('launchpad_location', '2dsphere');
    $collection->geospatial('runway_location', '2d');
});

[
  { v: 2, key: { _id: 1 }, name: '_id_' },
  {
    v: 2,
    key: { launchpad_location: '2dsphere' },
    name: 'launchpad_location_2dsphere',
    '2dsphereIndexVersion': 3
  },
  { v: 2, key: { runway_location: '2d' }, name: 'runway_location_2d' }
]

To learn more about geospatial indexes, see Geospatial Indexes in the Server manual.

Drop an Index

To drop indexes from a collection, perform the following actions:

1. Call the table() method on the Schema facade in your migration file.

2. Pass it the table name and a callback method with a MongoDB\Laravel\Schema\Blueprint parameter.

3. Call the dropIndex() method with the index name on the Blueprint instance.

The following example migration drops an index called unique_mission_id_idx from the flights collection:

Schema::table('flights', function (Blueprint $collection) {
    $collection->dropIndex('unique_mission_id_idx');
});

Manage Atlas Search and Vector Search Indexes

In MongoDB, Atlas Search indexes support your full-text queries. Atlas Vector Search indexes support similarity searches that compare query vectors to vector embeddings in your documents.

View the following guides to learn more about the Atlas Search and Vector Search features:

• Atlas Search guide

• Atlas Vector Search guide

Schema::create('galaxies', function (Blueprint $collection) {
    $collection->searchIndex([
        'mappings' => [
            'dynamic' => true,
        ],
    ], 'dynamic_index');
    $collection->searchIndex([
        'mappings' => [
            'fields' => [
                'name' => [
                    ['type' => 'string', 'analyzer' => 'lucene.english'],
                    ['type' => 'autocomplete', 'analyzer' => 'lucene.english'],
                    ['type' => 'token'],
                ],
            ],
        ],
    ], 'auto_index');
});

{
  "id": "...",
  "name": "dynamic_index",
  "type": "search",
  "status": "READY",
  "queryable": true,
  "latestDefinition": {
    "mappings": { "dynamic": true }
  },
  ...
}
{
  "id": "...",
  "name": "auto_index",
  "type": "search",
  "status": "READY",
  "queryable": true,
  "latestDefinition": {
    "mappings": {
      "fields": { "name": [
        { "type": "string", "analyzer": "lucene.english" },
        { "type": "autocomplete", "analyzer": "lucene.english" },
        { "type": "token" }
      ] }
    }
  },
  ...
}

Schema::create('galaxies', function (Blueprint $collection) {
    $collection->vectorSearchIndex([
        'fields' => [
            [
                'type' => 'vector',
                'numDimensions' => 4,
                'path' => 'embeddings',
                'similarity' => 'cosine',
            ],
        ],
    ], 'vs_index');
});

{
  "id": "...",
  "name": "vs_index",
  "type": "vectorSearch",
  "status": "READY",
  "queryable": true,
  "latestDefinition": {
    "fields": [ {
        "type": "vector",
        "numDimensions": 4,
        "path": "embeddings",
        "similarity": "cosine"
    } ]
  },
  ...
}

Schema::table('galaxies', function (Blueprint $collection) {
    $collection->dropSearchIndex('auto_index');
});