...
ID | IEP-76 | ||||||||||
Author | |||||||||||
Sponsor | |||||||||||
Created |
| ||||||||||
Status |
|
Table of Contents |
---|
...
Adapt Ignite 2.x protocol for Ignite 3.0. Main The main differences are:
...
ClientConnectorConfiguration
class....
MsgPack is used for data serialization (uses big-endian byte order).
Ignite data types defined in IEP-54 map to MsgPack data types the following way:
Ignite Type | Size | MsgPack Type | Notes | ||
---|---|---|---|---|---|
Bitmask(n) | ⌈n/8⌉ bytes | bin8 / bin16 / bin32 | Extension 8 | ||
IntX, UintX | 1-8 bytes | fixint / intX / uintX | Integer types are interchangeable when possible. fixint (1 byte) can be passed as a value for uint64 column. | ||
Float | 4 bytes | float32 | |||
Double | 8 bytes | float64 | |||
Number([n]) | Variable | ext16 (up to 2^8 - 1 bytes) | Extension 1 | ||
Decimal | Variable | ext16 (up to 2^8 - 1 bytes) | Extension 2 | ||
UUID | 16 bytes | fixext16 | Extension 3 | ||
String | Variable | str | |||
Date | 3 bytes | fixext4 | Extension 4 | ||
Time | 4 5 bytes | fixext4ext8 | Extension 5 | ||
Datetime | 7 bytes | fixext8 | Extension 6 | ||
Timestamp | 8 bytes | 10 bytes | ext8 | Extension 7 | |
IgniteUuid | 24 bytes | ext8 | Extension 9 | ||
NoValue | 1 byte | fixext1 | Extension 10timestamp 64 | ||
Binary | Variable | bin32 (up to 2^32 - 1 bytes) |
...
MsgPack provides multiple data types for integer values. When encoding a value, the smallest data type for that value is picked automatically.
...
All messages, request requests and responseresponses, except handshake, start with int a 4-byte message length (excluding the length itself).
int 4 bytes | Length of Payload |
... | Payload |
A simple way to serialize a tuple would be to write a map (String → ...) from column name to value.
However, thanks to schema-first approach, we can avoid sending column names with the values (serializing strings is expensive). Instead, we can write an integer schema version, and then values for every column in that schema.
values "type" below indicates a raw sequence of values (not a MsgPack array). Since we know the number of columns in the schema, we don't need an array header.
int | Schema version |
values | Column values in schema order. nil when there is no value for a particular column. |
To read or write a value for a column, we get the column type from the schema and use corresponding MsgPack data type according to Data Types Mapping above.
Code Block | ||||
---|---|---|---|---|
| ||||
for (Column col : tuple) {
switch (col.type().spec()) {
case BYTE:
packer.packByte(tuple.byteValue(col.name()));
break;
case SHORT:
... |
Key tuples are tuples with key columns only. Key columns always come first in the schema. So if there are 2 key columns, first two values of the tuple is the key.
Ignite Table API handles "column set to null" (1) and "column not set" (2) differently.
NoValue custom protocol type reflects this distinction.
Request | |
---|---|
4 bytes | Magic number 49 47 4E 49, or "IGNI". Helps identifying to identify misconfigured SSL or other apps probing the port. |
int | Payload length |
int | Version major |
int | Version minor |
int | Version patch |
int | Client code (1 for JDBC, 2 for general-purpose client) |
bin | Features (bitmask) |
map (string → any) | Extensions (auth, attributes, etc). Server can skip unknown extension data (when client is newer). |
...
Response | |||
---|---|---|---|
4 bytes | Magic number 49 47 4E 49, or "IGNI". Helps identifying to identify misconfigured SSL or different server on the port. | ||
int | Payload length | ||
int | Server version major | ||
int | Server version minor | ||
int | Server version patch | ||
int | Error code (0 for success) | ||
string | Error message (when error code is not 0) | ||
int | When error code is 0: Server idle timeout | boolean | Success flag |
string | When success flag is false: Error messageerror code is 0: Server node id | ||
string | When error code is 0: Server node name (consistent id) | ||
bin | When success flag error code is true0: Server features (bitmask) | ||
map (string → any) | When success flag error code is true0: Extensions (auth, attributes, etc). Client can skip unknown extension data (when server is newer). |
...
Upon successful handshake, client can start performing operations by sending a request with specific op code. Each operation has it's its own request and response format, with a common header.
Request | |
int | Operation code |
int | Request id, generated by client and returned as-is in response |
... | Operation-specific data |
Response | ||
int | Type = 0 | |
int | Request id | |
int | Flags (1 = partition assignment changed) | |
long | Observable timestamp (causality token) | |
uuid or null | Trace id (null for success) | |
int | Error code ( | 0 for successwhen trace id is not null) |
string | Error message | (when error code is not 0(when trace id is not null) |
string or null | Error stack trace (when trace id is not null) | |
map or null | Error details (when trace id is not null) | |
... | Operation-specific data (when trace id is null) |
Request or response without operation-specific data is called basic request or basic response below.
Clients should expect notification messages at any moment after the successful handshake.
...
Operation codes and request ids are omitted everywhere below for brevity.
...
...
Basic request.
Response | |
---|---|
map (UUID -> string) | map of table ids and names |
Note: tables can only be created/deleted with SQL, there are no TABLE_CREATE or TABLE_DROP operations.
Request | |
---|---|
string | table name |
Response | |
---|---|
UUID or nil | table ID or null when a table with the given name does not exist |
...
TODO: Schema, settings - extendable (map-based)
TODO: Returns table UUID
...
Request | |
---|---|
UUID | table ID |
Response does not have extra data (see basic response above).
Request does not have extra data (see basic request above).
...
arr or nil | schema IDs, or null to get latest |
Response | |
---|---|
map (int → array (array)) | Map from schema ID to columns. Column is represented by an array of values for: name, type, isKey, isNullable. The array can contain extra data in future for additional properties. |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
values | values for all columns in given schema (nil when value is missing for a column) |
Basic response.
Client side is supposed to match provided columns against the latest known schema.
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
values | values for key columns (in schema order) |
Response | |
---|---|
int or nil | schema id for the current tuple, or nil when there is no matching record |
values | values for value columns in schema order, when schema id is not nil |
Clients should retrieve schemas with SCHEMAS_GET and cache them per table.
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
int | row count |
values | rows with values for all columns in given schema (nil when value is missing for a column) |
Basic response.
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID, or nil when result set is empty |
int | row count |
values | array of rows with values for key columns (in schema order) |
Response | |
---|---|
int | schema ID (for all tuples in response) |
int | row count |
values | rows with values in schema order |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
values | values for all columns in given schema (nil when value is missing for a column) |
Response | |
---|---|
int or nil | schema id for the current tuple, or nil when there is no matching record |
values | values for value columns in schema order |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
values | values for all columns in given schema (nil when value is missing for a column) |
Response | |
---|---|
bool | Insert result |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
int | row count |
values | rows with values for all columns in given schema (nil when value is missing for a column) |
Response | |
---|---|
int | schema id, or nil when no rows were skipped |
int | skipped row count |
values | skipped rows (values in schema order) |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
values | values for all columns in given schema (nil when value is missing for a column) |
Response | |
---|---|
bool | Replace result |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
values | oldRec: values for all columns in given schema (nil when value is missing for a column) |
values | newRec: values for all columns in given schema (nil when value is missing for a column) |
Response | |
---|---|
bool | Replace result |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
values | values for all columns in given schema (nil when value is missing for a column) |
Response | |
---|---|
int or nil | schema id for the current tuple, or nil when there is no matching record |
values | values for value columns in schema order |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
values | values for key columns in given schema |
Response | |
---|---|
bool | Delete result |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
int | row count |
values | rows with values for key columns in a given schema |
Response | |
---|---|
int | schema id, or nil when no rows were skipped |
int | skipped row count |
values | skipped rows (values for key columns in schema order) |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
values | values for all columns in given schema (nil when value is missing for a column) |
Response | |
---|---|
bool | Delete result |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
int | row count |
values | rows with values for all columns in given schema (nil when value is missing for a column) |
Response | |
---|---|
int | schema id, or nil when no rows were skipped |
int | skipped row count |
values | skipped rows (values for key columns in schema order) |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
values | values for all columns in given schema (nil when value is missing for a column) |
Response | |
---|---|
int or nil | schema id for the current tuple, or nil when there is no matching record |
values | values for value columns in schema order, when schema id is not null |
Request | |
---|---|
UUID | table ID |
int or nil | transaction ID |
int | schema ID |
values | values for key columns |
Response | |
---|---|
bool | whether a tuple with the given key exists |
Request | |
---|---|
bool | Read-only tx flag |
long | Observable timestamp (value from server - see standard response header) |
Response | |
---|---|
int | Transaction ID |
Request | |
---|---|
int | Transaction ID |
Basic response
Request | |
---|---|
int | Transaction ID |
Basic response
...
...
Response does not have extra data (see basic response above).
TODO: Separate key and value maps?
...
TODO: returns schema ID?
Schemas can be cached on the client.
gets one or more schemas by table UUID and ids
TODO
...
...