MySQL  8.0.20
Source Code Documentation
Messages

Topics in this section:

This section provides detailed information about how X Protocol defines messages.

Message Structure

Messages have a:

  • 4 byte length (little endian)
  • 1 byte message type
  • a message_payload of length .length - 1
Mysqlx.Message
Container of all messages that are exchanged between client and server.
Parameters
  • length – length of the whole message
  • message_type – type of the message_payload
  • message_payload – the message's payload encoded using Google Protobuf if not otherwise noted.
struct {
uint32 length;
uint8 message_type;
opaque message_payload[Message.length - 1];
} Message;
Note
The message_payload is generated from the protobuf files using protoc:
$ protoc --cpp_out=protodir mysqlx*.proto
  • [mysqlx.proto]
  • [mysqlx_connection.proto]
  • [mysqlx_session.proto]
  • [mysqlx_crud.proto]
  • [mysqlx_sql.proto]
  • [mysqlx_resultset.proto]
  • [mysqlx_expr.proto]
  • [mysqlx_datatypes.proto]
  • [mysqlx_expect.proto]
  • [mysqlx_notice.proto]
Note
The message_type can be taken from the ClientMessages for client-messages and from ServerMessages of server-side messages.
In C++ they are exposed in mysqlx.pb.h in the ClientMessages class.
ClientMessages.MsgCase.kMsgConGetCap
ClientMessages.kMsgConGetCapFieldNumber

Message Sequence

Messages usually appear in a sequence. Each initial message (one referenced by ClientMessages ) is associated with a set of possible following messages.

A message sequence either:

  • finishes successfully if it reaches its end-state or
  • is aborted with a Error Message

At any time in between local Notices may be sent by the server as part of the message sequence.

Global Notices may be sent by the server at any time.

Common Messages

Error Message

After the client sent the initial message, the server may send a Error message at any time to terminate the current message sequence.

package Mysqlx::

message Mysqlx::ClientMessages

IDs of messages that can be sent from client to the server.

Note
This message is never sent on the wire. It is only used to let protoc:
  • generate constants
  • check for uniqueness
message ClientMessages {
enum Type {
CON_CAPABILITIES_GET = 1;
CON_CAPABILITIES_SET = 2;
CON_CLOSE = 3;
SESS_AUTHENTICATE_START = 4;
SESS_AUTHENTICATE_CONTINUE = 5;
SESS_RESET = 6;
SESS_CLOSE = 7;
SQL_STMT_EXECUTE = 12;
CRUD_FIND = 17;
CRUD_INSERT = 18;
CRUD_UPDATE = 19;
CRUD_DELETE = 20;
EXPECT_OPEN = 24;
EXPECT_CLOSE = 25;
}
}

message Mysqlx::ServerMessages

IDs of messages that can be sent from server to client.

Note
This message is never sent on the wire. It is only used to let protoc:
  • generate constants
  • check for uniqueness
message ServerMessages {
enum Type {
OK = 0;
ERROR = 1;
CONN_CAPABILITIES = 2;
SESS_AUTHENTICATE_CONTINUE = 3;
SESS_AUTHENTICATE_OK = 4;
// NOTICE has to stay at 11 forever
NOTICE = 11;
RESULTSET_COLUMN_META_DATA = 12;
RESULTSET_ROW = 13;
RESULTSET_FETCH_DONE = 14;
RESULTSET_FETCH_SUSPENDED = 15;
RESULTSET_FETCH_DONE_MORE_RESULTSETS = 16;
SQL_STMT_EXECUTE_OK = 17;
RESULTSET_FETCH_DONE_MORE_OUT_PARAMS = 18;
};
}

message Mysqlx::Ok

Generic Ok message.

message Ok {
optional string msg = 1;
}

message Mysqlx::Error

Generic Error message.

A severity of ERROR indicates the current message sequence is aborted for the given error and the session is ready for more.

In case of a FATAL error message the client should not expect the server to continue handling any further messages and should close the connection.

Param severity
severity of the error message
Param code
error-code
Param sql_state
SQL state
Param msg
human-readable error message
message Error {
optional Severity severity = 1 [ default = ERROR ];
required uint32 code = 2;
required string sql_state = 4;
required string msg = 3;
enum Severity {
ERROR = 0;
FATAL = 1;
};
}

Notices

Tip
For more information, see Notices.

The server may send notices Frame to the client at any time.

A notice can be:

  • global (.scope == GLOBAL) or
  • belong to the currently executed Message Sequence (.scope == LOCAL + message sequence is active):
Note
If the Server sends a LOCAL notice while no message sequence is active, the Notice should be ignored.

package Mysqlx.Notice::

A notice:

  • is sent from the server to the client
  • may be global or relate to the current message sequence

message Mysqlx.Notice::Frame

Common Frame for all Notices

.type Value
Warning 1
SessionVariableChanged 2
SessionStateChanged 3
Param type
the type of the payload
Param payload
the payload of the notification
Param scope
global or local notification
message Frame {
enum Scope {
GLOBAL = 1;
LOCAL = 2;
};
required uint32 type = 1;
optional Scope scope = 2 [ default = GLOBAL ];
optional bytes payload = 3;
}

message Mysqlx.Notice::Warning

Server-side warnings and notes

.scope == local
.level, .code and .msg map the content of:
SHOW WARNINGS
.scope == global
(undefined) Will be used for global, unstructured messages like:
  • server is shutting down
  • a node disconnected from group
  • schema or table dropped
Frame Field Value
.type 1
.scope local or global
Param level
warning level: Note or Warning
Param code
warning code
Param msg
warning message
message Warning {
enum Level {
NOTE = 1;
WARNING = 2;
ERROR = 3;
};
optional Level level = 1 [ default = WARNING ];
required uint32 code = 2;
required string msg = 3;
}

message Mysqlx.Notice::SessionVariableChanged

Notify clients about changes to the current session variables.

Every change to a variable that is accessible through:

SHOW SESSION VARIABLES
Frame Field Value
.type 2
.scope local
Param namespace
namespace that param belongs to
Param param
name of the variable
Param value
the changed value of param
message SessionVariableChanged {
required string param = 1;
optional Mysqlx.Datatypes.Scalar value = 2;
}

message Mysqlx.Notice::SessionStateChanged

Notify clients about changes to the internal session state.

Frame Field Value
.type 3
.scope local
Param param
Parameter key
Param value
updated value
message SessionStateChanged {
enum Parameter {
CURRENT_SCHEMA = 1;
ACCOUNT_EXPIRED = 2;
GENERATED_INSERT_ID = 3;
ROWS_AFFECTED = 4;
ROWS_FOUND = 5;
ROWS_MATCHED = 6;
TRX_COMMITTED = 7;
TRX_ROLLEDBACK = 9;
PRODUCED_MESSAGE = 10;
CLIENT_ID_ASSIGNED = 11;
// .. more to be added
}
required Parameter param = 1;
optional Mysqlx.Datatypes.Scalar value = 2;
}

Connection

package Mysqlx.Connection::

message Mysqlx.Connection::Capability

A tuple of a name and a Any :

message Capability {
required string name = 1;
required Mysqlx.Datatypes.Any value = 2;
}

message Mysqlx.Connection::Capabilities

Capabilities:

message Capabilities {
repeated Capability capabilities = 1;
}

message Mysqlx.Connection::CapabilitiesGet

Get supported connection capabilities and their current state.

Returns Capabilities or Error

message CapabilitiesGet {
};

message Mysqlx.Connection::CapabilitiesSet

Set connection capabilities atomically.

Only provided values are changed, other values are left unchanged. If any of the changes fails, all changes are discarded.

Precondition active sessions == 0

Returns Ok or Error

message CapabilitiesSet {
required Capabilities capabilities = 1;
};

message Mysqlx.Connection::Close

Announce to the server that the client wants to close the connection.

It discards any session state of the server.

Returns Ok

message Close {
};

Session

package Mysqlx.Session::

Messages to manage sessions.

Messages for Sessions

message Mysqlx.Session::AuthenticateStart

The initial message send from the client to the server to start the authentication process.

Param mech_name
authentication mechanism name
Param auth_data
authentication data
Param initial_response
initial response

Returns AuthenticateContinue

message AuthenticateStart {
required string mech_name = 1;
optional bytes auth_data = 2;
optional bytes initial_response = 3;
}

message Mysqlx.Session::AuthenticateContinue

Send by client or server after an AuthenticateStart to exchange more authentication data.

Param auth_data
authentication data

Returns AuthenticateContinue

message AuthenticateContinue {
required bytes auth_data = 1;
}

message Mysqlx.Session::AuthenticateOk

Sent by the server after successful authentication.

Param auth_data
authentication data
message AuthenticateOk {
optional bytes auth_data = 1;
}

message Mysqlx.Session::Reset

Reset the current session.

Returns Ok

message Reset {
}

message Mysqlx.Session::Close

Close the current session.

Returns Ok

message Close {
}

Expectations

Tip
For more information, see Expectations.

Expect

package Mysqlx.Expect::

Expect operations

message Mysqlx.Expect::Open

Open an Expect block and set/unset the conditions that have to be fulfilled.

If any of the conditions fail, all enclosed messages will fail with a Mysqlx.Error message.

Returns Ok on success, Error on error

message Open {
message Condition {
enum ConditionOperation {
// set the condition
//
// set, if not set
// overwrite, if set
EXPECT_OP_SET = 0;
// unset the condition
EXPECT_OP_UNSET = 1;
};
required uint32 condition_key = 1;
optional bytes condition_value = 2;
optional ConditionOperation op = 3 [ default = EXPECT_OP_SET ];
};
enum CtxOperation {
// copy the operations from the parent Expect-block
EXPECT_CTX_COPY_PREV = 0;
// start with a empty set of operations
EXPECT_CTX_EMPTY = 1;
};
optional CtxOperation op = 1 [ default = EXPECT_CTX_COPY_PREV ];
repeated Condition cond = 2;
}

message Mysqlx.Expect::Close

Close a Expect block.

Closing a Expect block restores the state of the previous Expect block for the following messages.

Returns Ok on success, Error on error

message Close {
}

CRUD

The CRUD operations work in a similar fashion as the SQL statements below:

  • prepare the CRUD operation
  • execute the operation
  • get the description of the result
  • fetch the rows in batches
  • close the prepared operation
Messages for CRUD

package Mysqlx.Crud::

Basic CRUD operations.

message Mysqlx.Crud::Column

Column definition:

message Column {
optional string name = 1;
optional string alias = 2;
repeated Mysqlx.Expr.DocumentPathItem document_path = 3;
}

message Mysqlx.Crud::Projection

A projection.

Param source
the expression identifying an element from the source data which can include a column identifier or any expression
Param alias
optional alias. Required for DOCUMENTs (clients may use the source string as default)
message Projection {
required Mysqlx.Expr.Expr source = 1;
optional string alias = 2;
}

message Mysqlx.Crud::Collection

Collection:

message Collection {
required string name = 1;
optional string schema = 2;
}

message Mysqlx.Crud::Limit

Limit

Param row_count
maximum rows to filter
Param offset
maximum rows to skip before applying the row_count
message Limit {
required uint64 row_count = 1;
optional uint64 offset = 2;
}

message Mysqlx.Crud::Order

Sort order:

message Order {
enum Direction {
ASC = 1;
DESC = 2;
};
required Mysqlx.Expr.Expr expr = 1;
optional Direction direction = 2 [ default=ASC ];
}

message Mysqlx.Crud::UpdateOperation

Update operations.

Param source
specification of the value to be updated:
  • if data_model is TABLE, then a column name may be specified
    • if the column type is JSON, then a document_path can be specified additionally
  • if the data_model is DOCUMENT, then only document paths are allowed
Note
In both cases, schema_name and table_name must be not set.
Param operation
the type of operation to be performed
Param value
an expression to be computed as the new value for the operation
message UpdateOperation {
enum UpdateType {
SET = 1; // only allowed for TABLE
ITEM_REMOVE = 2; // no value (removes the identified path from a object or array)
ITEM_SET = 3; // sets the new value on the identified path
ITEM_REPLACE = 4; // replaces a value if the path exists
ITEM_MERGE = 5; // source and value must be documents
ARRAY_INSERT = 6; // insert the value in the array at the index identified in the source path
ARRAY_APPEND = 7; // append the value on the array at the identified path
}
required Mysqlx.Expr.ColumnIdentifier source = 1;
required UpdateType operation = 2;
optional Mysqlx.Expr.Expr value = 3;
}

message Mysqlx.Crud::Find

Find Documents/Rows in a Collection/Table.

Find Operation
Param collection
collection to insert into
Param data_model
data model that the operations refer to
Param projection
list of column projections that shall be returned
Param args
values for parameters used in filter expression
Param criteria
filter criteria
Param limit
numbers of rows that shall be skipped and returned
Param order
sort-order in which the rows/document shall be returned in
Param grouping
column expression list for aggregation (GROUP BY)
Param grouping_criteria
filter criteria for aggregated groups

Returns Mysqlx.Resultset

message Find {
required Collection collection = 2;
optional DataModel data_model = 3;
repeated Projection projection = 4;
optional Mysqlx.Expr.Expr criteria = 5;
repeated Mysqlx.Datatypes.Scalar args = 11;
optional Limit limit = 6;
repeated Order order = 7;
repeated Mysqlx.Expr.Expr grouping = 8;
optional Mysqlx.Expr.Expr grouping_criteria = 9;
};

message Mysqlx.Crud::Insert

Insert documents/rows into a collection/table.

Param collection
collection to insert into
Param data_model
data model that the operations refer to
Param projection
name of the columns to insert data into (empty if data_model is DOCUMENT)
Param row
set of rows to insert into the collection/table (a single expression with a JSON document literal or an OBJECT expression)
Param args
values for parameters used in row expressions

Returns Mysqlx.Resultset

message Insert {
required Collection collection = 1;
optional DataModel data_model = 2;
repeated Column projection = 3;
message TypedRow {
repeated Mysqlx.Expr.Expr field = 1;
};
repeated TypedRow row = 4;
repeated Mysqlx.Datatypes.Scalar args = 5;
};

message Mysqlx.Crud::Update

Update documents/rows in a collection/table.

Param collection
collection to change
Param data_model
data model that the operations refer to
Param criteria
filter expression to match rows that the operations will apply on
Param args
values for parameters used in filter expression
Param limit
limits the number of rows to match
Param order
specifies order of matched rows
Param operation
list of operations to be applied. Valid operations will depend on the data_model.

Returns Mysqlx.Resultset

message Update {
required Collection collection = 2;
optional DataModel data_model = 3;
optional Mysqlx.Expr.Expr criteria = 4;
repeated Mysqlx.Datatypes.Scalar args = 8;
optional Limit limit = 5;
repeated Order order = 6;
repeated UpdateOperation operation = 7;
};

message Mysqlx.Crud::Delete

Delete documents/rows from a Collection/Table.

Param collection
collection to change
Param data_model
data model that the operations refer to
Param criteria
filter expression to match rows that the operations will apply on
Param args
values for parameters used in filter expression
Param limit
limits the number of rows to match
Param order
specifies order of matched rows

Returns Mysqlx.Resultset

message Delete {
required Collection collection = 1;
optional DataModel data_model = 2;
optional Mysqlx.Expr.Expr criteria = 3;
repeated Mysqlx.Datatypes.Scalar args = 6;
optional Limit limit = 4;
repeated Order order = 5;
};

SQL

  • Prepare the statement for execution
  • Execute the statement
  • Get a description of the rows
  • Fetch the rows in batches
  • Close the prepared operation
Note
As the stmt-id and cursor-id is assigned by the client, the client can pipeline the messages and assume that all the steps succeed. In case one command creates an error, all following commands should fail too and therefore it is possible to relate the errors to the right messages.
Messages for SQL

package Mysqlx.Sql::

Messages of the MySQL Package.

message Mysqlx.Sql::StmtExecute

Execute a statement in the given namespace.

Execute Statements

Notices: This message may generate a notice containing WARNINGs generated by its execution. This message may generate a notice containing INFO messages generated by its execution.

Param namespace
namespace of the statement to be executed
Param stmt
statement that shall be executed.
Param args
values for wildcard replacements
Param compact_metadata
send only type information for ColumnMetadata, skipping names and others

Returns

message StmtExecute {
optional string namespace = 3 [ default = "sql" ];
required bytes stmt = 1;
repeated Mysqlx.Datatypes.Any args = 2;
optional bool compact_metadata = 4 [ default = false ];
}

message Mysqlx.Sql::StmtExecuteOk

Statement executed successful:

message StmtExecuteOk {
}

Result Set

package Mysqlx.Resultset::

message Mysqlx.Resultset::FetchDoneMoreOutParams

Resultsets are finished, OUT paramset is next:

message FetchDoneMoreOutParams {
}

message Mysqlx.Resultset::FetchDoneMoreResultsets

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

message FetchDoneMoreResultsets {
}

message Mysqlx.Resultset::FetchDone

All resultsets are finished:

message FetchDone {
}

message Mysqlx.Resultset::ColumnMetaData

Metadata 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
Note
The server may not set the original_{table|name} fields if they are equal to the plain {table|name} field.
A client has to reconstruct it like:
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
Note
Compact metadata format can be requested by the client. In that case, only .type is set and all other fields are empty.
Param type
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 Row .
Tip
The protobuf encoding of primitive data types is described in https://developers.google.com/protocol-buffers/docs/encoding
  • SINT
    • .length
      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
      Tip
      Definition of M are in https://dev.mysql.com/doc/refman/5.5/en/numeric-type-overview.html.
    • value
      Variable length encoded signed 64 integer.
  • UINT
    • .flags & 1 (zerofill)
      The client has to left pad with 0's up to .length.
    • .length
      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
      Tip
      Definition of M are in https://dev.mysql.com/doc/refman/5.5/en/numeric-type-overview.html.
    • value
      Variable length encoded unsigned 64 integer.
  • BIT
  • DOUBLE
    • .length
      Maximum number of displayable decimal digits (including the decimal point and .fractional_digits).
    • .fractional_digits
      Maximum number of displayable decimal digits following the decimal point.
    • value
      Encoded as protobuf's 'double'.
  • FLOAT
    • .length
      Maximum number of displayable decimal digits (including the decimal point and .fractional_digits).
    • .fractional_digits
      Maximum number of displayable decimal digits following the decimal point.
    • value
      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
      Maximum length of characters of the underlying type.
    • .flags & 1 (rightpad)
      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
      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

        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
      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
      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
      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
Param name
name of the column
Param original_name
name of the column before an alias was applied
Param table
name of the table the column originates from
Param original_table
name of the table the column originates from before an alias was applied
Param schema
schema the column originates from
Param catalog
catalog the schema originates from
Note
As there is current no support for catalogs in MySQL, don't expect this field to be set. In the MySQL C/S protocol the field had the value def all the time.
Param fractional_digits
displayed factional decimal digits for floating point and fixed point numbers
Param length
maximum count of displayable characters of .type
Param flags
.type specific flags
Type Value Description
UINT 0x0001 zerofill
DOUBLE 0x0001 unsigned
FLOAT 0x0001 unsigned
DECIMAL 0x0001 unsigned
BYTES 0x0001 rightpad
Value Description
0x0010 NOT_NULL
0x0020 PRIMARY_KEY
0x0040 UNIQUE_KEY
0x0080 MULTIPLE_KEY
0x0100 AUTO_INCREMENT
default: 0
Param content_type
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 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 data types that rely on BLOB storage like image manipulation, seeking into complex types in BLOBs, and more types will be added.
message ColumnMetaData {
enum FieldType {
SINT = 1;
UINT = 2;
DOUBLE = 5;
FLOAT = 6;
BYTES = 7;
TIME = 10;
DATETIME = 12;
SET = 15;
ENUM = 16;
BIT = 17;
DECIMAL = 18;
}
// datatype of the field in a row
required FieldType type = 1;
optional bytes name = 2;
optional bytes original_name = 3;
optional bytes table = 4;
optional bytes original_table = 5;
optional bytes schema = 6;
optional bytes catalog = 7;
optional uint64 collation = 8;
optional uint32 fractional_digits = 9;
optional uint32 length = 10;
optional uint32 flags = 11;
optional uint32 content_type = 12;
}

message Mysqlx.Resultset::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 ColumnMetaData description.

message Row {
repeated bytes field = 1;
}

Expressions

package Mysqlx.Expr::

Expression syntax

expr is the fundamental structure in various places of the SQL language:

  • SELECT <expr> AS ...
  • WHERE <expr>

The structures can be used to:

  • build an Item-tree in the MySQL Server
  • generate SQL from it
  • use as filter condition in CRUD Find(), Update(), and Delete() calls.

message Mysqlx.Expr::Expr

Expressions

The "root" of the expression tree.

If expression type is PLACEHOLDER, then it refers to the value of a parameter specified when executing a statement (see args field of StmtExecute command). Field position (which must be present for such an expression) gives 0-based position of the

Parameter in the parameter list.
message Expr {
enum Type {
IDENT = 1;
LITERAL = 2;
VARIABLE = 3;
FUNC_CALL = 4;
OPERATOR = 5;
PLACEHOLDER = 6;
OBJECT = 7;
ARRAY = 8;
};
required Type type = 1;
optional ColumnIdentifier identifier = 2;
optional string variable = 3;
optional Mysqlx.Datatypes.Scalar literal = 4;
optional FunctionCall function_call = 5;
optional Operator operator = 6;
optional uint32 position = 7;
optional Object object = 8;
optional Array array = 9;
}

message Mysqlx.Expr::Identifier

Identifier: name, schema.name

message Identifier {
required string name = 1;
optional string schema_name = 2;
}

message Mysqlx.Expr::DocumentPathItem

DocumentPathItem

message DocumentPathItem {
enum Type {
MEMBER = 1; // .member
MEMBER_ASTERISK = 2; // .*
ARRAY_INDEX = 3; // [index]
ARRAY_INDEX_ASTERISK = 4; // [*]
DOUBLE_ASTERISK = 5; // **
};
required Type type = 1;
optional string value = 2;
optional uint32 index = 3;
}

message Mysqlx.Expr::ColumnIdentifier

col_identifier (table): col@doc_path, tbl.col@doc_path col, tbl.col, schema.tbl.col col_identifier (document): doc_path

message ColumnIdentifier {
repeated Mysqlx.Expr.DocumentPathItem document_path = 1;
optional string name = 2;
optional string table_name = 3;
optional string schema_name = 4;
}

message Mysqlx.Expr::FunctionCall

Function call: func(a, b, "1", 3)

message FunctionCall {
required Identifier name = 1;
repeated Expr param = 2;
}

message Mysqlx.Expr::Operator

Operator: <<(a, b)

Note
Non-authoritative list of operators implemented (case sensitive):
Nullary
  • *
  • default
Unary
  • !
  • sign_plus
  • sign_minus
  • ~
Binary
  • &&
  • ||
  • xor
  • ==
  • !=
  • >
  • >=
  • <
  • <=
  • &
  • |
  • ^
  • <<
  • >>
  • +
  • -
  • *
  • /
  • div
  • %
  • is
  • is_not
  • regexp
  • not_regexp
  • like
  • not_like
  • cast
Using special representation, with more than 2 params
  • in (param[0] IN (param[1], param[2], ...))
  • not_in (param[0] NOT IN (param[1], param[2], ...))
Ternary
  • between
  • between_not
  • date_add
  • date_sub
Units for date_add/date_sub
  • MICROSECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • MONTH
  • QUARTER
  • YEAR
  • SECOND_MICROSECOND
  • MINUTE_MICROSECOND
  • MINUTE_SECOND
  • HOUR_MICROSECOND
  • HOUR_SECOND
  • HOUR_MINUTE
  • DAY_MICROSECOND
  • DAY_SECOND
  • DAY_MINUTE
  • DAY_HOUR
Types for cast
  • BINARY[(N)]
  • CHAR[(N)]
  • DATE
  • DATETIME
  • DECIMAL[(M[,D])]
  • JSON
  • SIGNED [INTEGER]
  • TIME
  • UNSIGNED [INTEGER]
message Operator {
required string name = 1;
repeated Expr param = 2;
}

message Mysqlx.Expr::Object

An object (with expression values).

message Object {
message ObjectField {
required string key = 1;
required Expr value = 2;
}
repeated ObjectField fld = 1;
}

message Mysqlx.Expr::Array

An array of expressions.

message Array {
repeated Expr value = 1;
}

Data Types

package Mysqlx.Datatypes::

message Mysqlx.Datatypes::Scalar

A scalar.

message Scalar {
// a string with a charset/collation
message String {
required bytes value = 1;
optional uint64 collation = 2;
};
// an opaque octet sequence, with an optional content_type
// See ``Mysqlx.Resultset.ColumnMetadata`` for list of known values.
message Octets {
required bytes value = 1;
optional uint32 content_type = 2;
};
enum Type {
V_SINT = 1;
V_UINT = 2;
V_NULL = 3;
V_OCTETS = 4;
V_DOUBLE = 5;
V_FLOAT = 6;
V_BOOL = 7;
V_STRING = 8;
};
required Type type = 1;
optional sint64 v_signed_int = 2;
optional uint64 v_unsigned_int = 3;
// 4 is unused, was Null which doesn't have a storage anymore
optional Octets v_octets = 5;
optional double v_double = 6;
optional float v_float = 7;
optional bool v_bool = 8;
optional String v_string = 9;
}

message Mysqlx.Datatypes::Object

An object.

message Object {
message ObjectField {
required string key = 1;
required Any value = 2;
}
repeated ObjectField fld = 1;
}

message Mysqlx.Datatypes::Array

An Array.

message Array {
repeated Any value = 1;
}

message Mysqlx.Datatypes::Any

A helper to allow all field types.

message Any {
enum Type {
SCALAR = 1;
OBJECT = 2;
ARRAY = 3;
};
required Type type = 1;
optional Scalar scalar = 2;
optional Object obj = 3;
optional Array array = 4;
}