Apache Ignite

GridGain Developer Hub - Apache Ignitetm

Welcome to the Apache Ignite developer hub run by GridGain. Here you'll find comprehensive guides and documentation to help you start working with Apache Ignite as quickly as possible, as well as support if you get stuck.

 

GridGain also provides Community Edition which is a distribution of Apache Ignite made available by GridGain. It is the fastest and easiest way to get started with Apache Ignite. The Community Edition is generally more stable than the Apache Ignite release available from the Apache Ignite website and may contain extra bug fixes and features that have not made it yet into the release on the Apache website.

 

Let's jump right in!

 

Documentation     Ask a Question     Download

 

Javadoc     Scaladoc     Examples

REST API

Connect to Ignite over HTTP REST protocol.

Ignite provides an HTTP REST client that gives you the ability to communicate with the grid over HTTP and HTTPS protocols using REST approach. REST APIs can be used to perform different operations like read/write from/to cache, execute tasks, get various metrics and more.

Internally, Ignite uses Jetty server to provide HTTP server features. HTTP REST client is configured with ConnectorConfiguration bean.

Returned value

HTTP REST request returns JSON object which has similar structure for each command. This object has the following structure:

name
type
description
example

affinityNodeId

string

Affinity node ID.

2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37

error

string

The field contains description of error if server could not handle the request

specifically for each command

response

jsonObject

The field contains result of command.

specifically for each command

successStatus

integer

Exit status code. It might have the following values:

  • success = 0
  • failed = 1
  • authorization failed = 2
  • security check failed = 3

0

Log

Log command shows server logs.

http://host:port/ignite?cmd=log&from=10&to=100&path=/var/log/ignite.log

Request Parameters

name
type
optional
decription
example

cmd

string

No

Should be log lowercase.

from

integer

Yes

Number of line to start from. Parameter is mandatory if to is passed.

0

path

string

Yes

The path to log file. If not provided the a default one is used.

/log/cache_server.log

to

integer

Yes

Number to line to finish on. Parameter is mandatory if from is passed.

1000

Response example:

{
  "error": "",
  "response": ["[14:01:56,626][INFO ][test-runner][GridDiscoveryManager] Topology snapshot [ver=1, nodes=1, CPUs=8, heap=1.8GB]"],
  "successStatus": 0
}
name
type
description
example

response

string

logs

["[14:01:56,626][INFO ][test-runner][GridDiscoveryManager] Topology snapshot [ver=1, nodes=1, CPUs=8, heap=1.8GB]"]

Version

Version command shows current Ignite version.

http://host:port/ignite?cmd=version

Request Parameters

name
type
optional
description
example

cmd

string

Should be version lowercase.

Response example

{
  "error": "",
  "response": "1.0.0",
  "successStatus": 0
}
name
type
description
example

response

string

Ignite version

1.0.0

Decrement

Decrement command subtracts and gets current value of given atomic long.

http://host:port/ignite?cmd=decr&cacheName=partionedCache&key=decrKey&init=15&delta=10

Request parameters

name
type
optional
decription
example

cmd

string

Should be decr lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

The name of atomic long.

counter

init

long

Yes

Initial value.

15

delta

long

Number to be subtracted.

42

Response example

{
  "affinityNodeId": "e05839d5-6648-43e7-a23b-78d7db9390d5",
  "error": "",
  "response": -42,
  "successStatus": 0
}
name
type
description
example

response

long

Value after operation.

-42

Increment

Increment command adds and gets current value of given atomic long.

http://host:port/ignite?cmd=incr&cacheName=partionedCache&key=incrKey&init=15&delta=10

Request parameters

name
type
optional
decription
example

cmd

string

Should be incr lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

The name of atomic long.

counter

init

long

Yes

Initial value.

15

delta

long

Number to be added.

42

Response example

{
  "affinityNodeId": "e05839d5-6648-43e7-a23b-78d7db9390d5",
  "error": "",
  "response": 42,
  "successStatus": 0
}
name
type
description
example

response

long

Value after operation.

42

Cache metrics

Cache metrics command shows metrics for Ignite cache.

http://host:port/ignite?cmd=cache&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be cache lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "",
  "error": "",
  "response": {
    "createTime": 1415179251551,
    "hits": 0,
    "misses": 0,
    "readTime": 1415179251551,
    "reads": 0,
    "writeTime": 1415179252198,
    "writes": 2
  },
  "successStatus": 0
}
name
type
description
example

response

jsonObject

The JSON object contains cache metrics such as create time, count reads and etc.

{
"createTime": 1415179251551, "hits": 0, "misses": 0, "readTime":1415179251551, "reads": 0,"writeTime": 1415179252198, "writes": 2
}

Compare-And-Swap

CAS command stores given key-value pair in cache only if the previous value is equal to the expected value passed in.

http://host:port/ignite?cmd=cas&key=casKey&val2=casOldVal&val1=casNewVal&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be cas lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to store in cache.

name

val

string

Value associated with the given key.

Jack

val2

string

Expected value.

Bob

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if replace happened, false otherwise.

true

Prepend

Prepend command prepends a line for value which is associated with key.

http://host:port/ignite?cmd=prepend&key=prependKey&val=prefix_&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be prepend lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to store in cache.

name

val

string

Value to be prepended to the current value.

Name_

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if replace happened, false otherwise.

true

Append

Append command appends a line for value which is associated with key.

http://host:port/ignite?cmd=append&key=appendKey&val=_suffix&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be append lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to store in cache.

name

val

string

Value to be appended to the current value.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if replace happened, false otherwise.

true

Replace

Replace command stores a given key-value pair in cache only if there is a previous mapping for it.

http://host:port/ignite?cmd=rep&key=repKey&val=newValue&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be rep lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to store in cache.

name

val

string

Value associated with the given key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if replace happened, false otherwise.

true

Get and replace

Get and replace command stores a given key-value pair in cache only if there is a previous mapping for it.

http://host:port/ignite?cmd=getrep&key=repKey&val=newValue&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be getrep lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to store in cache.

name

val

string

Value associated with the given key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": oldValue,
  "successStatus": 0
}
name
type
description
example

response

jsonObject

The previous value associated with the specified key.

{"name": "Bob"}

Replace Value

Replace Value command replaces the entry for a key only if currently mapped to a given value.

http://host:port/ignite?cmd=repval&key=repKey&val=newValue&val2=oldVal&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be repval lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to store in cache.

name

val

string

Value associated with the given key.

Jack

val2

string

Value expected to be associated with the specified key.

oldValue

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if replace happened, false otherwise.

true

Remove all

Remove all command removes given key mappings from cache.

http://host:port/ignite?cmd=rmvall&k1=rmKey1&k2=rmKey2&k3=rmKey3&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be rmvall lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

k1...kN

string

Keys whose mappings are to be removed from cache.

name

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if replace happened, false otherwise.

true

Remove value

Remove value command removes the mapping for a key only if currently mapped to the given value.

http://host:port/ignite?cmd=rmvval&key=rmvKey&val=rmvVal&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be rmvval lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key whose mapping is to be removed from the cache.

name

val

string

Value expected to be associated with the specified key.

oldValue

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

False if there was no matching key

true

Remove

Remove command removes the given key mapping from cache.

http://host:port/ignite?cmd=rmv&key=rmvKey&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be rmv lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key - for which the mapping is to be removed from cache.

name

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if replace happened, false otherwise.

true

Get and remove

Get and remove command removes the given key mapping from cache and returns previous value.

http://host:port/ignite?cmd=getrmv&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be getrmv lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key whose mapping is to be removed from the cache.

name

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": value,
  "successStatus": 0
}
name
type
description
example

response

jsonObject

Value for the key.

{"name": "bob"}

Add

Add command stores a given key-value pair in cache only if there isn't a previous mapping for it.

http://host:port/ignite?cmd=add&key=newKey&val=newValue&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be add lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to be associated with the value.

name

val

string

Value to be associated with the key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if value was stored in cache, false otherwise.

true

Put all

Put all command stores the given key-value pairs in cache.

http://host:port/ignite?cmd=putall&k1=putKey1&k2=putKey2&k3=putKey3&v1=value1&v2=value2&v3=value3&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be putall lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

k1...kN

string

Keys to be associated with values.

name

v1...vN

string

Values to be associated with keys.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if values was stored in cache, false otherwise.

true

Put

Put command stores the given key-value pair in cache.

http://host:port/ignite?cmd=put&key=newKey&val=newValue&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be put lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to be associated with values.

name

val

string

Value to be associated with keys.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if value was stored in cache, false otherwise.

true

Get all

Get all command retrieves values mapped to the specified keys from cache.

http://host:port/ignite?cmd=getall&k1=getKey1&k2=getKey2&k3=getKey3&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be getall lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

k1...kN

string

Keys whose associated values are to be returned.

key1, key2, ..., keyN

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "",
  "error": "",
  "response": {
    "key1": "value1",
    "key2": "value2"
  },
  "successStatus": 0
}
name
type
description
example

response

jsonObject

The map of key-value pairs.

{"key1": "value1","key2": "value2"}

Get

Get command retrieves value mapped to the specified key from cache.

http://host:port/ignite?cmd=get&key=getKey&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be get lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key whose associated value is to be returned

testKey

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": "value",
  "successStatus": 0
}
name
type
description
example

response

jsonObject

Value for the given key.

{"name": "bob"}

Contains key

Contains key command determines if cache containes an entry for the specified key.

http://host:port/ignite?cmd=conkey&key=getKey&cacheName=partionedCache

Request parameters

name
type
optional
description
example

cmd

string

Should be conkey lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key whose presence in this cache is to be tested.

testKey

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if this map contains a mapping for the specified key.

true

Contains keys

Contains keys command determines if cache containes an entries for the specified keys.

http://host:port/ignite?cmd=conkeys&k1=getKey1&k2=getKey2&k3=getKey3&cacheName=partionedCache

Request parameters

name
type
optional
description
example

cmd

string

Should be conkeys lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

k1...kN

string

Key whose presence in this cache is to be tested.

key1, key2, ..., keyN

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if this cache contains a mapping for the specified keys.

true

Get and put

Get and put command stores the given key-value pair in cache and returns an existing value if one existed.

http://host:port/ignite?cmd=getput&key=getKey&val=newVal&cacheName=partionedCache

Request parameters

name
type
optional
description
example

cmd

string

Should be getput lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to be associated with value.

name

val

string

Value to be associated with key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": "value",
  "successStatus": 0
}
name
type
description
example

response

jsonObject

Previous value for the given key.

{"name": "bob"}

Put if absent

Put if absent command stores given key-value pair in cache only if cache had no previous mapping for it.

http://host:port/ignite?cmd=putifabs&key=getKey&val=newVal&cacheName=partionedCache

Request parameters

name
type
optional
description
example

cmd

string

Should be putifabs lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to be associated with value.

name

val

string

Value to be associated with key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": true,
  "successStatus": 0
}
name
type
description
example

response

boolean

True if a value was set.

true

Get and put if absent

Get and put if absent command stores given key-value pair in cache only if cache had no previous mapping for it. If cache previously contained value for the given key, then this value is returned.

http://host:port/ignite?cmd=getputifabs&key=getKey&val=newVal&cacheName=partionedCache

Request parameters

name
type
optional
description
example

cmd

string

Should be getputifabs lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to be associated with value.

name

val

string

Value to be associated with key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": "value",
  "successStatus": 0
}
name
type
description
example

response

jsonObject

Previous value for the given key.

{"name": "bob"}

Cache size

Cache size command gets the number of all entries cached across all nodes.

http://host:port/ignite?cmd=size&cacheName=partionedCache

Request parameters

name
type
optional
description
example

cmd

string

Should be size lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

Response example

{
  "affinityNodeId": "",
  "error": "",
  "response": 1,
  "successStatus": 0
}
name
type
description
example

response

number

Number of all entries cached across all nodes.

5

Cache metadata

Cache metadata command gets metadata for Ignite cache.

  http://host:port/ignite?cmd=metadata&cacheName=partionedCache

Request parameters

name
type
optional
description
example

cmd

String

Should be metadata lowercase.

cacheName

String

Yes

Cache name. If not provided, default cache will be used.

partionedCache

Response example

{
  "error": "",
  "response": {
    "cacheName": "partionedCache",
    "types": [
      "Person"
    ],
    "keyClasses": {
      "Person": "java.lang.Integer"
    },
    "valClasses": {
      "Person": "org.apache.ignite.Person"
    },
    "fields": {
      "Person": {
        "_KEY": "java.lang.Integer",
        "_VAL": "org.apache.ignite.Person",
        "ID": "java.lang.Integer",
        "FIRSTNAME": "java.lang.String",
        "LASTNAME": "java.lang.String",
        "SALARY": "double"
      }
    },
    "indexes": {
      "Person": [
        {
          "name": "ID_IDX",
          "fields": [
            "id"
          ],
          "descendings": [],
          "unique": false
        },
        {
          "name": "SALARY_IDX",
          "fields": [
            "salary"
          ],
          "descendings": [],
          "unique": false
        }
      ]
    }
  },
  "sessionToken": "",
  "successStatus": 0
}
name
type
description
example

response

jsonObject

Metadata for Ignite cache.

{
"cacheName": "partionedCache",
"types": [
"Person"
],
"keyClasses": {
"Person": "java.lang.Integer"
},
"valClasses": {
"Person": "org.apache.ignite.Person"
},
"fields": {
"Person": {
"_KEY": "java.lang.Integer",
"_VAL": "org.apache.ignite.Person",
"ID": "java.lang.Integer",
"FIRSTNAME": "java.lang.String",
"LASTNAME": "java.lang.String",
"SALARY": "double"
}
},
"indexes": {
"Person": [
{
"name": "ID_IDX",
"fields": [
"id"
],
"descendings": [],
"unique": false
},
{
"name": "SALARY_IDX",
"fields": [
"salary"
],
"descendings": [],
"unique": false
}
]
}
}

Get or create cache

Get or create cache command creates cache with given name if it does not exist.

http://host:port/ignite?cmd=getorcreate&cacheName=partionedCache

Request parameters

name
type
optional
description
example

cmd

string

Should be getorcreate lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

Response example

{
  "error": "",
  "response": null,
  "successStatus": 0
}

Destroy cache

Destroy cache command destroys cache with given name.

http://host:port/ignite?cmd=destcache&cacheName=partionedCache

Request parameters

name
type
optional
description
example

cmd

string

Should be destcache lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

Response example

{
  "error": "",
  "response": null,
  "successStatus": 0
}

Node

Node command gets information about a node.

http://host:port/ignite?cmd=node&attr=true&mtr=true&id=c981d2a1-878b-4c67-96f6-70f93a4cd241

Request parameters

name
type
optional
decription
example

cmd

string

Should be node lowercase.

mtr

boolean

Yes

Response will include metrics, if this parameter has value true.

true

attr

boolean

Yes

Response will include attributes, if this parameter has value true.

true

ip

string

This parameter is optional, if id parameter is passed. Response will be returned for node which has the IP.

192.168.0.1

id

string

This parameter is optional, if ip parameter is passed. Response will be returned for node which has the node ID.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "error": "",
  "response": {
    "attributes": null,
    "caches": {},
    "consistentId": "127.0.0.1:47500",
    "defaultCacheMode": "REPLICATED",
    "metrics": null,
    "nodeId": "2d0d6510-6fed-4fa3-b813-20f83ac4a1a9",
    "replicaCount": 128,
    "tcpAddresses": ["127.0.0.1"],
    "tcpHostNames": [""],
    "tcpPort": 11211
  },
  "successStatus": 0
}
name
type
description
example

response

jsonObject

Information about only one node.

{
"attributes": null,
"caches": {},
"consistentId": "127.0.0.1:47500",
"defaultCacheMode": "REPLICATED",
"metrics": null,
"nodeId": "2d0d6510-6fed-4fa3-b813-20f83ac4a1a9",
"replicaCount": 128,
"tcpAddresses": ["127.0.0.1"],
"tcpHostNames": [""],
"tcpPort": 11211
}

Topology

Topology command gets information about grid topology.

http://host:port/ignite?cmd=top&attr=true&mtr=true&id=c981d2a1-878b-4c67-96f6-70f93a4cd241

Request parameters

name
type
optional
decription
example

cmd

string

Should be top lowercase.

mtr

boolean

Yes

Response will include metrics, if this parameter has value true.

true

attr

boolean

Yes

Response will include attributes, if this parameter has value true.

true

ip

string

Yes

This parameter is optional, if id parameter is passed. Response will be returned for node which has the IP.

192.168.0.1

id

string

Yes

This parameter is optional, if ip parameter is passed. Response will be returned for node which has the node ID.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response example

{
  "error": "",
  "response": [
    {
      "attributes": {
        ...
      },
      "caches": [
        {
          name: "",
          mode: "PARTITIONED"
        },
        {
          name: "partionedCache",
          mode: "PARTITIONED",
          sqlSchema: "partionedCache"
        }
      ],
      "consistentId": "127.0.0.1:47500",
      "metrics": {
        ...
      },
      "nodeId": "96baebd6-dedc-4a68-84fd-f804ee1ed995",
      "replicaCount": 128,
      "tcpAddresses": ["127.0.0.1"],
      "tcpHostNames": [""],
      "tcpPort": 11211
   },
   {
     "attributes": {
       ...
     },
		 "caches": [
       {
         name: "",
         mode: "REPLICATED"
       }
     ],
     "consistentId": "127.0.0.1:47501",
     "metrics": {
       ...
     },
     "nodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
     "replicaCount": 128,
     "tcpAddresses": ["127.0.0.1"],
     "tcpHostNames": [""],
     "tcpPort": 11212
   }
  ],
  "successStatus": 0
}
name
type
description
example

response

jsonObject

Information about grid topology.

[
{
"attributes": {
...
},
"caches": [
{
name: "",
mode: "PARTITIONED"
},
{
name: "partionedCache",
mode: "PARTITIONED",
sqlSchema: "partionedCache"
}
],
"consistentId": "127.0.0.1:47500",
"REPLICATED",
"metrics": {
...
},
"nodeId": "96baebd6-dedc-4a68-84fd-f804ee1ed995",
...
"tcpPort": 11211
},
{
"attributes": {
...
},
"caches": [
{
name: "",
mode: "REPLICATED"
}
],
"consistentId": "127.0.0.1:47501",
"metrics": {
...
},
"nodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
...
"tcpPort": 11212
}
]

Execute

Execute command executes given task on grid.

http://host:port/ignite?cmd=exe&name=taskName&p1=param1&p2=param2&async=true

Request parameters

name
type
optional
decription
example

cmd

string

Should be exe lowercase.

name

string

Name of the task to execute.

summ

p1...pN

string

Yes

Argument of task execution.

arg1...argN

async

boolean

Yes

The flag determines whether the task is performed asynchronously.

true

Response example

{
  "error": "",
  "response": {
    "error": "",
    "finished": true,
    "id": "~ee2d1688-2605-4613-8a57-6615a8cbcd1b",
    "result": 4
  },
  "successStatus": 0
}
name
type
description
example

response

jsonObject

JSON object contains message about error, unique identifier of task, result of computation and status of computation.

{
"error": "",
"finished": true,
"id": "~ee2d1688-2605-4613-8a57-6615a8cbcd1b",
"result": 4
}

Result

Result command returns computation result for the given task.

http://host:port/ignite?cmd=res&id=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be res lowercase.

id

string

ID of the task whose result is to be returned.

69ad0c48941-4689aae0-6b0e-4d52-8758-ce8fe26f497d~4689aae0-6b0e-4d52-8758-ce8fe26f497d

Response example

{
  "error": "",
  "response": {
    "error": "",
    "finished": true,
    "id": "69ad0c48941-4689aae0-6b0e-4d52-8758-ce8fe26f497d~4689aae0-6b0e-4d52-8758-ce8fe26f497d",
    "result": 4
  },
  "successStatus": 0
}
name
type
description
example

response

jsonObject

JSON object contains message about error, ID of task, result of computation and status of computation.

{
"error": "",
"finished": true,
"id": "~ee2d1688-2605-4613-8a57-6615a8cbcd1b",
"result": 4
}

Result

Result command returns computation result for the given task.

http://host:port/ignite?cmd=res&id=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be res lowercase.

id

string

ID of the task whose result is to be returned.

69ad0c48941-4689aae0-6b0e-4d52-8758-ce8fe26f497d~4689aae0-6b0e-4d52-8758-ce8fe26f497d

Response example

{
  "error": "",
  "response": {
    "error": "",
    "finished": true,
    "id": "69ad0c48941-4689aae0-6b0e-4d52-8758-ce8fe26f497d~4689aae0-6b0e-4d52-8758-ce8fe26f497d",
    "result": 4
  },
  "successStatus": 0
}
name
type
description
example

response

jsonObject

JSON object contains message about error, ID of task, result of computation and status of computation.

{
"error": "",
"finished": true,
"id": "~ee2d1688-2605-4613-8a57-6615a8cbcd1b",
"result": 4
}

Sql query execute

Sql query execute command runs sql query over cache.

http://host:port/ignite?cmd=qryexe&type=Person&pageSize=10&cacheName=Person&arg1=1000&arg2=2000qry=salary+%3E+%3F+and+salary+%3C%3D+%3F

Request parameters

name
type
optional
decription
example

cmd

string

Should be qryexe lowercase.

type

string

Type for the query

String

pageSize

number

Page size for the query

3

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

testCache

arg1...argN

string

Qyery arguments

1000,2000

qry

strings

Encoding sql query

salary+%3E+%3F+and+salary+%3C%3D+%3F

Response example

{
  "error":"",
  "response":{
    "fieldsMetadata":[],
    "items":[
      {"key":3,"value":{"name":"Jane","id":3,"salary":2000}},
      {"key":0,"value":{"name":"John","id":0,"salary":2000}}],
    "last":true,
    "queryId":0},
  "successStatus":0
}
name
type
description
example

response

jsonObject

JSON object contains result items for query, flag for last page and queryId for query fetching.

{
"fieldsMetadata":[],
"items":[
{"key":3,"value":{"name":"Jane","id":3,"salary":2000}},
{"key":0,"value":{"name":"John","id":0,"salary":2000}}],
"last":true,
"queryId":0
}

Sql fields query execute

Sql fields query execute command runs sql fields query over cache.

http://host:port/ignite?cmd=qryfldexe&pageSize=10&cacheName=Person&qry=select+firstName%2C+lastName+from+Person

Request parameters

name
type
optional
decription
example

cmd

string

Should be qryfldexe lowercase.

pageSize

number

Page size for the query

3

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

testCache

arg1...argN

string

Qyery arguments

1000,2000

qry

strings

Encoding sql fields query

select+firstName%2C+lastName+from+Person

Response example

{
  "error": "",
  "response": {
    "fieldsMetadata": [
      {
        "fieldName": "FIRSTNAME",
        "fieldTypeName": "java.lang.String",
        "schemaName": "person",
        "typeName": "PERSON"
      },
      {
        "fieldName": "LASTNAME",
        "fieldTypeName": "java.lang.String",
        "schemaName": "person",
        "typeName": "PERSON"
      }
    ],
    "items": [["Jane", "Doe" ], ["John", "Doe"]],
    "last": true,
    "queryId": 0
  },
  "successStatus": 0
}
name
type
description
example

response

jsonObject

JSON object contains result items for query, fields query metadata, flag for last page and queryId for query fetching.

{
"fieldsMetadata":[{"fieldName":"FIRSTNAME", "fieldTypeName":"java.lang.String", "schemaName":"person", "typeName":"PERSON"},...],
"items":[["Jane","Doe"],["John","Doe"]],
"last":true,
"queryId":0
}

Sql scan query execute

Sql scan query execute command runs sql scan query over cache.

http://host:port/ignite?cmd=qryscanexe&pageSize=10&cacheName=Person&className=org.apache.ignite.schema.Person

Request parameters

name
type
optional
decription
example

cmd

String

Should be qryscanexe lowercase.

pageSize

Number

Page size for the query

3

cacheName

String

Yes

Cache name. If not provided, default cache will be used.

testCache

className

String

Yes

Predicate class name for scan query.

org.apache.ignite.schema.Person

Response example

{
  "error": "",
  "response": {
    "fieldsMetadata": [
      {
        "fieldName": "key",
        "fieldTypeName": "",
        "schemaName": "",
        "typeName": ""
      },
      {
        "fieldName": "value",
        "fieldTypeName": "",
        "schemaName": "",
        "typeName": ""
      }
    ],
    "items": [
      {
        "key": 1,
        "value": {
          "firstName": "Jane",
          "id": 1,
          "lastName": "Doe",
          "salary": 1000
        }
      },
      {
        "key": 3,
        "value": {
          "firstName": "Jane",
          "id": 3,
          "lastName": "Smith",
          "salary": 2000
        }
      }
    ],
    "last": true,
    "queryId": 0
  },
  "successStatus": 0
}
name
type
description
example

response

jsonObject

JSON object contains result items for scan query, fields query metadata, flag for last page and queryId for query fetching.

{
"fieldsMetadata":[{"fieldName":"key", "fieldTypeName":"", "schemaName":"", "typeName":""},{"fieldName":"value","fieldTypeName":"","schemaName":"","typeName":""}],
"items":[{"key":1,"value":{"firstName":"Jane","id":1,"lastName":"Doe","salary":1000}},{"key":3,"value":{"firstName":"Jane","id":3,"lastName":"Smith","salary":2000}}],
"last":true,
"queryId":0
}

Sql query fetch

Sql query fetch command gets next page for the query.

http://host:port/ignite?cmd=qryfetch&pageSize=10&qryId=5

Request parameters

name
type
optional
decription
example

cmd

string

Should be qryfetch lowercase.

pageSize

number

Page size for the query.

3

qryId

number

Query id that is returned from Sql query execute, sql fields query execute or sql fetch commands.

0

Response example

{
  "error":"",
  "response":{
    "fieldsMetadata":[],
    "items":[["Jane","Doe"],["John","Doe"]],
    "last":true,
    "queryId":0
  },
  "successStatus":0
}
name
type
description
example

response

jsonObject

JSON object contains result items for query, flag for last page and queryId for query fetching.

{
"fieldsMetadata":[],
"items":[["Jane","Doe"],["John","Doe"]],
"last":true,
"queryId":0
}

Sql query close

Sql query close command closes query resources.

http://host:port/ignite?cmd=qrycls&qryId=5

Request parameters

name
type
optional
decription
example

cmd

string

Should be qrycls lowercase.

qryId

number

Query id that is returned from Sql query execute, sql fields query execute or sql fetch commands.

0

Response example

{
  "error":"",
  "response":true,
  "successStatus":0
}
name
type
description
example

response

boolean

True if query closed successfully.

true

General Configuration

Parameter Name
Description
Optional
Default Value

setSecretKey(String)

Defines secret key used for client authentication. When provided, client request must contain HTTP header X-Signature with the string "[1]:[2]", where [1] is timestamp in milliseconds and [2] is the Base64 encoded SHA1 hash of the secret key.

Yes

null

setPortRange(int)

Port range for Jetty server. In case port provided in Jetty configuration or IGNITE_JETTY_PORT system property is already in use, Ignite will iteratively increment port by 1 and try binding once again until provided port range is exceeded.

Yes

100

setJettyPath(String)

Path to Jetty configuration file. Should be either absolute or relative to IGNITE_HOME. If not provided then GridGain will start Jetty server with simple HTTP connector. This connector will use IGNITE_JETTY_HOST and IGNITE_JETTY_PORT system properties as host and port respectively. In case IGNITE_JETTY_HOST is not provided, localhost will be used as default. In case IGNITE_JETTY_PORT is not provided, port 8080 will be used as default.

Yes

null

Sample Jetty XML configuration

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
    <Arg name="threadPool">
        <!-- Default queued blocking thread pool -->
        <New class="org.eclipse.jetty.util.thread.QueuedThreadPool">
            <Set name="minThreads">20</Set>
            <Set name="maxThreads">200</Set>
        </New>
    </Arg>
    <New id="httpCfg" class="org.eclipse.jetty.server.HttpConfiguration">
        <Set name="secureScheme">https</Set>
        <Set name="securePort">8443</Set>
        <Set name="sendServerVersion">true</Set>
        <Set name="sendDateHeader">true</Set>
    </New>
    <Call name="addConnector">
        <Arg>
            <New class="org.eclipse.jetty.server.ServerConnector">
                <Arg name="server"><Ref refid="Server"/></Arg>
                <Arg name="factories">
                    <Array type="org.eclipse.jetty.server.ConnectionFactory">
                        <Item>
                            <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                                <Ref refid="httpCfg"/>
                            </New>
                        </Item>
                    </Array>
                </Arg>
                <Set name="host">
                  <SystemProperty name="IGNITE_JETTY_HOST" default="localhost"/>
              	</Set>
                <Set name="port">
                  <SystemProperty name="IGNITE_JETTY_PORT" default="8080"/>
              	</Set>
                <Set name="idleTimeout">30000</Set>
                <Set name="reuseAddress">true</Set>
            </New>
        </Arg>
    </Call>
    <Set name="handler">
        <New id="Handlers" class="org.eclipse.jetty.server.handler.HandlerCollection">
            <Set name="handlers">
                <Array type="org.eclipse.jetty.server.Handler">
                    <Item>
                        <New id="Contexts" class="org.eclipse.jetty.server.handler.ContextHandlerCollection"/>
                    </Item>
                </Array>
            </Set>
        </New>
    </Set>
    <Set name="stopAtShutdown">false</Set>
</Configure>

REST API

Connect to Ignite over HTTP REST protocol.