MySQL Internals Manual  /  X Protocol  /  Messages

15.3 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

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::

Notices

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

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 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.

Figure 15.8 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.

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

Figure 15.9 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.

Figure 15.10 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.

Figure 15.11 Messages for SQL


package Mysqlx.Sql::

Messages of the MySQL Package.

message Mysqlx.Sql::StmtExecute

Execute a statement in the given namespace.

Figure 15.12 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 Sets

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
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
value

Variable length encoded unsigned 64 integer.

BIT

.length

Maximum number of displayable binary digits.

Note

The valid range for M of the BIT type is 1 - 64.

value

Variable length encoded unsigned 64 integer.

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

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;
}

User Comments
Sign Up Login You must be logged in to post a comment.