MongoDB C++ Driver  mongocxx-3.4.0
Public Member Functions | Friends | List of all members
mongocxx::gridfs::bucket Class Reference

Class representing a GridFS bucket. More...

#include <bucket.hpp>

Public Member Functions

 bucket () noexcept
 Default constructs a bucket object. More...
 
 bucket (bucket &&) noexcept
 Move constructs a bucket.
 
bucketoperator= (bucket &&) noexcept
 Move assigns a bucket.
 
 bucket (const bucket &)
 Copy constructs a bucket.
 
bucketoperator= (const bucket &)
 Copy assigns a bucket.
 
 ~bucket ()
 Destroys a bucket.
 
 operator bool () const noexcept
 Returns true if the bucket is valid, meaning it was not default constructed or moved from.
 
stdx::string_view bucket_name () const
 Gets the name of the GridFS bucket. More...
 
uploader open_upload_stream (stdx::string_view filename, const options::gridfs::upload &options={})
 Opens a gridfs::uploader to create a new GridFS file. More...
 
uploader open_upload_stream (const client_session &session, stdx::string_view filename, const options::gridfs::upload &options={})
 Opens a gridfs::uploader to create a new GridFS file. More...
 
uploader open_upload_stream_with_id (bsoncxx::types::value id, stdx::string_view filename, const options::gridfs::upload &options={})
 Opens a gridfs::uploader to create a new GridFS file. More...
 
uploader open_upload_stream_with_id (const client_session &session, bsoncxx::types::value id, stdx::string_view filename, const options::gridfs::upload &options={})
 Opens a gridfs::uploader to create a new GridFS file. More...
 
result::gridfs::upload upload_from_stream (stdx::string_view filename, std::istream *source, const options::gridfs::upload &options={})
 Creates a new GridFS file by uploading bytes from an input stream. More...
 
result::gridfs::upload upload_from_stream (const client_session &session, stdx::string_view filename, std::istream *source, const options::gridfs::upload &options={})
 Creates a new GridFS file by uploading bytes from an input stream. More...
 
void upload_from_stream_with_id (bsoncxx::types::value id, stdx::string_view filename, std::istream *source, const options::gridfs::upload &options={})
 Creates a new GridFS file with a user-supplied unique id by uploading bytes from an input stream. More...
 
void upload_from_stream_with_id (const client_session &session, bsoncxx::types::value id, stdx::string_view filename, std::istream *source, const options::gridfs::upload &options={})
 Creates a new GridFS file with a user-supplied unique id by uploading bytes from an input stream. More...
 
downloader open_download_stream (bsoncxx::types::value id)
 Opens a gridfs::downloader to read a GridFS file. More...
 
downloader open_download_stream (const client_session &session, bsoncxx::types::value id)
 Opens a gridfs::downloader to read a GridFS file. More...
 
void download_to_stream (bsoncxx::types::value id, std::ostream *destination)
 Downloads the contents of a stored GridFS file from the bucket and writes it to a stream. More...
 
void download_to_stream (const client_session &session, bsoncxx::types::value id, std::ostream *destination)
 Downloads the contents of a stored GridFS file from the bucket and writes it to a stream. More...
 
void delete_file (bsoncxx::types::value id)
 Deletes a GridFS file from the bucket. More...
 
void delete_file (const client_session &session, bsoncxx::types::value id)
 Deletes a GridFS file from the bucket. More...
 
cursor find (bsoncxx::document::view_or_value filter, const options::find &options={})
 Finds the documents in the files collection of the bucket which match the provided filter. More...
 
cursor find (const client_session &session, bsoncxx::document::view_or_value filter, const options::find &options={})
 Finds the documents in the files collection of the bucket which match the provided filter. More...
 

Friends

class mongocxx::database
 

Detailed Description

Class representing a GridFS bucket.

A GridFS bucket is used to store files that may be too large to store in a single document due to the 16 MB limit. The bucket comprises of two collections, <bucketname>.files and <bucketname>.chunks. A file written to a GridFS bucket will be serialized into zero or more chunk documents stored in the <bucketname>.chunks collection, and one document will be stored in the <bucketname>.files collection containing the information about the file. Users should not modify these collections directly.

Example of how obtain the default GridFS bucket for a given database:

auto gridfs_bucket = mongo_client["database"].gridfs_bucket();

See also the method documentation for mongocxx::database::gridfs_bucket().

See also
http://www.mongodb.org/display/DOCS/GridFS

Constructor & Destructor Documentation

◆ bucket()

mongocxx::gridfs::bucket::bucket ( )
noexcept

Default constructs a bucket object.

The bucket is equivalent to the state of a moved from bucket. The only valid actions to take with a default constructed bucket are to assign to it, or destroy it.

Member Function Documentation

◆ bucket_name()

stdx::string_view mongocxx::gridfs::bucket::bucket_name ( ) const

Gets the name of the GridFS bucket.

Returns
The name of the GridFS bucket.

◆ delete_file() [1/2]

void mongocxx::gridfs::bucket::delete_file ( bsoncxx::types::value  id)

Deletes a GridFS file from the bucket.

Parameters
idThe id of the file to be deleted.
Exceptions
mongocxx::gridfs_exceptionif the requested file does not exist.
mongocxx::bulk_write_exceptionif an error occurs when removing file data or chunk data from the database.

◆ delete_file() [2/2]

void mongocxx::gridfs::bucket::delete_file ( const client_session session,
bsoncxx::types::value  id 
)

Deletes a GridFS file from the bucket.

Parameters
sessionThe mongocxx::client_session with which to perform the delete.
idThe id of the file to be deleted.
Exceptions
mongocxx::gridfs_exceptionif the requested file does not exist.
mongocxx::bulk_write_exceptionif an error occurs when removing file data or chunk data from the database.

◆ download_to_stream() [1/2]

void mongocxx::gridfs::bucket::download_to_stream ( bsoncxx::types::value  id,
std::ostream *  destination 
)

Downloads the contents of a stored GridFS file from the bucket and writes it to a stream.

Parameters
idThe id of the file to read.
destinationThe non-null stream to which the GridFS file should be written.
Exceptions
mongocxx::gridfs_exceptionif the requested file does not exist, or if the requested file has been corrupted.
mongocxx::query_exceptionif an error occurs when reading from the files or chunks collections for this bucket.
std::ios_base::failureif writing to destination fails. In addition, if destination::exceptions() is set for badbit, any exception thrown during execution of destination::write() will be re-thrown.

◆ download_to_stream() [2/2]

void mongocxx::gridfs::bucket::download_to_stream ( const client_session session,
bsoncxx::types::value  id,
std::ostream *  destination 
)

Downloads the contents of a stored GridFS file from the bucket and writes it to a stream.

Parameters
sessionThe mongocxx::client_session with which to perform the download.
idThe id of the file to read.
destinationThe non-null stream to which the GridFS file should be written.
Exceptions
mongocxx::gridfs_exceptionif the requested file does not exist, or if the requested file has been corrupted.
mongocxx::query_exceptionif an error occurs when reading from the files or chunks collections for this bucket.
std::ios_base::failureif writing to destination fails. In addition, if destination::exceptions() is set for badbit, any exception thrown during execution of destination::write() will be re-thrown.

◆ find() [1/2]

cursor mongocxx::gridfs::bucket::find ( bsoncxx::document::view_or_value  filter,
const options::find options = {} 
)

Finds the documents in the files collection of the bucket which match the provided filter.

Parameters
filterDocument view representing a document that should match the query.
optionsOptional arguments; see options::find.
Returns
A mongocxx::cursor with the results. If the query fails, the cursor throws mongocxx::query_exception when the returned cursor is iterated.
Exceptions
mongocxx::logic_errorif the options are invalid, or if the unsupported option modifiers "$query" or "$explain" are used.
See also
mongocxx::collection::find.

◆ find() [2/2]

cursor mongocxx::gridfs::bucket::find ( const client_session session,
bsoncxx::document::view_or_value  filter,
const options::find options = {} 
)

Finds the documents in the files collection of the bucket which match the provided filter.

Parameters
sessionThe mongocxx::client_session with which to perform the query. The client session must remain valid for the lifetime of the cursor.
filterDocument view representing a document that should match the query.
optionsOptional arguments; see options::find.
Returns
A mongocxx::cursor with the results. If the query fails, the cursor throws mongocxx::query_exception when the returned cursor is iterated.
Exceptions
mongocxx::logic_errorif the options are invalid, or if the unsupported option modifiers "$query" or "$explain" are used.
See also
mongocxx::collection::find.

◆ open_download_stream() [1/2]

downloader mongocxx::gridfs::bucket::open_download_stream ( bsoncxx::types::value  id)

Opens a gridfs::downloader to read a GridFS file.

Parameters
idThe id of the file to read.
Returns
The gridfs::downloader from which the GridFS file should be read.
Exceptions
mongocxx::gridfs_exceptionif the requested file does not exist, or if the requested file has been corrupted.
mongocxx::query_exceptionif an error occurs when reading from the files collection for this bucket.

◆ open_download_stream() [2/2]

downloader mongocxx::gridfs::bucket::open_download_stream ( const client_session session,
bsoncxx::types::value  id 
)

Opens a gridfs::downloader to read a GridFS file.

Parameters
sessionThe mongocxx::client_session with which to perform the download. The client session must remain valid for the lifetime of the downloader.
idThe id of the file to read.
Returns
The gridfs::downloader from which the GridFS file should be read.
Exceptions
mongocxx::gridfs_exceptionif the requested file does not exist, or if the requested file has been corrupted.
mongocxx::query_exceptionif an error occurs when reading from the files collection for this bucket.

◆ open_upload_stream() [1/2]

uploader mongocxx::gridfs::bucket::open_upload_stream ( stdx::string_view  filename,
const options::gridfs::upload options = {} 
)

Opens a gridfs::uploader to create a new GridFS file.

The id of the file will be automatically generated as an ObjectId.

Parameters
filenameThe name of the file to be uploaded. A bucket can contain multiple files with the same name.
optionsOptional arguments; see options::gridfs::upload.
Returns
A stream for writing to the GridFS file.
Note
If this GridFS bucket does not already exist in the database, it will be implicitly created and initialized with GridFS indexes.
Exceptions
mongocxx::logic_errorif options are invalid.
mongocxx::query_exceptionif an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exceptionif an error occurs when building GridFS indexes.

◆ open_upload_stream() [2/2]

uploader mongocxx::gridfs::bucket::open_upload_stream ( const client_session session,
stdx::string_view  filename,
const options::gridfs::upload options = {} 
)

Opens a gridfs::uploader to create a new GridFS file.

The id of the file will be automatically generated as an ObjectId.

Parameters
sessionThe mongocxx::client_session with which to perform the upload. The client session must remain valid for the lifetime of the uploader.
filenameThe name of the file to be uploaded. A bucket can contain multiple files with the same name.
optionsOptional arguments; see options::gridfs::upload.
Returns
A stream for writing to the GridFS file.
Note
If this GridFS bucket does not already exist in the database, it will be implicitly created and initialized with GridFS indexes.
Exceptions
mongocxx::logic_errorif options are invalid.
mongocxx::query_exceptionif an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exceptionif an error occurs when building GridFS indexes.

◆ open_upload_stream_with_id() [1/2]

uploader mongocxx::gridfs::bucket::open_upload_stream_with_id ( bsoncxx::types::value  id,
stdx::string_view  filename,
const options::gridfs::upload options = {} 
)

Opens a gridfs::uploader to create a new GridFS file.

Parameters
idThe unique id of the file being uploaded.
filenameThe name of the file to be uploaded. A bucket can contain multiple files with the same name.
optionsOptional arguments; see options::gridfs::upload.
Returns
The gridfs::uploader to which the GridFS file should be written.
Note
If this GridFS bucket does not already exist in the database, it will be implicitly created and initialized with GridFS indexes.
Exceptions
mongocxx::logic_errorif options are invalid.
mongocxx::query_exceptionif an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exceptionif an error occurs when building GridFS indexes.

◆ open_upload_stream_with_id() [2/2]

uploader mongocxx::gridfs::bucket::open_upload_stream_with_id ( const client_session session,
bsoncxx::types::value  id,
stdx::string_view  filename,
const options::gridfs::upload options = {} 
)

Opens a gridfs::uploader to create a new GridFS file.

Parameters
sessionThe mongocxx::client_session with which to perform the upload. The client session must remain valid for the lifetime of the uploader.
idThe unique id of the file being uploaded.
filenameThe name of the file to be uploaded. A bucket can contain multiple files with the same name.
optionsOptional arguments; see options::gridfs::upload.
Returns
The gridfs::uploader to which the GridFS file should be written.
Note
If this GridFS bucket does not already exist in the database, it will be implicitly created and initialized with GridFS indexes.
Exceptions
mongocxx::logic_errorif options are invalid.
mongocxx::query_exceptionif an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exceptionif an error occurs when building GridFS indexes.

◆ upload_from_stream() [1/2]

result::gridfs::upload mongocxx::gridfs::bucket::upload_from_stream ( stdx::string_view  filename,
std::istream *  source,
const options::gridfs::upload options = {} 
)

Creates a new GridFS file by uploading bytes from an input stream.

The id of the file will be automatically generated as an ObjectId.

Parameters
filenameThe name of the file to be uploaded. A bucket can contain multiple files with the same name.
sourceThe non-null stream from which the GridFS file should be read. The exception mask on source will be cleared of eofbit and set for failbit and badbit.
optionsOptional arguments; see options::gridfs::upload.
Returns
The id of the uploaded file.
Note
If this GridFS bucket does not already exist in the database, it will be implicitly created and initialized with GridFS indexes.
Exceptions
mongocxx::logic_errorif options are invalid.
mongocxx::bulk_write_exceptionif an error occurs when writing chunk data or file metadata to the database.
std::ios_base::failureif reading from source fails. Any exception thrown during the execution of source::read() will be re-thrown.
mongocxx::gridfs_exceptionif the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::query_exceptionif an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exceptionif an error occurs when building GridFS indexes.

◆ upload_from_stream() [2/2]

result::gridfs::upload mongocxx::gridfs::bucket::upload_from_stream ( const client_session session,
stdx::string_view  filename,
std::istream *  source,
const options::gridfs::upload options = {} 
)

Creates a new GridFS file by uploading bytes from an input stream.

The id of the file will be automatically generated as an ObjectId.

Parameters
sessionThe mongocxx::client_session with which to perform the upload.
filenameThe name of the file to be uploaded. A bucket can contain multiple files with the same name.
sourceThe non-null stream from which the GridFS file should be read. The exception mask on source will be cleared of eofbit and set for failbit and badbit.
optionsOptional arguments; see options::gridfs::upload.
Returns
The id of the uploaded file.
Note
If this GridFS bucket does not already exist in the database, it will be implicitly created and initialized with GridFS indexes.
Exceptions
mongocxx::logic_errorif options are invalid.
mongocxx::bulk_write_exceptionif an error occurs when writing chunk data or file metadata to the database.
std::ios_base::failureif reading from source fails. Any exception thrown during the execution of source::read() will be re-thrown.
mongocxx::gridfs_exceptionif the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::query_exceptionif an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exceptionif an error occurs when building GridFS indexes.

◆ upload_from_stream_with_id() [1/2]

void mongocxx::gridfs::bucket::upload_from_stream_with_id ( bsoncxx::types::value  id,
stdx::string_view  filename,
std::istream *  source,
const options::gridfs::upload options = {} 
)

Creates a new GridFS file with a user-supplied unique id by uploading bytes from an input stream.

Parameters
idA unique id for the file being uploaded.
filenameThe name of the file to be uploaded. A bucket can contain multiple files with the same name.
sourceThe non-null stream from which the GridFS file should be read. The exception mask on source will be cleared of eofbit and set for failbit and badbit.
optionsOptional arguments; see options::gridfs::upload.
Note
If this GridFS bucket does not already exist in the database, it will be implicitly created and initialized with GridFS indexes.
Exceptions
mongocxx::logic_errorif options are invalid.
mongocxx::bulk_write_exceptionif an error occurs when writing chunk data or file metadata to the database.
std::ios_base::failureif reading from source fails. Any exception thrown during the execution of source::read() will be re-thrown.
mongocxx::gridfs_exceptionif the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::query_exceptionif an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exceptionif an error occurs when building GridFS indexes.

◆ upload_from_stream_with_id() [2/2]

void mongocxx::gridfs::bucket::upload_from_stream_with_id ( const client_session session,
bsoncxx::types::value  id,
stdx::string_view  filename,
std::istream *  source,
const options::gridfs::upload options = {} 
)

Creates a new GridFS file with a user-supplied unique id by uploading bytes from an input stream.

Parameters
sessionThe mongocxx::client_session with which to perform the upload.
idA unique id for the file being uploaded.
filenameThe name of the file to be uploaded. A bucket can contain multiple files with the same name.
sourceThe non-null stream from which the GridFS file should be read. The exception mask on source will be cleared of eofbit and set for failbit and badbit.
optionsOptional arguments; see options::gridfs::upload.
Note
If this GridFS bucket does not already exist in the database, it will be implicitly created and initialized with GridFS indexes.
Exceptions
mongocxx::logic_errorif options are invalid.
mongocxx::bulk_write_exceptionif an error occurs when writing chunk data or file metadata to the database.
std::ios_base::failureif reading from source fails. Any exception thrown during the execution of source::read() will be re-thrown.
mongocxx::gridfs_exceptionif the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::query_exceptionif an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exceptionif an error occurs when building GridFS indexes.

The documentation for this class was generated from the following file: