Skip to main content
Aerospike 8 introduces a new era of real-time transaction processingLearn more
Loading

List operations

Contextโ€‹

Context TypeDescription
LIST_INDEXFinds an element in a List by index. A negative index is a lookup performed in reverse from the end of the list. If it is out of bounds, a parameter error is returned.
LIST_RANKFinds an element in a List by rank. A negative rank is a lookup performed in reverse from the highest ranked.
LIST_VALUEFinds an element in a List by value.
LIST_INDEX_CREATEFinds an element in a List by index. Creates the element if it does not exist.
MAP_INDEXFinds an element in a Map by index. A negative index is a lookup performed in reverse from the end of the map. If it is out of bounds, a parameter error is returned.
MAP_KEYFinds an element in a Map by key.
MAP_RANKFinds an element in a Map by rank. A negative rank is a lookup performed in reverse from the highest ranked.
MAP_VALUEFinds an element in a Map by value.
MAP_KEY_CREATEFinds an element in a Map by key. Creates the element if it does not exist.

The context parameter is a list of context types defining a path to the nested list or map element the operation should be applied to. Without a context it is assumed that the operation occurs at the top level of the List or Map.

Write Flagsโ€‹

FlagDescription
MODIFY_DEFAULTDefault: upserts; not bound by list size; accepts duplicate elements; throws error on failure
ADD_UNIQUEOnly add elements if they do not already exist in the list
INSERT_BOUNDEDDo not insert past index N, where N is element count
NO_FAILNo-op instead of fail if a policy violation occurred, such as ADD_UNIQUE or INSERT_BOUNDED
DO_PARTIALWhen used with NO_FAIL, add elements that did not violate a policy

Return Typesโ€‹

Return TypeDescription
VALUEThe value of the element (in single result operations) or elements (in multi result operations)
NONENothing is returned. It speeds up remove operations by not constructing a reply
COUNTNumber of elements returned
INDEXIndex position of the element, from 0 (first) to N-1 (last)
REVERSE_INDEXReverse index position of the element, from 0 (last) to N-1 (first)
RANKValue order of the element, with 0 being the smallest
REVERSE_RANKReverse rank order of the element, with 0 being the largest value
INVERTEDInvert the search criteria. It can be combined with another return type in the range operations
EXISTSIf the return type is EXISTS, the function returns a boolean value. For example, using the List function get_all_by_value with the return type EXISTS, returnstrue if the specified value is contained in the List. The List function get_all_by_value_list with the EXISTS, returns true if the List contains any of the specified values.

Availabilityโ€‹

EXISTS available since 6.1.0
NO_FAIL and DO_PARTIAL write flags available since 4.3.0.
Relative rank operations since 4.3.0.
Context available since 4.6.0.

note

In certain older server versions, for ordered lists and a VALUE return type, an empty list is always returned.
Affected versions are:

  • 3.16.0.1 to 4.6.0.21
  • 4.7.0.2 to 4.7.0.19
  • 4.8.0.1 to 4.8.0.15
  • 4.9.0.3 to 4.9.0.12
  • 5.0.0.3 to 5.0.0.13
  • 5.1.0.3 to 5.1.0.10
  • 5.2.0.2

These operations and examples are for use with the Aerospike Java Client.


Set Type Operationsโ€‹

setOrder

ListOperation.setOrder(binName, order, persistIndex, context)

Modifies the order of an existing list. Order can be UNORDERED (default) or ORDERED.

See CDT Element Ordering and Comparison.

Returns: Operation

The writeFlags and context are described at the top of this page.

Performance: The setOrder operation does nothing when called on an already ordered list or on an ordered-to-unordered transition. The worst-case performance of modifying an unordered list to an ordered one is ๐“ž(N log N). See List performance for the full worst-case performance analysis of the List API.

Code Samplesโ€‹

// Before list operation
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
        writePolicy,
        key,
        ListOperation.setOrder(testBinName, ListOrder.ORDERED, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
        );

// After list operation
// {"sighting":{"reportedBy":["Bill Gruber","Elon Smith","Jeff Baker","Jesse Rogan","Mark Zimmer"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

Read Operationsโ€‹

size

ListOperation.size(binName, context)

Gets the size of a list, optionally at a given sub-context.

Returns: Operation

The writeFlags and context are described at the top of this page.

Performance: The worst-case performance of getting the size of the list is ๐“ž(1). See List performance for the full worst-case performance analysis of the List API.

Code Samplesโ€‹


// Sighting record
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.size(binName, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `5`

getByIndex

ListOperation.getByIndex(binName, index, listReturnType, context)

Gets the element at the specified list index. The index must be a number between 0 and N-1, where N is the length of the list. The index can also be a negative number, with -1 being the last element by index position.

On an ordered list this operation with a VALUE return type will be the same as a list get_by_rank operation.

Returns: Operation

Note on return types: INDEX and COUNT are redundant in this operation. INVERTED has no meaning in this operation.

The returnTypes and context are described at the top of this page.

throws: An Operation Not Applicable error (code 26) when trying to get an inaccessible index.

Exampleโ€‹

["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"] modified with set_order to ORDERED will turn into ["Bill Gruber","Elon Smith","Jeff Baker","Jesse Rogan","Mark Zimmer"].

The value of element at index -1 is Mark Zimmer, the rank at -1 is Mark Zimmer.

The value of element at index 2 is Jeff Baker, the rank at 2 is Jeff Baker.

Code Samplesโ€‹


// Sighting record
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.getByIndex(binName, 2, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `Jeff Baker`

getByIndexRange

ListOperation.getByIndexRange(binName, index, listReturnType, context)

Gets a range of count elements starting at a specified list index. The INVERTED flag may be used to get the elements not in a specified range.

The index and count can be any number, but the result may be an empty list if the specified range contains no elements.

Returns: Operation

The returnTypes and context are described at the top of this page.

Note on return types: INDEX is redundant in this operation.

Performance: The worst-case performance of getting elements by index range is ๐“ž(M) for an ordered list that is stored in memory. Unordered lists, or an ordered list stored on SSD has a ๐“ž(N + M), where M is the element count of the range, and N is the element count of the list. See List performance for the full worst-case performance analysis of the List API.

Exampleโ€‹

For ["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"] the VALUE range starting at index 2 and containing 3 elements gives back ["Jeff Baker","Mark Zimmer","Bill Gruber"], while the INVERTED | VALUE of the same range gives back ["Jesse Rogan","Elon Smith"].

Code Samplesโ€‹


// Sighting record
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.getByIndexRange(binName, 3, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `["Mark Zimmer","Bill Gruber"]`

getByRank

ListOperation.getByRank(binName, rank, listReturnType, context)

Gets the element with the specified rank order. The rank must be a number between 0 (lowest rank) and N-1 (highest rank), where N is the length of the list. The rank can also be a negative number, with -1 being the element with the highest rank.

On an ordered list this operation with a VALUE return type will be the same as a list get_by_index operation, (see this example).

Whether the list is unordered or ordered, get_by_rank will return the same elements, based on the ordering rules. The performance of 'by rank' operations is better on an ordered list than an unordered one.

Returns: Operation

The returnTypes and context are described at the top of this page.

Note on return types: RANK and COUNT are redundant in this operation. INVERTED has no meaning in this operation.

Exampleโ€‹

[ "Jesse Rogan", "Elon Smith", ["Lisa White", "Moe Simpson"], "Jeff Baker", ["Lisa White", "Bart Flanders"], "Mark Zimmer", "Bill Gruber", "Will Gruber" ] modified with ListOrder.setOrder to ListOrder.ORDERED will turn into ["Bill Gruber","Elon Smith","Jeff Baker","Jesse Rogan","Mark Zimmer","Will Gruber",["Lisa White","Bart Flanders"],["Lisa White","Moe Simpson"]] because a list has higher ranking order than integers, and the list elements are compared by index when sorted.

Code Samplesโ€‹


// Sighting record
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.setOrder(testBinName, ListOrder.ORDERED, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Sorts elements of the list for the key `reportedBy` in ascending order
    ListOperation.getByRank(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `Bill Gruber` at rank `0` (lowest rank)

client.operate(
    writePolicy,
    key,
    ListOperation.getByRank(binName, -1, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns value `Will Gruber` at rank `-1` (highest rank)

getByRankRange

ListOperation.getByRankRange(binName, rank, listReturnType, context)

Gets a range of count elements starting at a specified rank. The INVERTED flag may be used to get the elements not in a specified range.

The rank and count can be any number, but the result may be an empty list if the specified range contains no elements.

Returns: Operation

One or a list of values, based on the return type. The elements returned may not be in rank order.

The returnTypes and context are described at the top of this page.

Examplesโ€‹

["Jesse Rogan", "Elon Smith", "Jeff Baker", "Mark Zimmer", "Bill Gruber", "Will Gruber"] the VALUE range starting at rank 2 and containing 2 elements gives back ["Jesse Rogan", "Jeff Baker"], while the INVERTED | VALUE of the same range gives back ["Elon Smith", "Mark Zimmer", "Bill Gruber", "Will Gruber"].

Code Samplesโ€‹

// Sighting record
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.getByRankRange(binName, 2, 2, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns list `["Jesse Rogan", "Jeff Baker"]` starting at rank 2 with size of 2

client.operate(
    writePolicy,
    key,
    ListOperation.getByRankRange(binName, 2, 2, ListReturnType.INVERTED | ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returned inverted list `["Elon Smith", "Mark Zimmer", "Bill Gruber", "Will Gruber"]` starting at rank 2 with size of 2

client.operate(
    writePolicy,
    key,
    ListOperation.getByRank(binName, -3, 3, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operations returns `["Jesse Rogan", "Mark Zimmer", "Will Gruber"]` (get the top three ranked elements)

getByValue

ListOperation.getByValue(binName, value, listReturnType, context)

Gets all the elements in the list matching value. The INVERTED flag may be used to get the elements not matching the specified value.

Whether the list is unordered or ordered, getByValue will return the same elements, based on the ordering rules. The performance of 'by value' operations is better on an ordered list than an unordered one.

Returns: Operation

Zero, one or a list of values, based on the return type. The elements returned may not be in index order.

The returnTypes and context are described at the top of this page.

Performance:

The worst-case performance of getting elements by value is ๐“ž(log N + M) for an ordered list that is stored in memory, ๐“ž(log N + N) for an ordered list stored on SSD, and ๐“ž(N + M) for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list. See List performance for the full worst-case performance analysis of the List API.

Trivial Exampleโ€‹

// Sighting record
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

// Count all the elements whose value is `"Elon Smith"`
client.operate(
    writePolicy,
    key,
    ListOperation.getByValue(binName, Value.get("Elon Smith"), ListReturnType.COUNT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `1`

Matching Tuples with Wildcardโ€‹

It is common to model complex data in Aerospike as a list of tuples, each element a list, where the index order carries meaning. For an example, see Aerospike Modeling: IoT Sensors.

In a list of mostly ordered pairs, we could search for a specific kind of element, such as all the tuples where the 0th position is "v2", by using a wildcard (typically stylized as a * in documentation).

// Sighting record
// {"sighting":{"reportedBy":[["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["VP","Jeff Baker"],["VP","Mark Zimmer"],["Engineer","Bill Gruber"],["Engineer","Will Gruber"]],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.getByValue(binName, Value.get(List.of("VP", Value.WILDCARD)) , ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `[["VP","Jeff Baker"],["VP","Mark Zimmer"]]`

Code Examplesโ€‹

See the examples above, or follow any of these language-specific links for detailed code examples for the operation.

getByValueList

ListOperation.getByValueList(binName, valueList, listReturnType, context)

Returns: Operation

Zero, one or a list of values, based on the return type. The elements returned may not be in index order.

The returnTypes and context are described at the top of this page.

Performance:

The worst-case performance of getting elements by a value list is ๐“ž((M+N) log M) for an ordered list that is stored in memory, ๐“ž((M+N) log M + N) for an ordered list stored on SSD, or for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list. See List performance for the full worst-case performance analysis of the List API.

Trivial Exampleโ€‹

Count the number of elements in the list with a specified scalar value.

// Sighting record
// {"sighting":{"reportedBy":[["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["VP","Jeff Baker"],["VP","Mark Zimmer"],["Engineer","Bill Gruber"],["Engineer","Will Gruber"],["Director","Marge Flanders"]],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.getByValueList(binName, List.of(Value.get("Jesse Rogan"), Value.get("Will Gruber")), ListReturnType.COUNT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `2`

Matching Tuples with Wildcardโ€‹

See the example given for getByValueList.

In a list of mostly ordered pairs, we could search for all the tuples that do not start with "VP" or "Engineer", by using a wildcard and an INVERTED | VALUE return type.

// Sighting record
// {"sighting":{"reportedBy":[["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["VP","Jeff Baker"],["VP","Mark Zimmer"],["Engineer","Bill Gruber"],["Engineer","Will Gruber"],["Director","Marge Flanders"]],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.getByValueList(testBinName, List.of(Value.get(List.of("VP", Value.WILDCARD)), Value.get(List.of("Engineer", Value.WILDCARD))), ListReturnType.VALUE | ListReturnType.INVERTED, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `[["Director","Marge Flanders"]]`

The wildcard matches any sequence of elements to the end of the tuple. In this example, this means matching any tuple whose first position is "VP" or "Engineer".

Code Examplesโ€‹

See the examples above, or follow any of these language-specific links for detailed code examples for the operation.

getByValueRange

ListOperation.getByValueRange(binName, valueBegin, valueEnd, listReturnType, context)

Gets the list elements that sort into the interval between valueStart (inclusive) and valueStop (exclusive). The INVERTED flag may be used to get the elements outside this interval.

Whether the list is unordered or ordered, getByValueRange will return the same elements, based on the ordering rules. The performance of 'by value' operations is better on an ordered list than an unordered one.

Returns: Operation

Zero, one or a list of values, based on the return type. The elements returned may not be in index order.

The returnTypes and context are described at the top of this page.

Performance:

The worst-case performance of getting elements in a value interval is ๐“ž(log N + M) for an ordered list that is stored in memory, ๐“ž(log N + N) for an ordered list stored on SSD, and ๐“ž(N + M) for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list. See List performance for the full worst-case performance analysis of the List API.

Trivial Exampleโ€‹

// Sighting
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber","Will Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}
client.operate(
    writePolicy,
    testKey,
    ListOperation.setOrder(testBinName, ListOrder.ORDERED, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Ordering values in lexicographical ascending order
    ListOperation.getByValueRange(testBinName, Value.get("Jesse Rogan"), null, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Returns `["Jesse Rogan","Mark Zimmer","Will Gruber"]` since sorted input list is `["Bill Gruber","Elon Smith","Jeff Baker","Jesse Rogan","Mark Zimmer","Will Gruber"]`

Interval Comparison of Tuplesโ€‹

It is common to model complex data in Aerospike as a list of tuples, each element a list, where the index order carries meaning. For an example, see Aerospike Modeling: IoT Sensors.

This modeling relies on the ordering rules that apply to list elements. Ordered pairs sort into

[1, NIL] < [1, 1] < [1, 1, 2] < [1, 2] < [1, '1'] < [1, 1.0] < [1, INF]

Take the list of ordered pairs, [[100, 1], [101, 2], [102, 3], [103, 4], [104, 5]] and the following intervals:

valueStart: [101, NIL], valueStop: [103, NIL]

Iterating over the elements we check if [101, NIL] <= value < [103, NIL]. This is true for the elements [101, 2] and [102, 3]. The element [103, 4] is not in this interval, because its order is higher than [103, NIL]. The comparison starts with the 0th index values, in this case both are 103. Next the 1st index position values are compared, and NIL is lower than 3 (actually its order is lower than any value).

valueStart: [101, NIL], valueStop: [103, INF]

The elements [101, 2] and [102, 3] are obviously in the interval. The element [103, 4] is also in this interval, because its order is lower than [103, INF]. The comparison starts with the 0th index values, in this case both are 103. Next the 1st index position values are compared, and INF is higher than 3 (actually its order is higher than any value).

valueStart: [101, INF], valueStop: [103, INF]

The elements [102, 2] and [103, 4] are in the interval. The element [101, 2] is not in this interval, because its order is lower than [101, INF].

Code Examplesโ€‹

// Sighting
// {"sighting":{"reportedBy":[["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["VP","Jeff Baker"],["VP","Mark Zimmer"],["Engineer","Bill Gruber"],["Engineer","Will Gruber"],["Director","Liza Flanders"]],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(binName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Sorts lists at key `reportedBy` to `[["Director","Liza Flanders"],["Engineer","Bill Gruber"],["Engineer","Elon Smith"],["Engineer","Jesse Rogan"],["Engineer","Will Gruber"],["VP","Jeff Baker"],["VP","Mark Zimmer"]]`
    ListOperation.getByValueRange(binName, Value.get(List.of(Value.get("Engineer"))), Value.get(List.of(Value.get("VP"))), ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))) // Returns all entries between tags `Director` and `VP` (exclusively)
);

// Operation returns `[["Engineer","Bill Gruber"],["Engineer","Elon Smith"],["Engineer","Jesse Rogan"],["Engineer","Will Gruber"]]`

getByRelativeRankRange

ListOperation.getByRelativeRankRange(binName, value, rank, count, listReturnType, context)

Gets a range of count elements starting at a rank offset from the relative rank of the given value. The INVERTED flag may be used to get the elements not in this range.

The value can be anything, not necessarily a value that exists in the list. The rank and count can be any number, but the result may be an empty list if the specified range contains no elements.

The relative rank of the value compared to the current list follows the ordering rules.

Returns: Operation

Zero, one or a list of values, based on the return type. The elements returned may not be in index order.

The returnTypes and context are described at the top of this page.

Performance: The worst-case performance of getting elements by relative rank range is ๐“ž(M + log N) for an ordered list that is stored in memory. An ordered list stored on SSD has a ๐“ž(N + M + log N), where M is the element count of the range, and N is the element count of the list. An unordered list has a ๐“ž(R log N + N), with R for rank. See List performance for the full worst-case performance analysis of the List API.

Exampleโ€‹

For [0, 3, 9, 12, 15] a value of 5 would rank between 3 and 9, relative to the current list. A rank of -1 from there would select 3 as the starting point of the range, and then the count would select the elements. So a count of 3 would return the range 3, 9 and 12.

Code Examplesโ€‹

// Sighting
// {"sighting":{"reportedBy":[["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["VP","Jeff Baker"],["VP","Mark Zimmer"],["Engineer","Bill Gruber"],["Engineer","Will Gruber"],["Director","Marge Flanders"]],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(binName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Sort list at key `reportedBy` to `[["Director","Liza Flanders"],["Engineer","Bill Gruber"],["Engineer","Elon Smith"],["Engineer","Jesse Rogan"],["Engineer","Will Gruber"],["VP","Jeff Baker"],["VP","Mark Zimmer"]]` 
    ListOperation.getByValueRelativeRankRange(binName, Value.get(List.of(Value.get("Engineer"))), 0, 4, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Fetches all lists with Engineer tag including first `"Engineer"` since we have specified 0 rank and counts up to 4 elements.
);

// Operation returns `[["Engineer","Will Gruber"],["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["Engineer","Bill Gruber"]]`

Modify Operationsโ€‹

clear

ListOperation.clear(binName, context)

Clears a list, optionally at a given sub_context.

Returns: Operation

The writeFlags and context are described at the top of this page.

Performance: The worst-case performance of clearing a list is ๐“ž(1). See List performance for the full worst-case performance analysis of the List API.

Code Samplesโ€‹

// Before list operation
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.clear(binName, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))),
);

// After list operation
// {"sighting":{"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

sort

ListOperation.sort(binName, context)

Sorts a list, but doesn't change the list order. An unordered list will remain unordered after being sorted. An ordered list doesn't need to be sorted, because by definition it sorts itself any time elements are added to it.

Returns: Operation

The writeFlags and context are described at the top of this page.

Sort Flags:

FlagDescription
ListSortFlags.DEFAULTDefault keep duplicates
ListSortFlags.DROP_DUPLICATESDrop duplicates while sorting

Performance: The sort operation will do no work when called on an already ordered list. The worst-case performance of sorting an unordered list is ๐“ž(N log N). See List performance for the full worst-case performance analysis of the List API.

Code Samplesโ€‹

// Sighting 
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(testBinName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))),
    ListOperation.getByIndexRange(testBinName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `["Bill Gruber","Elon Smith","Jeff Baker","Jesse Rogan","Mark Zimmer","Will Gruber"]`

append

ListOperation.append(binName, value, context)

Creates a list bin with a specified order, if the bin does not exist. Adds a value to the list. In an UNORDERED list the value is appended to the end of the list. In an ORDERED list the value is inserted by value order.

Returns: Operation

The element count due to the operation, in the 'bins' part of the record under the bin name.

The writeFlags and context are described at the top of this page.

Order: A list newly created with append can be declared UNORDERED (default) or ORDERED using the list order attribute of the list policy. Once a list is created its order can only be modified with setOrder.

Note on write flags:

Write flags can be combined to alter the behavior of the operation. For example, ADD_UNIQUE | NO_FAIL will fail gracefully without throwing an exception if the element already exists.

INSERT_BOUNDED and DO_PARTIAL are not applicable for this operation.

Performance: The worst-case performance of append() on an unordered list is ๐“ž(N). See List performance for the full worst-case performance analysis of the List API.

Code Samplesโ€‹

// Sighting 
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(binName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Sorts list in lexicographical ascending order
    ListOperation.append(binName, Value.get("Lisa Flanders"),  CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Appends `Lisa Flanders` to sorted list
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))) // Fetch updated list
);

// Operation returns `["Bill Gruber","Elon Smith","Jeff Baker","Jesse Rogan","Mark Zimmer","Will Gruber","Lisa Flanders"]`

appendItems

ListOperation.appendItems(binName, valueList..., context)

Creates a list bin with a specified order, if the bin does not exist. Adds the items to the list. In an UNORDERED list the items are appended to the end of the list. In an ORDERED list the items are inserted by value order.

Returns: Operation

The element count due to the operation, in the 'bins' part of the record under the bin name.

The writeFlags and context are described at the top of this page.

Order: A list newly created with append_items can be declared UNORDERED (default) or ORDERED using the list order attribute of the list policy. Once a list is created its order can only be modified with setOrder.

Note on write flags:

Write flags can be combined to alter the behavior of the operation. For example, ADD_UNIQUE | NO_FAIL will fail gracefully without throwing an exception if any new item already exists.

INSERT_BOUNDED is not applicable for this operation.

Performance: The worst-case performance of append_items on an unordered list is ๐“ž(M), and ๐“ž((M+N) log (M+N)) on an ordered list, where M is the number of items to append and N is the number of items already in the list. See List performance for the full worst-case performance analysis of the List API.

Code Samplesโ€‹

// Sighting 
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(binName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))),
    ListOperation.appendItems(binName, List.of(Value.get("Lisa Flanders"), Value.get("Milhouse House")),  CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))),
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `["Bill Gruber","Elon Smith","Jeff Baker","Jesse Rogan","Mark Zimmer","Will Gruber","Lisa Flanders","Milhouse House"]`

insert

ListOperation.insert(binName, index, value, context)

Creates an unordered list bin, if the bin does not exist. Inserts a value into the list at the specified index, and shifts elements with a higher index to the right of the new element.

By default the index can be any number, and NIL values will be added as padding to the left of the new element, as needed. Using the INSERT_BOUNDED policy, a developer can limit this behavior, and only allow for an element to be inserted at an index value between 0 and the size of the list.

Note:

You cannot insert into an ordered list, only append or appendItems to one.

Returns: Operation

The element count due to the operation, in the 'bins' part of the record under the bin name.

The writeFlags and context are described at the top of this page.

Order: A list newly created with insert is always unordered. Once a list is created its order can only be modified with setOrder.

Note on write flags:

Write flags can be combined to alter the behavior of the operation. For example, ADD_UNIQUE | NO_FAIL will fail gracefully without throwing an exception if any new item already exists.

DO_PARTIAL is not applicable for this operation, as we only insert one element at a time.

Performance: The worst-case performance of inserting an item at the head of a list (at its 0th index) is ๐“ž(1). At any other index it is ๐“ž(N). See List performance for the full worst-case performance analysis of the List API.

Code Samplesโ€‹

// Sighting 
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(binName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))),
    ListOperation.insert(binName, 0, Value.get("Milhouse House"),  CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))),
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `["Bill Gruber","Elon Smith","Jeff Baker","Jesse Rogan","Mark Zimmer","Will Gruber","Lisa Flanders","Milhouse House"]`

set

ListOperation.set(binName, index, value, context)

Creates an unordered list bin, if the bin does not exist. Sets or overwrites a value at the specified list index. (This set function has no relation to the Aerospike concept of sets as a collection of records.)

By default the index can be any number, and NIL values will be added as padding to the left of the new element, as needed. Using the INSERT_BOUNDED policy, a developer can limit this behavior, and only allow for an element to be set at an index value between 0 and the size of the list.

Note:

You cannot set a value in an ordered list, only append or appendItems to one.

Returns: Operation

The element count due to the operation, in the 'bins' part of the record under the bin name.

The writeFlags and context are described at the top of this page.

Order: A list newly created with set() is always unordered.

Note on write flags:

Write flags can be combined to alter the behavior of the operation. For example, ADD_UNIQUE | NO_FAIL will fail gracefully without throwing an exception if the element already exists.

DO_PARTIAL is not applicable for this operation, as we only set one element at a time.

Performance: The worst-case performance of setting an item at the head of a list (at its 0th index) is ๐“ž(1). At any other index it is ๐“ž(N). See List performance for the full worst-case performance analysis of the List API.

Code Samplesโ€‹

// Sighting 
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(binName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))),
    ListOperation.set(binName, 1, Value.get("Milhouse House"),  CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))),
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `["Bill Gruber","Milhouse House","Jeff Baker","Jesse Rogan","Mark Zimmer","Will Gruber"]`

increment

ListOperation.increment(binName, index, value, context)

Creates an unordered list bin if the bin does not exist. In an UNORDERED list, increment() initializes or increments a numeric value at the specified list index. In an ORDERED list, increments a numeric value at a specific rank, given by the index argument.

By default the index can be any number, and NIL values will be added as padding to the left of the new element, as needed. Using the INSERT_BOUNDED policy, a developer can limit this behavior, and only allow for an element to be incremented at an index value between 0 and the size of the list.

Increment delta values can be either float or integer. An integer delta value will be converted into a float if the server-side type is a float. A float delta-value will be converted and truncated into an integer if the server-side value is an integer.

Returns: Operation

The new value after the increment, in the 'bins' part of the record under the bin name.

The writeFlags and context are described at the top of this page.

Order: A list newly created with increment is always unordered. Once a list is created its order can only be modified with setOrder.

Note on flags:

Write flags can be combined to alter the behavior of the operation. For example, ADD_UNIQUE | NO_FAIL will fail gracefully without throwing an exception if the element already exists.

DO_PARTIAL is not applicable for this operation, as we only increment one element at a time.

Performance: The worst-case performance of increment() on an unordered list is ๐“ž(N). See List performance for the full worst-case performance analysis of the List API.

Code Samplesโ€‹

// Sighting 
// {"sighting":{"occurred":[20200228,20210228,20220228,20230228],"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(binName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("occurred"))), // Sorting elements in 
    ListOperation.increment(binName, 1, Value.get(5),  CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("occurred"))), // Incrementing value at index 1 by 5
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("occurred"))) // Returns updated list
);

// Operation returns `[20200228,20210233,20220228,20230228]`

removeByIndex

ListOperation.removeByIndex(binName, index, value, context)

Removes the element at the specified list index. The index must be a number between 0 and N-1, where N is the length of the list. The index can also be a negative number, with -1 being the last element by index position.

Returns: Operation

Zero or one value, based on the return type. The NONE return type will execute faster because no reply is constructed for the operation.

The returnTypes and context are described at the top of this page.

Note on return types: INDEX and COUNT are redundant for this operation. INVERTED has no meaning for this operation.

Throws: An Operation Not Applicable error (code 26) when trying to remove an inaccessible index.

Performance: The worst-case performance of removing the element by index is ๐“ž(1) for an ordered list that is stored in memory. Unordered lists, or an ordered list stored on SSD has a ๐“ž(N). See List performance for the full worst-case performance analysis of the List API.

Code Samplesโ€‹

// Sighting 
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber","Will Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.removeByIndex(testBinName, 0,  ListReturnType.NONE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Removes element at index 0 `"Jesse Rogan"`
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("occurred"))) // Returns updated list
);

// Operation returns `["Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber","Will Gruber"]`

removeByIndexRange

ListOperation.removeByIndexRange(binName, index, count, listReturnType, context)

Removes a range of count elements starting at a specified list index. The INVERTED flag may be used to remove the elements not in a specified range.

The index and count can be any number, but the result may be an empty list if the specified range contains no elements.

Returns: Operation

Zero, one or a list of values, based on the return type. The NONE return type will execute faster because no reply is constructed for the operation. The elements returned by other return types may not be in index order.

The returnTypes and context are described at the top of this page.

Note on return types: INDEX is redundant for this operation.

Performance: The worst-case performance of removing elements by index range is ๐“ž(M) for an ordered list that is stored in memory. Unordered lists, or an ordered list stored on SSD has a ๐“ž(N + M), where M is the element count of the range, and N is the element count of the list. See List performance for the full worst-case performance analysis of the List API.

Examplesโ€‹

["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber","Will Gruber"] a range starting at 0 and containing 3 elements removes ["Jesse Rogan","Elon Smith","Jeff Baker"], while the INVERTED | NONE of the same range removes ["Mark Zimmer","Bill Gruber","Will Gruber"].

Code Samplesโ€‹

// Sighting 
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber","Will Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.removeByIndexRange(binName, 0, 3, ListReturnType.NONE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Removed elements from index 0 to index 3 (exclusive)
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))) // Return list starting at index 0
);

// Operation returns `["Mark Zimmer","Bill Gruber","Will Gruber"]`

removeByRankRange

ListOperation.removeByRankRange(binName, index, count, listReturnType, context)

Removes a range of count elements starting at a specified rank. The INVERTED flag may be used to remove the elements not in a specified range.

The rank and count can be any number, but the result may be an empty list if the specified range contains no elements.

Returns: Operation

Zero, one or a list of values, based on the return type. The NONE return type will execute faster because no reply is constructed for the operation. The elements returned by other return types may not be in rank order.

The returnTypes and context are described at the top of this page.

Note on return types: INDEX is redundant for this operation.

Performance: The worst-case performance of removing elements by rank range is ๐“ž(M) for an ordered list that is stored in memory. An ordered list stored on SSD has a ๐“ž(N + M), where M is the element count of the range, and N is the element count of the list. An unordered list has a ๐“ž(R log N + N). See List performance for the full worst-case performance analysis of the List API.

Code Samplesโ€‹

// Sighting 
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber","Will Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(binName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Sorts list at `reportedBy` to  `["Bill Gruber","Elon Smith","Jeff Baker","Jesse Rogan","Mark Zimmer","Will Gruber"]`
    ListOperation.removeByRankRange(binName, 0, 3, ListReturnType.NONE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))),  // Removes ["Bill Gruber","Elon Smith","Jeff Baker"]
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))) // Returns updated list at `reportedBy`
);

// Operation returns `["Jesse Rogan","Mark Zimmer","Will Gruber"]`

removeByValue

ListOperation.removeByValue(binName, value, listReturnType, context)

Removes all the elements in the list matching value. The INVERTED flag may be used to remove the elements not matching the specified value.

Returns: Operation

Zero, one or a list of values, based on the return type. The NONE return type will execute faster because no reply is constructed for the operation. The elements returned by other return types may not be in index order.

The returnTypes and context are described at the top of this page.

Order: Whether the list is unordered or ordered, removeByValue will return the same elements, based on the ordering rules. The performance of 'by value' operations is better on an ordered list than an unordered one.

Performance: The worst-case performance of removing elements by value is ๐“ž(log N + M) for an ordered list that is stored in memory, ๐“ž(log N + N) for an ordered list stored on SSD, and ๐“ž(N + M) for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list. See List performance for the full worst-case performance analysis of the List API.

Trivial Exampleโ€‹

// Sighting 
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber","Will Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.removeByValue(binName, Value.get("Elon Smith"), ListReturnType.NONE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Removes `"Elon Smith"` from the list at key `reportedBy`
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))) // Returns updated list at `reportedBy`
);

// Operation returns `["Jesse Rogan","Jeff Baker","Mark Zimmer","Bill Gruber","Will Gruber"]`

Matching Tuples with Wildcardโ€‹

// Sighting
// {"sighting":{"reportedBy":[["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["VP","Jeff Baker"],["VP","Mark Zimmer"],["Engineer","Bill Gruber"],["Engineer","Will Gruber"]],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.removeByValue(binName, Value.get(List.of(Value.get("VP"), Value.WILDCARD)), ListReturnType.NONE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Removes all tuples with tag `VP`
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))) // Return updated list at `reportedBy`
);

// Operation returns `[["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["Engineer","Bill Gruber"],["Engineer","Will Gruber"],["Director","Marge Flanders"]]`

Code Samplesโ€‹

See the examples above, or follow any of these language-specific links for detailed code examples for the operation.

removeByValueList

ListOperation.removeByValueLIst(binName, value, listReturnType, context)

Removes all the elements in the list matching value. The INVERTED flag may be used to remove the elements not matching the specified value.

Returns: Operation

Zero, one or a list of values, based on the return type. The NONE return type will execute faster because no reply is constructed for the operation. The elements returned by other return types may not be in index order.

The returnTypes and context are described at the top of this page.

Order: Whether the list is unordered or ordered, removeByValue will return the same elements, based on the ordering rules. The performance of 'by value' operations is better on an ordered list than an unordered one.

Performance: The worst-case performance of removing elements by value is ๐“ž(log N + M) for an ordered list that is stored in memory, ๐“ž(log N + N) for an ordered list stored on SSD, and ๐“ž(N + M) for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list. See List performance for the full worst-case performance analysis of the List API.

Trivial Exampleโ€‹

// Sighting 
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber","Will Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.removeByValue(binName, Value.get("Elon Smith"), ListReturnType.NONE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Removes `"Elon Smith"` from the list at key `reportedBy`
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))) // Returns updated list at `reportedBy`
);

// Operation returns `["Jesse Rogan","Jeff Baker","Mark Zimmer","Bill Gruber","Will Gruber"]`

Matching Tuples with Wildcardโ€‹

// Sighting
// {"sighting":{"reportedBy":[["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["VP","Jeff Baker"],["VP","Mark Zimmer"],["Engineer","Bill Gruber"],["Engineer","Will Gruber"]],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.removeByValue(binName, Value.get(List.of(Value.get("VP"), Value.WILDCARD)), ListReturnType.NONE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Removes all tuples with tag `VP`
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))) // Return updated list at `reportedBy`
);

// Operation returns `[["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["Engineer","Bill Gruber"],["Engineer","Will Gruber"],["Director","Marge Flanders"]]`

Code Samplesโ€‹

See the examples above, or follow any of these language-specific links for detailed code examples for the operation.

removeByValueRange

ListOperation.removeByValueRange(binName, startValue, endValue, listReturnType, context)

Removes the list elements that sort into the interval between valueStart (inclusive) and valueStop (exclusive). The INVERTED flag may be used to remove the elements outside this interval.

Returns: Operation

Zero, one or a list of values, based on the return type. The elements returned may not be in index order.

The returnTypes and context are described at the top of this page.

Order: Whether the list is unordered or ordered, removeByValueRange will return the same elements, based on the ordering rules. The performance of 'by value' operations is better on an ordered list than an unordered one.

Performance: The worst-case performance of removing elements in a value interval is ๐“ž(log N + M) for an ordered list that is stored in memory, ๐“ž(log N + N) for an ordered list stored on SSD, and ๐“ž(N + M) for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list. See List performance for the full worst-case performance analysis of the List API.

Trivial Exampleโ€‹

// Sighting 
// {"sighting":{"reportedBy":["Jesse Rogan","Elon Smith","Jeff Baker","Mark Zimmer","Bill Gruber","Will Gruber"],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(binName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Sorts input list at key `reportedBy` to `["Bill Gruber","Elon Smith","Jeff Baker","Jesse Rogan","Mark Zimmer","Will Gruber"]`
    ListOperation.removeByValueRange(binName, Value.get("Elon Smith"), Value.get("Jesse Rogan"), ListReturnType.NONE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Removes values between "Elon Smith" and "Jesse Rogan" (exclusive)
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))) // Returns updated list
);

// Operation returns `["Bill Gruber","Jesse Rogan","Mark Zimmer","Will Gruber"]`

Interval Comparison of Tuplesโ€‹

It is common to model complex data in Aerospike as a list of tuples, each element a list, where the index order carries meaning. For an example, see Aerospike Modeling: IoT Sensors.

This modeling relies on the ordering rules that apply to list elements. Ordered pairs sort into

[1, NIL] < [1, 1] < [1, 1, 2] < [1, 2] < [1, '1'] < [1, 1.0] < [1, INF]

Take the list of ordered pairs, [[100, 1], [101, 2], [102, 3], [103, 4], [104, 5]] and the following intervals:

valueStart: [101, NIL], valueStop: [103, NIL]

Iterating over the elements we check if [101, NIL] <= value < [103, NIL]. This is true for the elements [101, 2] and [102, 3]. The element [103, 4] is not in this interval, because its order is higher than [103, NIL]. The comparison starts with the 0th index values, in this case both are 103. Next the 1st index position values are compared, and NIL is lower than 3 (actually its order is lower than any value).

valueStart: [101, NIL], valueStop: [103, INF]

The elements [101, 2] and [102, 3] are obviously in the interval. The element [103, 4] is also in this interval, because its order is lower than [103, INF]. The comparison starts with the 0th index values, in this case both are 103. Next the 1st index position values are compared, and INF is higher than 3 (actually its order is higher than any value).

valueStart: [101, INF], valueStop: [103, INF]

The elements [102, 2] and [103, 4] are in the interval. The element [101, 2] is not in this interval, because its order is lower than[101, INF].

Code Samplesโ€‹

// Sighting
// {"sighting":{"reportedBy":[["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["VP","Jeff Baker"],["VP","Mark Zimmer"],["Engineer","Bill Gruber"],["Engineer","Will Gruber"],["Director","Liza Flanders"]],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(testBinName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Sorts lists at key `reportedBy` to `[["Director","Liza Flanders"],["Engineer","Bill Gruber"],["Engineer","Elon Smith"],["Engineer","Jesse Rogan"],["Engineer","Will Gruber"],["VP","Jeff Baker"],["VP","Mark Zimmer"]]`
    ListOperation.removeByValueRange(testBinName, Value.get(List.of(Value.get("Engineer"))), Value.get(List.of(Value.get("VP"))), ListReturnType.NONE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Removes all lists betwee tags `"Engineer"` and `"VP"` (exclusieve)
    ListOperation.getByIndexRange(testBinName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))) // Returns updated list and key `reportedBy`
);

// Operation returns `[["Director","Liza Flanders"],["VP","Jeff Baker"],["VP","Mark Zimmer"]]`

removeByValueRelativeRankRange

ListOperation.removeByValueRelativeRankRange(binName, value, rank, listReturnType, context)

Removes a range of count elements starting at a specified rank, relative to the given value. The INVERTED flag may be used to remove the elements not in a specified range.

The value can be anything, not necessarily a value that exists in the list. The rank and count can be any number, but the result may be an empty list if the specified range contains no elements.

Returns: Operation

Zero, one or a list of values, based on the return type. The elements returned may not be in rank order.

The returnTypes and context are described at the top of this page.

Order: The relative rank of the value compared to the current list follows the ordering rules.

Performance: The worst-case performance of removing elements by relative rank range is ๐“ž(M + log N) for an ordered list that is stored in memory. An ordered list stored on SSD has a ๐“ž(N + M + log N), where M is the element count of the range, and N is the element count of the list. An unordered list has a ๐“ž(R log N + N), with R for rank. See List performance for the full worst-case performance analysis of the List API.

Exampleโ€‹

For [0, 3, 9, 12, 15] a value of 5 would rank between 3 and 9, relative to the current list. A rank of -1 from there would select 3 as the starting point of the range, and then the count would select the elements. So a count of 3 would remove the elements 3, 9 and 12.

Code Exampleโ€‹

// Sighting
// {"sighting":{"reportedBy":[["Engineer","Jesse Rogan"],["Engineer","Elon Smith"],["VP","Jeff Baker"],["VP","Mark Zimmer"],["Engineer","Bill Gruber"],["Engineer","Will Gruber"],["Director","Marge Flanders"]],"occurred":20200228,"reported":20200228,"posted":20200409,"report":{"city":"Waupaca","duration":"45 minutes","shape":["sphere"],"state":"WI","summary":"Brightest object in the sky next to the moon. Took the dogs out to do their business, noticed a brighter than normal light near the moon."},"location":{"value":{"type":"Point","coordinates":[-89.1207,44.3223]}}}}

client.operate(
    writePolicy,
    key,
    ListOperation.sort(binName, ListSortFlags.DEFAULT, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Sort list at key `reportedBy` to `[["Director","Liza Flanders"],["Engineer","Bill Gruber"],["Engineer","Elon Smith"],["Engineer","Jesse Rogan"],["Engineer","Will Gruber"],["VP","Jeff Baker"],["VP","Mark Zimmer"]]` 
    ListOperation.removeByValueRelativeRankRange(binName, Value.get(List.of(Value.get("Engineer"))), 0, 4, ListReturnType.NONE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy"))), // Remove all lists with Engineer tag including first `"Engineer"` since we have specified 0 rank and count up to 4 elements. This will remove all lists wihich contain `"Engineer"` tag. 
    ListOperation.getByIndexRange(binName, 0, ListReturnType.VALUE, CTX.mapKey(Value.get("sighting")), CTX.mapKey(Value.get("reportedBy")))
);

// Operation returns `[["Director","Liza Flanders"],["VP","Jeff Baker"],["VP","Mark Zimmer"]]`