class Mongo::Grid::FSBucket

Represents a view of the GridFS in the database.

@since 2.0.0

Constants

CHUNKS_INDEX

The specification for the chunks collection index.

@since 2.0.0

DEFAULT_ROOT

The default root prefix.

@since 2.0.0

FILES_INDEX

The specification for the files collection index.

@since 2.1.0

Attributes

chunks_collection[R]

@return [ Collection ] chunks_collection The chunks collection.

@since 2.0.0

database[R]

@return [ Database ] database The database.

@since 2.0.0

files_collection[R]

@return [ Collection ] files_collection The files collection.

@since 2.0.0

options[R]

@return [ Hash ] options The FSBucket options.

@since 2.1.0

Public Class Methods

new(database, options = {}) click to toggle source

Create the GridFS.

@example Create the GridFS.

Grid::FSBucket.new(database)

@param [ Database ] database The database the files reside in. @param [ Hash ] options The GridFS options.

@option options [ String ] :fs_name The prefix for the files and chunks

collections.

@option options [ String ] :bucket_name The prefix for the files and chunks

collections.

@option options [ Integer ] :chunk_size Override the default chunk

size.

@option options [ String ] :read The read preference. @option options [ Session ] :session The session to use. @option options [ Hash ] :write Deprecated. Equivalent to :write_concern

option.

@option options [ Hash ] :write_concern The write concern options.

Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.

@since 2.0.0

# File lib/mongo/grid/fs_bucket.rb, line 156
      def initialize(database, options = {})
        @database = database
        @options = options.dup
=begin WriteConcern object support
        if @options[:write_concern].is_a?(WriteConcern::Base)
          # Cache the instance so that we do not needlessly reconstruct it.
          @write_concern = @options[:write_concern]
          @options[:write_concern] = @write_concern.options
        end
=end
        @options.freeze
        @chunks_collection = database[chunks_name]
        @files_collection = database[files_name]
      end

Public Instance Methods

delete(id) click to toggle source

Remove a single file, identified by its id from the GridFS.

@example Remove a file from the GridFS.

fs.delete(id)

@param [ BSON::ObjectId, Object ] id The id of the file to remove.

@return [ Result ] The result of the remove.

@raise [ Error::FileNotFound ] If the file is not found.

@since 2.1.0

# File lib/mongo/grid/fs_bucket.rb, line 209
def delete(id)
  result = files_collection.find({ :_id => id }, @options).delete_one
  chunks_collection.find({ :files_id => id }, @options).delete_many
  raise Error::FileNotFound.new(id, :id) if result.n == 0
  result
end
delete_one(file) click to toggle source

Remove a single file from the GridFS.

@example Remove a file from the GridFS.

fs.delete_one(file)

@param [ Grid::File ] file The file to remove.

@return [ Result ] The result of the remove.

@since 2.0.0

# File lib/mongo/grid/fs_bucket.rb, line 193
def delete_one(file)
  delete(file.id)
end
download_to_stream(id, io) click to toggle source

Downloads the contents of the file specified by id and writes them to the destination io object.

@example Download the file and write it to the io object.

fs.download_to_stream(id, io)

@param [ BSON::ObjectId, Object ] id The id of the file to read. @param [ IO ] io The io object to write to.

@since 2.1.0

# File lib/mongo/grid/fs_bucket.rb, line 254
def download_to_stream(id, io)
  open_download_stream(id) do |stream|
    stream.each do |chunk|
      io << chunk
    end
  end
end
download_to_stream_by_name(filename, io, opts = {}) click to toggle source

Downloads the contents of the stored file specified by filename and by the revision in options and writes the contents to the destination io object.

Revision numbers are defined as follows: 0 = the original stored file 1 = the first revision 2 = the second revision etc… -2 = the second most recent revision -1 = the most recent revision

@example Download the most recent revision.

fs.download_to_stream_by_name('some-file.txt', io)

# @example Download the original file.

fs.download_to_stream_by_name('some-file.txt', io, revision: 0)

@example Download the second revision of the stored file.

fs.download_to_stream_by_name('some-file.txt', io, revision: 2)

@param [ String ] filename The file's name. @param [ IO ] io The io object to write to. @param [ Hash ] opts Options for the download.

@option opts [ Integer ] :revision The revision number of the file to download.

Defaults to -1, the most recent version.

@raise [ Error::FileNotFound ] If the file is not found. @raise [ Error::InvalidFileRevision ] If the requested revision is not found for the file.

@since 2.1.0

# File lib/mongo/grid/fs_bucket.rb, line 347
def download_to_stream_by_name(filename, io, opts = {})
  download_to_stream(open_download_stream_by_name(filename, opts).file_id, io)
end
find(selector = nil, options = {}) click to toggle source

Find files collection documents matching a given selector.

@example Find files collection documents by a filename.

fs.find(filename: 'file.txt')

@param [ Hash ] selector The selector to use in the find. @param [ Hash ] options The options for the find.

@option options [ Integer ] :batch_size The number of documents returned in each batch

of results from MongoDB.

@option options [ Integer ] :limit The max number of docs to return from the query. @option options [ true, false ] :no_cursor_timeout The server normally times out idle

cursors after an inactivity period (10 minutes) to prevent excess memory use.
Set this option to prevent that.

@option options [ Integer ] :skip The number of docs to skip before returning results. @option options [ Hash ] :sort The key and direction pairs by which the result set

will be sorted.

@return [ CollectionView ] The collection view.

@since 2.1.0

# File lib/mongo/grid/fs_bucket.rb, line 86
def find(selector = nil, options = {})
  opts = options.merge(read: read_preference) if read_preference
  files_collection.find(selector, opts || options)
end
find_one(selector = nil) click to toggle source

Find a file in the GridFS.

@example Find a file by its id.

fs.find_one(_id: id)

@example Find a file by its filename.

fs.find_one(filename: 'test.txt')

@param [ Hash ] selector The selector.

@return [ Grid::File ] The file.

@since 2.0.0

@deprecated Please use find instead with a limit of -1.

Will be removed in version 3.0.
# File lib/mongo/grid/fs_bucket.rb, line 107
def find_one(selector = nil)
  file_info = files_collection.find(selector).first
  return nil unless file_info
  chunks = chunks_collection.find(:files_id => file_info[:_id]).sort(:n => 1)
  Grid::File.new(chunks.to_a, Options::Mapper.transform(file_info, Grid::File::Info::MAPPINGS.invert))
end
insert_one(file) click to toggle source

Insert a single file into the GridFS.

@example Insert a single file.

fs.insert_one(file)

@param [ Grid::File ] file The file to insert.

@return [ BSON::ObjectId ] The file id.

@since 2.0.0

@deprecated Please use upload_from_stream or open_upload_stream instead.

Will be removed in version 3.0.
# File lib/mongo/grid/fs_bucket.rb, line 127
def insert_one(file)
  @indexes ||= ensure_indexes!
  chunks_collection.insert_many(file.chunks)
  files_collection.insert_one(file.info)
  file.id
end
open_download_stream(id, options = nil) { |stream| ... } click to toggle source

Opens a stream from which a file can be downloaded, specified by id.

@example Open a stream from which a file can be downloaded.

fs.open_download_stream(id)

@param [ BSON::ObjectId, Object ] id The id of the file to read. @param [ Hash ] options The options.

@option options [ BSON::Document ] :file_info_doc For internal

driver use only. A BSON document to use as file information.

@return [ Stream::Read ] The stream to read from.

@yieldparam [ Hash ] The read stream.

@since 2.1.0

# File lib/mongo/grid/fs_bucket.rb, line 232
def open_download_stream(id, options = nil)
  read_stream(id, options).tap do |stream|
    if block_given?
      begin
        yield stream
      ensure
        stream.close
      end
    end
  end
end
open_download_stream_by_name(filename, opts = {}, &block) click to toggle source

Opens a stream from which the application can read the contents of the stored file specified by filename and the revision in options.

Revision numbers are defined as follows: 0 = the original stored file 1 = the first revision 2 = the second revision etc… -2 = the second most recent revision -1 = the most recent revision

@example Open a stream to download the most recent revision.

fs.open_download_stream_by_name('some-file.txt')

# @example Open a stream to download the original file.

fs.open_download_stream_by_name('some-file.txt', revision: 0)

@example Open a stream to download the second revision of the stored file.

fs.open_download_stream_by_name('some-file.txt', revision: 2)

@param [ String ] filename The file's name. @param [ Hash ] opts Options for the download.

@option opts [ Integer ] :revision The revision number of the file to download.

Defaults to -1, the most recent version.

@return [ Stream::Read ] The stream to read from.

@raise [ Error::FileNotFound ] If the file is not found. @raise [ Error::InvalidFileRevision ] If the requested revision is not found for the file.

@yieldparam [ Hash ] The read stream.

@since 2.1.0

# File lib/mongo/grid/fs_bucket.rb, line 296
def open_download_stream_by_name(filename, opts = {}, &block)
  revision = opts.fetch(:revision, -1)
  if revision < 0
    skip = revision.abs - 1
    sort = { 'uploadDate' => Mongo::Index::DESCENDING }
  else
    skip = revision
    sort = { 'uploadDate' => Mongo::Index::ASCENDING }
  end
  file_info_doc = files_collection.find({ filename: filename} ,
                                     sort: sort,
                                     skip: skip,
                                     limit: -1).first
  unless file_info_doc
    raise Error::FileNotFound.new(filename, :filename) unless opts[:revision]
    raise Error::InvalidFileRevision.new(filename, opts[:revision])
  end
  open_download_stream(file_info_doc[:_id], file_info_doc: file_info_doc, &block)
end
open_upload_stream(filename, opts = {}) { |stream| ... } click to toggle source

Opens an upload stream to GridFS to which the contents of a user file came be written.

@example Open a stream to which the contents of a file came be written.

fs.open_upload_stream('a-file.txt')

@param [ String ] filename The filename of the file to upload. @param [ Hash ] opts The options for the write stream.

@option opts [ Object ] :file_id An optional unique file id. An ObjectId is generated otherwise. @option opts [ Integer ] :chunk_size Override the default chunk size. @option opts [ Hash ] :metadata User data for the 'metadata' field of the files

collection document.

@option opts [ String ] :content_type The content type of the file.

Deprecated, please use the metadata document instead.

@option opts [ Array<String> ] :aliases A list of aliases.

Deprecated, please use the metadata document instead.

@option options [ Hash ] :write Deprecated. Equivalent to :write_concern

option.

@option options [ Hash ] :write_concern The write concern options.

Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.

@return [ Stream::Write ] The write stream.

@yieldparam [ Hash ] The write stream.

@since 2.1.0

# File lib/mongo/grid/fs_bucket.rb, line 377
def open_upload_stream(filename, opts = {})
  write_stream(filename, opts).tap do |stream|
    if block_given?
      begin
        yield stream
      ensure
        stream.close
      end
    end
  end
end
prefix() click to toggle source

Get the prefix for the GridFS

@example Get the prefix.

fs.prefix

@return [ String ] The GridFS prefix.

@since 2.0.0

# File lib/mongo/grid/fs_bucket.rb, line 179
def prefix
  @options[:fs_name] || @options[:bucket_name]|| DEFAULT_ROOT
end
read_preference() click to toggle source

Get the read preference.

@example Get the read preference.

fs.read_preference

@return [ Mongo::ServerSelector ] The read preference.

@since 2.1.0

# File lib/mongo/grid/fs_bucket.rb, line 439
def read_preference
  @read_preference ||= options[:read] || database.read_preference
end
upload_from_stream(filename, io, opts = {}) click to toggle source

Uploads a user file to a GridFS bucket. Reads the contents of the user file from the source stream and uploads it as chunks in the chunks collection. After all the chunks have been uploaded, it creates a files collection document for the filename in the files collection.

@example Upload a file to the GridFS bucket.

fs.upload_from_stream('a-file.txt', file)

@param [ String ] filename The filename of the file to upload. @param [ IO ] io The source io stream to upload from. @param [ Hash ] opts The options for the write stream.

@option opts [ Object ] :file_id An optional unique file id. An ObjectId is generated otherwise. @option opts [ Integer ] :chunk_size Override the default chunk size. @option opts [ Hash ] :metadata User data for the 'metadata' field of the files

collection document.

@option opts [ String ] :content_type The content type of the file. Deprecated, please

use the metadata document instead.

@option opts [ Array<String> ] :aliases A list of aliases. Deprecated, please use the

metadata document instead.

@option options [ Hash ] :write Deprecated. Equivalent to :write_concern

option.

@option options [ Hash ] :write_concern The write concern options.

Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.

@return [ BSON::ObjectId ] The ObjectId file id.

@since 2.1.0

# File lib/mongo/grid/fs_bucket.rb, line 417
def upload_from_stream(filename, io, opts = {})
  open_upload_stream(filename, opts) do |stream|
    begin
      stream.write(io)
    rescue IOError
      begin
        stream.abort
      rescue Error::OperationFailure
      end
      raise
    end
  end.file_id
end
write_concern() click to toggle source

Get the write concern.

@example Get the write concern.

stream.write_concern

@return [ Mongo::WriteConcern ] The write concern.

@since 2.1.0

# File lib/mongo/grid/fs_bucket.rb, line 451
def write_concern
  @write_concern ||= if wco = @options[:write_concern] || @options[:write]
    WriteConcern.get(wco)
  else
    database.write_concern
  end
end

Private Instance Methods

chunks_name() click to toggle source
# File lib/mongo/grid/fs_bucket.rb, line 473
def chunks_name
  "#{prefix}.#{Grid::File::Chunk::COLLECTION}"
end
ensure_indexes!() click to toggle source
# File lib/mongo/grid/fs_bucket.rb, line 481
def ensure_indexes!
  if files_collection.find({}, limit: 1, projection: { _id: 1 }).first.nil?
    chunks_collection.indexes.create_one(FSBucket::CHUNKS_INDEX, :unique => true)
    files_collection.indexes.create_one(FSBucket::FILES_INDEX)
  end
end
files_name() click to toggle source
# File lib/mongo/grid/fs_bucket.rb, line 477
def files_name
  "#{prefix}.#{Grid::File::Info::COLLECTION}"
end
read_stream(id, opts = nil) click to toggle source

@param [ Hash ] opts The options.

@option opts [ BSON::Document ] :file_info_doc For internal

driver use only. A BSON document to use as file information.
# File lib/mongo/grid/fs_bucket.rb, line 465
def read_stream(id, opts = nil)
  Stream.get(self, Stream::READ_MODE, { file_id: id }.update(options).update(opts || {}))
end
write_stream(filename, opts) click to toggle source
# File lib/mongo/grid/fs_bucket.rb, line 469
def write_stream(filename, opts)
  Stream.get(self, Stream::WRITE_MODE, { filename: filename }.merge!(options).merge!(opts))
end