db.createCollection()
定義
db.createCollection(name, options)
新しいコレクションを作成します。ビューについては、「
db.createView()
」を参照してください。MongoDB はコレクションがコマンドで最初に参照されたときに暗黙的にコレクションを作成するため、このメソッドは主に特定のオプションを使用する新しいコレクションを作成するために使用されます。たとえば、
db.createCollection()
を使用して次のものを作成する場合です。ドキュメント検証機能を使用する新しいコレクション。
db.createCollection()
はデータベースコマンドcreate
を囲んでいるラッパーです。
互換性
次の環境でホストされる配置には db.createCollection()
を使用できます。
MongoDB Atlas はクラウドでの MongoDB 配置のためのフルマネージド サービスです
MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン
MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン
構文
db.createCollection()
メソッドには次のプロトタイプ形式があります。
db.createCollection( <name>, { capped: <boolean>, timeseries: { // Added in MongoDB 5.0 timeField: <string>, // required for time series collections metaField: <string>, granularity: <string>, bucketMaxSpanSeconds: <number>, // Added in MongoDB 6.3 bucketRoundingSeconds: <number> // Added in MongoDB 6.3 }, expireAfterSeconds: <number>, clusteredIndex: <document>, // Added in MongoDB 5.3 changeStreamPreAndPostImages: <document>, // Added in MongoDB 6.0 size: <number>, max: <number>, storageEngine: <document>, validator: <document>, validationLevel: <string>, validationAction: <string>, indexOptionDefaults: <document>, viewOn: <string>, pipeline: <pipeline>, collation: <document>, writeConcern: <document> } )
db.createCollection()
メソッドには次のパラメーターがあります。
Parameter | タイプ | 説明 |
---|---|---|
name | string | 作成するコレクションの名前。詳細は、「命名制限」を参照してください。 |
options | ドキュメント | 任意。次の要素を作成するための構成オプションです。
|
options
ドキュメントには、次のフィールドが含まれています。
フィールド | タイプ | 説明 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
capped | ブール値 | |||||||||||
timeseries.timeField | string | 必須(時系列コレクションの作成時)。各時系列ドキュメントの日付を含むフィールドの名前です。時系列コレクション内のドキュメントには、 timeField の値として有効な BSON 日付が必要です。 | ||||||||||
timeseries.metaField | string | オプション。各時系列ドキュメントのメタデータを含むフィールドの名前。指定されたフィールドのメタデータは、ユニークな一連のドキュメントにラベルを付けるために使用されるデータでなければなりません。メタデータは、変更されることはほとんどありません。 指定フィールドの名前を | ||||||||||
timeseries.granularity | string | 任意。
粒度とバケット間隔の詳細については、「時系列データの粒度の設定」を参照してください。 | ||||||||||
timeseries.bucketMaxSpanSeconds | integer | 任意。 MongoDB 6.3 以前のバージョンにダウングレードするには、対応する | ||||||||||
timeseries.bucketRoundingSeconds | integer | 任意。 たとえば、両方のパラメーターを | ||||||||||
expireAfterSeconds | 数値 | 任意。時系列コレクションまたはクラスター化されたコレクションのドキュメントが期限切れになる秒数を指定します。MongoDB は期限切れのドキュメントを自動的に削除します。 クラスター化されたコレクションでは、ドキュメントはクラスター化されたインデックス キー | ||||||||||
clusteredIndex | ドキュメント | MongoDB 5.3 以降、クラスター インデックス 付きのコレクションを作成できます。クラスター インデックスは、コレクション同様、WiredTiger ファイルに保存されます。結果として得られるコレクションは、クラスター化されたコレクションと呼ばれます。
バージョン 5.3 で追加。 | ||||||||||
changeStreamPreAndPostImages | ドキュメント | 任意。 MongoDB 6.0 以降では、変更ストリーム イベントを使用して、変更前と変更後のドキュメントのバージョン(変更前とイメージと変更後のイメージ)を出力できます。
コレクションの変更ストリームの事前イメージと事後イメージを有効にするには、 変更ストリーム出力の完全な例については、「Change Streams とドキュメントの変更前イメージおよび変更後イメージ」を参照してください。 このページの バージョン 6.0 で追加。 | ||||||||||
size | 数値 | 任意。上限付きコレクションの最大サイズをバイト単位で指定します。MongoDB は、上限付きコレクションが最大サイズに達すると、古いドキュメントを削除して新しいドキュメント用スペースを確保します。 size フィールドは、上限付きコレクションに必須であり、他のコレクションでは無視されます。 | ||||||||||
max | 数値 | 任意。上限付きコレクションで許可されるドキュメントの最大数。 size の制限がこの制限よりも優先されます。上限付きコレクションがドキュメントの最大数に達する前に size の制限に達した場合、MongoDB は古いドキュメントを削除します。max 制限の使用を優先する場合は、上限付きコレクションに必要な size 制限をドキュメントの最大数を十分に超える値に設定してください。 | ||||||||||
storageEngine | ドキュメント | 任意。WiredTiger ストレージエンジンでのみ使用できます。 コレクション作成時に、ユーザーがコレクションごとにストレージエンジンの構成を指定できるようにします。
コレクション作成時に指定されたストレージエンジンの設定は、レプリカセット内で異なるストレージエンジンを使用するノードをサポートするために、複製中に oplog に検証され、ログが記録されます。 MongoDB 7.2以降、 詳細については、「ストレージエンジン オプションの指定 」を参照してください。 | ||||||||||
validator | ドキュメント | 任意。ユーザーがコレクションの検証ルールまたは式を指定できるようにします。
スキーマ検証を使用してコレクションを作成する方法については、「JSON スキーマ検証の指定」を参照してください。 | ||||||||||
validationLevel | string | 任意。更新中に MongoDB が既存のドキュメントに検証ルールをどの程度厳密に適用するかを決定します。
| ||||||||||
validationAction | string | 任意。無効なドキュメントで 重要:ドキュメントの検証は、
| ||||||||||
indexOptionDefaults | ドキュメント | 任意。ユーザーがコレクションの作成時にインデックスのデフォルト構成を指定できるようにします。
インデックスの作成時に指定されたストレージエンジン構成は、異なるストレージエンジンを使用するノードのあるレプリカセットをサポートするために、レプリケーション中に検証され、oplog に記録されます。 | ||||||||||
viewOn | string | ビューの作成元となるコレクションまたはビューの名前。詳細については、「 db.createView() 」を参照してください。 | ||||||||||
pipeline | 配列 | 集計パイプラインステージで構成される配列。 db.createView() は、指定された pipeline を viewOn コレクションまたはビューに適用してビューを作成します。詳細については、「db.createView() 」を参照してください。 | ||||||||||
collation | ドキュメント | コレクションにデフォルトの照合を指定します。 照合を指定すると、大文字・小文字やアクセント記号など、文字列を比較するための言語独自のルールを指定できます。 照合オプションの構文は次のとおりです。
照合を指定する場合、 コレクション・レベルで照合を指定すると、次の効果が生じます。
コレクションにも操作にも照合が指定されていない場合、MongoDB では以前のバージョンで使用されていた単純なバイナリ比較によって文字列が比較されます。 コレクションに照合を指定できるのは、コレクションの作成時のみです。コレクションのデフォルトの照合は、一度設定すると変更できません。 例については、「照合の指定 」を参照してください。 | ||||||||||
writeConcern | ドキュメント | 任意。操作の書込み保証(write concern)を表現するドキュメント。デフォルトの書込み保証を使用する場合は省略します。 シャーディングされたクラスターで発行すると、 |
アクセス制御
配置で認証/承認が強制される場合、 db.createCollection()
には次の特権が必要です。
タスク | 必要な特権 |
---|---|
上限のないコレクションの作成 | データベース上の
|
上限付きコレクションの作成 |
|
ビューの作成 |
ただし、ユーザーがデータベースに対して |
データベースに対して readWrite
組み込みロールを持つユーザーは、リスト内の操作を実行するために必要な権限があります。必要なロールを持つユーザーを作成するか、既存ユーザーにロールを付与してください。
動作
db.createCollection()
は、次のような動作をします。
リソースのロック
db.createCollection()
は、操作中、指定されたコレクションまたはビューに対する排他ロックを取得します。 コレクションに対する後続のすべての操作は、 db.createCollection()
がロックを解放するまで待機する必要があります。 db.createCollection()
は通常、このロックを短時間保持します。
ビューを作成するには、データベース内の system.views
コレクションに対する追加の排他ロックを取得する必要があります。このロックは、コマンドが完了するまでデータベース内のビューの作成または変更をブロックします。
トランザクション
トランザクションがクロスシャード間書込みトランザクション(write transaction)でない場合に、分散トランザクション内にコレクションとインデックスを作成できます。
トランザクションで db.createCollection()
を使用するには、そのトランザクションで読み取り保証(read concern)"local"
を使用する必要があります。読み取り保証レベルを "local"
以外に指定すると、トランザクションは失敗します。
同じ名前とオプションのコレクションまたはビュー
既存のコレクションまたはビューと同じ名前とオプションを使用してdb.createCollection()
を実行すると、 db.createCollection()
は成功を返します。
例
上限付きコレクションの作成
上限付きコレクションには最大サイズまたはドキュメント数が設定されているため、最大しきい値を超えて増えることはありません。すべての上限付きコレクションでは最大サイズを指定する必要があり、最大ドキュメント数も指定できます。MongoDB は、コレクションが最大ドキュメント数に達する前に最大サイズ制限に達した場合、古いドキュメントを削除します。次の例で考えてみましょう。
db.createCollection("log", { capped : true, size : 5242880, max : 5000 } )
このコマンドは、最大サイズが 5 メガバイトで、最大ドキュメント数が 5000 の「log
」という名前のコレクションを作成します。
上限付きコレクションの詳細については、「上限付きコレクション」を参照してください。
時系列コレクションの作成
過去 24 時間の気象データを取得する時系列コレクションを作成するには、次のコマンドを実行します。
db.createCollection( "weather24h", { timeseries: { timeField: "timestamp", metaField: "data", granularity: "hours" }, expireAfterSeconds: 86400 } )
あるいは、同じコレクションを作成し、各バケットを同じ時間内のタイムスタンプ値に制限するには、次のコマンドを実行します。
db.createCollection( "weather24h", { timeseries: { timeField: "timestamp", metaField: "data", bucketMaxSpanSeconds: "3600", bucketRoundingSeconds: "3600" }, expireAfterSeconds: 86400 } )
クラスター化されたコレクションの作成
次の db.createCollection()
の例では、stocks
という名前の クラスター化されたコレクション を追加します。
db.createCollection( "stocks", { clusteredIndex: { "key": { _id: 1 }, "unique": true, "name": "stocks clustered key" } } )
この例では、 clusteredIndexは以下を指定しています。
"key": { _id: 1 }
は、_id
フィールドにクラスター化されたインデックス キーを設定します。"unique": true
は、クラスター化されたインデックス キーの値が一意でなければならないことを示しています。"name": "stocks clustered key"
は、クラスター化されたインデックス名を設定します。
ドキュメントの変更ストリームの事前・事後イメージによるコレクションの作成
MongoDB 6.0 以降では、変更ストリーム イベントを使用して、変更前と変更後のドキュメントのバージョン(変更前とイメージと変更後のイメージ)を出力できます。
変更前のイメージとは、置換、更新、または削除される前のドキュメントです。挿入されたドキュメントには、変更前のイメージはありません。
変更後のイメージとは、挿入、置換、または更新された後のドキュメントです。削除されたドキュメントには、変更後のイメージはありません。
db.createCollection()
、create
、またはcollMod
を使用してコレクションでchangeStreamPreAndPostImages
を有効にします。
次の例では、changeStreamPreAndPostImages が有効になっているコレクションを作成します。
db.createCollection( "temperatureSensor", { changeStreamPreAndPostImages: { enabled: true } } );
変更ストリーム イベントにおいて、次の条件に当てはまる場合、変更前と変更後のイメージは使用できません。
ドキュメントの更新または削除操作時に、コレクションにおいて有効になっていない場合。
expireAfterSeconds
で設定した、変更前と変更後のイメージ保持時間が経過した後に削除された場合。次の例では、クラスター全体で
expireAfterSeconds
を100
秒に設定します。use admin db.runCommand( { setClusterParameter: { changeStreamOptions: { preAndPostImages: { expireAfterSeconds: 100 } } } } ) 次の例では、
expireAfterSeconds
を含む現在のchangeStreamOptions
設定を返します。db.adminCommand( { getClusterParameter: "changeStreamOptions" } ) expireAfterSeconds
をoff
に設定すると、デフォルトの保持ポリシーが適用されます。対応する変更ストリーム イベントがoplog から削除されるまで、変更前と変更後のイメージは保持されます。変更ストリーム イベントが oplog から削除されると、
expireAfterSeconds
の変更前と変更後のイメージの保持時間にかかわらず、対応する変更前と変更後のイメージも削除されます。
その他の考慮事項
変更前と変更後のイメージを有効にすると、ストレージ容量が消費され、処理時間が増えます。変更前と変更後のイメージは、必要な場合のみ有効にしてください。
変更ストリーム イベントのサイズを 16 メガバイト未満に制限します。イベントのサイズを制限するには、次の方法があります。
ドキュメントのサイズを 8 MB に制限します。
updateDescription
のような他の変更ストリーム イベントのフィールドがそれほど大きくない場合、変更ストリーム出力で変更前と変更後のイメージを同時にリクエストできます。updateDescription
のような他の変更ストリーム イベントのフィールドがそれほど大きくない場合、ドキュメントの変更ストリーム出力では最大 16 MB の変更後のイメージのみをリクエストしてください。次の場合、ドキュメントの変更ストリーム出力では最大 16 MB の変更前のイメージのみをリクエストしてください。
ドキュメントのアップデートがドキュメントの構造または内容のごく一部にしか影響しない場合、そして
replace
変更イベントが発生しない場合。replace
イベントには、常に変更後のイメージが含まれます。
変更前イメージをリクエストするには、
db.collection.watch()
で、fullDocumentBeforeChange
をrequired
またはwhenAvailable
に設定します。変更後イメージをリクエストするには、同じ方法でfullDocument
を設定します。変更前のイメージは
config.system.preimages
コレクションに書き込まれます。config.system.preimages
コレクションが大きくなる場合があります。コレクションのサイズを制限するには、前述のとおり、変更前のイメージにexpireAfterSeconds
時間を設定します。変更前のイメージはバックグラウンド プロセスによって非同期で削除されます。
重要
下位互換性のない機能
MongoDB 6.0 以降では、変更ストリームにドキュメントの変更前のイメージと変更後のイメージを使用している場合、以前の MongoDB バージョンにダウングレードする前に、collMod
コマンドを使用して各コレクションの changeStreamPreAndPostImages を無効にする必要があります。
Tip
以下も参照してください。
変更ストリーム イベントと出力については、「変更イベント」を参照してください。
コレクションの変更を監視するには、
db.collection.watch()
を参照してください。変更ストリーム出力の完全な例については、「Change Streams とドキュメントの変更前イメージおよび変更後イメージ」を参照してください。
照合の指定
照合を指定すると、大文字・小文字やアクセント記号など、文字列を比較するための言語独自のルールを指定できます。
照合はコレクション レベルまたはビュー レベルで指定できます。たとえば、次の操作で照合を作成し、コレクションの照合を指定します(照合フィールドの説明については、照合ドキュメントを参照してください)。
db.createCollection( "myColl", { collation: { locale: "fr" } } );
この照合は、別の照合を明示的に指定しない限り、照合をサポートするインデックスと操作で使用されます。たとえば、次のドキュメントを myColl
に挿入します。
{ _id: 1, category: "café" } { _id: 2, category: "cafe" } { _id: 3, category: "cafE" }
次の操作はコレクションの照合を使用します。
db.myColl.find().sort( { category: 1 } )
この操作を実行すると、次の順序でドキュメントが返されます。
{ "_id" : 2, "category" : "cafe" } { "_id" : 3, "category" : "cafE" } { "_id" : 1, "category" : "café" }
単純なバイナリ照合(特定の照合が設定されていない)を使用するコレクションに対して同じ操作を実行すると、次の順序でドキュメントが返されます。
{ "_id" : 3, "category" : "cafE" } { "_id" : 2, "category" : "cafe" } { "_id" : 1, "category" : "café" }
ストレージエンジン オプションの指定
db.createCollection()
を使用してコレクションを作成するときに、コレクション固有のストレージエンジン構成オプションを指定できます。次の操作を検討してください。
db.createCollection( "users", { storageEngine: { wiredTiger: { configString: "<option>=<setting>" } } } )
この操作では、MongoDB がwiredTiger
ストレージエンジンに渡す特定の構成文字列を使用して、users
という名前の新しいコレクションが作成されます。
たとえば、users
コレクション内のファイル ブロックに zlib
コンプレッサーを指定するには、次のコマンドで block_compressor
オプションを設定します。
db.createCollection( "users", { storageEngine: { wiredTiger: { configString: "block_compressor=zlib" } } } )
MongoDB 7.2以降、 db.createCollection()
でコレクションを作成する場合、 wiredTiger
ストレージエンジン暗号化オプションは指定できません。 WiredTiger ストレージ エンジンで暗号化を構成するには、「 保管時の暗号化 」を参照してください。