You can search for the values of a specific attribute label based on predefined search criteria. For example, you may want to get only those values of an attribute label that are used in a specific report. Or, you may need to get the values that contain a specific string of characters in their names.

NOTE: Any data permissions assigned to you are applied to the returned results of your filtering.

If the data permissions do not allow you to see some values, these values will not appear in the results.

For more information about attribute labels and values, see Determine the Attribute Value ID. For each obtained value, the API returns its title and URI.

You can set filter criteria as parameters in the request body and as URL parameters.

Request body parameters

All the request body parameters are optional.

The request body with no parameter returns all the values of the specified attribute label (with the URL parameters applied if they are set).

• uris (array of strings in the format of URI, optional) specifies the URIs of the label values that you want to obtain.

  Example: [ "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/1234/elements?id=9876", "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/1234/elements?id=9877" ]

• complement (boolean, optional) specifies whether the response should (true) or should not (false; default) return the complement of the array of the label values that are specified by the uris parameter. The complement is returned as all the values of the attribute label minus those that you specified in the uris parameter. For example, the attribute label has values with IDs 81, 82, 83, 84, 85, and 86. In the uris parameter, you specify the values with IDs 83, 84, and 85. In this case, the returned complement will contain the values with IDs 81, 82, and 86.

• titles (array of strings, optional) specifies the titles of the label values that you want to obtain. Values are searched for the exact match with the specified titles. The specified titles are case-sensitive.

  You must specify the exact titles of values to get them returned. To obtain the value with the title Language training, specify the titles parameter as [ "Language training" ]. Using [ "Language" ] or [ "training" ] will not return the value with the title Language training.

  Example: [ "Language training", "QA training" ]

  NOTE: If you want to obtain the values with a specific string of characters in their titles (not necessarily the exact whole titles), use the filter URL parameter (see further in this section under URL parameters).

• restrictiveDefinition (string in the format of URI, optional) specifies the URI of the report definition that determines the label values used and for which you want to obtain those values.

  Example: "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/2574"

  For a report definition, you can obtain not only the label values that are used in this report definition explicitly, but also the label values that are used indirectly.

  Example: You have a report definition that demonstrates sales amounts broken down by product and by months of the year. Let's say you use the Product Name attribute to represent the product, and you chose to use the Product short name label. To represent the month of the year, you use the Month/Year (Sales Date) attribute and its label Short (Jan 2101) (Sales Date).

  • You obtain the values of the Product short name label that are used in the report definition. Let's say that the obtained values are Bikes, Lamps, and Apples. The Product short name label and its attribute are used directly in the report definition. However, you can also obtain the values for the Product ID attribute and its default label. The API will return the values of the default label that correspond to the product names used in the report definition. That is, you will obtain the IDs of the products Bikes, Lamps, and Apples, which are 11, 35, and 83 correspondingly. Although the Product ID attribute and its label are not used in the report definition explicitly, the corresponding label values can still be obtained because they are connected to the Product Name attribute.
  • You obtain the values of the Month/Year (Sales Date) label that are used in the report definition. Let's say that the obtained values are Oct 2015, Nov 2015, Dec 2015, and Jan 2016. This label and its attribute are used directly in the report definition. However, you can also obtain the values for the Year (Sales Date) attribute and its default label. The API will return the values of the default label that correspond to the month/year combinations used in the report definition. That is, you will obtain the years of 2015 and 2016. Although the Year (Sales Date) attribute and its label are not used in the report definition explicitly, the corresponding label values can still be obtained because they are connected to the Month/Year (Sales Date) attribute.

• restrictiveDefinitionContent (JSON, optional) specifies the JSON structure describing the report definition that determines the label values used and for which you want to obtain those values. To build the restrictiveDefinitionContent parameter, use the contents of the content parameter from the JSON structure of the report definition that you want to use.

  For example, for the following JSON structure of the report definition:

{ "reportDefinition":{
  "content": {
    "filters": [],
    "format": "grid",
    "grid": {
      "columnWidths": [],
      "columns": ["metricGroup"],
      "metrics": [ {
        alias": "",
        "uri": "/gdc/md/{project_id}/obj/{metric_id}\"
        } ],
      "rows\": [ {
        "attribute": {
          "alias": "",
          "totals": [[]],
          "uri": "/gdc/md/{project_id}/obj/{attribute_id}"
          }
        } ],
        "sort": {
          "columns": [],
          "rows": []
          }
        },
      "oneNumber": {
        "labels": {}
        }
      },
    "links\": {
      "explain2": "/gdc/md/{project_id}/obj/{report_definition_id}/explain2"
      },
    "meta": {
      "author": "/gdc/account/profile/{user_id}\",
      ...
      "uri": "/gdc/md/{project_id}/obj/{report_definition_id}
      }
    }
  }

...the restrictiveDefinitionContent parameter would look like this:

"restrictiveDefinitionContent": {
  "filters": [],
  "format": "grid",
  "grid": {
    "columnWidths\": [],
    "columns": ["metricGroup\"],
    "metrics": [ {
      "alias": "",
      "uri": "/gdc/md/{project_id}/obj/{metric_id}"
      } ],
    "rows": [ {
      "attribute": {
        "alias": "",
        "totals": [[]],
        "uri": "/gdc/md/{project_id}/obj/{attribute_id}"
        }
        } ],
      "sort": {
        "columns": [],
        "rows": []
        }
      },
    "oneNumber": {
      "labels": {}
      }
    }

For a report definition, you can obtain not only the label values that are used in this report definition explicitly, but also the label values that are used indirectly. For the details of how it works, see the example for the restrictiveDefinition parameter earlier in this section.

URL parameters

• order (optional, string) specifies the order of sorting the returned values by their titles. The order can be set to be ascending (asc; default) or descending (desc).

  NOTE: Do not use the order parameter in the same call with orderKey (use either order or orderKey, not both).

• orderKey (optional, string) specifies the label property to sort the returned values by. The property can be set to label (the values are sorted by their titles in ascending order; default) or pk (the values are sorted randomly).

  You can find more information about using this parameter later in this section under Paging through the returned results.

• offset (optional, integer) specifies the offset of the first record in the returned list. You can find more information about using this parameter later in this section under Paging through the returned results.

• limit (optional, integer) specifies the number of values returned on one page. You can find more information about using this parameter later in this section under Paging through the returned results.

• filter (string, optional) specifies the search keyword/phrase/string to look for in the value titles and to return those containing it.

  • The search keyword/phrase/string is not case-sensitive. auto and AUTO will return the same result.

  • Values are searched for the exact match with the search keyword/phrase/string. lang training will not return the values with language training in their titles. language train, however, will return such values.

  Example: opportunity, closed opportu, 1990

  NOTE: If you want to obtain the values by searching for their exact titles, use the titles request body parameter (see earlier in this section under Request body parameters).

• prompt (string in the format of URI, optional) specifies the URI of the variable for which you want to obtain the label values used in it.

  Example: /gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/2579

Additional parameters

In addition to the filter criteria, you can specify the following parameter in the request body:

• includeTotalCountWithoutFilters (boolean, optional) specifies whether the total number of label values should be included in the response (true) or not (false; default). The total number is calculated as one of the following: * As the total number of values under the specified attribute label * If you provided a report definition in the request body in either the restrictiveDefinition or restrictiveDefinitionContent parameter, as the number of the values under the specified attribute label that are used in the provided report definition

When calculating the total number, any filters applied by the filter and prompt URL parameters and the uris and titles request body parameters are ignored. The total number is returned in the totalCountWithoutFilters parameter in the response.

Paging through the returned results

If the response returns too many values, use the limit, offset, and orderKey URL parameters to page through the output.

• The offset parameter is the offset of the first returned record on a page. For example, offset=20 returns the values starting from the 20th value in the generated list.

• The limit parameter is the number of the values returned on one page. Set it according to your preferences.

• The orderKey parameter is the label property by which the returned values are sorted. By default, the values are sorted by their titles

When making the first API call for label values, make it without specifying offset. It will return the values starting from the beginning of the generated list. In the response, the offset parameter will be returned as 0.

In the subsequent API calls, customize the limit and offset URL parameters to see a particular section of the generated list.

For example, making a call with ?limit=5&offset=10 returns five values starting from the 10th value in the list. In the response, the offset parameter will be returned set to 10 and the count parameter will be returned set to 5.

For attribute labels with high cardinality, sorting the label values by their titles (which is the default sorting) may take too long and time out, and no result will be returned. To avoid such situations and speed up the sorting, make a call with ?orderKey=pk to sort the values randomly instead of sorting them by their titles. Internally, they are sorted by their primary keys (hence the value pk), so even though the order is seemingly random, it is always the same. You can rely on the order, which is crucial for paging.

NOTE: Do not use the orderKey parameter in the same call with order (use either order or orderKey, not both).

{
  "validElements": {
    "elementsMeta": {
      "attribute": "/gdc/md/{project_id}/obj/{attribute_id}",
      "attributeDisplayForm": "/gdc/md/{project_id}/obj/{label_id}"
    },
    "items": [
      {
        "element": {
          "uri": "/gdc/md/FoodMartDemo/obj/71/elements?id=7"
        }
      }
    ]
  }
}