Options and filters

You can use batch query/update options to group queries, pagination query options to limit the results of your query, and filtering options to manage the results of your query.

For more information about options and filters, use the following ODATA references:

Batch options

You can use OData v4.01 based $batch options.

The implementation of $batch options in the OData v4.0 based TM1 REST API implementation follows the v4.01 specification and takes the following limitations into account:

Supports only the v4.01 JSON format, not the v4.0 multi-part format.
Does not support atomicity groups, therefore the atomicityGroup property must not be defined in requests.
Does not support dependencies, therefore the dependsOn property must not be defined in requests.
No dependencies implies no referencing to results of previous requests. That is, no $id as first segment of a relative path.
Does not support nested $batch requests in a batch request.
Asynchronously executed requests, execute asynchronously and do not return interim results.
The v4.01 specification allows and describes a mechanism to return interim results but doesn't require a service to implement.
The TM1SessionId cookie can be set on the $batch request itself and must not be set on the individual requests.
The Authorization header, which triggers Authentication, must be set on the $batch request itself and must not be set on any of the individual requests.
If the content-type, which by definition is application/json, is the same as on the $batch response (including parameters), it is ignored.
According to the specification, this header must be included if it is not exactly application/json and has no parameters, which it never is for TM1 REST APIs but it is typically the same as what is put on the $batch response itself.
Requests that return binary responses are not supported (currently only limits requests for content of files and attachments).

For more information, see the OData v4.01 protocol specification and Chapter 19 of the OData JSON Format v4.01.

Pagination query options

You can use pagination query options to limit the results of your query.

For queries that return many results, the OData specification provides navigation options to limit and manipulate the results by using pagination system query options, such as $top and $skip.

To limit the size of the results, use the $top option.

   Cubes?$select=Name&$top=2

This example displays the first two cubes from the model.

{
    "@odata.context": "$metadata#Cubes",
    "value": [
        {
            "Name": "plan_BudgetPlan"
        },
        {
            "Name": "plan_BudgetPlanLineItem"
        }
    ]
}

The $skip option sets the beginning of the list returned to the specified value.

   Cubes?$select=Name&$top=2&$skip=2

In this example, the next two cube names (the third and fourth cubes) are listed in the results.

{
    "@odata.context": "$metadata#Cubes",
    "value": [
        {
            "Name": "plan_Control"
        },
        {
            "Name": "plan_ExchangeRate"
        }
    ]
}

Filter options

You can use filtering options to manage the results of your query.

The OData specification includes a number of filtering options to manage result output. For more information, see 5.1.1 System Query Option $filter.

Using the startswith and $top options

To list dimensions where the name of the dimensions begins with the string plan, use the startswith function. To limit the size of the results, use the $top query option.

For example:

   Dimensions?$filter=startswith(Name,'plan')&$top=2

Results:

{
    "@odata.context": "$metadata#Dimensions",
    "value": [
        {
            "Name": "plan_business_unit",
            "UniqueName": "[plan_business_unit]",
            "Attributes": {
                "Caption": "plan_business_unit"
            }
        },
        {
            "Name": "plan_chart_of_accounts",
            "UniqueName": "[plan_chart_of_accounts]",
            "Attributes": {
                "Caption": "plan_chart_of_accounts"
            }
        }
    ]
}

Using the startswith and $select filters

To list TM1 control cubes that are identified by names that begin with the "}" character, use the startswith function.

   Cubes?$filter=startswith(Name, '}')

Combine the previous example with the $select option to return only the names (Name property) of the cubes that match the filter. Add the $top query option to display only the first three control cubes.

For example:

   Cubes?$filter=startswith(Name, '}')&$select=Name&$top=3

Results:

{
    "@odata.context": "$metadata#Cubes",
    "value": [
        {
            "Name": "}ApplicationSecurity"
        },
        {
            "Name": "}Capabilities"
        },
        {
            "Name": "}ChoreSecurity"
        }
    ]
}