MongoDB::GridFSBucket(3pm)

1MongoDB::GridFSBucket(3U)ser Contributed Perl DocumentatiMoonngoDB::GridFSBucket(3)
2
3
4

NAME

6       MongoDB::GridFSBucket - A file storage abstraction
7

VERSION

9       version v2.2.2
10

SYNOPSIS

12           $bucket = $database->gfs;
13
14           # upload a file
15           $stream  = $bucket->open_upload_stream("foo.txt");
16           $stream->print( $data );
17           $stream->close;
18
19           # find and download a file
20           $result  = $bucket->find({filename => "foo.txt"});
21           $file_id = $result->next->{_id};
22           $stream  = $bucket->open_download_stream($file_id)
23           $data    = do { local $/; $stream->readline() };
24

DESCRIPTION

26       This class models a GridFS file store in a MongoDB database and
27       provides an API for interacting with it.
28
29       Generally, you never construct one of these directly with "new".
30       Instead, you call "gfs" (short for "get_gridfsbucket") on a
31       MongoDB::Database object.
32

USAGE

34   Data model
35       A GridFS file is represented in MongoDB as a "file document" with
36       information like the file's name, length, and any user-supplied
37       metadata.  The actual contents are stored as a number of "chunks" of
38       binary data.  (Think of the file document as a directory entry and the
39       chunks like blocks on disk.)
40
41       Valid file documents typically include the following fields:
42
43       •   _id – a unique ID for this document, typically a BSON ObjectId.
44
45       •   length – the length of this stored file, in bytes
46
47       •   chunkSize – the size, in bytes, of each full data chunk of this
48           file. This value is configurable per file.
49
50       •   uploadDate – the date and time this file was added to GridFS,
51           stored as a BSON datetime value.
52
53       •   filename – the name of this stored file; the combination of
54           filename and uploadDate (millisecond resolution) must be unique
55
56       •   metadata – any additional application data the user wishes to store
57           (optional)
58
59       •   md5 – DEPRECATED a hash of the contents of the stored file (store
60           this in "metadata" if you need it) (optional)
61
62       •   contentType – DEPRECATED (store this in "metadata" if you need it)
63           (optional)
64
65       •   aliases – DEPRECATED (store this in "metadata" if you need it)
66           (optional)
67
68       The "find" method searches file documents using these fields.  Given
69       the "_id" from a document, a file can be downloaded using the download
70       methods.
71
72   API Overview
73       In addition to general methods like "find", "delete" and "drop", there
74       are two ways to go about uploading and downloading:
75
76       •   filehandle-like: you get an object that you can read/write from
77           similar to a filehandle.  You can even get a tied filehandle that
78           you can hand off to other code that requires an actual Perl handle.
79
80       •   streaming: you provide a file handle to read from (upload) or print
81           to (download) and data is streamed to (upload) or from (download)
82           GridFS until EOF.
83
84   Error handling
85       Unless otherwise explicitly documented, all methods throw exceptions if
86       an error occurs.  The error types are documented in MongoDB::Error.
87

ATTRIBUTES

89   database
90       The MongoDB::Database containing the GridFS bucket collections.
91
92   bucket_name
93       The name of the GridFS bucket.  Defaults to 'fs'.  The underlying
94       collections that are used to implement a GridFS bucket get this string
95       as a prefix (e.g "fs.chunks").
96
97   chunk_size_bytes
98       The number of bytes per chunk.  Defaults to 261120 (255kb).
99
100   write_concern
101       A MongoDB::WriteConcern object.  It may be initialized with a hash
102       reference that will be coerced into a new MongoDB::WriteConcern object.
103       By default it will be inherited from a MongoDB::Database object.
104
105   read_concern
106       A MongoDB::ReadConcern object.  May be initialized with a hash
107       reference or a string that will be coerced into the level of read
108       concern.
109
110       By default it will be inherited from a MongoDB::Database object.
111
112   read_preference
113       A MongoDB::ReadPreference object.  It may be initialized with a string
114       corresponding to one of the valid read preference modes or a hash
115       reference that will be coerced into a new MongoDB::ReadPreference
116       object.  By default it will be inherited from a MongoDB::Database
117       object.
118
119       Note: Because many GridFS operations require multiple independent reads
120       from separate collections, use with secondaries is strongly discouraged
121       because reads could go to different secondaries, resulting in
122       inconsistent data if all file and chunk documents have not replicated
123       to all secondaries.
124
125   bson_codec
126       An object that provides the "encode_one" and "decode_one" methods, such
127       as from BSON.  It may be initialized with a hash reference that will be
128       coerced into a new BSON object.  By default it will be inherited from a
129       MongoDB::Database object.
130
131   max_time_ms
132       Specifies the maximum amount of time in milliseconds that the server
133       should use for working on a query.  By default it will be inherited
134       from a MongoDB::Database object.
135
136       Note: this will only be used for server versions 2.6 or greater, as
137       that was when the $maxTimeMS meta-operator was introduced.
138
139   disable_md5
140       When true, files will not include the deprecated "md5" field in the
141       file document.  Defaults to false.
142

METHODS

144   find
145           $result = $bucket->find($filter);
146           $result = $bucket->find($filter, $options);
147
148           $file_doc = $result->next;
149
150       Executes a query on the file documents collection with a filter
151       expression and returns a MongoDB::QueryResult object.  It takes an
152       optional hashref of options identical to "find" in MongoDB::Collection.
153
154   find_one
155           $file_doc = $bucket->find_one($filter, $projection);
156           $file_doc = $bucket->find_one($filter, $projection, $options);
157
158       Executes a query on the file documents collection with a filter
159       expression and returns the first document found, or "undef" if no
160       document is found.
161
162       See "find_one" in MongoDB::Collection for details about the $projection
163       and optional $options fields.
164
165   find_id
166           $file_doc = $bucket->find_id( $id );
167           $file_doc = $bucket->find_id( $id, $projection );
168           $file_doc = $bucket->find_id( $id, $projection, $options );
169
170       Executes a query with a filter expression of "{ _id => $id }" and
171       returns a single document or "undef" if no document is found.
172
173       See "find_one" in MongoDB::Collection for details about the $projection
174       and optional $options fields.
175
176   open_download_stream
177           $stream = $bucket->open_download_stream($id);
178           $line = $stream->readline;
179
180       Returns a new MongoDB::GridFSBucket::DownloadStream that can be used to
181       download the file with the file document "_id" matching $id.  This
182       throws a MongoDB::GridFSError if no such file exists.
183
184   open_upload_stream
185           $stream = $bucket->open_upload_stream($filename);
186           $stream = $bucket->open_upload_stream($filename, $options);
187
188           $stream->print('data');
189           $stream->close;
190           $file_id = $stream->id
191
192       Returns a new MongoDB::GridFSBucket::UploadStream that can be used to
193       upload a new file to a GridFS bucket.
194
195       This method requires a filename to store in the "filename" field of the
196       file document.  Note: the filename is an arbitrary string; the method
197       does not read from this filename locally.
198
199       You can provide an optional hash reference of options that are passed
200       to the MongoDB::GridFSBucket::UploadStream constructor:
201
202       •   "chunk_size_bytes" – the number of bytes per chunk.  Defaults to
203           the "chunk_size_bytes" of the bucket object.
204
205       •   "metadata" – a hash reference for storing arbitrary metadata about
206           the file.
207
208   open_upload_stream_with_id
209           $stream = $bucket->open_upload_stream_with_id($id, $filename);
210           $stream = $bucket->open_upload_stream_with_id($id, $filename, $options);
211
212           $stream->print('data');
213           $stream->close;
214
215       Returns a new MongoDB::GridFSBucket::UploadStream that can be used to
216       upload a new file to a GridFS bucket.
217
218       This method uses $id as the _id of the file being created, which must
219       be unique.
220
221       This method requires a filename to store in the "filename" field of the
222       file document.  Note: the filename is an arbitrary string; the method
223       does not read from this filename locally.
224
225       You can provide an optional hash reference of options, just like
226       "open_upload_stream".
227
228   download_to_stream
229           $bucket->download_to_stream($id, $out_fh);
230
231       Downloads the file matching $id and writes it to the file handle
232       $out_fh.  This throws a MongoDB::GridFSError if no such file exists.
233
234   upload_from_stream
235           $file_id = $bucket->upload_from_stream($filename, $in_fh);
236           $file_id = $bucket->upload_from_stream($filename, $in_fh, $options);
237
238       Reads from a filehandle and uploads its contents to GridFS.  It returns
239       the "_id" field stored in the file document.
240
241       This method requires a filename to store in the "filename" field of the
242       file document.  Note: the filename is an arbitrary string; the method
243       does not read from this filename locally.
244
245       You can provide an optional hash reference of options, just like
246       "open_upload_stream".
247
248   upload_from_stream_with_id
249           $bucket->upload_from_stream_with_id($id, $filename, $in_fh);
250           $bucket->upload_from_stream_with_id($id, $filename, $in_fh, $options);
251
252       Reads from a filehandle and uploads its contents to GridFS.
253
254       This method uses $id as the _id of the file being created, which must
255       be unique.
256
257       This method requires a filename to store in the "filename" field of the
258       file document.  Note: the filename is an arbitrary string; the method
259       does not read from this filename locally.
260
261       You can provide an optional hash reference of options, just like
262       "open_upload_stream".
263
264       Unlike "open_upload_stream", this method returns nothing.
265
266   delete
267           $bucket->delete($id);
268
269       Deletes the file matching $id from the bucket.  This throws a
270       MongoDB::GridFSError if no such file exists.
271
272   drop
273           $bucket->drop;
274
275       Drops the underlying files documents and chunks collections for this
276       bucket.
277

AUTHORS

282       •   David Golden <david@mongodb.com>
283
284       •   Rassi <rassi@mongodb.com>
285
286       •   Mike Friedman <friedo@friedo.com>
287
288       •   Kristina Chodorow <k.chodorow@gmail.com>
289
290       •   Florian Ragwitz <rafl@debian.org>
291

COPYRIGHT AND LICENSE

293       This software is Copyright (c) 2020 by MongoDB, Inc.
294
295       This is free software, licensed under:
296
297         The Apache License, Version 2.0, January 2004
298
299
300
301perl v5.32.1                      2021-01-27          MongoDB::GridFSBucket(3)