GridFS

On this page本页内容

GridFS is a specification for storing and retrieving files that exceed the BSON-document size limit of 16 MB.是用于存储和检索超过16 MB BSON文档大小限制的文件的规范。

Note注意

GridFS does not support multi-document transactions.GridFS不支持多文档事务。

Instead of storing a file in a single document, GridFS divides the file into parts, or chunks [1], and stores each chunk as a separate document. GridFS不是将文件存储在单个文档中，而是将文件分成多个部分或块[1]，并将每个块存储为单独的文档。By default, GridFS uses a default chunk size of 255 kB; that is, GridFS divides a file into chunks of 255 kB with the exception of the last chunk. 默认情况下，GridFS使用255 kB的默认块大小；也就是说，GridFS将文件划分为255 kB的块，最后一个块除外。The last chunk is only as large as necessary. 最后一个块只有必要的大小。Similarly, files that are no larger than the chunk size only have a final chunk, using only as much space as needed plus some additional metadata.类似地，不大于块大小的文件只有一个最终块，只使用所需的空间和一些附加元数据。

GridFS uses two collections to store files. GridFS使用两个集合来存储文件。One collection stores the file chunks, and the other stores file metadata. 一个集合存储文件块，另一个存储文件元数据。The section GridFS Collections describes each collection in detail.GridFS集合一节详细描述了每个集合。

When you query GridFS for a file, the driver will reassemble the chunks as needed. 当您查询GridFS文件时，驱动程序将根据需要重新组合块。You can perform range queries on files stored through GridFS. 您可以对通过GridFS存储的文件执行范围查询。You can also access information from arbitrary sections of files, such as to "skip" to the middle of a video or audio file.您还可以从文件的任意部分访问信息，例如“跳过”到视频或音频文件的中间。

GridFS is useful not only for storing files that exceed 16 MB but also for storing any files for which you want access without having to load the entire file into memory. GridFS不仅适用于存储超过16 MB的文件，而且还适用于存储您想要访问的任何文件，而无需将整个文件加载到内存中。See also When to Use GridFS.另请参见何时使用GridFS。

When to Use GridFS何时使用GridFS

In MongoDB, use GridFS for storing files larger than 16 MB.在MongoDB中，使用GridFS存储大于16MB的文件。

In some situations, storing large files may be more efficient in a MongoDB database than on a system-level filesystem.在某些情况下，在MongoDB数据库中存储大文件可能比在系统级文件系统中更有效。

  • If your filesystem limits the number of files in a directory, you can use GridFS to store as many files as needed.如果文件系统限制了一个目录中的文件数量，则可以使用GridFS存储所需的文件。
  • When you want to access information from portions of large files without having to load whole files into memory, you can use GridFS to recall sections of files without reading the entire file into memory.当您希望访问大文件的部分信息而不必将整个文件加载到内存中时，可以使用GridFS调用文件的部分，而无需将整个文件读取到内存中。
  • When you want to keep your files and metadata automatically synced and deployed across a number of systems and facilities, you can use GridFS. 当您希望在多个系统和设施中自动同步和部署文件和元数据时，可以使用GridFS。When using geographically distributed replica sets, MongoDB can distribute files and their metadata automatically to a number of mongod instances and facilities.当使用地理分布的副本集时，MongoDB可以将文件及其元数据自动分发到多个mongod实例和设施。

Do not use GridFS if you need to update the content of the entire file atomically. 如果需要以原子方式更新整个文件的内容，请不要使用GridFS。As an alternative you can store multiple versions of each file and specify the current version of the file in the metadata. 或者，您可以存储每个文件的多个版本，并在元数据中指定文件的当前版本。You can update the metadata field that indicates "latest" status in an atomic update after uploading the new version of the file, and later remove previous versions if needed.您可以在上传文件的新版本后，在原子更新中更新指示“最新”状态的元数据字段，然后根据需要删除以前的版本。

Furthermore, if your files are all smaller than the 16 MB BSON Document Size limit, consider storing each file in a single document instead of using GridFS. 此外，如果您的文件都小于16 MB BSON文档大小限制，请考虑将每个文件存储在单个文档中，而不是使用GridFS。You may use the BinData data type to store the binary data. 您可以使用BinData数据类型来存储二进制数据。See your drivers documentation for details on using BinData.有关使用BinData的详细信息，请参阅驱动程序文档。

Use GridFS使用GridFS

To store and retrieve files using GridFS, use either of the following:要使用GridFS存储和检索文件，请使用以下任一选项：

  • A MongoDB driver. MongoDB驱动程序。See the drivers documentation for information on using GridFS with your driver.有关在驱动程序中使用GridFS的信息，请参阅驱动程序文档。
  • The mongofiles command-line tool. mongofiles命令行工具。See the mongofiles reference for documentation.有关文档，请参阅mongofiles参考。

GridFS CollectionsGridFS集合

GridFS stores files in two collections:将文件存储在两个集合中：

GridFS places the collections in a common bucket by prefixing each with the bucket name. GridFS通过在每个集合前面加上桶名，将集合放在一个公共桶中。By default, GridFS uses two collections with a bucket named fs:默认情况下，GridFS使用两个具有名为fs的bucket的集合：

  • fs.files
  • fs.chunks

You can choose a different bucket name, as well as create multiple buckets in a single database. 您可以选择不同的存储桶名称，也可以在单个数据库中创建多个存储桶。The full collection name, which includes the bucket name, is subject to the namespace length limit.完整的集合名称（包括bucket名称）受命名空间长度限制。

The chunks Collectionchunks集合

Each document in the chunks [1] collection represents a distinct chunk of a file as represented in GridFS. chunks[1]集合中的每个文档都表示一个文件的不同块，如GridFS所示。Documents in this collection have the following form:此集合中的文档具有以下形式：

{
  "_id" : <ObjectId>,
  "files_id" : <ObjectId>,
  "n" : <num>,
  "data" : <binary>
}

A document from the chunks collection contains the following fields:chunks集合中的文档包含以下字段：

chunks._id

The unique ObjectId of the chunk.块的唯一ObjectId。

chunks.files_id

The _id of the "parent" document, as specified in the files collection.files集合中指定的“父”文档的_id。

chunks.n

The sequence number of the chunk. GridFS numbers all chunks, starting with 0.块的序列号。GridFS对所有块进行编号，从0开始。

chunks.data

The chunk's payload as a BSON Binary type.块的有效负载为BSONBinary类型。

The files Collectionfiles集合

Each document in the files collection represents a file in GridFS.files集合中的每个文档表示GridFS中的一个文件。

{
  "_id" : <ObjectId>,
  "length" : <num>,
  "chunkSize" : <num>,
  "uploadDate" : <timestamp>,
  "md5" : <hash>,
  "filename" : <string>,
  "contentType" : <string>,
  "aliases" : <string array>,
  "metadata" : <any>,
}

Documents in the files collection contain some or all of the following fields:files集合中的文档包含以下部分或全部字段：

files._id

The unique identifier for this document. 此文档的唯一标识符。The _id is of the data type you chose for the original document. _id是您为原始文档选择的数据类型。The default type for MongoDB documents is BSON ObjectId.MongoDB文档的默认类型是BSON BSON ObjectId。

files.length

The size of the document in bytes.文档的大小（以字节为单位）。

files.chunkSize

The size of each chunk in bytes. 每个块的大小（以字节为单位）。GridFS divides the document into chunks of size chunkSize, except for the last, which is only as large as needed. GridFS将文档划分为大小为chunkSize的块，但最后一个除外，后者仅根据需要大小。The default size is 255 kilobytes (kB).默认大小为255 kB。

files.uploadDate

The date the document was first stored by GridFS. GridFS首次存储文档的日期。This value has the Date type.此值具有Date类型。

files.md5

Deprecated不赞成

The MD5 algorithm is prohibited by FIPS 140-2. MD5算法被FIPS 140-2禁止。MongoDB drivers deprecate MD5 support and will remove MD5 generation in future releases. MongoDB驱动程序不支持MD5，并将在未来版本中删除MD5生成。Applications that require a file digest should implement it outside of GridFS and store in files.metadata.需要文件摘要的应用程序应该在GridFS之外实现，并存储在files.metadata中。

An MD5 hash of the complete file returned by the filemd5 command. filemd5命令返回的完整文件的MD5哈希。This value has the String type.此值具有String类型。

files.filename

Optional. 可选，A human-readable name for the GridFS file.GridFS文件的可读名称。

files.contentType

Deprecated不赞成

Optional. 可选。A valid MIME type for the GridFS file. For application use only.GridFS文件的有效MIME类型。仅用于应用。

Use files.metadata for storing information related to the MIME type of the GridFS file.使用files.metadata存储与GridFS文件的MIME类型相关的信息。

files.aliases

Deprecated不赞成

Optional. 可选。An array of alias strings. 别名字符串的数组。For application use only.仅用于应用。

Use files.metadata for storing information related to the MIME type of the GridFS file.使用files.metadata存储与GridFS文件的MIME类型相关的信息。

files.metadata

Optional. 可选。The metadata field may be of any data type and can hold any additional information you want to store. 元数据字段可以是任何数据类型，并且可以包含您想要存储的任何附加信息。If you wish to add additional arbitrary fields to documents in the files collection, add them to an object in the metadata field.如果要向files集合中的文档添加其他任意字段，请将其添加到元数据字段中的对象中。

GridFS IndexesGridFS索引

GridFS uses indexes on each of the chunks and files collections for efficiency. 为了提高效率，GridFS在每个chunks和files集合上使用索引。Drivers that conform to the GridFS specification automatically create these indexes for convenience. 为了方便起见，符合GridFS规范的驱动程序会自动创建这些索引。You can also create any additional indexes as desired to suit your application's needs.您还可以根据需要创建任何其他索引，以满足应用程序的需要。

The chunks Indexchunks索引

GridFS uses a unique, compound index on the chunks collection using the files_id and n fields. 使用files_id和n字段对chunks集合使用唯一的复合索引。This allows for efficient retrieval of chunks, as demonstrated in the following example:这允许高效检索块，如以下示例所示：

db.fs.chunks.find( { files_id: myFileID } ).sort( { n: 1 } )

Drivers that conform to the GridFS specification will automatically ensure that this index exists before read and write operations. 符合GridFS规范的驱动程序将自动确保该索引在读写操作之前存在。See the relevant driver documentation for the specific behavior of your GridFS application.有关GridFS应用程序的具体行为，请参阅相关驱动程序文档。

If this index does not exist, you can issue the following operation to create it using mongosh:如果此索引不存在，您可以使用mongosh发出以下操作来创建它：

db.fs.chunks.createIndex( { files_id: 1, n: 1 }, { unique: true } );

The files Indexfiles索引

GridFS uses an index on the files collection using the filename and uploadDate fields. GridFS使用filename和uploadDate字段对files集合进行索引。This index allows for efficient retrieval of files, as shown in this example:此索引允许高效检索文件，如本例所示：

db.fs.files.find( { filename: myFileName } ).sort( { uploadDate: 1 } )

Drivers that conform to the GridFS specification will automatically ensure that this index exists before read and write operations. 符合GridFS规范的驱动程序将自动确保该索引在读写操作之前存在。See the relevant driver documentation for the specific behavior of your GridFS application.有关GridFS应用程序的具体行为，请参阅相关驱动程序文档。

If this index does not exist, you can issue the following operation to create it using mongosh:如果此索引不存在，您可以使用mongosh发出以下操作来创建它：

db.fs.files.createIndex( { filename: 1, uploadDate: 1 } );
[1](1, 2) The use of the term chunks in the context of GridFS is not related to the use of the term chunks in the context of sharding.GridFS上下文中术语块的使用与分片上下文中术语组块的使用无关。

Sharding GridFS分片网格

There are two collections to consider with GridFS - files and chunks.GGridFS需要考虑两个集合：files和chunks。

chunks Collection集合

To shard the chunks collection, use either { files_id : 1, n : 1 } or { files_id : 1 } as the shard key index. 要对chunks集合进行分片，请使用{ files_id : 1, n : 1 }或{ files_id : 1 }作为分片键索引。files_id is an ObjectId and changes monotonically.是ObjectId，并且单调变化。

For MongoDB drivers that do not run filemd5 to verify successful upload (for example, MongoDB drivers that support MongoDB 4.0 or greater), you can use Hashed Sharding for the chunks collection.对于不运行filemd5来验证上传成功的MongoDB驱动程序（例如，支持MongoDB 4.0或更高版本的MongoDB驱动程序），可以对chunks集合使用哈希分片。

If the MongoDB driver runs filemd5, you cannot use Hashed Sharding. 如果MongoDB驱动程序运行filemd5，则不能使用哈希分片。For details, see SERVER-9888.有关详细信息，请参阅SERVER-9888。

files Collection集合

The files collection is small and only contains metadata. files集合很小，仅包含元数据。None of the required keys for GridFS lend themselves to an even distribution in a sharded environment. GridF所需的键都不适合在分片环境中均匀分布。Leaving files unsharded allows all the file metadata documents to live on the primary shard.不共享files允许所有文件元数据文档都位于主分片上。

If you must shard the files collection, use the _id field, possibly in combination with an application field.如果必须对files集合进行分片，请使用_id字段，可能与应用程序字段结合使用。

←  Manage JournalingFAQ: MongoDB Storage →