ID

IEP-9

Author

Pavel Tupitsyn

Sponsor

Pavel Tupitsyn

Created

20-NOV-2017

Status


colour	GreyGreen
title	DRAFTCOMPLETED

Table of Contents

Info
This page includes low-level protocol documentation that might be outdated and is not maintained. Refer to the official protocol documentation here: https://apacheignite.readme.io/docs/binary-client-protocol

Motivation

Implement thin Ignite client in any programming language / platform using a well-defined binary connectiona protocol.

...

Name	Type Code	Size (bytes)
byte	1	1
short	2	2
int	3	4
long	4	8
float	5	4
double	6	8
char	7	2
bool	8	1
string	9	4 bytes length + length * 2Utf8 byte count + Utf8 bytes
UUID (Guid)	10	16
date	11	8 (milliseconds from 1 Jan 1970)
byte array	12	4 bytes length + length
short array	13	4 bytes length + length * 2
int array	14	4 bytes length + length * 4
long array	15	4 bytes length + length * 8
float array	16	4 bytes length + length * 4
double array	17	4 bytes length + length * 8
char array	18	4 bytes length + length * 2
bool array	19	4 bytes length + length
string array	20	4 bytes length + variable length strings, see above. Nulls (byte 101) are allowed.
UUID (Guid) array	21	4 bytes length + length * 16. Nulls (byte 101) are allowed.
date array	22	4 bytes length + length * 8. Nulls (byte 101) are allowed.
object array	23	4 bytes length + 4 bytes element type id + variable size binary objects
map	25	4 bytes length + byte type (1 = HASH_MAP, 2 = LINKED_HASH_MAP) + length * (BinaryObject + BinaryObject)
NULL	101	0

...

Header
byte	Object type code, always 103
byte	Version, always 1
short	Flags, USER_TYPE = 1, HAS_SCHEMA = 2
int	Type id, Java-style hash code of the type name
int	Hash code, Java-style hash of contents without header, necessary for comparisons
int	Length, including header
int	Schema Id
int	Schema offset from the header start, position where fields end
BinaryObject * n	Fields
(int + int) * n	Schema, fieldId (Java-style hash of field name) + offset (from header start)

Message format

All messages, request and response, including handshake, start with int message length (excluding these first 4 bytes). E.g. empty message would be represented by 4 zero bytes.

int	Length of Payload
...	Payload

Wrapped Binary Objects

One ore more binary objects can be wrapped in an array. This allows reading, storing, passing and writing objects efficiently without understanding their contents, performing simple byte copy.

All cache operations return complex objects inside a wrapper (but not primitives).

byte	Type code, always 27
int	Byte array size
n bytes	Payload
int	Offset of the object within array (array can contain an object graph, this offset points to the root object)

Message format

All messages, request and response, including handshake, start with int message length (excluding these first 4 bytes). E.g. empty message would be represented by 4 zero bytes.

int	Length of Payload
...	Payload

Length is omitted Length is omitted in all message descriptions below for brevity.

...

Response
BinaryObject	value

Cache flags

GET and all other cache operations include flags byte.

1

KEEP_BINARY

Indicates wether IgniteCache.withKeepBinary should be called on the server side.

This flag has effect only for OP_QUERY_SCAN when Java filter is used.

Other operations ignore the flag and call withKeepBinary anyway.

OP_OP_CACHE_GET_ALL = 1003

Retrieves multiple values from cache given multiple keys.

...

Request
int	Cache ID: Java-style hash code of the cache name

Response
CacheConfiguration	See below

Cache configuration is sent and received by server in the following format:

Response
CacheConfiguration	See below

Cache configuration is sent by server in the following format:

CacheConfiguration

int

Length of the configuration, in bytes

int

CacheAtomicityMode, TRANSACTIONAL = 0, ATOMIC = 1

int

Backups

int

CacheMode, LOCAL = 0, REPLICATED = 1, PARTITIONED = 2

bool

CopyOnRead

string

DataRegionName

bool

EagerTtl

bool

StatisticsEnabled

string

GroupName

long

DefaultLockTimeout (milliseconds)

int

MaxConcurrentAsyncOperations

int

MaxQueryIterators

string

Name

bool

IsOnheapcacheEnabled

int

PartitionLossPolicy, READ_ONLY_SAFE = 0, READ_ONLY_ALL = 1, READ_WRITE_SAFE = 2, READ_WRITE_ALL = 3, IGNORE = 4

int

QueryDetailMetricsSize

int

QueryParallelism

bool

ReadFromBackup

int

RebalanceBatchSize

long

RebalanceBatchesPrefetchCount

long

RebalanceDelay (milliseconds)

int

RebalanceMode, SYNC = 0, ASYNC = 1, NONE = 2

int

RebalanceOrder

long

RebalanceThrottle (milliseconds)

long

RebalanceTimeout (milliseconds)

bool

SqlEscapeAll

int

SqlIndexInlineMaxSize

string

SqlSchema

int

WriteSynchronizationMode, FULL_SYNC = 0, FULL_ASYNC = 1, PRIMARY_SYNC = 2

int

CacheKeyConfiguration count

CacheKeyConfiguration * count

CacheKeyConfiguration
string	Type name
string	Affinity key field name

int

QueryEntity count

QueryEntity * count

QueryEntity

string

Key type name

string

Value type name

string

Table name

string

Key field name

string

Value field name

int

QueryField count

QueryField * count

QueryField
string	Name
string	Type name
bool	Is key field
bool	Is NotNull constraint field

int

Alias count

(string + string) * count

Field name aliases

int

QueryIndex count

QueryIndex * count

QueryIndex
string	Index name
byte	Index type, SORTED = 0, FULLTEXT = 1, GEOSPATIAL = 2
int	Inline size
int	Field count
(string + bool) * count	Fields (name + IsDescensing)

OP_CACHE_CREATE_WITH_CONFIGURATION = 1053

Creates cache with provided configuration. Throws an exception if the name is already in use.

Request
int	Length of the configuration, in bytes
short	Number of configuration properties
(short + ...) * n	Configuration property data

Any number of configuration properties can be provided. Name is required.

Cache configuration data is specified in key-value form, where key is `short` property id and value is property-specific data. Table below describes all available properties.

Length of the configuration, in bytes

Property code

Property type

Description

2

CacheConfiguration

int

CacheAtomicityMode, TRANSACTIONAL = 0, ATOMIC = 1

3

int

Backups

1

int

CacheMode, LOCAL = 0, REPLICATED = 1, PARTITIONED = 2

5

bool

CopyOnRead

100

string

DataRegionName

405

bool

EagerTtl

406

bool

StatisticsEnabled

400

string

GroupName

bool402

invalidate

long

DefaultLockTimeout (milliseconds)

403

int

MaxConcurrentAsyncOperations

206

int

MaxQueryIterators

0

string

Name

101

bool

IsOnheapcacheEnabled

404

int

PartitionLossPolicy, READ_ONLY_SAFE = 0, READ_ONLY_ALL = 1, READ_WRITE_SAFE = 2, READ_WRITE_ALL = 3, IGNORE = 4

202

int

QueryDetailMetricsSize

201

int

QueryParallelism

6

bool

ReadFromBackup

303

int

RebalanceBatchSize

304

long

RebalanceBatchesPrefetchCount

301

long

RebalanceDelay (milliseconds)

300

int

RebalanceMode, SYNC = 0, ASYNC = 1, NONE = 2

305

int

RebalanceOrder

306

long

RebalanceThrottle (milliseconds)

302

long

RebalanceTimeout (milliseconds)

205

bool

SqlEscapeAll

204

int

SqlIndexInlineMaxSize

203

string

SqlSchema

4

int

WriteSynchronizationMode, FULL_SYNC = 0, FULL_ASYNC = 1, PRIMARY_SYNC = 2

401

int + CacheKeyConfiguration * count

CacheKeyConfiguration

*

count

CacheKeyConfiguration
string	Type name
string	Affinity key field name

200

int + QueryEntity countQueryEntity * count

QueryEntity

string

Key type name

string

Value type name

string

Table name

string

Key field name

string

Value field name

int

QueryField count

QueryField * count

QueryField
string	Name
string	Type name
bool	Is key field
bool	Is NotNull constraint field

int

Alias count

(string + string) * count

Field name aliases

int

QueryIndex count

QueryIndex * count

QueryIndex
string	Index name
byte	Index type, SORTED = 0, FULLTEXT = 1, GEOSPATIAL = 2
int	Inline size
int	Field count
(string + bool) * count	Fields (name + IsDescensing)

...

OP_CACHE_CREATE_WITH_CONFIGURATION = 1053

Creates cache with provided configuration. Throws an exception if the name is already in use.

Request
CacheConfiguration	Cache config (see format above)

Empty response.

OP_CACHE_GET_OR_CREATE_WITH_CONFIGURATION = 1054

Creates cache with provided configuration. Does nothing if the name is already in use.

Request
CacheConfiguration	Cache config (see format above)

Same request format as above. Empty response.

OP_QUERY_SQL = 2002

Performs SQL query.

...

Response

bool

False: binary type does not exist, response end.

True: binary type exists, response as follows.

int

Type id

string

Type name

string

Affinity key field name

int

BinaryField count

BinaryField * count

BinaryField
string	Field name
int	Type id
int	Field id

bool

Is enum

int (if isEnum)

Enum field count

(string + int) * count (if isEnum)

Enum values

int

Schema count

(int + int[](schema id) + int (field count) + int (field id) * n) * count

Binary schemas, set of (schemaId + fieldIds) pairs

...

Request

int

Type id

string

Type name

string

Affinity key field name

int

BinaryField count

BinaryField * count

BinaryField
string	Field name
int	Type id
int	Field id

bool

Is enum

int (if isEnum)

Enum field count

(string + int) * count (if isEnum)

Enum values

int

Schema count

(int (schema id) + int (field count) + int [](field id) * n) * count

Binary schemas, set of (schemaId + fieldIds) pairs

...

Request
int	Cache ID: Java-style hash code of the cache name
BinaryObject	Filter object
byte (if filter object is not null)	Filter platform, JAVA = 1, DOTNET = 2, CPP = 3
int	Cursor page size
int	Partition to query (negative to query entire cache)
bool	Local flag
cache)
bool	Local flag

Response
long	Cursor id
int	Row count for the first page
(Object + Object) * count	Cache entries, key + value
bool	Indicates whether more results are available to be fetched with OP_QUERY_SCAN_CURSOR_GET_PAGE
Response
long	Cursor id

OP_QUERY_SCAN_CURSOR_GET_PAGE = 2001

...

Tickets

See "thin client" component in JIRA

...

Page tree

Versions Compared

Old Version 56

New Version Current

Key

Motivation

Message format

Message format

Tickets

Page tree

Page History

Versions Compared

Old Version 56

New Version Current

Key

Motivation

Message format

Message format

Tickets