Namespace Mysqlx.Resultset

Classes

ColumnMetaData

Meta data of a column

@note The encoding used for the different bytes fields in the meta data is externally controlled. See also: https://dev.mysql.com/doc/refman/5.0/en/charset-connection.html

@par @note The server may not set the original_{table|name} fields if they are equal to the plain {table|name} field.

@par @note A client has to reconstruct it like: @code{py} if .original_name is empty and .name is not empty: .original_name = .name

if .original_table is empty and .table is not empty: .original_table = .table @endcode

@par @note Compact metadata format can be requested by the client. In that case, only .type is set and all other fields are empty.

Expected data type of Mysqlx.Resultset.Row per SQL Type for non-NULL values:

SQL Type .type .length .frac_dig .flags .charset
TINY SINT x
TINY UNSIGNED UINT x x
SHORT SINT x
SHORT UNSIGNED UINT x x
INT24 SINT x
INT24 UNSIGNED UINT x x
INT SINT x
INT UNSIGNED UINT x x
LONGLONG SINT x
LONGLONG UNSIGNED UINT x x
DOUBLE DOUBLE x x x
FLOAT FLOAT x x x
DECIMAL DECIMAL x x x
VARCHAR,CHAR,... BYTES x x x
GEOMETRY BYTES
TIME TIME x
DATE DATETIME x
DATETIME DATETIME x
YEAR UINT x x
TIMESTAMP DATETIME x
SET SET x
ENUM ENUM x
NULL BYTES
BIT BIT x

@note The SQL "NULL" value is sent as an empty field value in @ref Mysqlx::Resultset::Row.

@par Tip The protobuf encoding of primitive data types is described in https://developers.google.com/protocol-buffers/docs/encoding

  • SINT
  • .length @n Maximum number of displayable decimal digits (including minus sign) of the type. @note The valid range is 0-255, but usually you'll see 1-20.
SQL Type Maximum Digits per Type
TINY SIGNED 4
SHORT SIGNED 6
INT24 SIGNED 8
INT SIGNED 11
LONGLONG SIGNED 20

@par Tip Definition of M are in https://dev.mysql.com/doc/refman/5.5/en/numeric-type-overview.html.

  • value@n Variable length encoded signed 64 integer.
  • UINT

  • .flags & 1 (zerofill) @n The client has to left pad with 0's up to .length.

  • .length @n Maximum number of displayable decimal digits of the type. @note The valid range is 0-255, but usually you'll see 1-20.

SQL Type max digits per type
TINY UNSIGNED 3
SHORT UNSIGNED 5
INT24 UNSIGNED 8
INT UNSIGNED 10
LONGLONG UNSIGNED 20

@par Tip Definition of M are in https://dev.mysql.com/doc/refman/5.5/en/numeric-type-overview.html.

  • value @n Variable length encoded unsigned 64 integer.
  • BIT
  • .length @n Maximum number of displayable binary digits. @note The valid range for M of the BIT type is 1 - 64.

@par Tip https://dev.mysql.com/doc/refman/5.5/en/numeric-type-overview.html

  • value @n Variable length encoded unsigned 64 integer.
  • DOUBLE

  • .length @n Maximum number of displayable decimal digits (including the decimal point and .fractional_digits).

  • .fractional_digits @n Maximum number of displayable decimal digits following the decimal point.

  • value@n Encoded as protobuf's 'double'.

  • FLOAT

  • .length@n Maximum number of displayable decimal digits (including the decimal point and .fractional_digits).

  • .fractional_digits@n Maximum number of displayable decimal digits following the decimal point.

  • value@n Encoded as protobuf's 'float'.

  • BYTES, ENUM @note BYTES is used for all opaque byte strings that may have a charset:

  • TINYBLOB, BLOB, MEDIUMBLOB, LONGBLOB

  • TINYTEXT, TEXT, MEDIUMTEXT, LONGTEXT

  • VARCHAR, VARBINARY

  • CHAR, BINARY

  • ENUM

  • .length@n Maximum length of characters of the underlying type.

  • .flags & 1 (rightpad) @n If the length of the field is less than .length, the receiver is supposed to add padding characters to the right end of the string. If the .charset is "binary", the padding character is 0x00, otherwise it is a space character as defined by that character set. | SQL Type | .length | .charset | .flags | |---------------|----------|-----------|----------| | TINYBLOB | 256 | binary | | | BLOB | 65535 | binary | | | VARCHAR(32) | 32 | utf8 | | | VARBINARY(32) | 32 | utf8_bin | | | BINARY(32) | 32 | binary | rightpad | | CHAR(32) | 32 | utf8 | rightpad |

  • value Sequence of bytes with added one extra 0x00 byte at the end. To obtain the original string, the extra 0x00 should be removed. The length of the string can be acquired with protobuf's field length() method:

length of sequence-of-bytes = length-of-field - 1 @note The extra byte allows to distinguish between a NULL and empty byte sequence.

  • TIME

A time value.

  • value@n The following bytes sequence:

negate [ hour [ minutes [ seconds [ useconds ]]]]

  • negate - one byte, should be one of: 0x00 for "+", 0x01 for "-"

  • hour - optional variable length encoded unsigned64 value for the hour

  • minutes - optional variable length encoded unsigned64 value for the minutes

  • seconds - optional variable length encoded unsigned64 value for the seconds

  • useconds - optional variable length encoded unsigned64 value for the microseconds

@par Tip The protobuf encoding in https://developers.google.com/protocol-buffers/docs/encoding.

@note Hour, minutes, seconds, and useconds are optional if all the values to the right are 0.

Example: 0x00 -> +00:00:00.000000

  • DATETIME

A date or date and time value.

  • value @n A sequence of variants, arranged as follows:

| year | month | day | [ | hour | [ | minutes | [ | seconds | [ | useconds | ]]]]

  • year - variable length encoded unsigned64 value for the year

  • month - variable length encoded unsigned64 value for the month

  • day - variable length encoded unsigned64 value for the day

  • hour - optional variable length encoded unsigned64 value for the hour

  • minutes - optional variable length encoded unsigned64 value for the minutes

  • seconds - optional variable length encoded unsigned64 value for the seconds

  • useconds - optional variable length encoded unsigned64 value for the microseconds @note Hour, minutes, seconds, useconds are optional if all the values to the right are 0.

  • .flags@n | Name | Position | |---------------|----------| | is_timestamp | 1 |

  • DECIMAL

An arbitrary length number. The number is encoded as a single byte indicating the position of the decimal point followed by the Packed BCD encoded number. Packed BCD is used to simplify conversion to and from strings and other native arbitrary precision math data types. See also: packed BCD in https://en.wikipedia.org/wiki/Binary-coded_decimal

  • .length Maximum number of displayable decimal digits (excluding the decimal point and sign, but including .fractional_digits). @note Should be in the range of 1 - 65.

  • .fractional_digits The decimal digits to display out of length. @note Should be in the range of 0 - 30.

value The following bytes sequence:

scale | BCD+ sign [0x00]?

  • scale - 8bit scale value (number of decimal digit after the '.')

  • BCD - BCD encoded digits (4 bits for each digit)

  • sign - sign encoded on 4 bits (0xc = "+", 0xd = "-")

  • 0x0 - last 4bits if length(digits) % 2 == 0

Example: x04 0x12 0x34 0x01 0xd0 -> -12.3401

  • SET

A list of strings representing a SET of values.

  • value@n A sequence of 0 or more of protobuf's bytes (length prepended octets) or one of the special sequences with a predefined meaning listed below.

Example (length of the bytes array shown in brackets):

  • [0] - the NULL value

  • [1] 0x00 - a set containing a blank string ''

  • [1] 0x01 - this would be an invalid value, but is to be treated as the empty set

  • [2] 0x01 0x00 - a set with a single item, which is the '0' character

  • [8] 0x03 F O O 0x03 B A R - a set with 2 items: FOO,BAR

ColumnMetaData.Types

Container for nested types declared in the ColumnMetaData message type.

FetchDone

All resultsets are finished

FetchDoneMoreOutParams

Resultsets are finished, OUT paramset is next:

FetchDoneMoreResultsets

Resultset and out-params are finished, but more resultsets available

FetchSuspended

Cursor is opened; still, the execution of PrepFetch or PrepExecute ended

MysqlxResultsetReflection

Holder for reflection information generated from mysqlx_resultset.proto

Row

Row in a Resultset.

A row is represented as a list of fields encoded as byte blobs. Value of each field is encoded as sequence of bytes using encoding appropriate for the type of the value given by ColumnMetadata, as specified in the @ref Mysqlx::Resultset::ColumnMetaData description.

Enums

ColumnMetaData.Types.FieldType

ContentType_BYTES

A hint about the higher-level encoding of a BYTES field

type value description
BYTES 0x0001 GEOMETRY (WKB encoding)
BYTES 0x0002 JSON (text encoding)
BYTES 0x0003 XML (text encoding)

@note this list isn't comprehensive. As a guideline: the field's value is expected to pass a validator check on client and server if this field is set. If the server adds more internal datatypes that rely on BLOB storage like image manipulation, seeking into complex types in BLOBs, ... more types will be added.

ContentType_DATETIME

A hint about the higher-level encoding of a DATETIME field

type value description
DATE 0x0001 DATETIME contains only date part
DATETIME 0x0002 DATETIME contains both date and time parts