A MongoTool is a datatype that allows access to the data stored within a MongoDB instance. More...

#include <mongodb_tool.h>

Public Member Functions
bool	SetMongoToolDatabaseAndCollection (MongoTool tool_p, const char db_s, const char *collection_s)
	Set the database and collection that a MongoTool will use. More...

bool	SetMongoToolDatabase (MongoTool tool_p, const char db_s)
	Set the database that a MongoTool will use. More...

bool	SetMongoToolCollection (MongoTool tool_p, const char collection_s)
	Set the collection that a MongoTool will use. More...

MongoTool *	AllocateMongoTool (mongoc_client_t client_p, struct MongoClientManager mongo_manager_p)
	This allocates a MongoTool that connects to the MongoDB instance specified in the grassroots.config file. More...

void	FreeMongoTool (MongoTool *tool_p)
	Delete a MongoTool and release the connection that it held. More...

bson_oid_t *	InsertJSONIntoMongoCollection (MongoTool tool_p, json_t json_p)
	Insert data from a given JSON fragment using a given MongoTool. More...

bool	UpdateMongoDocumentsByJSON (MongoTool tool_p, const json_t query_p, const json_t *update_p, const bool multiple_flag)
	Update some MongoDB documents. More...

bool	UpdateMongoDocuments (MongoTool tool_p, const bson_oid_t id_p, const json_t *json_p, const bool multiple_flag)
	Create a BSON object from the given id and use it to update some MongoDB documents. More...

bool	RemoveMongoDocuments (MongoTool tool_p, const json_t selector_json_p, const bool remove_first_match_only_flag)
	Remove some documents from a MongoDB collection. More...

bool	FindMatchingMongoDocumentsByJSON (MongoTool tool_p, const json_t query_json_p, const char *fields_ss, bson_t extra_opts_p)
	Find matching documents for a given query. More...

bool	FindMatchingMongoDocumentsByBSON (MongoTool tool_p, const bson_t query_p, const char *fields_ss, bson_t extra_opts_p)
	Find matching documents for a given query. More...

bool	IterateOverMongoResults (MongoTool tool_p, bool(process_bson_fn)(const bson_t document_p, void data_p), void *data_p)
	Iterate over all of a MongoTool's results. More...

bool	HasMongoQueryResults (MongoTool *tool_p)
	Check whether a MongoTool has any results after running a query. More...

json_t *	GetAllMongoResultsAsJSON (MongoTool tool_p, bson_t query_p, bson_t *extra_opts_p)
	Get all results from a mongodb collection. More...

bool	PopulateJSONWithAllMongoResults (MongoTool tool_p, bson_t query_p, bson_t extra_opts_p, json_t results_array_p)
	Fill an existing json array with all the results from searching a mongodb collection. More...

int32	GetAllMongoResultsForKeyValuePair (MongoTool tool_p, json_t docs_pp, const char const key_s, const char const value_s, const char *fields_ss)
	Get all results for a given key-value query. More...

json_t *	GetCurrentValuesAsJSON (MongoTool tool_p, const char *fields_ss, const size_t num_fields)
	When iterating over a MongoTool's results get the values and increment the current result that the MongoTool is pointing at. More...

json_t *	GetAllExistingMongoResultsAsJSON (MongoTool *tool_p)
	Convert all of a MongoTool's results into JSON array. More...

int32	IsKeyValuePairInCollection (MongoTool tool_p, const char database_s, const char collection_s, const char key_s, const char *value_s)
	Check whether a collection contains any documents with a given key-value pair. More...

const char *	InsertOrUpdateMongoData (MongoTool tool_p, json_t values_p, const char const database_s, const char const collection_s, const char *primary_keys_ss, const size_t num_keys, const char const mapped_id_s, const char *const object_key_s)
	Insert of update data in a set of matching documents. More...

const char *	EasyInsertOrUpdateMongoData (MongoTool tool_p, json_t values_p, const char *const primary_key_id_s)
	Insert of update data in a set of matching documents. More...

bool	CreateIndexForMongoCollection (MongoTool tool_p, char *fields_ss)
	Create an index for the current collection of a MongoTool. More...

bool	RemoveMongoFields (MongoTool tool_p, bson_t selector_p, const char fields_ss, bson_t reply_pp)
	Remove the specified fields from a document. More...

bool	UpdateMongoDocumentsByBSON (MongoTool tool_p, const bson_t query_p, const json_t *update_p, const bool multiple_flag)
	Update some MongoDB documents. More...

bool	AddCollectionCompoundIndex (MongoTool tool_p, const char database_s, const char const collection_s, const char *const keys_ss, const bool unique_flag, const bool sparse_flag)
	Create an index for given set of keys. More...

bool	AddCollectionSingleIndex (MongoTool tool_p, const char database_s, const char const collection_s, const char key_s, const char *index_type_s, const bool unique_flag, const bool sparse_flag)
	Create an index for given key. More...

bool	CreateMongoToolCollection (MongoTool tool_p, const char collection_s, bson_t *opts_p)
	Create a Collection. More...

int	DoesCollectionExist (MongoTool tool_p, const char collection_s)
	Check if a named Collection exists. More...

bool	DropCollectionIndex (MongoTool tool_p, const char index_s)
	Drop an index with a given name from a Collection. More...

Data Fields
const char *	MONGO_ID_S = "_id"
	The identifier used to uniquely specify a MongoDB document. More...

const char *	MONGO_COLLECTION_S = "collection"
	The identifier used to specify a collection name to use. More...

const char *	MONGO_OPERATION_S = "operation"
	The identifier used to specify the operation to perform. More...

const char *	MONGO_OPERATION_INSERT_S = "insert"
	The identifier used to specify an add data to a collection or document. More...

const char *	MONGO_OPERATION_SEARCH_S = "search"
	The identifier used to specify searching for documents. More...

const char *	MONGO_OPERATION_REMOVE_S = "remove"
	The identifier used to specify an remove data from a collection or document. More...

const char *	MONGO_OPERATION_DATA_S = "data"
	The identifier used to specify a JSON fragment denoting operations. More...

const char *	MONGO_OPERATION_FIELDS_S = "fields"
	The identifier used to specify which fields to get the values of for the results of a query. More...

const char *	MONGO_OPERATION_GET_ALL_S = "dump"
	The identifier used to generate a dump of an entire collection. More...

const char *	MONGO_CLAUSE_OPERATOR_S = "operator"
	The identifier used to specify a query operator. More...

const char *	MONGO_CLAUSE_VALUE_S = "value"
	The identifier used to specify a query value. More...

bool	mt_owns_client_flag

struct MongoClientManager *	mt_manager_p

Detailed Description

A MongoTool is a datatype that allows access to the data stored within a MongoDB instance.

Member Function Documentation

◆ SetMongoToolDatabaseAndCollection()

bool SetMongoToolDatabaseAndCollection	(	MongoTool *	tool_p,
		const char *	db_s,
		const char *	collection_s
	)

Set the database and collection that a MongoTool will use.

Parameters

tool_p	The MongoTool to update.
db_s	The database to use.
collection_s	The collection to use.

Returns: true if the MongoTool was updated successfully, false otherwise.

◆ SetMongoToolDatabase()

bool SetMongoToolDatabase	(	MongoTool *	tool_p,
		const char *	db_s
	)

Set the database that a MongoTool will use.

Parameters

tool_p	The MongoTool to update.
db_s	The database to use.

Returns: true if the MongoTool was updated successfully, false otherwise.

◆ SetMongoToolCollection()

bool SetMongoToolCollection	(	MongoTool *	tool_p,
		const char *	collection_s
	)

Set the collection that a MongoTool will use.

Parameters

tool_p	The MongoTool to update.
collection_s	The collection to use.

Returns: true if the MongoTool was updated successfully, false otherwise.

◆ AllocateMongoTool()

MongoTool * AllocateMongoTool	(	mongoc_client_t *	client_p,
		struct MongoClientManager *	mongo_manager_p
	)

This allocates a MongoTool that connects to the MongoDB instance specified in the grassroots.config file.

Returns: A MongoTool or NULL upon error.

See also: InitMongoDB

◆ FreeMongoTool()

void FreeMongoTool ( MongoTool * tool_p )

Delete a MongoTool and release the connection that it held.

Parameters

tool_p The MongoTool to free.

◆ InsertJSONIntoMongoCollection()

bson_oid_t * InsertJSONIntoMongoCollection	(	MongoTool *	tool_p,
		json_t *	json_p
	)

Insert data from a given JSON fragment using a given MongoTool.

Parameters

tool_p	The MongoTool to use.
json_p	The JSON fragment to insert.

Returns: A pointer to a newly-created BSON id or NULL upon error. This value will need to be freed using FreeMemory() to avoid a memory leak.

◆ UpdateMongoDocumentsByJSON()

bool UpdateMongoDocumentsByJSON	(	MongoTool *	tool_p,
		const json_t *	query_p,
		const json_t *	update_p,
		const bool	multiple_flag
	)

Update some MongoDB documents.

Parameters

tool_p	The MongoTool that will update the MongoDB documents.
query_p	The query used to choose the MongoDB documents that will be updated.
update_p	The update statement specifying the update operation to perform.

Returns: true if the MongoDB documents were updated successfully, false otherwise.

◆ UpdateMongoDocuments()

bool UpdateMongoDocuments	(	MongoTool *	tool_p,
		const bson_oid_t *	id_p,
		const json_t *	json_p,
		const bool	multiple_flag
	)

Create a BSON object from the given id and use it to update some MongoDB documents.

Parameters

tool_p	The MongoTool that will update the MongoDB documents.
id_p	The id to update the MongoDB documents with.
json_p	The update statement specifying the update operation to perform.

Returns: true if the MongoDB documents were updated successfully, false otherwise.

See also: UpdateMongoDocumentByBSON

◆ RemoveMongoDocuments()

bool RemoveMongoDocuments	(	MongoTool *	tool_p,
		const json_t *	selector_json_p,
		const bool	remove_first_match_only_flag
	)

Remove some documents from a MongoDB collection.

Parameters

tool_p	The MongoTool that will amend the collection.
selector_json_p	The statement used to choose which documents to remove.
remove_first_match_only_flag	If this is `true` then only the first matching document will be removed. If this is `false` then all matching documents will be removed.

Returns: true if any matching MongoDB documents were removed successfully, false otherwise.

◆ FindMatchingMongoDocumentsByJSON()

bool FindMatchingMongoDocumentsByJSON	(	MongoTool *	tool_p,
		const json_t *	query_json_p,
		const char **	fields_ss,
		bson_t *	extra_opts_p
	)

Find matching documents for a given query.

Parameters

tool_p	The MongoTool that will search the collection.
query_json_p	The statement used to choose which documents to store.
fields_ss	If specified, then just the keys listed in this array along with their associated values will be stored. This array must have `NULL` as its final element. If this is `NULL`, then all of the keys and values in the matching documents will be stored.

Returns: true if any matching MongoDB documents were found successfully, false otherwise.

◆ FindMatchingMongoDocumentsByBSON()

bool FindMatchingMongoDocumentsByBSON	(	MongoTool *	tool_p,
		const bson_t *	query_p,
		const char **	fields_ss,
		bson_t *	extra_opts_p
	)

Find matching documents for a given query.

Parameters

tool_p	The MongoTool that will search the collection.
query_p	The statement used to choose which documents to store.
fields_ss	If specified, then just the keys listed in this array along with their associated values will be stored. This array must have `NULL` as its final element. If this is `NULL`, then all of the keys and values in the matching documents will be stored.

Returns: true if any matching MongoDB documents were found successfully, false otherwise.

◆ IterateOverMongoResults()

bool IterateOverMongoResults	(	MongoTool *	tool_p,
		bool()(const bson_t document_p, void *data_p)	process_bson_fn,
		void *	data_p
	)

Iterate over all of a MongoTool's results.

Parameters

tool_p	The MongoTool to iterate over.
process_bson_fn	The function that will be called for each bson document in the results.
data_p	Any required custom data that will be passed to the callback function for each bson document.

Returns: true if the MongoDB documents were iterated over successfully, false otherwise.

◆ HasMongoQueryResults()

bool HasMongoQueryResults ( MongoTool * tool_p )

Check whether a MongoTool has any results after running a query.

Parameters

tool_p The MongoTool to check.

Returns: true if the MongoTool has results, false otherwise.

◆ GetAllMongoResultsAsJSON()

json_t * GetAllMongoResultsAsJSON	(	MongoTool *	tool_p,
		bson_t *	query_p,
		bson_t *	extra_opts_p
	)

Get all results from a mongodb collection.

Parameters

tool_p	The MongoTool to get the results with.
query_p	The query to run.

Returns: A json_t array with all of the results from the search or NULL upon error.

◆ PopulateJSONWithAllMongoResults()

bool PopulateJSONWithAllMongoResults	(	MongoTool *	tool_p,
		bson_t *	query_p,
		bson_t *	extra_opts_p,
		json_t *	results_array_p
	)

Fill an existing json array with all the results from searching a mongodb collection.

Parameters

tool_p	The MongoTool to get the results with.
query_p	The query to run.
results_array_p	A json_t array with all of the results from the search.
<code>true</code>	if the search and retrieval of the results was successful, `false` otherwise.

◆ GetAllMongoResultsForKeyValuePair()

int32 GetAllMongoResultsForKeyValuePair	(	MongoTool *	tool_p,
		json_t **	docs_pp,
		const char *const	key_s,
		const char *const	value_s,
		const char **	fields_ss
	)

Get all results for a given key-value query.

Parameters

tool_p	The MongoTool to get the results with.
docs_pp	A pointer to a JSON array pointer where the results will be placed.
key_s	The key of the query.
value_s	The value of the query.
fields_ss	If specified, then just the keys listed in this array along with their associated values will be stored. This array must have `NULL` as its final element. If this is `NULL`, then all of the keys and values in the matching documents will be stored.

Returns: The number of results found or -1 on error.

◆ GetCurrentValuesAsJSON()

json_t * GetCurrentValuesAsJSON	(	MongoTool *	tool_p,
		const char **	fields_ss,
		const size_t	num_fields
	)

When iterating over a MongoTool's results get the values and increment the current result that the MongoTool is pointing at.

Parameters

tool_p	The MongoTool to get the results from.
fields_ss	If specified, then just the keys listed in this array along with their associated values will be stored. If this is `NULL`, then all of the keys and values in the matching documents will be stored.
num_fields	The number of entries in fields_ss.

Returns: A newly-allocated json_object with the key-value pair results or NULL upon error.

◆ GetAllExistingMongoResultsAsJSON()

json_t * GetAllExistingMongoResultsAsJSON ( MongoTool * tool_p )

Convert all of a MongoTool's results into JSON array.

Parameters

tool_p The MongoTool to get the results with.

Returns: The newly-allocated JSON array containing the results or NULL upon error.

◆ IsKeyValuePairInCollection()

int32 IsKeyValuePairInCollection	(	MongoTool *	tool_p,
		const char *	database_s,
		const char *	collection_s,
		const char *	key_s,
		const char *	value_s
	)

Check whether a collection contains any documents with a given key-value pair.

Parameters

tool_p	The MongoTool to check with.
database_s	The database to check.
collection_s	The collection to check.
key_s	The key to search for.
value_s	The value to search for.

Returns: The number of matching documents in the given collection or -1 upon error.

◆ InsertOrUpdateMongoData()

const char * InsertOrUpdateMongoData	(	MongoTool *	tool_p,
		json_t *	values_p,
		const char *const	database_s,
		const char *const	collection_s,
		const char **	primary_keys_ss,
		const size_t	num_keys,
		const char *const	mapped_id_s,
		const char *const	object_key_s
	)

Insert of update data in a set of matching documents.

Parameters

tool_p	The MongoTool to update with.
values_p	The JSON values to add to the documents.
database_s	The database to check.
collection_s	The collection to check.
primary_key_id_s	The key used to get the values from values_p that the matching documents will be updated with.
mapped_id_s	The key to use for the query to get the documents with. If this is `NULL` then the primary_key_id_s will be used instead.
object_key_s	The key used to insert values_p into the matching documents.

Returns: An error string or NULL if the updates were successful.

◆ EasyInsertOrUpdateMongoData()

const char * EasyInsertOrUpdateMongoData	(	MongoTool *	tool_p,
		json_t *	values_p,
		const char *const	primary_key_id_s
	)

Insert of update data in a set of matching documents.

This calls InsertOrUpdateMongoData() with NULL entries for the database, collection, mapped_id_s and object_key_s values.

Parameters

tool_p	The MongoTool to update with.
values_p	The JSON values to add to the documents.
primary_key_id_s	The key used to get the values from values_p that the matching documents will be updated with.

Returns: An error string or NULL if the updates were successful.

◆ CreateIndexForMongoCollection()

bool CreateIndexForMongoCollection	(	MongoTool *	tool_p,
		char **	fields_ss
	)

Create an index for the current collection of a MongoTool.

Parameters

tool_p	The MongoTool whose collection will have the new index.
fields_ss	An array of field names to use to generate the unique or compound index. The final element in this array must be `NULL`.

Returns: true if the values were added successfully, false otherwise.

◆ RemoveMongoFields()

bool RemoveMongoFields	(	MongoTool *	tool_p,
		bson_t *	selector_p,
		const char **	fields_ss,
		bson_t **	reply_pp
	)

Remove the specified fields from a document.

Parameters

tool_p	The MongoTool to use to remove the fields with.
selector_p	The query to find the document to alter.
fields_ss	An array of strings specifying the fields to remove. This array must have a `NULL` as its final entry.
reply_pp	If you wish to any error messages back then a pointer to a bson_t pointer can be placed here. This can be `NULL`

Returns: true if the fields were removed successfully, false otherwise.

◆ UpdateMongoDocumentsByBSON()

bool UpdateMongoDocumentsByBSON	(	MongoTool *	tool_p,
		const bson_t *	query_p,
		const json_t *	update_p,
		const bool	multiple_flag
	)

Update some MongoDB documents.

Parameters

tool_p	The MongoTool that will update the MongoDB documents.
query_p	The query used to choose the MongoDB documents that will be updated.
update_p	The update statement specifying the update operation to perform.

Returns: true if the MongoDB documents were updated successfully, false otherwise.

◆ AddCollectionCompoundIndex()

bool AddCollectionCompoundIndex	(	MongoTool *	tool_p,
		const char *	database_s,
		const char *const	collection_s,
		const char **const	keys_ss,
		const bool	unique_flag,
		const bool	sparse_flag
	)

Create an index for given set of keys.

Parameters

tool_p	The MongoTool that will be used to create the index.
database_s	The database to that the collection to add the index to is in.
collection_s	The collection to add the index for.
key_ss	An array of keys that will have the index. The final entry must be NULL.
unique_flag	`true` if the values for the key are unique, `false` otherwise. The default value is `false`.
sparse_flag	If `true`, the index only references documents with the specified field. These indexes use less space but behave differently in some situations (particularly sorts). The default value is `false`.

Returns: true if the index was created successfully, false otherwise.

◆ AddCollectionSingleIndex()

bool AddCollectionSingleIndex	(	MongoTool *	tool_p,
		const char *	database_s,
		const char *const	collection_s,
		const char *	key_s,
		const char *	index_type_s,
		const bool	unique_flag,
		const bool	sparse_flag
	)

Create an index for given key.

Parameters

tool_p	The MongoTool that will be used to create the index.
database_s	The database to that the collection to add the index to is in.
collection_s	The collection to add the index for.
key_s	The key that will have the index.
index_type_s	The type of data being indexed if you it is 2d data or something similar. If this is `NULL` then this will be a default index.
unique_flag	`true` if the values for the key are unique, `false` otherwise. The default value is `false`.
sparse_flag	If `true`, the index only references documents with the specified field. These indexes use less space but behave differently in some situations (particularly sorts). The default value is `false`.

Returns: true if the index was created successfully, false otherwise.

◆ CreateMongoToolCollection()

bool CreateMongoToolCollection	(	MongoTool *	tool_p,
		const char *	collection_s,
		bson_t *	opts_p
	)

Create a Collection.

Parameters

tool_p	The MongoTool that will be used to create the index.
collection_s	The name of the collection to create.
opts_p	The MongoDB options for creating the collection. Leave this as `NULL` to use the defaults. See https://www.mongodb.com/docs/manual/reference/command/create/ for more information.

Returns: true if the collection was created successfully, false otherwise.

◆ DoesCollectionExist()

int DoesCollectionExist	(	MongoTool *	tool_p,
		const char *	collection_s
	)

Check if a named Collection exists.

Parameters

tool_p	The MongoTool that will be used to create the index.
collection_s	The name of the collection to check.

Returns: 1 if the collection already exists, 0 if it does not or -1 upon error.

◆ DropCollectionIndex()

bool DropCollectionIndex	(	MongoTool *	tool_p,
		const char *	index_s
	)

Drop an index with a given name from a Collection.

Parameters

tool_p	The MongoTool that will be used to create the index.
index_s	The index to remove.

Returns: true if the index was dropped successfully, false otherwise.

Field Documentation

◆ MONGO_ID_S

const char* MONGO_ID_S = "_id"

The identifier used to uniquely specify a MongoDB document.

◆ MONGO_COLLECTION_S

const char* MONGO_COLLECTION_S = "collection"

The identifier used to specify a collection name to use.

◆ MONGO_OPERATION_S

const char* MONGO_OPERATION_S = "operation"

The identifier used to specify the operation to perform.

◆ MONGO_OPERATION_INSERT_S

const char* MONGO_OPERATION_INSERT_S = "insert"

The identifier used to specify an add data to a collection or document.

◆ MONGO_OPERATION_SEARCH_S

const char* MONGO_OPERATION_SEARCH_S = "search"

The identifier used to specify searching for documents.

◆ MONGO_OPERATION_REMOVE_S

const char* MONGO_OPERATION_REMOVE_S = "remove"

The identifier used to specify an remove data from a collection or document.

◆ MONGO_OPERATION_DATA_S

const char* MONGO_OPERATION_DATA_S = "data"

The identifier used to specify a JSON fragment denoting operations.

◆ MONGO_OPERATION_FIELDS_S

const char* MONGO_OPERATION_FIELDS_S = "fields"

The identifier used to specify which fields to get the values of for the results of a query.

◆ MONGO_OPERATION_GET_ALL_S

const char* MONGO_OPERATION_GET_ALL_S = "dump"

The identifier used to generate a dump of an entire collection.

◆ MONGO_CLAUSE_OPERATOR_S

const char* MONGO_CLAUSE_OPERATOR_S = "operator"

The identifier used to specify a query operator.

◆ MONGO_CLAUSE_VALUE_S

const char* MONGO_CLAUSE_VALUE_S = "value"

The identifier used to specify a query value.

◆ mt_owns_client_flag

bool mt_owns_client_flag

◆ mt_manager_p

struct MongoClientManager* mt_manager_p

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

mongodb_tool.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ SetMongoToolDatabaseAndCollection()

◆ SetMongoToolDatabase()

◆ SetMongoToolCollection()

◆ AllocateMongoTool()

◆ FreeMongoTool()

◆ InsertJSONIntoMongoCollection()

◆ UpdateMongoDocumentsByJSON()

◆ UpdateMongoDocuments()

◆ RemoveMongoDocuments()

◆ FindMatchingMongoDocumentsByJSON()

◆ FindMatchingMongoDocumentsByBSON()

◆ IterateOverMongoResults()

◆ HasMongoQueryResults()

◆ GetAllMongoResultsAsJSON()

◆ PopulateJSONWithAllMongoResults()

◆ GetAllMongoResultsForKeyValuePair()

◆ GetCurrentValuesAsJSON()

◆ GetAllExistingMongoResultsAsJSON()

◆ IsKeyValuePairInCollection()

◆ InsertOrUpdateMongoData()

◆ EasyInsertOrUpdateMongoData()

◆ CreateIndexForMongoCollection()

◆ RemoveMongoFields()

◆ UpdateMongoDocumentsByBSON()

◆ AddCollectionCompoundIndex()

◆ AddCollectionSingleIndex()

◆ CreateMongoToolCollection()

◆ DoesCollectionExist()

◆ DropCollectionIndex()

Field Documentation

◆ MONGO_ID_S

◆ MONGO_COLLECTION_S

◆ MONGO_OPERATION_S

◆ MONGO_OPERATION_INSERT_S

◆ MONGO_OPERATION_SEARCH_S

◆ MONGO_OPERATION_REMOVE_S

◆ MONGO_OPERATION_DATA_S

◆ MONGO_OPERATION_FIELDS_S

◆ MONGO_OPERATION_GET_ALL_S

◆ MONGO_CLAUSE_OPERATOR_S

◆ MONGO_CLAUSE_VALUE_S

◆ mt_owns_client_flag

◆ mt_manager_p