wip

Author: Chris Cho

docs/eloquent-models/schema-builder.txt

@@ -30,7 +30,6 @@ available in {+odm-short+} and show examples of how to use them:
 - :ref:`<laravel-eloquent-migrations>`
 - :ref:`<laravel-eloquent-indexes>`
 - :ref:`<laravel-eloquent-collections>`
-- :ref:`<laravel-eloquent-customize-collection>`
 
 .. _laravel-eloquent-migrations:
 
@@ -50,7 +49,7 @@ You can create migration classes manually or generate them by using the
 following changes to perform the schema changes on your MongoDB database:
 
 - Replace the ``Illuminate\Database\Schema\Blueprint`` import with
-  ``MongoDB\Laravel\Schema\Blueprint``
+  ``MongoDB\Laravel\Schema\Blueprint`` if it is referenced in your migration
 - Specify ``mongodb`` in the ``$connection`` field
 - Use only commands and syntax supported by {+odm-short+}
 
@@ -60,10 +59,12 @@ following changes to perform the schema changes on your MongoDB database:
    file so that PHP artisan performs the migration on the correct database.
 
 The following example migration class file that creates a collection and
-index when you run the migration and drops it when you roll back the migration:
+index when you run the migration and drops it when you reverse, or roll back
+the migration:
 
 .. literalinclude:: /includes/schema-builder/astronauts_migration.php
    :language: php
+   :emphasize-lines: 4, 10
 
 Run or Roll Back a Migration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -97,33 +98,259 @@ in the Laravel documentation.
 Manage Indexes
 --------------
 
-TODO
+MongoDB indexes are data structures that improve query efficiency by reducing
+the number of documents needed to retrieve results of a query. Indexes such as
+geospatial indexes extend the ways in which you can query the data.
+
+ To improve query performance by using an index, make sure the query is
+covered by the index. To learn more about indexes and query optimization, see
+the following MongoDB server manual pages:
+
+- :manual:`Indexes </indexes>`
+- :manual:`Query Optimization </core/query-optimization/>`
+
+The following sections show how you can use the schema builder to create and
+drop various types of indexes on a collection.
+
+Create an Index
+~~~~~~~~~~~~~~~
+
+To create indexes, call the ``create()`` method on the ``Schema`` facade
+in your migration file. Pass ``create()`` the collection name and a callback
+method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. 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 :guilabel:`VIEW OUTPUT` button to see the indexes created by running
+the migration, including the default index on the ``_id`` field:
+
+
+.. io-code-block::
+
+   .. input:: /includes/schema-builder/flights_migration.php
+      :language: php
+      :dedent:
+      :start-after: begin create index
+      :end-before: end create index
+
+  .. output::
+     :language: json
+     :visible: false
+
+     [
+       { 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 :guilabel:`VIEW OUTPUT` button to see the indexes
+created by running the migration, including the default index on the ``_id``
+field:
+
+.. io-code-block::
+
+   .. input:: /includes/schema-builder/passengers_migration.php
+      :language: php
+      :dedent:
+      :start-after: begin create index
+      :end-before: end create index
+
+   .. output:
+      :language: json
+      :visible: false
+
+      [
+        { 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 :manual:`Options for All Index Types </reference/method/db.collection.createIndex/#options-for-all-index-types>`
+in the MongoDB server manual.
+
+Create Sparse, TTL, and Unique Indexes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use {+odm-short+} 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, call the ``create()`` method on the ``Schema`` facade
+in your migration file. Pass ``create()`` the collection name and a callback
+method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Call the
+appropriate helper method on the ``Blueprint`` instance and pass the
+index creation details.
+
+The following migration code shows how to create a sparse index and TTL index
+by using the index helpers. Click the :guilabel:`VIEW OUTPUT` button to see
+the indexes created by running the migration, including the default index on
+the ``_id`` field:
+
+.. io-code-block::
+
+   .. input:: /includes/schema-builder/planets_migration.php
+      :language: php
+      :dedent:
+      :start-after: begin index helpers
+      :end-before: end index helpers
+
+   .. output::
+      :language: json
+      :visible: false
+
+      [
+        { 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 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 :guilabel:`VIEW OUTPUT` button to see the indexes
+created by running the migration, including the default index on the ``_id``
+field:
+
+.. io-code-block::
+
+   .. input:: /includes/schema-builder/planets_migration.php
+      :language: php
+      :dedent:
+      :start-after: begin multi index helpers
+      :end-before: end multi index helpers
+
+   .. output::
+      :language: json
+      :visible: false
+
+      [
+        { 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 :manual:`Index Properties </core/indexes/index-properties/>`
+in the MongoDB 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, call the ``create()`` method on the ``Schema`` facade
+in your migration file. Pass ``create()`` the collection name and a callback
+method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. 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:
+
+.. literalinclude:: /includes/schema-builder/spaceports_migration.php
+   :language: php
+   :start-after: begin create geospatial index
+   :end-before: end create geospatial index
+
+To learn more about geospatial indexes, see
+:manual:`Geospatial Indexes </core/indexes/index-types/index-geospatial/>` in
+the MongoDB Server manual.
+
+Drop an Index
+~~~~~~~~~~~~~
+
+You can drop indexes from a collection when you no longer need them.
+
+When you no longer use an index, you can drop them
+
+When you drop a collection, MongoDB automatically drops all the indexes
+associated with it.
+
+To drop an index, call the ``table()`` method on the ``Schema`` facade in your
+migration file.
+
+you must reference it by name.
+
+The following example migration drops an index called ``unique_mission_id_idx``
+from the ``flights`` collection:
+
+.. literalinclude:: /includes/schema-builder/flights_migration.php
+   :language: php
+   :start-after: begin drop index
+   :end-before: end drop index
 
 .. _laravel-eloquent-collections:
 
 Manage Collections
 ------------------
 
+Check if a collection exists: Schema::hasCollection(<collection name>)
+
 TODO
 
 Note that creating a collection is a noop unless it also creates an index
 since MongoDB automatically creates collections when you first write to them.
 
-.. _laravel-eloquent-customize-collection:
-
-Customize Collection Creation
------------------------------
-
-TODO
-
 Notes:
 
-- create and drop (is this different from index and dropIndex?)
-  Schema::create(<collection name>, function ($collection) {
-  $collection->index(<>);
-  $collection->unique(<>);
-  Geospatial index
-
 - collection (what does this method do?)
   Schema::hasCollection(<collection name>); check whether a collection exists
 
@@ -140,19 +367,11 @@ dropIndex($index = null)
 public function dropIndexIfExists($indexOrColumns = null)\
 public function hasIndex($indexOrColumns = null)
 
-public function unique($columns = null, $name = null, $algorithm = null, $options = [])
-
-Creation options
-
-https://www.mongodb.com/docs/manual/reference/method/db.collection.createIndex/#options-for-all-index-types
-
-- background - what is this? Hasn't this been replaced by index behavior in 4.2?
-- sparse https://www.mongodb.com/docs/manual/core/index-sparse/
-- expire is this a ttl index? https://www.mongodb.com/docs/manual/core/index-ttl/
-- geospatial https://www.mongodb.com/docs/manual/core/indexes/index-types/index-geospatial/
-
 .. note::
 
-   Although MongoDB collections can be schemaless, you can provide
-   schemas for data validation. The {+odm-short+} schema builder does not
-   currently offer methods to
+   Although MongoDB collections can be schemaless, they can use JSON schemas
+   for data validation. The {+odm-short+} schema builder does not offer methods
+   for data validation schemas. To learn more about JSON schema validation,
+   see :manual:`Schema Validation </core/schema-validation/>` in the
+   MongoDB server documentation.
+

docs/includes/schema-builder/astronauts_migration.php

@@ -16,7 +16,6 @@ public function up(): void
     {
       Schema::create('astronauts', function ($collection) {
           $collection->index('name');
-          $collection->unique('email');
       });
     }
 

docs/includes/schema-builder/flights_migration.php

@@ -0,0 +1,31 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use MongoDB\Laravel\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+ 
+return new class extends Migration
+{
+
+    protected $connect = 'mongodb';
+
+    public function up(): void
+    {
+      // begin create index
+      Schema::create('flights', function (Blueprint $collection) {
+          $collection->index('mission_type');
+          $collection->index(['launch_location' => 1, 'launch_date' => -1]);
+          $collection->unique('mission_id', null, null, [ 'name' => 'unique_mission_id_idx']);
+      });
+      // end create index
+    }
+    
+    public function down(): void
+    {
+        // begin drop index
+        Schema::table('flights', function (Blueprint $collection) {
+            $collection->dropIndex('unique_mission_id_idx');
+        });
+        // end drop index
+    }
+};

docs/includes/schema-builder/passengers_migration.php

@@ -0,0 +1,26 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use MongoDB\Laravel\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+ 
+return new class extends Migration
+{
+
+    protected $connect = 'mongodb';
+
+    public function up(): void
+    {
+        // begin index options
+        Schema::create('passengers', function(Blueprint $collection) {    
+            $collection->index('last_name', 'passengers_collation_idx', null, [
+                'collation' => [ 'locale' => 'de@collation=phonebook', 'numericOrdering' => true ]]);
+        });
+        // end index options
+    }
+
+    public function down(): void
+    {
+        Schema::drop('passengers');
+    }
+};