Statement execution

Functions
int	mysqlx_set_insert_row (mysqlx_stmt_t *stmt,...)
	Specify a row to be added by an INSERT statement. More...
mysqlx_result_t *	mysqlx_execute (mysqlx_stmt_t *stmt)
	Execute a statement. More...
int	mysqlx_stmt_bind (mysqlx_stmt_t *stmt,...)
	Bind values for parametrized statements. More...
int	mysqlx_set_items (mysqlx_stmt_t *stmt,...)
	Specify a table query projection. More...
int	mysqlx_set_where (mysqlx_stmt_t *stmt, const char *where_expr)
	Specify selection criteria for a statement. More...
int	mysqlx_set_having (mysqlx_stmt_t *stmt, const char *having_expr)
	Specify filter conditions for a group of rows/documents or aggregates such as GROUP BY. More...
int	mysqlx_set_group_by (mysqlx_stmt_t *stmt,...)
	Specify one or more columns/values to group the result in conjunction with the aggregate functions. More...
int	mysqlx_set_order_by (mysqlx_stmt_t *stmt,...)
	Specify ordering for a statement. More...
int	mysqlx_set_limit_and_offset (mysqlx_stmt_t *stmt, uint64_t row_count, uint64_t offset)
	Set limit and offset information for a statement. More...
int	mysqlx_set_row_locking (mysqlx_stmt_t *stmt, int locking, int contention)
	Set row locking mode for a statement. More...
void	mysqlx_free (void *obj)
	Free the allocated handle explicitly. More...

Detailed Description

Function Documentation

mysqlx_set_insert_row()

int mysqlx_set_insert_row	(	mysqlx_stmt_t *	stmt,
			...
	)

Specify a row to be added by an INSERT statement.

The function provides the row data for an INSERT statement. User code must ensure that the number of values and their order matches the list of columns specified for the operation. If column names were not explicitly specified, the values must match the columns of the table.

Parameters

stmt	statement handle
...	variable parameters list consisting of (type, value) pairs terminated by PARAM_END. The pairs must be listed in the order they appear in the list of columns For MYSQLX_TYPE_BYTES the function will expect three parameters instead of two as for all other types: <MYSQLX_TYPE_BYTES, (void*)byte_data, (size_t)length>

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

Each new call provides the row values for the new row, which can be used for multi-row inserts

mysqlx_execute()

mysqlx_result_t * mysqlx_execute

(

mysqlx_stmt_t *

stmt

)

Execute a statement.

Executes statement created by mysqlx_table_select_new(), mysqlx_table_insert_new(), mysqlx_table_update_new(), mysqlx_table_delete_new(), mysqlx_sql_new(), etc.

Parameters

stmt	statement handle

Returns

handle that can be used to access results of the operation. Returned handle is valid until the statement handle is freed (when session is closed or explicitly with mysqlx_free()) or until another call to mysqlx_execute() on the same statement handle is made. It is also possible to close a result handle and free all resources used by it earlier with mysqlx_free() call. On error NULL is returned. The statement is set to an error state and errors can be examined using the statement handle.

mysqlx_stmt_bind()

int mysqlx_stmt_bind	(	mysqlx_stmt_t *	stmt,
			...
	)

Bind values for parametrized statements.

This function binds values of either ? placeholders in an SQL statement or of named parameters that can be used in other statements.

User code must ensure that the number of values in bind is the same as the number of parameters in the query because this is not checked until receiving the query on the server side.

Parameters

stmt	statement handle
...	variable parameters list, which has different structure for SQL statements that use placeholders and for other statements that use named parameters.

For SQL statements it is consisting of (type, value) pairs terminated by PARAM_END: type_id1, value1, type_id2, value2, ..., type_id_n, value_n, PARAM_END.

For SELECT, INSERT, UPDATE, DELETE, FIND, ADD, MODIFY and REMOVE statements, the parameters come as triplets (param_name, type, value): name1, type_id1, value1, name2, type_id2, value2, ..., name_n, type_id_n, value_n, PARAM_END (PARAM_END marks the end of the parameters list).

type_id is the numeric identifier, which helps to determine the type of the value provided as the next parameter. The user code must ensure that type_id corresponds to the actual value type. Otherwise, the value along with and all sequential types and values are most likely to be corrupted.

It is recommended to use PARAM_TTT() macros to keep the list integrity: PARAM_UINT(), PARAM_SINT(), PARAM_FLOAT(), PARAM_DOUBLE(), PARAM_STRING(), PARAM_BYTES(), PARAM_EXPR() for different data types instead of (MYSQLX_TYPE_TTT, value) pairs.

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

Each new call resets the binds set by the previous call to mysqlx_stmt_bind()

mysqlx_set_items()

int mysqlx_set_items	(	mysqlx_stmt_t *	stmt,
			...
	)

Specify a table query projection.

Using projection, rows found by the query can be mapped to a new set of rows which is returned in the final result. Projection is given by a list of expressions determining values of fields in the resulting rows. These expressions can refer to the fields in the original row (via column names of the original table).

Parameters

stmt	handle to the statement for which the projection is set
...	variable parameters list consisting of character strings containing expressions: proj_1, ..., proj_n, PARAM_END (PARAM_END marks the end of projection's item list)

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

This function can be only called for table SELECT statements

See also

mysqlx_table_select_new()

mysqlx_set_where()

int mysqlx_set_where	(	mysqlx_stmt_t *	stmt,
		const char *	where_expr
	)

Specify selection criteria for a statement.

Restrict the statement to rows/documents that satisfy given selection criteria:

• for select/find operations limit the returned rows/documents,
• for update/modify/delete/remove operations limit the rows/documents affected by the operations.

Statements supported by this function: SELECT, FIND, UPDATE, MODIFY, DELETE, REMOVE. Calling it for INSERT or ADD will result in an error

Parameters

stmt	statement handle
where_expr	character string containing Boolean expression like in SQL WHERE clause

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_where() macros that map the corresponding mysqlx_set_where() function. This way the unsupported operations will not be used.

mysqlx_set_having()

int mysqlx_set_having	(	mysqlx_stmt_t *	stmt,
		const char *	having_expr
	)

Specify filter conditions for a group of rows/documents or aggregates such as GROUP BY.

Restrict the statement to rows/documents that satisfy given selection criteria:

• for select/find operations limit the returned rows/documents,

Statements supported by this function: SELECT, FIND. Calling it for UPDATE, MODIFY, DELETE, REMOVE, INSERT or ADD will result in an error

Parameters

stmt	statement handle
having_expr	character string containing Boolean expression like in SQL HAVING clause

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_having() macros that map the corresponding mysqlx_set_having() function. This way the unsupported operations will not be used.

mysqlx_set_group_by()

int mysqlx_set_group_by	(	mysqlx_stmt_t *	stmt,
			...
	)

Specify one or more columns/values to group the result in conjunction with the aggregate functions.

Statements supported by this function: SELECT, FIND. Calling it for UPDATE, MODIFY, DELETE, REMOVE, INSERT or ADD will result in an error

Parameters

stmt	statement handle
...	variable parameters list consisting of character strings containing expressions specifying grouping: expr_1, ..., expr_n, PARAM_END (PARAM_END marks the end of projection's item list)

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_group_by() macros that map the corresponding mysqlx_set_group_by() function. This way the unsupported operations will not be used.

mysqlx_set_order_by()

int mysqlx_set_order_by	(	mysqlx_stmt_t *	stmt,
			...
	)

Specify ordering for a statement.

Operations supported by this function: SELECT, FIND, UPDATE, MODIFY, DELETE, REMOVE Calling it for INSERT or ADD will result in an error

Parameters

stmt

statement handle

...

variable parameters list consisting of (expression, direction) pairs terminated by PARAM_END: expr_1, direction_1, ..., expr_n, direction_n, PARAM_END. Each expression computes a value used to sort the rows/documents in ascending or descending order, as determined by direction constant (list the direction enum names). Special attention must be paid to the expression strings because the empty string "" or NULL will be treated as the end of sequence

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_order_by() macros that map the corresponding mysqlx_set_order_by() function. This way the unsupported operations will not be used.

mysqlx_set_limit_and_offset()

int mysqlx_set_limit_and_offset	(	mysqlx_stmt_t *	stmt,
		uint64_t	row_count,
		uint64_t	offset
	)

Set limit and offset information for a statement.

Set LIMIT and OFFSET for statement operations which work on ranges of rows/documents: for select/find operations limit the number of returned rows/documents, for update/delete limit the number of documents affected by the operation.

Operations supported by this function: SELECT, FIND - use both LIMIT and OFFSET UPDATE, MODIFY, DELETE, REMOVE - use only LIMIT

Calling it for INSERT or ADD will result in an error

Parameters

stmt	statement handle
row_count	the number of result rows to return
offset	the number of rows to skip before starting counting

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_limit_and_offset() macros that map the corresponding mysqlx_set_limit_and_offset() function. This way the unsupported operations will not be used.

Each call to this function replaces previously set LIMIT

mysqlx_set_row_locking()

int mysqlx_set_row_locking	(	mysqlx_stmt_t *	stmt,
		int	locking,
		int	contention
	)

Set row locking mode for a statement.

Set row locking mode for statement operations working on ranges of rows/documents.

Operations supported by this function: SELECT, FIND

Calling it for INSERT, UPDATE, DELETE, ADD, MODIFY and REMOVE will result in an error.

Parameters

stmt	statement handle
locking	the integer mode identifier (see mysqlx_row_locking_t).
contention	the integer locking contention (see mysqlx_lock_contention_t).

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_row_locking() macros that map the corresponding mysqlx_set_row_locking() function. This way the unsupported operations will not be used.

Each call to this function replaces previously set locking mode

mysqlx_free()

void mysqlx_free

(

void *

obj

)

Free the allocated handle explicitly.

After calling this function on a handle it becomes invalid and should not be used any more.

Note

This function should not be called on a client or session handle

• use mysqlx_client_close() or mysqlx_session_close() instead.

Statement, result, schema, collection, table and some error handles are also freed automatically when the session is closed.

Only errors that originate from an already established session are freed automatically when that session is closed. Errors reported from one of the following functions when they fail to create a new session or a new client must be freed explicitly: mysqlx_get_session(), mysqlx_get_session_from_url(), mysqlx_get_session_from_options(), mysqlx_get_session_from_client(), mysqlx_get_client_from_url() and mysqlx_get_client_from_options().

Parameters

obj	object handle