Result processing

Functions
mysqlx_row_t *	mysqlx_row_fetch_one (mysqlx_result_t *res)
	Fetch one row from the result. More...
const char *	mysqlx_json_fetch_one (mysqlx_result_t *res, size_t *out_length)
	Fetch one document as a JSON string. More...
int	mysqlx_next_result (mysqlx_result_t *res)
	Proceed to the next result set in the reply. More...
uint64_t	mysqlx_get_affected_count (mysqlx_result_t *res)
	Get number of rows affected by a statement. More...
int	mysqlx_store_result (mysqlx_result_t *result, size_t *num)
	Store result data in an internal buffer. More...
int	mysqlx_get_count (mysqlx_result_t *result, size_t *num)
	Function for getting the number of remaining cached items in a result. More...
const char *	mysqlx_fetch_generated_id (mysqlx_result_t *result)
	Get identifiers of the documents added to the collection. More...
uint64_t	mysqlx_get_auto_increment_value (mysqlx_result_t *res)
	Get auto increment value generated by a statement that inserts rows into a table with auto increment column. More...
int	mysqlx_get_bytes (mysqlx_row_t *row, uint32_t col, uint64_t offset, void *buf, size_t *buf_len)
	Read bytes stored in a row into a pre-allocated buffer. More...
int	mysqlx_get_uint (mysqlx_row_t *row, uint32_t col, uint64_t *val)
	Get an unsigned integer number from a row. More...
int	mysqlx_get_sint (mysqlx_row_t *row, uint32_t col, int64_t *val)
	Get a signed integer number from a row. More...
int	mysqlx_get_float (mysqlx_row_t *row, uint32_t col, float *val)
	Get a float number from a row. More...
int	mysqlx_get_double (mysqlx_row_t *row, uint32_t col, double *val)
	Get a double number from a row. More...
void	mysqlx_result_free (mysqlx_result_t *res)
	Free the result explicitly. More...

Detailed Description

Function Documentation

mysqlx_row_fetch_one()

mysqlx_row_t * mysqlx_row_fetch_one

(

mysqlx_result_t *

res

)

Fetch one row from the result.

The result is advanced to the next row (if any).

Parameters

res	result handle

Returns

row handle or NULL if no more rows left or if an error occurred. In case of an error it can be retrieved from the result using mysqlx_error() or mysqlx_error_message().

Note

The previously fetched row and its data will become invalid.

mysqlx_json_fetch_one()

const char * mysqlx_json_fetch_one	(	mysqlx_result_t *	res,
		size_t *	out_length
	)

Fetch one document as a JSON string.

Parameters

	res	result handle
[out]	out_length	the total number of bytes in the JSON string; can be NULL, in that case nothing is returned through this parameter and user must ensure the data is correctly interpreted

Returns

pointer to character JSON string or NULL if no more documents left in the result. No need to free this data as it is tied and freed with the result handle.

mysqlx_next_result()

int mysqlx_next_result

(

mysqlx_result_t *

res

)

Proceed to the next result set in the reply.

This function is used to process replies containing multiple result sets. After a successful call to this function, given result handle will be moved to access the next result set from the reply.

Note

Any data from the previous result set that has not yet been fetched is no more accessible after moving to the next result set.

Parameters

res	result handle

Returns

RESULT_OK - on success; RESULT_NULL when there is no more results; RESULT_ERROR - on error

mysqlx_get_affected_count()

uint64_t mysqlx_get_affected_count

(

mysqlx_result_t *

res

)

Get number of rows affected by a statement.

Parameters

res	result handle

Returns

the number of rows affected by the statement that produced the result

Note

The returned number is meaningful only for results of statements which modify data stored in a table or collection.

mysqlx_store_result()

int mysqlx_store_result	(	mysqlx_result_t *	result,
		size_t *	num
	)

Store result data in an internal buffer.

Rows/documents contained in a result must be fetched in a timely fashion. Failing to do that can result in an error and lost access to the remaining part of the result. This function can store complete result in memory so it can be accessed at any time, as long as the result handle is valid.

Parameters

	result	result handle
[out]	num	number of records buffered. Zero is never returned. If the number of records to buffer is zero the function returns RESULT_ERROR

Returns

RESULT_OK - on success; RESULT_ERROR - on error. If the error occurred it can be retrieved by mysqlx_error() function.

Note

Even in case of an error some rows/documents might be buffered if they were retrieved before the error occurred.

When called for second time on the same result the function does not store anything because the data is already buffered. Instead it returns the number of items that have not been fetched yet.

mysqlx_get_count()

int mysqlx_get_count	(	mysqlx_result_t *	result,
		size_t *	num
	)

Function for getting the number of remaining cached items in a result.

If nothing is cached if will attempt to store result in the internal cache like mysqlx_store_result().

Parameters

	result	result handle
[out]	num	number of records buffered.

Returns

RESULT_OK - on success; RESULT_ERROR - on error. If the error occurred it can be retrieved by mysqlx_error() function.

Note

Even in case of an error some rows/documents might be buffered if they were retrieved before the error occurred.

mysqlx_fetch_generated_id()

const char * mysqlx_fetch_generated_id

(

mysqlx_result_t *

result

)

Get identifiers of the documents added to the collection.

This function returns both generated document ids and document ids specified by user in _id field.

The function can be used for the multi-document inserts. In this case each call to mysqlx_fetch_generated_id() returns identifier of the next document, until NULL is returned.

Parameters

result

handle to a result of a statement which adds documents to a collection

Returns

character string containing an identifier of a document added by the statement; NULL - if all UUIDs for all added documents have been returned

Note

The returned string is valid as long as the result handle is valid. Starting a new operation will invalidate it.

mysqlx_get_auto_increment_value()

uint64_t mysqlx_get_auto_increment_value

(

mysqlx_result_t *

res

)

Get auto increment value generated by a statement that inserts rows into a table with auto increment column.

Parameters

res	handle to a result of INSERT statement

Returns

the generated auto increment value

Note

with multi-row inserts the function returns the value generated for the first row

mysqlx_get_bytes()

int mysqlx_get_bytes	(	mysqlx_row_t *	row,
		uint32_t	col,
		uint64_t	offset,
		void *	buf,
		size_t *	buf_len
	)

Read bytes stored in a row into a pre-allocated buffer.

The raw bytes are as received from the server. In genral the value is represented using x-protocol encoding that corresponds to the type and other meta-data of the given column. This information can be obtained from mysqlx_column_get_type() and other mysqlx_column_get_*() functions.

The x-protocol represenation of different value types is documented here. Most types in the mysqlx_data_type_t enumeration correspond to an x-protocol value type of the same name.

STRING values are encoded using the character set encoding as reported by mysqlx_column_get_collation() function.

JSON data is represented as a JSON string. ENUM values are represented as strings with enum constant names. Values of type TIMESTAMP use the same representation as DATETIME. GEOMETRY values use the internal geometry storage format described here.

Types BOOL and EXPR are never reported for data received from server – they are used when sending data to the server.

Note that raw representation of BYTES and STRING values has an extra 0x00 byte added at the end, which is not part of the originial data. It is used to distinguish null values from empty byte sequences.

Parameters

	row	row handle
	col	zero-based column number
	offset	the number of bytes to skip before reading them from source row
[out]	buf	the buffer allocated on the user side into which to write data
[in,out]	buf_len	pointer to a variable holding the length of the buffer [IN], the number of bytes actually written into the buffer [OUT]

Returns

RESULT_OK - on success; RESULT_NULL when the value in the requested column is NULL; RESULT_MORE_DATA if not all data was fetched after the last call to the function; RESULT_ERROR - on error

mysqlx_get_uint()

int mysqlx_get_uint	(	mysqlx_row_t *	row,
		uint32_t	col,
		uint64_t *	val
	)

Get an unsigned integer number from a row.

It is important to pay attention to the signed/unsigned type of the column. Attempting to call this function for a column whose type is different from MYSQLX_TYPE_UINT will result in wrong data being retrieved.

Parameters

	row	row handle
	col	zero-based column number
[out]	val	the pointer to a variable of the 64-bit unsigned integer type in which to write the data

Returns

RESULT_OK - on success; RESULT_NULL when the column is NULL; RESULT_ERROR - on error

mysqlx_get_sint()

int mysqlx_get_sint	(	mysqlx_row_t *	row,
		uint32_t	col,
		int64_t *	val
	)

Get a signed integer number from a row.

It is important to pay attention to the signed/unsigned type of the column. Attempting to call this function for a column whose type is different from MYSQLX_TYPE_SINT will result in wrong data being retrieved.

Parameters

	row	row handle
	col	zero-based column number
[out]	val	the pointer to a variable of the 64-bit signed integer type in which to write the data

Returns

RESULT_OK - on success; RESULT_NULL when the column is NULL; RESULT_ERROR - on error

mysqlx_get_float()

int mysqlx_get_float	(	mysqlx_row_t *	row,
		uint32_t	col,
		float *	val
	)

Get a float number from a row.

It is important to pay attention to the type of the column. Attempting to call this function for a column whose type is different from MYSQLX_TYPE_FLOAT will result in wrong data being retrieved.

Parameters

	row	row handle
	col	zero-based column number
[out]	val	the pointer to a variable of the float type in which to write the data

Returns

RESULT_OK - on success; RESULT_NULL when the column is NULL; RESULT_ERROR - on error

mysqlx_get_double()

int mysqlx_get_double	(	mysqlx_row_t *	row,
		uint32_t	col,
		double *	val
	)

Get a double number from a row.

It is important to pay attention to the type of the column. Attempting to call this function for a column whose type is different from MYSQLX_TYPE_DOUBLE will result in wrong data being retrieved.

Parameters

	row	row handle
	col	zero-based column number
[out]	val	the pointer to a variable of the double type in which to write the data.

Returns

RESULT_OK - on success; RESULT_NULL when the column is NULL; RESULT_ERROR - on error

mysqlx_result_free()

void mysqlx_result_free

(

mysqlx_result_t *

res

)

Free the result explicitly.

Note

This function is DEPRECATED. Use mysqlx_free() instead.

Results are also freed automatically when the corresponding statement handle is freed.

Parameters

res	the result handle