Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MongoDB::GridFSBucket(User Contributed Perl DocumentatMongoDB::GridFSBucket(3)

NAME
       MongoDB::GridFSBucket - A file storage abstraction

VERSION
       version v2.2.2

SYNOPSIS
	   $bucket = $database->gfs;

	   # upload a file
	   $stream  = $bucket->open_upload_stream("foo.txt");
	   $stream->print( $data );
	   $stream->close;

	   # find and download a file
	   $result  = $bucket->find({filename => "foo.txt"});
	   $file_id = $result->next->{_id};
	   $stream  = $bucket->open_download_stream($file_id)
	   $data    = do { local $/; $stream->readline() };

DESCRIPTION
       This class models a GridFS file store in	a MongoDB database and
       provides	an API for interacting with it.

       Generally, you never construct one of these directly with "new".
       Instead,	you call "gfs" (short for "get_gridfsbucket") on a
       MongoDB::Database object.

USAGE
   Data	model
       A GridFS	file is	represented in MongoDB as a "file document" with
       information like	the file's name, length, and any user-supplied
       metadata.  The actual contents are stored as a number of	"chunks" of
       binary data.  (Think of the file	document as a directory	entry and the
       chunks like blocks on disk.)

       Valid file documents typically include the following fields:

       o   _id a a unique ID for this document,	typically a BSON ObjectId.

       o   length a the	length of this stored file, in bytes

       o   chunkSize a the size, in bytes, of each full	data chunk of this
	   file. This value is configurable per	file.

       o   uploadDate a	the date and time this file was	added to GridFS,
	   stored as a BSON datetime value.

       o   filename a the name of this stored file; the	combination of
	   filename and	uploadDate (millisecond	resolution) must be unique

       o   metadata a any additional application data the user wishes to store
	   (optional)

       o   md5 a DEPRECATED a hash of the contents of the stored file (store
	   this	in "metadata" if you need it) (optional)

       o   contentType a DEPRECATED (store this	in "metadata" if you need it)
	   (optional)

       o   aliases a DEPRECATED	(store this in "metadata" if you need it)
	   (optional)

       The "find" method searches file documents using these fields.  Given
       the "_id" from a	document, a file can be	downloaded using the download
       methods.

   API Overview
       In addition to general methods like "find", "delete" and	"drop",	there
       are two ways to go about	uploading and downloading:

       o   filehandle-like: you	get an object that you can read/write from
	   similar to a	filehandle.  You can even get a	tied filehandle	that
	   you can hand	off to other code that requires	an actual Perl handle.

       o   streaming: you provide a file handle	to read	from (upload) or print
	   to (download) and data is streamed to (upload) or from (download)
	   GridFS until	EOF.

   Error handling
       Unless otherwise	explicitly documented, all methods throw exceptions if
       an error	occurs.	 The error types are documented	in MongoDB::Error.

ATTRIBUTES
   database
       The MongoDB::Database containing	the GridFS bucket collections.

   bucket_name
       The name	of the GridFS bucket.  Defaults	to 'fs'.  The underlying
       collections that	are used to implement a	GridFS bucket get this string
       as a prefix (e.g	"fs.chunks").

   chunk_size_bytes
       The number of bytes per chunk.  Defaults	to 261120 (255kb).

   write_concern
       A MongoDB::WriteConcern object.	It may be initialized with a hash
       reference that will be coerced into a new MongoDB::WriteConcern object.
       By default it will be inherited from a MongoDB::Database	object.

   read_concern
       A MongoDB::ReadConcern object.  May be initialized with a hash
       reference or a string that will be coerced into the level of read
       concern.

       By default it will be inherited from a MongoDB::Database	object.

   read_preference
       A MongoDB::ReadPreference object.  It may be initialized	with a string
       corresponding to	one of the valid read preference modes or a hash
       reference that will be coerced into a new MongoDB::ReadPreference
       object.	By default it will be inherited	from a MongoDB::Database
       object.

       Note: Because many GridFS operations require multiple independent reads
       from separate collections, use with secondaries is strongly discouraged
       because reads could go to different secondaries,	resulting in
       inconsistent data if all	file and chunk documents have not replicated
       to all secondaries.

   bson_codec
       An object that provides the "encode_one"	and "decode_one" methods, such
       as from BSON.  It may be	initialized with a hash	reference that will be
       coerced into a new BSON object.	By default it will be inherited	from a
       MongoDB::Database object.

   max_time_ms
       Specifies the maximum amount of time in milliseconds that the server
       should use for working on a query.  By default it will be inherited
       from a MongoDB::Database	object.

       Note: this will only be used for	server versions	2.6 or greater,	as
       that was	when the $maxTimeMS meta-operator was introduced.

   disable_md5
       When true, files	will not include the deprecated	"md5" field in the
       file document.  Defaults	to false.

METHODS
   find
	   $result = $bucket->find($filter);
	   $result = $bucket->find($filter, $options);

	   $file_doc = $result->next;

       Executes	a query	on the file documents collection with a	filter
       expression and returns a	MongoDB::QueryResult object.  It takes an
       optional	hashref	of options identical to	"find" in MongoDB::Collection.

   find_one
	   $file_doc = $bucket->find_one($filter, $projection);
	   $file_doc = $bucket->find_one($filter, $projection, $options);

       Executes	a query	on the file documents collection with a	filter
       expression and returns the first	document found,	or "undef" if no
       document	is found.

       See "find_one" in MongoDB::Collection for details about the $projection
       and optional $options fields.

   find_id
	   $file_doc = $bucket->find_id( $id );
	   $file_doc = $bucket->find_id( $id, $projection );
	   $file_doc = $bucket->find_id( $id, $projection, $options );

       Executes	a query	with a filter expression of "{ _id => $id }" and
       returns a single	document or "undef" if no document is found.

       See "find_one" in MongoDB::Collection for details about the $projection
       and optional $options fields.

   open_download_stream
	   $stream = $bucket->open_download_stream($id);
	   $line = $stream->readline;

       Returns a new MongoDB::GridFSBucket::DownloadStream that	can be used to
       download	the file with the file document	"_id" matching $id.  This
       throws a	MongoDB::GridFSError if	no such	file exists.

   open_upload_stream
	   $stream = $bucket->open_upload_stream($filename);
	   $stream = $bucket->open_upload_stream($filename, $options);

	   $stream->print('data');
	   $stream->close;
	   $file_id = $stream->id

       Returns a new MongoDB::GridFSBucket::UploadStream that can be used to
       upload a	new file to a GridFS bucket.

       This method requires a filename to store	in the "filename" field	of the
       file document.  Note: the filename is an	arbitrary string; the method
       does not	read from this filename	locally.

       You can provide an optional hash	reference of options that are passed
       to the MongoDB::GridFSBucket::UploadStream constructor:

       o   "chunk_size_bytes" a	the number of bytes per	chunk.	Defaults to
	   the "chunk_size_bytes" of the bucket	object.

       o   "metadata" a	a hash reference for storing arbitrary metadata	about
	   the file.

   open_upload_stream_with_id
	   $stream = $bucket->open_upload_stream_with_id($id, $filename);
	   $stream = $bucket->open_upload_stream_with_id($id, $filename, $options);

	   $stream->print('data');
	   $stream->close;

       Returns a new MongoDB::GridFSBucket::UploadStream that can be used to
       upload a	new file to a GridFS bucket.

       This method uses	$id as the _id of the file being created, which	must
       be unique.

       This method requires a filename to store	in the "filename" field	of the
       file document.  Note: the filename is an	arbitrary string; the method
       does not	read from this filename	locally.

       You can provide an optional hash	reference of options, just like
       "open_upload_stream".

   download_to_stream
	   $bucket->download_to_stream($id, $out_fh);

       Downloads the file matching $id and writes it to	the file handle
       $out_fh.	 This throws a MongoDB::GridFSError if no such file exists.

   upload_from_stream
	   $file_id = $bucket->upload_from_stream($filename, $in_fh);
	   $file_id = $bucket->upload_from_stream($filename, $in_fh, $options);

       Reads from a filehandle and uploads its contents	to GridFS.  It returns
       the "_id" field stored in the file document.

       This method requires a filename to store	in the "filename" field	of the
       file document.  Note: the filename is an	arbitrary string; the method
       does not	read from this filename	locally.

       You can provide an optional hash	reference of options, just like
       "open_upload_stream".

   upload_from_stream_with_id
	   $bucket->upload_from_stream_with_id($id, $filename, $in_fh);
	   $bucket->upload_from_stream_with_id($id, $filename, $in_fh, $options);

       Reads from a filehandle and uploads its contents	to GridFS.

       This method uses	$id as the _id of the file being created, which	must
       be unique.

       This method requires a filename to store	in the "filename" field	of the
       file document.  Note: the filename is an	arbitrary string; the method
       does not	read from this filename	locally.

       You can provide an optional hash	reference of options, just like
       "open_upload_stream".

       Unlike "open_upload_stream", this method	returns	nothing.

   delete
	   $bucket->delete($id);

       Deletes the file	matching $id from the bucket.  This throws a
       MongoDB::GridFSError if no such file exists.

   drop
	   $bucket->drop;

       Drops the underlying files documents and	chunks collections for this
       bucket.

SEE ALSO
       Core documentation on GridFS: <http://dochub.mongodb.org/core/gridfs>.

AUTHORS
       o   David Golden	<david@mongodb.com>

       o   Rassi <rassi@mongodb.com>

       o   Mike	Friedman <friedo@friedo.com>

       o   Kristina Chodorow <k.chodorow@gmail.com>

       o   Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE
       This software is	Copyright (c) 2020 by MongoDB, Inc.

       This is free software, licensed under:

	 The Apache License, Version 2.0, January 2004

perl v5.32.1			  2020-08-13	      MongoDB::GridFSBucket(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | USAGE | ATTRIBUTES | METHODS | SEE ALSO | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MongoDB::GridFSBucket&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help