MySQL Connector/C++
MySQL connector library for C and C++ applications
Functions | Macros
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_tmysqlx_collection_find (mysqlx_collection_t *collection, const char *criteria)
 Execute a collection FIND statement with a specific find criteria. More...
 
mysqlx_result_tmysqlx_collection_add (mysqlx_collection_t *collection,...)
 Add a set of new documents to a collection. More...
 
mysqlx_result_tmysqlx_collection_remove (mysqlx_collection_t *collection, const char *criteria)
 Remove documents from a collection. More...
 
mysqlx_result_tmysqlx_collection_modify_set (mysqlx_collection_t *collection, const char *criteria,...)
 Modify documents in the collection. More...
 
mysqlx_result_tmysqlx_collection_modify_unset (mysqlx_collection_t *collection, const char *criteria,...)
 Unset fields in documents from the collection. More...
 
mysqlx_result_tmysqlx_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_tmysqlx_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_tmysqlx_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_tmysqlx_collection_remove_new (mysqlx_collection_t *collection)
 Create a statement which removes documents from a collection. More...
 
mysqlx_stmt_tmysqlx_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
collectioncollection handle
[out]countthe 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
collectioncollection handle
criteriacriteria 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
collectioncollection 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
collectioncollection handle
criteriacriteria 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
collectioncollection handle
criteriacriteria 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
collectioncollection handle
criteriacriteria 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
collectioncollection handle
criteriacriteria selecting documents to be modified; if this parameter is NULL then all documents are modified
patch_specpatch 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
stmtmodify statement
patch_specpatch 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
collectioncollection 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
stmtstatement handle
projprojection 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
collectioncollection 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
stmtstatement 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
collectioncollection 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
collectioncollection 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
stmthandle 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
stmthandle 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
stmthandle 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
stmthandle 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
stmthandle 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
tabletable handle
[out]countthe number of rows in a given table is returned through the parameter
Returns
RESULT_OK - on success; RESULT_ERROR - on error