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.

bucket &	operator= (bucket &&) noexcept
	Move assigns a bucket.

	bucket (const bucket &)
	Copy constructs a bucket.

bucket &	operator= (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::bson_value::view 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::bson_value::view 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::bson_value::view 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::bson_value::view 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::bson_value::view id)
	Opens a gridfs::downloader to read a GridFS file. More...

downloader	open_download_stream (const client_session &session, bsoncxx::types::bson_value::view id)
	Opens a gridfs::downloader to read a GridFS file. More...


void	download_to_stream (bsoncxx::types::bson_value::view 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 (bsoncxx::types::bson_value::view id, std::ostream *destination, std::size_t start, std::size_t end)
	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::bson_value::view 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::bson_value::view id, std::ostream *destination, std::size_t start, std::size_t end)
	Downloads the contents of a stored GridFS file from the bucket and writes it to a stream. More...


void	delete_file (bsoncxx::types::bson_value::view id)
	Deletes a GridFS file from the bucket. More...

void	delete_file (const client_session &session, bsoncxx::types::bson_value::view 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:

mongocxx::client mongo_client{mongocxx::uri{}};

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::bson_value::view id )

Deletes a GridFS file from the bucket.

Parameters

id	The id of the file to be deleted.

Exceptions

mongocxx::gridfs_exception	if the requested file does not exist.
mongocxx::bulk_write_exception	if 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::bson_value::view	id
	)

Deletes a GridFS file from the bucket.

Parameters

session	The mongocxx::client_session with which to perform the delete.
id	The id of the file to be deleted.

Exceptions

mongocxx::gridfs_exception	if the requested file does not exist.
mongocxx::bulk_write_exception	if an error occurs when removing file data or chunk data from the database.

◆ download_to_stream() [1/4]

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

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

Parameters

id	The id of the file to read.
destination	The non-null stream to which the GridFS file should be written.

Exceptions

mongocxx::gridfs_exception	if the requested file does not exist, or if the requested file has been corrupted.
mongocxx::query_exception	if an error occurs when reading from the files or chunks collections for this bucket.
std::ios_base::failure	if 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/4]

void mongocxx::gridfs::bucket::download_to_stream	(	bsoncxx::types::bson_value::view	id,
		std::ostream *	destination,
		std::size_t	start,
		std::size_t	end
	)

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

Parameters

id	The id of the file to read.
destination	The non-null stream to which the GridFS file should be written.

Exceptions

mongocxx::gridfs_exception	if the requested file does not exist, or if the requested file has been corrupted.
mongocxx::query_exception	if an error occurs when reading from the files or chunks collections for this bucket.
std::ios_base::failure	if 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() [3/4]

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

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

Parameters

session	The mongocxx::client_session with which to perform the download.
id	The id of the file to read.
destination	The non-null stream to which the GridFS file should be written.

Exceptions

mongocxx::gridfs_exception	if the requested file does not exist, or if the requested file has been corrupted.
mongocxx::query_exception	if an error occurs when reading from the files or chunks collections for this bucket.
std::ios_base::failure	if 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() [4/4]

void mongocxx::gridfs::bucket::download_to_stream	(	const client_session &	session,
		bsoncxx::types::bson_value::view	id,
		std::ostream *	destination,
		std::size_t	start,
		std::size_t	end
	)

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

Parameters

id	The id of the file to read.
destination	The non-null stream to which the GridFS file should be written.

Exceptions

mongocxx::gridfs_exception	if the requested file does not exist, or if the requested file has been corrupted.
mongocxx::query_exception	if an error occurs when reading from the files or chunks collections for this bucket.
std::ios_base::failure	if 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

filter	Document view representing a document that should match the query.
options	Optional 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_error if 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

session	The mongocxx::client_session with which to perform the query. The client session must remain valid for the lifetime of the cursor.
filter	Document view representing a document that should match the query.
options	Optional 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_error if 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::bson_value::view id )

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

Parameters

id	The id of the file to read.

Returns: The gridfs::downloader from which the GridFS file should be read.

Exceptions

mongocxx::gridfs_exception	if the requested file does not exist, or if the requested file has been corrupted.
mongocxx::query_exception	if 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::bson_value::view	id
	)

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

Parameters

session	The mongocxx::client_session with which to perform the download. The client session must remain valid for the lifetime of the downloader.
id	The id of the file to read.

Returns: The gridfs::downloader from which the GridFS file should be read.

Exceptions

mongocxx::gridfs_exception	if the requested file does not exist, or if the requested file has been corrupted.
mongocxx::query_exception	if an error occurs when reading from the files collection for this bucket.

◆ open_upload_stream() [1/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

session	The mongocxx::client_session with which to perform the upload. The client session must remain valid for the lifetime of the uploader.
filename	The name of the file to be uploaded. A bucket can contain multiple files with the same name.
options	Optional 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_error	if `options` are invalid.
mongocxx::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exception	if an error occurs when building GridFS indexes.

◆ open_upload_stream() [2/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

filename	The name of the file to be uploaded. A bucket can contain multiple files with the same name.
options	Optional 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_error	if `options` are invalid.
mongocxx::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exception	if 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::bson_value::view	id,
		stdx::string_view	filename,
		const options::gridfs::upload &	options = `{}`
	)

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

Parameters

id	The unique id of the file being uploaded.
filename	The name of the file to be uploaded. A bucket can contain multiple files with the same name.
options	Optional 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_error	if `options` are invalid.
mongocxx::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exception	if 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::bson_value::view	id,
		stdx::string_view	filename,
		const options::gridfs::upload &	options = `{}`
	)

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

Parameters

session	The mongocxx::client_session with which to perform the upload. The client session must remain valid for the lifetime of the uploader.
id	The unique id of the file being uploaded.
filename	The name of the file to be uploaded. A bucket can contain multiple files with the same name.
options	Optional 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_error	if `options` are invalid.
mongocxx::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exception	if an error occurs when building GridFS indexes.

◆ upload_from_stream() [1/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

session	The mongocxx::client_session with which to perform the upload.
filename	The name of the file to be uploaded. A bucket can contain multiple files with the same name.
source	The 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`.
options	Optional 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_error	if `options` are invalid.
mongocxx::bulk_write_exception	if an error occurs when writing chunk data or file metadata to the database.
std::ios_base::failure	if reading from `source` fails. Any exception thrown during the execution of `source::read()` will be re-thrown.
mongocxx::gridfs_exception	if the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exception	if an error occurs when building GridFS indexes.

◆ upload_from_stream() [2/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

filename	The name of the file to be uploaded. A bucket can contain multiple files with the same name.
source	The 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`.
options	Optional 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_error	if `options` are invalid.
mongocxx::bulk_write_exception	if an error occurs when writing chunk data or file metadata to the database.
std::ios_base::failure	if reading from `source` fails. Any exception thrown during the execution of `source::read()` will be re-thrown.
mongocxx::gridfs_exception	if the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exception	if 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::bson_value::view	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

id	A unique id for the file being uploaded.
filename	The name of the file to be uploaded. A bucket can contain multiple files with the same name.
source	The 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`.
options	Optional 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_error	if `options` are invalid.
mongocxx::bulk_write_exception	if an error occurs when writing chunk data or file metadata to the database.
std::ios_base::failure	if reading from `source` fails. Any exception thrown during the execution of `source::read()` will be re-thrown.
mongocxx::gridfs_exception	if the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exception	if 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::bson_value::view	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

session	The mongocxx::client_session with which to perform the upload.
id	A unique id for the file being uploaded.
filename	The name of the file to be uploaded. A bucket can contain multiple files with the same name.
source	The 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`.
options	Optional 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_error	if `options` are invalid.
mongocxx::bulk_write_exception	if an error occurs when writing chunk data or file metadata to the database.
std::ios_base::failure	if reading from `source` fails. Any exception thrown during the execution of `source::read()` will be re-thrown.
mongocxx::gridfs_exception	if the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::operation_exception	if an error occurs when building GridFS indexes.

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

src/mongocxx/gridfs/bucket.hpp

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ bucket()

Member Function Documentation

◆ bucket_name()

◆ delete_file() [1/2]

◆ delete_file() [2/2]

◆ download_to_stream() [1/4]

◆ download_to_stream() [2/4]

◆ download_to_stream() [3/4]

◆ download_to_stream() [4/4]

◆ find() [1/2]

◆ find() [2/2]

◆ open_download_stream() [1/2]

◆ open_download_stream() [2/2]

◆ open_upload_stream() [1/2]

◆ open_upload_stream() [2/2]

◆ open_upload_stream_with_id() [1/2]

◆ open_upload_stream_with_id() [2/2]

◆ upload_from_stream() [1/2]

◆ upload_from_stream() [2/2]

◆ upload_from_stream_with_id() [1/2]

◆ upload_from_stream_with_id() [2/2]