mongocxx::v_noabi::gridfs::bucket Class Reference

#include <mongocxx/v_noabi/mongocxx/gridfs/bucket.hpp>

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

mongocxx::v_noabi::client mongo_client{mongocxx::v_noabi::uri{}};
 
// Obtain the default GridFS bucket for a given database.
auto gridfs_bucket = mongo_client["database"].gridfs_bucket();

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

See also

• https://www.mongodb.com/display/DOCS/GridFS

Public Member Functions
	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.
	bucket (bucket &&) noexcept
	Move constructs a bucket.
	bucket (const bucket &)
	Copy constructs a bucket.
	~bucket ()
	Destroys a bucket.
stdx::string_view	bucket_name () const
	Gets the name of the GridFS bucket.
void	delete_file (bsoncxx::v_noabi::types::bson_value::view id)
	Deletes a GridFS file from the bucket.
void	delete_file (const client_session &session, bsoncxx::v_noabi::types::bson_value::view id)
	Deletes a GridFS file from the bucket.
void	download_to_stream (bsoncxx::v_noabi::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.
void	download_to_stream (bsoncxx::v_noabi::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.
void	download_to_stream (const client_session &session, bsoncxx::v_noabi::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.
void	download_to_stream (const client_session &session, bsoncxx::v_noabi::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.
cursor	find (bsoncxx::v_noabi::document::view_or_value filter, const options::find &options={})
	Finds the documents in the files collection of the bucket which match the provided filter.
cursor	find (const client_session &session, bsoncxx::v_noabi::document::view_or_value filter, const options::find &options={})
	Finds the documents in the files collection of the bucket which match the provided filter.
downloader	open_download_stream (bsoncxx::v_noabi::types::bson_value::view id)
	Opens a gridfs::downloader to read a GridFS file.
downloader	open_download_stream (const client_session &session, bsoncxx::v_noabi::types::bson_value::view id)
	Opens a gridfs::downloader to read a GridFS file.
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. The id of the file will be automatically generated as an ObjectId.
uploader	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.
uploader	open_upload_stream_with_id (bsoncxx::v_noabi::types::bson_value::view id, stdx::string_view filename, const options::gridfs::upload &options={})
	Opens a gridfs::uploader to create a new GridFS file.
uploader	open_upload_stream_with_id (const client_session &session, bsoncxx::v_noabi::types::bson_value::view id, stdx::string_view filename, const options::gridfs::upload &options={})
	Opens a gridfs::uploader to create a new GridFS file.
	operator bool () const noexcept
	Returns true if the bucket is valid, meaning it was not default constructed or moved from.
bucket &	operator= (bucket &&) noexcept
	Move assigns a bucket.
bucket &	operator= (const bucket &)
	Copy assigns a bucket.
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. The id of the file will be automatically generated as an ObjectId.
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. The id of the file will be automatically generated as an ObjectId.
void	upload_from_stream_with_id (bsoncxx::v_noabi::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.
void	upload_from_stream_with_id (const client_session &session, bsoncxx::v_noabi::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.

Constructor & Destructor Documentation

bucket() [1/3]

mongocxx::v_noabi::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.

bucket() [2/3]

mongocxx::v_noabi::gridfs::bucket::bucket ( bucket && )

noexcept

Move constructs a bucket.

bucket() [3/3]

mongocxx::v_noabi::gridfs::bucket::bucket

(

const bucket &

)

Copy constructs a bucket.

~bucket()

mongocxx::v_noabi::gridfs::bucket::~bucket

(

)

Destroys a bucket.

Member Function Documentation

bucket_name()

stdx::string_view mongocxx::v_noabi::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::v_noabi::gridfs::bucket::delete_file

(

bsoncxx::v_noabi::types::bson_value::view

id

)

Deletes a GridFS file from the bucket.

Parameters

id	The id of the file to be deleted.

Exceptions

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

delete_file() [2/2]

void mongocxx::v_noabi::gridfs::bucket::delete_file	(	const client_session &	session,
		bsoncxx::v_noabi::types::bson_value::view	id )

Deletes a GridFS file from the bucket.

Parameters

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

Exceptions

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

download_to_stream() [1/4]

void mongocxx::v_noabi::gridfs::bucket::download_to_stream	(	bsoncxx::v_noabi::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::v_noabi::gridfs_exception	if the requested file does not exist, or if the requested file has been corrupted.
mongocxx::v_noabi::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::v_noabi::gridfs::bucket::download_to_stream	(	bsoncxx::v_noabi::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::v_noabi::gridfs_exception	if the requested file does not exist, or if the requested file has been corrupted.
mongocxx::v_noabi::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.

Parameters

start	The byte offset to the beginning of content to download.
end	The byte offset to the end of content to download.

download_to_stream() [3/4]

void mongocxx::v_noabi::gridfs::bucket::download_to_stream	(	const client_session &	session,
		bsoncxx::v_noabi::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::v_noabi::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::v_noabi::gridfs_exception	if the requested file does not exist, or if the requested file has been corrupted.
mongocxx::v_noabi::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::v_noabi::gridfs::bucket::download_to_stream	(	const client_session &	session,
		bsoncxx::v_noabi::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

session	The mongocxx::v_noabi::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::v_noabi::gridfs_exception	if the requested file does not exist, or if the requested file has been corrupted.
mongocxx::v_noabi::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.

Parameters

start	The byte offset to the beginning of content to download.
end	The byte offset to the end of content to download.

find() [1/2]

cursor mongocxx::v_noabi::gridfs::bucket::find	(	bsoncxx::v_noabi::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::v_noabi::cursor with the results. If the query fails, the cursor throws mongocxx::v_noabi::query_exception when the returned cursor is iterated.

Exceptions

mongocxx::v_noabi::logic_error

if the options are invalid, or if the unsupported option modifiers "$query" or "$explain" are used.

See also

• mongocxx::v_noabi::collection::find.

find() [2/2]

cursor mongocxx::v_noabi::gridfs::bucket::find	(	const client_session &	session,
		bsoncxx::v_noabi::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::v_noabi::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::v_noabi::cursor with the results. If the query fails, the cursor throws mongocxx::v_noabi::query_exception when the returned cursor is iterated.

Exceptions

mongocxx::v_noabi::logic_error

if the options are invalid, or if the unsupported option modifiers "$query" or "$explain" are used.

See also

• mongocxx::v_noabi::collection::find.

open_download_stream() [1/2]

downloader mongocxx::v_noabi::gridfs::bucket::open_download_stream

(

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

open_download_stream() [2/2]

downloader mongocxx::v_noabi::gridfs::bucket::open_download_stream	(	const client_session &	session,
		bsoncxx::v_noabi::types::bson_value::view	id )

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

Parameters

session	The mongocxx::v_noabi::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::v_noabi::gridfs_exception	if the requested file does not exist, or if the requested file has been corrupted.
mongocxx::v_noabi::query_exception	if an error occurs when reading from the files collection for this bucket.

open_upload_stream() [1/2]

uploader mongocxx::v_noabi::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::v_noabi::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::v_noabi::logic_error	if options are invalid.
mongocxx::v_noabi::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::v_noabi::operation_exception	if an error occurs when building GridFS indexes.

open_upload_stream() [2/2]

uploader mongocxx::v_noabi::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::v_noabi::logic_error	if options are invalid.
mongocxx::v_noabi::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::v_noabi::operation_exception	if an error occurs when building GridFS indexes.

open_upload_stream_with_id() [1/2]

uploader mongocxx::v_noabi::gridfs::bucket::open_upload_stream_with_id	(	bsoncxx::v_noabi::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::v_noabi::logic_error	if options are invalid.
mongocxx::v_noabi::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::v_noabi::operation_exception	if an error occurs when building GridFS indexes.

open_upload_stream_with_id() [2/2]

uploader mongocxx::v_noabi::gridfs::bucket::open_upload_stream_with_id	(	const client_session &	session,
		bsoncxx::v_noabi::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::v_noabi::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::v_noabi::logic_error	if options are invalid.
mongocxx::v_noabi::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::v_noabi::operation_exception	if an error occurs when building GridFS indexes.

operator bool()

mongocxx::v_noabi::gridfs::bucket::operator bool ( ) const

explicitnoexcept

Returns true if the bucket is valid, meaning it was not default constructed or moved from.

operator=() [1/2]

bucket & mongocxx::v_noabi::gridfs::bucket::operator= ( bucket && )

noexcept

Move assigns a bucket.

operator=() [2/2]

bucket & mongocxx::v_noabi::gridfs::bucket::operator=

(

const bucket &

)

Copy assigns a bucket.

upload_from_stream() [1/2]

result::gridfs::upload mongocxx::v_noabi::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::v_noabi::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::v_noabi::logic_error	if options are invalid.
mongocxx::v_noabi::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::v_noabi::gridfs_exception	if the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::v_noabi::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::v_noabi::operation_exception	if an error occurs when building GridFS indexes.

upload_from_stream() [2/2]

result::gridfs::upload mongocxx::v_noabi::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::v_noabi::logic_error	if options are invalid.
mongocxx::v_noabi::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::v_noabi::gridfs_exception	if the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::v_noabi::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::v_noabi::operation_exception	if an error occurs when building GridFS indexes.

upload_from_stream_with_id() [1/2]

void mongocxx::v_noabi::gridfs::bucket::upload_from_stream_with_id	(	bsoncxx::v_noabi::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::v_noabi::logic_error	if options are invalid.
mongocxx::v_noabi::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::v_noabi::gridfs_exception	if the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::v_noabi::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::v_noabi::operation_exception	if an error occurs when building GridFS indexes.

upload_from_stream_with_id() [2/2]

void mongocxx::v_noabi::gridfs::bucket::upload_from_stream_with_id	(	const client_session &	session,
		bsoncxx::v_noabi::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::v_noabi::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::v_noabi::logic_error	if options are invalid.
mongocxx::v_noabi::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::v_noabi::gridfs_exception	if the uploader requires more than 2^31-1 chunks to store the file at the requested chunk size.
mongocxx::v_noabi::query_exception	if an error occurs when reading from the files collection for this bucket.
mongocxx::v_noabi::operation_exception	if an error occurs when building GridFS indexes.

---

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

• mongocxx/v_noabi/mongocxx/gridfs/bucket.hpp