Statements operating on document collections

Functions
int	mysqlx_collection_count (mysqlx_collection_t *collection, uint64_t *count)
	Return a number of documents in a collection. More...
mysqlx_result_t *	mysqlx_collection_find (mysqlx_collection_t *collection, const char *criteria)
	Execute a collection FIND statement with a specific find criteria. More...
mysqlx_result_t *	mysqlx_collection_add (mysqlx_collection_t *collection,...)
	Add a set of new documents to a collection. More...
mysqlx_result_t *	mysqlx_collection_remove (mysqlx_collection_t *collection, const char *criteria)
	Remove documents from a collection. More...
mysqlx_result_t *	mysqlx_collection_modify_set (mysqlx_collection_t *collection, const char *criteria,...)
	Modify documents in the collection. More...
mysqlx_result_t *	mysqlx_collection_modify_unset (mysqlx_collection_t *collection, const char *criteria,...)
	Unset fields in documents from the collection. More...
mysqlx_result_t *	mysqlx_collection_modify_patch (mysqlx_collection_t *collection, const char *criteria, const char *patch_spec)
	Apply a given patch to documents in a collection. More...
int	mysqlx_set_modify_patch (mysqlx_stmt_t *stmt, const char *patch_spec)
	Set a given patch for a modify statement to be applied to documents in a collection after executing the statement. More...
mysqlx_stmt_t *	mysqlx_collection_find_new (mysqlx_collection_t *collection)
	Create a statement which finds documents in a collection. More...
int	mysqlx_set_find_projection (mysqlx_stmt_t *stmt, const char *proj)
	Specify a projection for a collection find query. More...
mysqlx_stmt_t *	mysqlx_collection_add_new (mysqlx_collection_t *collection)
	Create a statement which adds documents to a collection. More...
int	mysqlx_set_add_document (mysqlx_stmt_t *stmt, const char *json_doc)
	Specify a document to be added to a collection. More...
mysqlx_stmt_t *	mysqlx_collection_remove_new (mysqlx_collection_t *collection)
	Create a statement which removes documents from a collection. More...
mysqlx_stmt_t *	mysqlx_collection_modify_new (mysqlx_collection_t *collection)
	Create a statement which modifies documents in a collection. More...
int	mysqlx_set_modify_set (mysqlx_stmt_t *stmt,...)
	Set fields in a document to given values. More...
int	mysqlx_set_modify_unset (mysqlx_stmt_t *stmt,...)
	Unset fields in a document. More...
int	mysqlx_set_modify_array_insert (mysqlx_stmt_t *stmt,...)
	Insert elements into array fields in a document. More...
int	mysqlx_set_modify_array_append (mysqlx_stmt_t *stmt,...)
	Append to array fields in a document. More...
int	mysqlx_set_modify_array_delete (mysqlx_stmt_t *stmt,...)
	Delete elements from array fields in a document. More...
int	mysqlx_table_count (mysqlx_table_t *table, uint64_t *count)
	Return a number of rows in a table. More...

Macros
#define	mysqlx_set_find_criteria   mysqlx_set_where
	A macro defining a function for setting criteria for FIND operation. More...
#define	mysqlx_set_find_limit_and_offset(STMT, LIM, OFFS)   mysqlx_set_limit_and_offset(STMT, LIM, OFFS)
	A macro defining a function for setting LIMIT for DELETE operation. More...
#define	mysqlx_set_find_order_by   mysqlx_set_order_by
	A macro defining a function for setting ORDER BY for SELECT operation. More...
#define	mysqlx_set_find_row_locking   mysqlx_set_row_locking
	A macro defining a function for setting row locking mode for FIND operation. More...
#define	mysqlx_set_remove_criteria   mysqlx_set_where
	A macro defining a function for setting WHERE for REMOVE operation. More...
#define	mysqlx_set_remove_order_by   mysqlx_set_order_by
	A macro defining a function for setting ORDER BY for REMOVE operation. More...
#define	mysqlx_set_remove_limit_and_offset   mysqlx_set_limit_and_offset
	A macro defining a function for setting LIMIT for REMOVE operation. More...
#define	mysqlx_set_modify_criteria   mysqlx_set_where
	A macro defining a function for setting WHERE for MODIFY operation. More...
#define	mysqlx_set_select_row_locking   mysqlx_set_row_locking
	A macro defining a function for setting row locking mode for SELECT operation. More...

Detailed Description

Macro Definition Documentation

mysqlx_set_find_criteria

#define mysqlx_set_find_criteria   mysqlx_set_where

A macro defining a function for setting criteria for FIND operation.

See also

mysqlx_set_where()

mysqlx_set_find_limit_and_offset

#define mysqlx_set_find_limit_and_offset	(		STMT,
			LIM,
			OFFS
	)		mysqlx_set_limit_and_offset(STMT, LIM, OFFS)

A macro defining a function for setting LIMIT for DELETE operation.

See also

mysqlx_set_limit_and_offset()

mysqlx_set_find_order_by

#define mysqlx_set_find_order_by   mysqlx_set_order_by

A macro defining a function for setting ORDER BY for SELECT operation.

See also

mysqlx_set_order_by()

mysqlx_set_find_row_locking

#define mysqlx_set_find_row_locking   mysqlx_set_row_locking

A macro defining a function for setting row locking mode for FIND operation.

See also

mysqlx_set_row_locking()

mysqlx_set_remove_criteria

#define mysqlx_set_remove_criteria   mysqlx_set_where

A macro defining a function for setting WHERE for REMOVE operation.

See also

mysqlx_set_where()

mysqlx_set_remove_order_by

#define mysqlx_set_remove_order_by   mysqlx_set_order_by

A macro defining a function for setting ORDER BY for REMOVE operation.

See also

mysqlx_set_order_by()

mysqlx_set_remove_limit_and_offset

#define mysqlx_set_remove_limit_and_offset   mysqlx_set_limit_and_offset

A macro defining a function for setting LIMIT for REMOVE operation.

See also

mysqlx_set_limit_and_offset()

mysqlx_set_modify_criteria

#define mysqlx_set_modify_criteria   mysqlx_set_where

A macro defining a function for setting WHERE for MODIFY operation.

See also

mysqlx_set_where()

mysqlx_set_select_row_locking

#define mysqlx_set_select_row_locking   mysqlx_set_row_locking

A macro defining a function for setting row locking mode for SELECT operation.

See also

mysqlx_set_row_locking()

Function Documentation

mysqlx_collection_count()

int mysqlx_collection_count	(	mysqlx_collection_t *	collection,
		uint64_t *	count
	)

Return a number of documents in a collection.

Parameters

	collection	collection handle
[out]	count	the number of documents in a given collection is returned through the parameter

Returns

RESULT_OK - on success; RESULT_ERROR - on error

mysqlx_collection_find()

mysqlx_result_t * mysqlx_collection_find	(	mysqlx_collection_t *	collection,
		const char *	criteria
	)

Execute a collection FIND statement with a specific find criteria.

Parameters

collection	collection handle
criteria	criteria for finding documents; if this parameter is NULL then all documents are returned

Returns

handle to the query results. NULL is returned only in case of an error. The error details can be obtained using mysqlx_error() function

mysqlx_collection_add()

mysqlx_result_t * mysqlx_collection_add	(	mysqlx_collection_t *	collection,
			...
	)

Add a set of new documents to a collection.

Each document is defined by a JSON string like "{ \"key_1\": value_1, ..., \"key_N\": value_N }"

Parameters

collection	collection handle
...	list of parameters containing the character JSON strings describing documents to be added. Each parameter is a separate document. The list has to be terminated by PARAM_END macro

Returns

handle to the statement result. NULL is returned only in case of an error. The error details can be obtained using mysqlx_error() function

Each document must have a unique identifier which is stored in _id field of the document. Document identifiers are character strings no longer than 32 characters. If added document does not have _id field, a unique identifier will be generated for it. Document identifier generated by given collection add operation can be examined using mysqlx_fetch_generated_id() function. Generated document identifiers are strings of 32 hexadecimal digits, like this one 0512020981044082E6119DFA0E4C0584.

Note

Generated document identifiers are based on UUIDs but they are not valid UUIDs (fields are reversed).

See also

mysqlx_collection_add_new()

mysqlx_collection_remove()

mysqlx_result_t * mysqlx_collection_remove	(	mysqlx_collection_t *	collection,
		const char *	criteria
	)

Remove documents from a collection.

Parameters

collection	collection handle
criteria	criteria selecting documents to be removed; if this parameter is NULL, all documents are removed

Returns

handle to the statement result. NULL is returned only in case of an error. The error details can be obtained using mysqlx_error() function

mysqlx_collection_modify_set()

mysqlx_result_t * mysqlx_collection_modify_set	(	mysqlx_collection_t *	collection,
		const char *	criteria,
			...
	)

Modify documents in the collection.

Parameters

collection	collection handle
criteria	criteria selecting documents to be modified; if this parameter is NULL then all documents are modified
...	list of parameters that come as triplets <field_path, value_type, value> Each triplet specifies a field inside a document that should be modified (field_path) and the new value for that field. The value_type is the type identifier for the data type of value (see mysqlx_data_type_t enum) The list is terminated by PARAM_END. For MYSQLX_TYPE_BYTES there will be one extra parameter specifying the length of the binary data: <field_path, MYSQLX_TYPE_BYTES, value, length> The X DevAPI for C defines the convenience macros that help to specify the types and values: See PARAM_SINT(), PARAM_UINT(), PARAM_FLOAT(), PARAM_DOUBLE(), PARAM_BYTES(), PARAM_STRING(), PARAM_EXPR():

..., "a_key", PARAM_STRING("New Text Value"), "b_key", PARAM_EXPR("b_key-1000"), PARAM_END

Returns

handle to the statement result NULL is returned only in case of an error. The error details can be obtained using mysqlx_error() function

mysqlx_collection_modify_unset()

mysqlx_result_t * mysqlx_collection_modify_unset	(	mysqlx_collection_t *	collection,
		const char *	criteria,
			...
	)

Unset fields in documents from the collection.

Parameters

collection	collection handle
criteria	criteria selecting documents to be modified; if this parameter is NULL then all documents are modified
...	list of field paths that should be unset; The list end is marked using PARAM_END

Returns

handle to the statement result. NULL is returned only in case of an error. The error details can be obtained using mysqlx_error() function

mysqlx_collection_modify_patch()

mysqlx_result_t * mysqlx_collection_modify_patch	(	mysqlx_collection_t *	collection,
		const char *	criteria,
		const char *	patch_spec
	)

Apply a given patch to documents in a collection.

Parameters

collection	collection handle
criteria	criteria selecting documents to be modified; if this parameter is NULL then all documents are modified
patch_spec	patch specification given as a character string and interpreted like a JSON documents, but values of fields are interpreted as expressions

Returns

handle to the statement result. NULL is returned only in case of an error. The error details can be obtained using mysqlx_error() function

mysqlx_set_modify_patch()

int mysqlx_set_modify_patch	(	mysqlx_stmt_t *	stmt,
		const char *	patch_spec
	)

Set a given patch for a modify statement to be applied to documents in a collection after executing the statement.

Parameters

stmt	modify statement
patch_spec	patch specification given as a character string and interpreted like a JSON documents, but values of fields are interpreted as expressions

Returns

RESULT_OK - on success; RESULT_ERROR - on error

mysqlx_collection_find_new()

mysqlx_stmt_t * mysqlx_collection_find_new

(

mysqlx_collection_t *

collection

)

Create a statement which finds documents in a collection.

Parameters

collection

collection handle

Returns

handle for the newly created FIND statement. NULL can be returned only in case when there are problems allocating memory, which normally should not happen. It is very unlikely for this function to end with an error because it does not do any parsing, parameter checking etc.

Note

To actually execute the operation, use mysqlx_execute().

mysqlx_set_find_projection()

int mysqlx_set_find_projection	(	mysqlx_stmt_t *	stmt,
		const char *	proj
	)

Specify a projection for a collection find query.

The projection, if present, specifies mapping from documents found by the query to new documents returned in the final result.

Parameters

stmt	statement handle
proj	projection specification describing JSON document projections as "{ \"proj1\": expr1, ..., \"projN\": exprN }". Expressions used in the projection can refer to fields in the original document using $.path.to.field syntax.

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

This function can be only called for the collection FIND statements

See also

mysqlsx_collection_find_new()

mysqlx_collection_add_new()

mysqlx_stmt_t * mysqlx_collection_add_new

(

mysqlx_collection_t *

collection

)

Create a statement which adds documents to a collection.

Parameters

collection

collection handle

Returns

handle for the newly created ADD statement. NULL can be returned only in case when there are problems allocating memory, which normally should not happen. It is very unlikely for this function to end with an error because it does not do any parsing, parameter checking etc.

Note

To actually execute the operation, use mysqlx_execute() after specifying documents to be added.

mysqlx_set_add_document()

int mysqlx_set_add_document	(	mysqlx_stmt_t *	stmt,
		const char *	json_doc
	)

Specify a document to be added to a collection.

The function provides the document data for the ADD statement as a JSON string like "{ \"key_1\": value_1, ..., \"key_N\": value_N }" User code must ensure the validity of the document because it is not checked until receiving the query on the server side.

Note

key names and string values in a JSON string must be given in quotes and such quotes need to be escaped.

Parameters

stmt	statement handle
json_doc	- the JSON string describing document to add

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

Each new call provides the values for the new document, which can be used for multi-document add operations.

User can provide document id as a value of _id field, otherwise document id is generated by the add operation. Document id must be a string - setting _id to a non-string value triggers an error.

mysqlx_collection_remove_new()

mysqlx_stmt_t * mysqlx_collection_remove_new

(

mysqlx_collection_t *

collection

)

Create a statement which removes documents from a collection.

Parameters

collection

collection handle

Returns

handle for the newly created REMOVE statement. NULL can be returned only in case when there are problems allocating memory, which normally should not happen. It is very unlikely for this function to end with an error because it does not do any parsing, parameter checking etc.

Note

To actually execute the statement, use mysqlx_execute()

mysqlx_collection_modify_new()

mysqlx_stmt_t * mysqlx_collection_modify_new

(

mysqlx_collection_t *

collection

)

Create a statement which modifies documents in a collection.

Parameters

collection

collection handle

Returns

handle for the newly created MODIFY statement. NULL can be returned only in case when there are problems allocating memory, which normally should not happen. It is very unlikely for this function to end with an error because it does not do any parsing, parameter checking etc.

Note

To actually execute the statement, use mysqlx_execute() after specifying modifications that should be performed.

mysqlx_set_modify_set()

int mysqlx_set_modify_set	(	mysqlx_stmt_t *	stmt,
			...
	)

Set fields in a document to given values.

Parameters

stmt

handle to MODIFY statement

...

list of parameters that come as triplets <field_path, value_type, value> Each triplet represents a value inside a document that can be located by field_path. The value_type is the type identifier for the data type of value (see mysqlx_data_type_t enum) The list is terminated by PARAM_END. For MYSQLX_TYPE_BYTES there will be one extra parameter specifying the length of the binary data: <field_path, MYSQLX_TYPE_BYTES, value, length>

Note

For the convenience the code can use PARAM_TTT(val) macros instead of (MYSQLX_TYPE_TTT, value) pairs (see mysqlx_stmt_bind()).

Returns

RESULT_OK - on success; RESULT_ERROR - on error

mysqlx_set_modify_unset()

int mysqlx_set_modify_unset	(	mysqlx_stmt_t *	stmt,
			...
	)

Unset fields in a document.

Parameters

stmt	handle to MODIFY statement
...	list of paths to the documents fields that should be unset. Each entry in this list is a character string. The list is terminated by PARAM_END.

Returns

RESULT_OK - on success; RESULT_ERROR - on error

mysqlx_set_modify_array_insert()

int mysqlx_set_modify_array_insert	(	mysqlx_stmt_t *	stmt,
			...
	)

Insert elements into array fields in a document.

Parameters

stmt	handle to MODIFY statement
...	list of parameters that come as triplets <field_path, value_type, value> Each triplet represents a position in an array field of a document, given by field_path, and a value to be inserted in that position. The value_type is the type identifier for the data type of value (see mysqlx_data_type_t enum). The list is terminated by PARAM_END.

Note

For the convenience the code can use PARAM_TTT(val) macros instead of (MYSQLX_TYPE_TTT, value) pairs (see mysqlx_stmt_bind()).

Returns

RESULT_OK - on success; RESULT_ERROR - on error

mysqlx_set_modify_array_append()

int mysqlx_set_modify_array_append	(	mysqlx_stmt_t *	stmt,
			...
	)

Append to array fields in a document.

Parameters

stmt	handle to MODIFY statement
...	list of parameters that come as triplets <field_path, value_type, value>. Each triplet specifies an array field in a document, given by field_path, and a value that should be appended to that array. The value_type is the type identifier for the data type of value (see mysqlx_data_type_t enum). The list is terminated by PARAM_END.

Note

For the convenience the code can use PARAM_TTT(val) macros instead of (MYSQLX_TYPE_TTT, value) pairs (see mysqlx_stmt_bind()).

Returns

RESULT_OK - on success; RESULT_ERROR - on error

mysqlx_set_modify_array_delete()

int mysqlx_set_modify_array_delete	(	mysqlx_stmt_t *	stmt,
			...
	)

Delete elements from array fields in a document.

Parameters

stmt	handle to MODIFY statement
...	list of paths to array elements that should be deleted from their arrays. The list is terminated by PARAM_END.

Returns

RESULT_OK - on success; RESULT_ERROR - on error

mysqlx_table_count()

int mysqlx_table_count	(	mysqlx_table_t *	table,
		uint64_t *	count
	)

Return a number of rows in a table.

Parameters

	table	table handle
[out]	count	the number of rows in a given table is returned through the parameter

Returns

RESULT_OK - on success; RESULT_ERROR - on error