# Using Audience API to Create Attribute Groupings

Attribute groupings are defined by the value in the `groupingName` field of the `attributes` objects contained in Treasure Data parent segment objects. By default `groupingName` is set to NULL. However, if `groupingName` is set to a string value, an attribute grouping is created in the Treasure Data console with that name. Any `attributes` objects that have that string specified in `groupingName` will be included in the attribute grouping.

In Figure 1, at the end of this article, there is a complete listing of a parent segment object. The `attributes` of the object (i.e. the table columns of the segment) start on line 34. Observe that both of the objects described in the `attributes` object have `groupingName` set to `null` (line 47 and 61).


```
    34:   "attributes":[
    35:      {
    36:         "audienceId":"12345",
    37:         "id":"56662",
    38:         "name":"c1-test",
    39:         "type":"string",
    40:         "parentDatabaseName":"_mobile_sdk",
    41:         "parentTableName":"android",
    42:         "parentColumn":"c1",
    43:         "parentKey":"c0",
    44:         "foreignKey":"c_comment",
    45:         "matrixColumnName":"c1",
    46:         "usedBySegmentInsight":false,
    47:         "groupingName": null
    48:      },
    49:      {
    50:         "audienceId":"12345",
    51:         "id":"56663",
    52:         "name":"c2-test",
    53:         "type":"string",
    54:         "parentDatabaseName":"_mobile_sdk",
    55:         "parentTableName":"android",
    56:         "parentColumn":"activity_date",
    57:         "parentKey":"c0",
    58:         "foreignKey":"c_comment",
    59:         "matrixColumnName":"activity_date",
    60:         "usedBySegmentInsight":false,
    61:         "groupingName": null
    62:      }
```

However, if `groupingName` were changed, for example, to `wtt_test` (as shown in line 47) then an attribute grouping would be created with the name `wtt_test`.


```
    35:      {
    36:         "audienceId":"12345",
    37:         "id":"56662",
    38:         "name":"c1-test",
    39:         "type":"string",
    40:         "parentDatabaseName":"_mobile_sdk",
    41:         "parentTableName":"android",
    42:         "parentColumn":"c1",
    43:         "parentKey":"c0",
    44:         "foreignKey":"c_comment",
    45:         "matrixColumnName":"c1",
    46:         "usedBySegmentInsight":false,
    47:         "groupingName": 'wtt_test'
    48:      },
```

![](/assets/attrgrpconsole.8ba1bace301a487115dfa39b431161fb6283d15b6c5ddba5e12cd23cc259e326.cf3845cb.png)

# Creating an Attribute Grouping

There are three steps in creating an attribute grouping:

1. Getting the parent segment ID
2. Getting the parent segment object
3. Patching the parent segment object with a `groupingName`


## Getting a parent segment ID

There are two ways you can get the ID of the parent segment you want to work with. You can use the Treasure Data Console or you can make an Audience API call.

In the Treasure Data Console, navigate to Audience Studio and select the parent segment you want to work with. The segment ID can be found in the URL after the text `/app/ps/`.

![](/assets/consoleps.9dfc3a18810682c0a90f219583260a7d0f491393f806376ee59f821b4ae3f2a3.cf3845cb.png)

Alternately, if make an Audience API call to display all the parent segments, the `id` and `name` of every parent segment is part of the response. For example, you could make a call similar to that shown below. The response comes back in unformatted JSON. In this example, though, the response has been edited and formatted for readability.


```bash
$ curl -H 'AUTHORIZATION: TD1 1/1234567891234567891234567891234567891234' 'https://api-cdp.treasuredata.com/audiences/'
```


```json
{
   "id":"12345",
   "name":"Attribute Grouping",
   "description":"Contains grouping names set through Audience API.",
   "scheduleType":"none",
   "scheduleOption":null,
    .
    .
    .
}
```

If there are a lot of parent segments in the response, one strategy for simplifying the output is to format it and then filter it by id and 'name`. Here is an example of how that can be accomplished.


```bash
curl -H 'AUTHORIZATION: TD1 1/1234567891234567891234567891234567891234' 'https://api-cdp.treasuredata.com/audiences/' | python -m json.tool | grep '^\s\s\s\s\s\s\s\s\"id\|^\s\s\s\s\s\s\s\s\"name'
```


```bash
% Total    % Received % Xferd  Average Speed   Time    Time     Time  CurrentDload  Upload   Total   Spent    Left  Speed
100 1188k    0 1188k    0     0  81378      0 --:--:--  0:00:14 --:--:--  323k
"id": "12345",
"name": "Attribute Grouping",
"id": "23456",
"name": "PS1",
"id": "34567",
"name": "PS2",
"id": "45678",
"name": "Test Segment",
    .
    .
    .
```

## Getting the parent segment object

After you have the parent segment ID you can retrieve the parent segment object. In the example below, the parent segment object ID is `12345`.


```bash
curl -H 'AUTHORIZATION: TD1 1/1234567891234567891234567891234567891234' https://api-cdp.treasuredata.com/audiences/12345
```

The response comes back as unformatted JSON. It can be useful to use a JSON formatting tool to make the response more readable. For example, here is an example that uses the Python `json.tool` to format the response.


```bash
$ curl -H 'AUTHORIZATION: TD1 1/1234567891234567891234567891234567891234' 'https://api-cdp.treasuredata.com/audiences/12345' | python -m json.tool
```

Patching the parent segment object with a `groupingName`

After you have the parent segment object, you can edit the response and change the `null` setting for `groupingName` on one or more attributes that you want to be included in the grouping. The string value you provide for `groupingName` will be the name of the attribute grouping.

After you have finished editing the parent segment object, use this edited object as the request payload for a PATCH request.

Large, unformatted JSON objects that contain multiple embedded objects can be difficult to work with. Consequently, the parent segment object that is used as the request payload has been formatted and put into a file named `attrGroupingRequest.json (see Figure 1 below)`. After the file has been edited as necessary, the file can be included in a PATCH request that looks something like this:


```bash
$ curl --location --request PATCH -H 'AUTHORIZATION: TD1 1/1234567891234567891234567891234567891234' -H 'Content-Type: application/json' -d @attrGroupingRequest.json https://api-cdp.treasuredata.com/audiences/12345
```

# Modifying an Attribute Grouping

Modifying an attribute grouping consists of editing the parent segment object and modifying the `groupingName` values as needed. You can change it to `null` to remove a column from all attribute groupings, or you can change the name to a different attribute grouping, effectively moving the column to the new attribute grouping. After modifying the parent segment object, send a PATCH request with the modified object.

# Deleting an Attribute Grouping

To delete an attribute grouping, edit the parent segment object and remove the name of the attribute grouping you want to delete. Remove the name from from every instance of `groupingName`. In most cases, you will simply change the value to 'null`. After modifying the parent segment object, send a PATCH request with the new object.

Figure 1: File listing for attrGroupingRequest.json which contains a parent segment object


```json
{
  "id": "12345",
  "name": "Attribute Grouping",
  "description": "Contains grouping names set through Audience API.",
  "scheduleType": "none",
  "scheduleOption": null,
  "timezone": "UTC",
  "createdAt": "2022-02-10T19:17:45.107Z",
  "updatedAt": "2022-02-10T19:17:45.107Z",
  "createdBy": {
    "id": "111",
    "td_user_id": "4567",
    "name": "firstName lastName"
  },
  "updatedBy": {
    "id": "3210",
    "td_user_id": "45678",
    "name": "Me"
  },
  "matrixUpdatedAt": "2022-02-10T19:25:09.676Z",
  "workflowHiveOnly": false,
  "hiveEngineVersion": "cdpaudience",
  "hivePoolName": null,
  "prestoPoolName": null,
  "population": 150000,
  "enrichmentWordTaggingEnabled": true,
  "enrichmentIpEnabled": true,
  "enrichmentTdJsSdkEnabled": true,
  "rootFolderId": "987654",
  "master": {
    "parentDatabaseName": "test_db_1",
    "parentTableName": "sample"
  },
  "attributes": [
    {
      "audienceId": "12345",
      "id": "56662",
      "name": "c1-test",
      "type": "string",
      "parentDatabaseName": "_mobile_sdk",
      "parentTableName": "android",
      "parentColumn": "c1",
      "parentKey": "c0",
      "foreignKey": "c_comment",
      "matrixColumnName": "c1",
      "usedBySegmentInsight": false,
      "groupingName": null
    },
    {
      "audienceId": "12345",
      "id": "56663",
      "name": "c2-test",
      "type": "string",
      "parentDatabaseName": "_mobile_sdk",
      "parentTableName": "android",
      "parentColumn": "activity_date",
      "parentKey": "c0",
      "foreignKey": "c_comment",
      "matrixColumnName": "activity_date",
      "usedBySegmentInsight": false,
      "groupingName": null
    }
  ],
  "behaviors": [
    {
      "audienceId": "12345",
      "id": "23456",
      "name": "Orders",
      "parentDatabaseName": "test_db_1",
      "parentTableName": "orders",
      "parentKey": "o_custkey",
      "foreignKey": "c_custkey",
      "matrixDatabaseName": "audience_76543",
      "matrixTableName": "behavior_orders",
      "allColumns": false,
      "scheduleType": "none",
      "scheduleOption": null,
      "defaultTimeFilterEnabled": true,
      "filterRule": {},
      "schema": [
        {
          "name": "o_clerk",
          "type": "string",
          "parentColumn": "o_clerk",
          "matrixColumnName": "o_clerk"
        }
      ]
    }
  ]
}
```