Package com.aerospike.client.exp

Class MapExp

java.lang.Object

com.aerospike.client.exp.MapExp

public final class MapExp
extends Object

Map expression generator. See Exp.

The bin expression argument in these methods can be a reference to a bin or the result of another expression. Expressions that modify bin values are only used for temporary expression evaluation and are not permanently applied to the bin.

Map modify expressions return the bin's value. This value will be a map except when the map is nested within a list. In that case, a list is returned for the map modify expression.

Valid map key types are:

• String
• Integer
• byte[]

The server will validate map key types in an upcoming release.

All maps maintain an index and a rank. The index is the item offset from the start of the map, for both unordered and ordered maps. The rank is the sorted index of the value component. Map supports negative indexing for index and rank.

Index examples:

• Index 0: First item in map.
• Index 4: Fifth item in map.
• Index -1: Last item in map.
• Index -3: Third to last item in map.
• Index 1 Count 2: Second and third items in map.
• Index -3 Count 3: Last three items in map.
• Index -5 Count 4: Range between fifth to last item to second to last item inclusive.

Rank examples:

• Rank 0: Item with lowest value rank in map.
• Rank 4: Fifth lowest ranked item in map.
• Rank -1: Item with highest ranked value in map.
• Rank -3: Item with third highest ranked value in map.
• Rank 1 Count 2: Second and third lowest ranked items in map.
• Rank -3 Count 3: Top three ranked items in map.

Nested expressions are supported by optional CTX context arguments. Example:

• bin = {key1={key11=9,key12=4}, key2={key21=3,key22=5}}
• Set map value to 11 for map key "key21" inside of map key "key2".
• Get size of map key2.
• MapExp.size(Exp.mapBin("bin"), CTX.mapKey(Value.get("key2"))
• result = 2

Constructor Summary

Constructors

Constructor	Description
MapExp()

Method Summary

Modifier and Type	Method	Description
static Exp	clear(Exp bin, CTX... ctx)	Create expression that removes all items in map.
static Exp	getByIndex(int returnType, Exp.Type valueType, Exp index, Exp bin, CTX... ctx)	Create expression that selects map item identified by index and returns selected data specified by returnType (See MapReturnType).
static Exp	getByIndexRange(int returnType, Exp index, Exp bin, CTX... ctx)	Create expression that selects map items starting at specified index to the end of map and returns selected data specified by returnType (See MapReturnType).
static Exp	getByIndexRange(int returnType, Exp index, Exp count, Exp bin, CTX... ctx)	Create expression that selects "count" map items starting at specified index and returns selected data specified by returnType (See MapReturnType).
static Exp	getByKey(int returnType, Exp.Type valueType, Exp key, Exp bin, CTX... ctx)	Create expression that selects map item identified by key and returns selected data specified by returnType.
static Exp	getByKeyList(int returnType, Exp keys, Exp bin, CTX... ctx)	Create expression that selects map items identified by keys and returns selected data specified by returnType (See MapReturnType).
static Exp	getByKeyRange(int returnType, Exp keyBegin, Exp keyEnd, Exp bin, CTX... ctx)	Create expression that selects map items identified by key range (keyBegin inclusive, keyEnd exclusive).
static Exp	getByKeyRelativeIndexRange(int returnType, Exp key, Exp index, Exp bin, CTX... ctx)	Create expression that selects map items nearest to key and greater by index.
static Exp	getByKeyRelativeIndexRange(int returnType, Exp key, Exp index, Exp count, Exp bin, CTX... ctx)	Create expression that selects map items nearest to key and greater by index with a count limit.
static Exp	getByRank(int returnType, Exp.Type valueType, Exp rank, Exp bin, CTX... ctx)	Create expression that selects map item identified by rank and returns selected data specified by returnType (See MapReturnType).
static Exp	getByRankRange(int returnType, Exp rank, Exp bin, CTX... ctx)	Create expression that selects map items starting at specified rank to the last ranked item and returns selected data specified by returnType (See MapReturnType).
static Exp	getByRankRange(int returnType, Exp rank, Exp count, Exp bin, CTX... ctx)	Create expression that selects "count" map items starting at specified rank and returns selected data specified by returnType (See MapReturnType).
static Exp	getByValue(int returnType, Exp value, Exp bin, CTX... ctx)	Create expression that selects map items identified by value and returns selected data specified by returnType.
static Exp	getByValueList(int returnType, Exp values, Exp bin, CTX... ctx)	Create expression that selects map items identified by values and returns selected data specified by returnType (See MapReturnType).
static Exp	getByValueRange(int returnType, Exp valueBegin, Exp valueEnd, Exp bin, CTX... ctx)	Create expression that selects map items identified by value range (valueBegin inclusive, valueEnd exclusive) If valueBegin is null, the range is less than valueEnd.
static Exp	getByValueRelativeRankRange(int returnType, Exp value, Exp rank, Exp bin, CTX... ctx)	Create expression that selects map items nearest to value and greater by relative rank.
static Exp	getByValueRelativeRankRange(int returnType, Exp value, Exp rank, Exp count, Exp bin, CTX... ctx)	Create expression that selects map items nearest to value and greater by relative rank with a count limit.
static Exp	increment(MapPolicy policy, Exp key, Exp incr, Exp bin, CTX... ctx)	Create expression that increments values by incr for all items identified by key.
static Exp	put(MapPolicy policy, Exp key, Exp value, Exp bin, CTX... ctx)	Create expression that writes key/value item to a map bin.
static Exp	putItems(MapPolicy policy, Exp map, Exp bin, CTX... ctx)	Create expression that writes each map item to a map bin.
static Exp	removeByIndex(Exp index, Exp bin, CTX... ctx)	Create expression that removes map item identified by index.
static Exp	removeByIndexRange(int returnType, Exp index, Exp bin, CTX... ctx)	Create expression that removes map items starting at specified index to the end of map.
static Exp	removeByIndexRange(int returnType, Exp index, Exp count, Exp bin, CTX... ctx)	Create expression that removes "count" map items starting at specified index.
static Exp	removeByKey(Exp key, Exp bin, CTX... ctx)	Create expression that removes map item identified by key.
static Exp	removeByKeyList(int returnType, Exp keys, Exp bin, CTX... ctx)	Create expression that removes map items identified by keys.
static Exp	removeByKeyRange(int returnType, Exp keyBegin, Exp keyEnd, Exp bin, CTX... ctx)	Create expression that removes map items identified by key range (keyBegin inclusive, keyEnd exclusive).
static Exp	removeByKeyRelativeIndexRange(int returnType, Exp key, Exp index, Exp bin, CTX... ctx)	Create expression that removes map items nearest to key and greater by index.
static Exp	removeByKeyRelativeIndexRange(int returnType, Exp key, Exp index, Exp count, Exp bin, CTX... ctx)	Create expression that removes map items nearest to key and greater by index with a count limit.
static Exp	removeByRank(Exp rank, Exp bin, CTX... ctx)	Create expression that removes map item identified by rank.
static Exp	removeByRankRange(int returnType, Exp rank, Exp bin, CTX... ctx)	Create expression that removes map items starting at specified rank to the last ranked item.
static Exp	removeByRankRange(int returnType, Exp rank, Exp count, Exp bin, CTX... ctx)	Create expression that removes "count" map items starting at specified rank.
static Exp	removeByValue(int returnType, Exp value, Exp bin, CTX... ctx)	Create expression that removes map items identified by value.
static Exp	removeByValueList(int returnType, Exp values, Exp bin, CTX... ctx)	Create expression that removes map items identified by values.
static Exp	removeByValueRange(int returnType, Exp valueBegin, Exp valueEnd, Exp bin, CTX... ctx)	Create expression that removes map items identified by value range (valueBegin inclusive, valueEnd exclusive).
static Exp	removeByValueRelativeRankRange(int returnType, Exp value, Exp rank, Exp bin, CTX... ctx)	Create expression that removes map items nearest to value and greater by relative rank.
static Exp	removeByValueRelativeRankRange(int returnType, Exp value, Exp rank, Exp count, Exp bin, CTX... ctx)	Create expression that removes map items nearest to value and greater by relative rank with a count limit.
static Exp	size(Exp bin, CTX... ctx)	Create expression that returns list size.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MapExp

public MapExp()

Method Details

put

public static Exp put(MapPolicy policy,
 Exp key,
 Exp value,
 Exp bin,
 CTX... ctx)

Create expression that writes key/value item to a map bin. The 'bin' expression should either reference an existing map bin or be a expression that returns a map.

 // Add entry{11,22} to existing map bin.
 Expression e = Exp.build(MapExp.put(MapPolicy.Default, Exp.val(11), Exp.val(22), Exp.mapBin(binName)));
 client.operate(null, key, ExpOperation.write(binName, e, ExpWriteFlags.DEFAULT));

 // Combine entry{11,22} with source map's first index entry and write resulting map to target map bin.
 Expression e = Exp.build(
   MapExp.put(MapPolicy.Default, Exp.val(11), Exp.val(22),
     MapExp.getByIndexRange(MapReturnType.KEY_VALUE, Exp.val(0), Exp.val(1), Exp.mapBin(sourceBinName)))
   );
 client.operate(null, key, ExpOperation.write(targetBinName, e, ExpWriteFlags.DEFAULT));
 

putItems

public static Exp putItems(MapPolicy policy,
 Exp map,
 Exp bin,
 CTX... ctx)

Create expression that writes each map item to a map bin.

increment

public static Exp increment(MapPolicy policy,
 Exp key,
 Exp incr,
 Exp bin,
 CTX... ctx)

Create expression that increments values by incr for all items identified by key. Valid only for numbers.

clear

public static Exp clear(Exp bin,
 CTX... ctx)

Create expression that removes all items in map.

removeByKey

public static Exp removeByKey(Exp key,
 Exp bin,
 CTX... ctx)

Create expression that removes map item identified by key.

removeByKeyList

public static Exp removeByKeyList(int returnType,
 Exp keys,
 Exp bin,
 CTX... ctx)

Create expression that removes map items identified by keys. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

removeByKeyRange

public static Exp removeByKeyRange(int returnType,
 Exp keyBegin,
 Exp keyEnd,
 Exp bin,
 CTX... ctx)

Create expression that removes map items identified by key range (keyBegin inclusive, keyEnd exclusive). If keyBegin is null, the range is less than keyEnd. If keyEnd is null, the range is greater than equal to keyBegin. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

removeByKeyRelativeIndexRange

public static Exp removeByKeyRelativeIndexRange(int returnType,
 Exp key,
 Exp index,
 Exp bin,
 CTX... ctx)

Create expression that removes map items nearest to key and greater by index. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

Examples for map [{0=17},{4=2},{5=15},{9=10}]:

• (value,index) = [removed items]
• (5,0) = [{5=15},{9=10}]
• (5,1) = [{9=10}]
• (5,-1) = [{4=2},{5=15},{9=10}]
• (3,2) = [{9=10}]
• (3,-2) = [{0=17},{4=2},{5=15},{9=10}]

removeByKeyRelativeIndexRange

public static Exp removeByKeyRelativeIndexRange(int returnType,
 Exp key,
 Exp index,
 Exp count,
 Exp bin,
 CTX... ctx)

Create expression that removes map items nearest to key and greater by index with a count limit. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

Examples for map [{0=17},{4=2},{5=15},{9=10}]:

• (value,index,count) = [removed items]
• (5,0,1) = [{5=15}]
• (5,1,2) = [{9=10}]
• (5,-1,1) = [{4=2}]
• (3,2,1) = [{9=10}]
• (3,-2,2) = [{0=17}]

removeByValue

public static Exp removeByValue(int returnType,
 Exp value,
 Exp bin,
 CTX... ctx)

Create expression that removes map items identified by value. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

removeByValueList

public static Exp removeByValueList(int returnType,
 Exp values,
 Exp bin,
 CTX... ctx)

Create expression that removes map items identified by values. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

removeByValueRange

public static Exp removeByValueRange(int returnType,
 Exp valueBegin,
 Exp valueEnd,
 Exp bin,
 CTX... ctx)

Create expression that removes map items identified by value range (valueBegin inclusive, valueEnd exclusive). If valueBegin is null, the range is less than valueEnd. If valueEnd is null, the range is greater than equal to valueBegin. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

removeByValueRelativeRankRange

public static Exp removeByValueRelativeRankRange(int returnType,
 Exp value,
 Exp rank,
 Exp bin,
 CTX... ctx)

Create expression that removes map items nearest to value and greater by relative rank. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

Examples for map [{4=2},{9=10},{5=15},{0=17}]:

• (value,rank) = [removed items]
• (11,1) = [{0=17}]
• (11,-1) = [{9=10},{5=15},{0=17}]

removeByValueRelativeRankRange

public static Exp removeByValueRelativeRankRange(int returnType,
 Exp value,
 Exp rank,
 Exp count,
 Exp bin,
 CTX... ctx)

Create expression that removes map items nearest to value and greater by relative rank with a count limit. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

Examples for map [{4=2},{9=10},{5=15},{0=17}]:

• (value,rank,count) = [removed items]
• (11,1,1) = [{0=17}]
• (11,-1,1) = [{9=10}]

removeByIndex

public static Exp removeByIndex(Exp index,
 Exp bin,
 CTX... ctx)

Create expression that removes map item identified by index.

removeByIndexRange

public static Exp removeByIndexRange(int returnType,
 Exp index,
 Exp bin,
 CTX... ctx)

Create expression that removes map items starting at specified index to the end of map. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

removeByIndexRange

public static Exp removeByIndexRange(int returnType,
 Exp index,
 Exp count,
 Exp bin,
 CTX... ctx)

Create expression that removes "count" map items starting at specified index. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

removeByRank

public static Exp removeByRank(Exp rank,
 Exp bin,
 CTX... ctx)

Create expression that removes map item identified by rank.

removeByRankRange

public static Exp removeByRankRange(int returnType,
 Exp rank,
 Exp bin,
 CTX... ctx)

Create expression that removes map items starting at specified rank to the last ranked item. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

removeByRankRange

public static Exp removeByRankRange(int returnType,
 Exp rank,
 Exp count,
 Exp bin,
 CTX... ctx)

Create expression that removes "count" map items starting at specified rank. Valid returnType values are MapReturnType.NONE or MapReturnType.INVERTED.

size

public static Exp size(Exp bin,
 CTX... ctx)

Create expression that returns list size.

 // Map bin "a" size > 7
 Exp.gt(MapExp.size(Exp.mapBin("a")), Exp.val(7))
 

getByKey

public static Exp getByKey(int returnType,
 Exp.Type valueType,
 Exp key,
 Exp bin,
 CTX... ctx)

Create expression that selects map item identified by key and returns selected data specified by returnType.

 // Map bin "a" contains key "B"
 MapExp.getByKey(MapReturnType.EXISTS, Exp.Type.BOOL, Exp.val("B"), Exp.mapBin("a"))
 

Parameters:

returnType - metadata attributes to return. See MapReturnType

valueType - expected type of return value

key - map key expression

bin - bin or map value expression

ctx - optional context path for nested CDT

getByKeyRange

public static Exp getByKeyRange(int returnType,
 Exp keyBegin,
 Exp keyEnd,
 Exp bin,
 CTX... ctx)

Create expression that selects map items identified by key range (keyBegin inclusive, keyEnd exclusive). If keyBegin is null, the range is less than keyEnd. If keyEnd is null, the range is greater than equal to keyBegin.

Expression returns selected data specified by returnType (See MapReturnType).

getByKeyList

public static Exp getByKeyList(int returnType,
 Exp keys,
 Exp bin,
 CTX... ctx)

Create expression that selects map items identified by keys and returns selected data specified by returnType (See MapReturnType).

getByKeyRelativeIndexRange

public static Exp getByKeyRelativeIndexRange(int returnType,
 Exp key,
 Exp index,
 Exp bin,
 CTX... ctx)

Create expression that selects map items nearest to key and greater by index. Expression returns selected data specified by returnType (See MapReturnType).

Examples for ordered map [{0=17},{4=2},{5=15},{9=10}]:

• (value,index) = [selected items]
• (5,0) = [{5=15},{9=10}]
• (5,1) = [{9=10}]
• (5,-1) = [{4=2},{5=15},{9=10}]
• (3,2) = [{9=10}]
• (3,-2) = [{0=17},{4=2},{5=15},{9=10}]

getByKeyRelativeIndexRange

public static Exp getByKeyRelativeIndexRange(int returnType,
 Exp key,
 Exp index,
 Exp count,
 Exp bin,
 CTX... ctx)

Create expression that selects map items nearest to key and greater by index with a count limit. Expression returns selected data specified by returnType (See MapReturnType).

Examples for ordered map [{0=17},{4=2},{5=15},{9=10}]:

• (value,index,count) = [selected items]
• (5,0,1) = [{5=15}]
• (5,1,2) = [{9=10}]
• (5,-1,1) = [{4=2}]
• (3,2,1) = [{9=10}]
• (3,-2,2) = [{0=17}]

getByValue

public static Exp getByValue(int returnType,
 Exp value,
 Exp bin,
 CTX... ctx)

Create expression that selects map items identified by value and returns selected data specified by returnType.

 // Map bin "a" contains value "BBB"
 MapExp.getByValue(MapReturnType.EXISTS, Exp.val("BBB"), Exp.mapBin("a"))
 

Parameters:

returnType - metadata attributes to return. See MapReturnType

value - value expression

bin - bin or map value expression

ctx - optional context path for nested CDT

getByValueRange

public static Exp getByValueRange(int returnType,
 Exp valueBegin,
 Exp valueEnd,
 Exp bin,
 CTX... ctx)

Create expression that selects map items identified by value range (valueBegin inclusive, valueEnd exclusive) If valueBegin is null, the range is less than valueEnd. If valueEnd is null, the range is greater than equal to valueBegin.

Expression returns selected data specified by returnType (See MapReturnType).

getByValueList

public static Exp getByValueList(int returnType,
 Exp values,
 Exp bin,
 CTX... ctx)

Create expression that selects map items identified by values and returns selected data specified by returnType (See MapReturnType).

getByValueRelativeRankRange

public static Exp getByValueRelativeRankRange(int returnType,
 Exp value,
 Exp rank,
 Exp bin,
 CTX... ctx)

Create expression that selects map items nearest to value and greater by relative rank. Expression returns selected data specified by returnType (See MapReturnType).

Examples for map [{4=2},{9=10},{5=15},{0=17}]:

• (value,rank) = [selected items]
• (11,1) = [{0=17}]
• (11,-1) = [{9=10},{5=15},{0=17}]

getByValueRelativeRankRange

public static Exp getByValueRelativeRankRange(int returnType,
 Exp value,
 Exp rank,
 Exp count,
 Exp bin,
 CTX... ctx)

Create expression that selects map items nearest to value and greater by relative rank with a count limit. Expression returns selected data specified by returnType (See MapReturnType).

Examples for map [{4=2},{9=10},{5=15},{0=17}]:

• (value,rank,count) = [selected items]
• (11,1,1) = [{0=17}]
• (11,-1,1) = [{9=10}]

getByIndex

public static Exp getByIndex(int returnType,
 Exp.Type valueType,
 Exp index,
 Exp bin,
 CTX... ctx)

Create expression that selects map item identified by index and returns selected data specified by returnType (See MapReturnType).

getByIndexRange

public static Exp getByIndexRange(int returnType,
 Exp index,
 Exp bin,
 CTX... ctx)

Create expression that selects map items starting at specified index to the end of map and returns selected data specified by returnType (See MapReturnType).

getByIndexRange

public static Exp getByIndexRange(int returnType,
 Exp index,
 Exp count,
 Exp bin,
 CTX... ctx)

Create expression that selects "count" map items starting at specified index and returns selected data specified by returnType (See MapReturnType).

getByRank

public static Exp getByRank(int returnType,
 Exp.Type valueType,
 Exp rank,
 Exp bin,
 CTX... ctx)

Create expression that selects map item identified by rank and returns selected data specified by returnType (See MapReturnType).

getByRankRange

public static Exp getByRankRange(int returnType,
 Exp rank,
 Exp bin,
 CTX... ctx)

Create expression that selects map items starting at specified rank to the last ranked item and returns selected data specified by returnType (See MapReturnType).

getByRankRange

public static Exp getByRankRange(int returnType,
 Exp rank,
 Exp count,
 Exp bin,
 CTX... ctx)

Create expression that selects "count" map items starting at specified rank and returns selected data specified by returnType (See MapReturnType).