--- title: "Filter out values of an attribute label" method: POST path: "/gdc/md/{project_id}/obj/{label_id}/validElements" tags: ["attribute-elements"] --- # Filter out values of an attribute label `POST /gdc/md/{project_id}/obj/{label_id}/validElements` ## Request - Base URL: `https://secure.gooddata.com` - URL: `https://secure.gooddata.com/gdc/md/{project_id}/obj/{label_id}/validElements` - Auth: none declared 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](https://help.gooddata.com/display/doc/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](https://help.gooddata.com/display/doc/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). ## Path parameters - `project_id` string, required - `label_id` string, required ## Query parameters - `order` 'asc' | 'desc' - `orderKey` 'label' | 'pk' - `offset` number - `limit` number - `filter` string - `prompt` string ## Request body - union - ValidElementsRequest - `validElementsRequest` object, required - `uris` string[] - `titles` string[] - `complement` union: Legacy boolean allowing boolean values represented by booleans or numbers - '0' | '1' - 0 | 1 - boolean - `includeTotalCountWithoutFilters` union - '0' | '1': include 'totalCountWithoutFilters - 0 | 1: include 'totalCountWithoutFilters - boolean: include 'totalCountWithoutFilters - `restrictiveDefinitionContent` ReportDefinitionContentWithInlinedMetrics - `format` 'grid' | 'chart' | 'oneNumber', required - `filters` ReportFilter[], required - `expression` string, required - `tree` MAQLTree1 - `type` string, required - `value` string - `position` object, required - … - `content` MAQLTree - … - `having` ReportFilter - `expression` string, required - `tree` MAQLTree1 - `type` string, required - `value` string - `position` object, required - … - `content` MAQLTree - … - `chart` ChartContent - `styles` object - `buckets` object, required - `x` ChartBucketItem[], required - … - `y` ChartBucketItem[], required - … - `color` ChartBucketItem[] - … - `angle` ChartBucketItem[] - … - `size` ChartBucketItem[] - … - `detail` ChartBucketItem[] - … - `marker` ChartBucketItem[] - … - `axes` ChartAxisItem[] - `locators` union, required - … - `id` string, required - `sort` object - `x` ChartSortRule[] - … - `y` ChartSortRule[] - … - `color` AttributeChartSortRule[] - … - `oneNumber` OneNumberVisualization - `labels` object, required - `sortedLookups` AttributeSortRule[] - `attributeSort` object, required - `uri` string, uri, required: URI of attributeDisplayForm (or metricGroup) - `direction` 'asc' | 'desc', required: sort order ascending (asc) or descending (desc) - `aggregation` string: aggregation function - how to put values from area together - `grid` GridContentWithInlinedMetrics, required - `rows` GridElement[], required - union - … - `columns` GridElement[], required - union - … - `metrics` object[], required - `uri` string, uri - `expression` string - `alias` string, required - `format` string - `drillAcrossStepAttributeDF` string, uri - `sort` Sort, required - `columns` string[], required - `rows` string[], required - `columnWidths` ColumnWidth[], required: here is possible to define specific column(s) width - `locator` Locators[], required - … - `width` integer, required - `defaultColumnWidth` string: configurable default column width used in grid visualization - `restrictiveDefinition` string, uri - ElementLabelToUri - `elementLabelToUri` object, required - `mode` string: match mode, only 'EXACT' supported - `labelUri` string, uri, required: uri of the label (attribute display form) - `patterns` string[], required: element labels (in EXACT mode) or patterns to match them ## Response `200` Valid elements of the label matching the request - union - ValidElements - `validElements` object, required - `totalCountWithoutFilters` string: total count of elements (ignoring any filter or request uris) - `elementsMeta` object, required - `attribute` string, uri, required - `filter` string, required: we search only for substring of filter ie *filter* - `order` string, required - `attributeDisplayForm` string, uri, required - `paging` object, required - `total` string, int, required: total amount of existing elements for a given attributeDisplayForm (which match filter and request uris) - `count` integer, required: amount of returned elements - `offset` string, int, required: offset of first item, starts from 0 - `items` object[], required - `element` object, required - `uri` string, uri, required - `title` unknown, required - ElementLabelUri: Result structure with list of element labels and theirs uris. Each element in 'patterns' array of input structure (ElementLabelToUri) has correspondig element (on the same position in array) in 'result' array of output structure (ElementLabelToUri). See structures example. - `elementLabelUri` object[], required - `mode` string, required: match mode - `labelUri` string, required: uri of the label (attribute display form) - `result` object[], required - `pattern` string, required: pattern (or element label in EXACT mode) - `elementLabels` object[], required - `elementLabel` string, required: element label (string) - `uri` string, uri, required ## Other responses - `303`: Redirect to the polling location of the asynchronous validElements task --- [API](https://skmtc.dev/gooddata/apis/gooddata-api-documentation.md) - [All operations](https://skmtc.dev/gooddata/apis/gooddata-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/gooddata/apis/gooddata-api-documentation/revisions/e5dc0ee6ab00?raw)