.. _gridfs:

******
GridFS
******

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

The driver provides a clean and simple interface to work with storage of
chunked files in the database, also known as the pattern "GridFS". The API allows you to either
work with Grid::File objects or with read and write streams.

Creating a GridFS object ("Grid::FSBucket")
===========================================

You can create a GridFS object by calling ``fs`` on a database, with optional
arguments. ``fs`` returns a ``Grid::FSBucket`` object.

The options that ``Grid::FSBucket`` supports are:

.. list-table::
   :header-rows: 1
   :widths: 40 80

   * - Option
     - Description
   * - ``:bucket_name``
     - The name of the GridFS Bucket. Default is ``fs``.
   * - ``:fs_name``
     - The name of the GridFS Bucket. Takes precedence over ``bucket_name``.
       Default is ``fs``.
   * - ``:chunk_size``
     - Specifies the size of each file chunk in the database.
   * - ``:write_concern``
     - The write concern to use when uploading files. Please see the
       :ref:`Write Concern <write-concern>` section under CRUD operations
       for how to work with write concerns.
   * - ``:write``
     - Deprecated. Same as ``:write_concern``.
   * - ``:read``
     - The read preference to use when downloading files.


For example, you can create a GridFS bucket object with a particular read preference:

.. code-block:: ruby

  fs_bucket = database.fs( read: { mode: :secondary } )


Working with write streams
==========================

To upload a file to GridFS using a write stream, you can either open a stream
and write to it directly or write the entire contents of an ``IO`` object to
GridFS all at once.

To open an upload stream and write to it:

.. code-block:: ruby

  File.open('/path/to/my-file.txt', 'r') do |file|
    fs_bucket.open_upload_stream('my-file.txt') do |stream|
      stream.write(file)
    end
  end

To upload the entire contents of an IO object in one call:

.. code-block:: ruby

  File.open('/path/to/my-file.txt', 'r') do |file|
    fs_bucket.upload_from_stream('my-file.txt', file)
  end

Write streams support the following options:

.. list-table::
   :header-rows: 1
   :widths: 40 80

   * - Option
     - Description
   * - ``:chunk_size``
     - Specifies the size of each file chunk in the database.
   * - ``:write_concern``
     - The write concern to use when uploading files. Please see the
       :ref:`Write Concern <write-concern>` section under CRUD operations
       for how to work with write concerns.
   * - ``:write``
     - Deprecated. Same as ``:write_concern``.

The options can be provided as the last argument to the write stream methods:

.. code-block:: ruby

    fs_bucket.open_upload_stream('my-file.txt', write_concern: {w: 2}) do |stream|
      stream.write_concern
      # => #<Mongo::WriteConcern::Acknowledged:0x46980201422160 options={:w=>2}>

      # ...
    end

    fs_bucket.upload_from_stream('my-file.txt', file, write_concern: {w: 2})


Working with read streams
=========================

To download a file from GridFS using a read stream, you can either open a
read stream and read from it directly or download the entire file all at once.

To open a download stream and read from it:

.. code-block:: ruby

  File.open('/path/to/my-output-file.txt', 'w') do |file|
    fs_bucket.open_download_stream(file_id) do |stream|
      file.write(stream.read)
    end
  end

To download the file all at once and write it to an IO object:

.. code-block:: ruby

  File.open('/path/to/my-output-file.txt', 'w') do |file|
    fs_bucket.download_from_stream(file_id, file)
  end

You can also download a file specified by a name and (optionally)
revision number. Revision numbers are used to distinguish between files
sharing the same name, ordered by date of upload. The revision number passed to
``open_download_stream_by_name`` can be positive or negative.

.. code-block:: ruby

  File.open('/path/to/my-output-file.txt', 'w') do |file|
    fs_bucket.open_download_stream_by_name('my-file.txt', revision: -2) do |stream|
      file.write(stream.read)
    end
  end

To download the entire contents of the file specified by name and (optionally)
revision number:

.. code-block:: ruby

  File.open('/path/to/my-output-file.txt', 'w') do |file|
    fs_bucket.download_to_stream_by_name('my-file.txt', file, revision: -2)
  end

Read streams support the following options:

.. list-table::
   :header-rows: 1
   :widths: 40 80

   * - Option
     - Description
   * - ``:read``
     - The read preference to use when downloading files.

Some, but not all, of the read methods listed above pass these options to
the underlying read streams. Please consult the API documentation for each
method to determine whether it supports a particular option.

Finding file metadata
=====================

You can retrieve documents containing metadata about files in the GridFS files collection.

.. code-block:: ruby

  fs_bucket.find(filename: 'my-file.txt')

Deleting files
==============

You can delete a file by id.

.. code-block:: ruby

  fs_bucket.delete(file_id)


Working with Grid::File objects
===============================

This object can be used to wrap a file to be inserted into the database using
GridFS and the object that is retrieved.

To create a file with raw data:

.. code-block:: ruby

  file = Mongo::Grid::File.new('I am a file', :filename => 'new-file.txt')

To create a file from a Ruby ``File`` object:

.. code-block:: ruby

  file = File.open('/path/to/my-file.txt')
  grid_file = Mongo::Grid::File.new(file.read, :filename => File.basename(file.path))

To change file options such as chunk size, pass options to the constructor:

.. code-block:: ruby

  file = File.open('/path/to/my-file.txt')
  grid_file = Mongo::Grid::File.new(
    file.read,
    :filename => File.basename(file.path),
    :chunk_size => 1024
  )

The following is a full list of the available options that files support.

.. list-table::
   :header-rows: 1
   :widths: 40 80

   * - Option
     - Description
   * - ``:chunk_size``
     - Sets the size of each file chunk in the database.
   * - ``:content_type``
     - Set a content type for the file.
   * - ``:filename`` (Required)
     - The file name.
   * - ``:upload_date``
     - The date the file was uploaded (stored).


Inserting Files
===============

Files can be inserted into the database one at a time. File chunks are inserted
by default into the ``fs.chunks`` collection and file metadata is inserted into the
``fs.files`` collection.

.. code-block:: ruby

  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
  file = Mongo::Grid::File.new('I am a file', :filename => 'new-file.txt')

  client.database.fs.insert_one(file)

To insert into collections with a name prefix other than `fs`, access the
filesystem with a ``:fs_name`` option.

.. code-block:: ruby

  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
  file = Mongo::Grid::File.new('I am a file', :filename => 'new-file.txt')

  client.database.fs(:fs_name => 'grid').insert_one(file)

When the driver is inserting the first file into a bucket, it will attempt to create the required
indexes on ``files`` and ``chunks`` collections. The required indexes are as follows:

.. code-block:: ruby

  # files collection
  { :filename => 1, :uploadDate => 1 }

  # chunks collection
  { :files_id => 1, :n => 1 }, { :unique => true }

.. note::

  If the indexes cannot be created, such as due to the current user lacking the permissions to do so,
  the file insert will be aborted. If the application does not have permissions to create indexes,
  a database administrator must create the required indexes ahead of time.

  If the bucket already has files, the driver will not attempt to create indexes, even if they are
  missing and the current user has permissions to create them. In this case a database administrator
  should create the needed indexes as soon as possible to ensure data integrity.

Files can also be streamed as an alternative to a direct insert.

.. code-block:: ruby

  client.database.fs.open_upload_stream(filename) do |stream|
    stream.write(file)
  end

Finding Files
=============

To retrieve a file from the database, call ``find_one`` with the appropriate filter.

.. code-block:: ruby

  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
  client.database.fs.find_one(:filename => 'new-file.txt') # Returns a Mongo::Grid::File

Files can also be streamed as an alternative to a direct find.

.. code-block:: ruby

  client.database.fs.open_download_stream(file_id) do |stream|
    io.write(stream.read)
  end

  fs.download_to_stream(file_id, io)


Deleting Files
==============

To delete a file, pass the file object to ``delete_one``.

.. code-block:: ruby

  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
  fs = client.database.fs
  file = fs.find_one(:filename => 'new-file.txt')
  fs.delete_one(file)