Elements

The REST APIs use a built-in generic function, called subList that takes a set of entities as the input and based on the keys that are specified in the Keys parameter, returns a list of items from the source collection. That is, it uses the collection to which the function was bound or called upon, containing one entity per Key entry and null if such an entity cannot be found. Therefore, the response format for the list is the same as for the source collection, which takes into account that the returned list can contain nulls, even if the source collection wasn't nullable. The Keys parameter is a JSON array and cannot be passed in place but must be passed as a query option by using a parameter alias.

Example 1:

GET ~/api/v1/Dimensions/tm1.subList(Keys=@keys)?@keys=["Customers","Products","Non-Existing-Dimension",{"Name":"Customers"},"T i M e "]

From all the dimensions in the model, example 1 returns the Customers dimension, the Products dimension, a null (you don't have the "Non-Existing-Dimension" dimension), the Customers dimension again (note: the object notation that represents the Keys, in this case just the Name, is allowed as well) and lastly, the Time dimension. Names, like resolution of entities themselves, are case- and space-insensitive and resolve aliases for those objects that support aliases.

Example 2:

GET ~/api/v1/Dimensions('Time')/Hierarchies('Quarters')/Elements/tm1.subList(Keys=@Keys)?@Keys=["Q1-1997","Q2-1997","Q3-1997","Q4-1997","Q5-1997"]

Form the Quarters hierarchy of the Time dimension's elements, example 2 returns the four quarters of 1997 plus a null because Q5 doesn't exist.

Example 3:

GET ~/api/v1/Dimensions('Time')/Hierarchies('Time')/Edges/tm1.subList(Keys=@Keys)?@Keys=[{"ParentName":"Q1-1997","ComponentName":"01-1997"},{"ParentName":"Q1-1997","ComponentName":"04-1997"},{"ParentName":"Q2-1997","ComponentName":"04-1997"}]

For entity types that have multi-part keys (currently only Edges in TM1), you can use the object notation to pair the keys to be used to look up entries. Example 3 returns three items. The second item is null because the fourth month is not a child of the first quarter and therefore this edge does not exist.

Example 4:

GET ~/api/v1/Dimensions('Time')/Hierarchies('Time')/Levels(1)/Members/tm1.subList(Keys=@Keys)?@Keys=["1996","Q3-1996","1997","Q1-1997"]

Example 4 shows that the source set limits the entities that are returned. Level 1 of the Time hierarchy has years only in the NorthWind sample database. Therefore, requesting a couple of years and quarters results in nulls for the quarters even though the members by themselves exists in the hierarchy but not in the level.

Using invalid JSON for the Keys parameter results in a 400 Invalid Request with an Invalid JSON message. Using incorrect types for the Keys parameter results in either an error message because the type is not acceptable as a key or results in null entries because the mapping to the actual keys and the lookup doesn't render any valid entities.

You can use GET on this function, which is by convention. You can also use POST. You must keep in mind that this is a function, therefore the open and close parentheses are required and the response is a 200 OK (not 201 Created) because the request is not creating any new entries.

Using POST instead of GET in example 1 would look like:

POST ~/api/v1/Dimensions/tm1.subList()
{"Keys":["Customers","Products","Non-Existing-Dimension",{"Name":"Customers"},"T i M e "]}

You can execute a PUT on the reference of the subset element collection to update the collection. You can execute a DELETE on the reference of the collection to empty the collection. The $filter query option can be used to specify which element should be removed.

This capability is a partial implementation of OData v4.01 11.4.6.4 on subset element collections.

A successful PUT request to a collection-valued navigation property’s reference resource replaces the set of related entities. The request body of the PUT must be a collection of entity references to elements of the hierarchy containing the subset.

For example, this request:

PUT /api/v1/Dimensions('D1')/Hierarchies('D1')/Subsets('S1')/Elements/$ref
[
    { "@odata.id": "Dimensions('D1')/Hierarchies('D1')/Elements('E3')" },
    { "@odata.id": "Dimensions('D1')/Hierarchies('D1')/Elements('E4')" },
    { "@odata.id": "Dimensions('D1')/Hierarchies('D1')/Elements('E5')" }
]

Has the following expected response:

{
    "@odata.context":"../../../../$metadata#Collection($ref)",
    "value":
    [
        {"@odata.id":"Dimensions('D1')/Hierarchies('D1')/Elements('E3')"},
        {"@odata.id":"Dimensions('D1')/Hierarchies('D1')/Elements('E4')"},
        {"@odata.id":"Dimensions('D1')/Hierarchies('D1')/Elements('E5')"}
    ]
}

A successful DELETE request to a collection-valued navigation property’s reference resource removes all requested references from the collection. You can use the $filter query option to specify elements to remove.

For example, the following request is a filtered delete that deletes all elements named E3 in the S2 subset of the D1 dimension:

DELETE /api/v1/Dimensions('D1')/Hierarchies('D1')/PrivateSubsets('S2')/Elements/$ref?$filter=Name eq 'E3'