The dataSets object lets you get information about the reference sets in your Connect subscription (their names, IDs, the data sets they are linked to and the attributes they contain).
Note
If you need reference set content, there is another query for it. See Get reference set content.
To get the list of all reference sets in your Connect subscription, use a filter based on the data set type.
query {
dataSets(filter: [{ field: "type", eq: "REFERENCE_SET" }]) {
nodes {
name
dataSetId
type
}
}
}
{
"data": {
"dataSets": {
"nodes": [
{
"name": "Physical Store Clients",
"dataSetId": "e83a688c-e53e-4a1c-8565-0000000001",
"type": "REFERENCE_SET"
},
{
"name": "Discount Coupons",
"dataSetId": "90f06be3-e617-4dff-b1ca-0000000000001",
"type": "REFERENCE_SET"
},
{
"name": "Store Locations",
"dataSetId": "271ae741-84b4-429d-abd4-0000000000003",
"type": "REFERENCE_SET"
},
{
"name": "Order History",
"dataSetId": "0108995f-317c-43b7-b905-0000000000000",
"type": "REFERENCE_SET"
}
]
}
}
}
To query a particular reference set, add a filter by ID.
query {
dataSets(filter: [{ field: "dataSetId", eq: "e83a688c-e53e-4a1c-8565-0000000001" }]) {
nodes {
name
dataSetId
type
tracking {
createdBy
createdAt
lastModifiedBy
lastModifiedAt
}
associations {
to {
dataSetId
name
type
}
mappings {
toAttribute
fromAttribute
}
}
attributes {
name
type
identifyAs {
key
index
}
}
}
}
}
{
"data": {
"dataSets": {
"nodes": [
{
"name": "Order History",
"dataSetId": "e83a688c-e53e-4a1c-8565-0000000001",
"type": "REFERENCE_SET",
"tracking": {
"createdBy": "[email protected]",
"createdAt": "2025-03-18T13:02:00.349Z",
"lastModifiedBy": "[email protected]",
"lastModifiedAt": "2025-09-09T13:58:53.345Z"
},
"associations": [
{
"to": {
"dataSetId": "0108995f-317c-43b7-b905-0000000000000",
"name": "Discount Coupons",
"type": "REFERENCE_SET"
},
"mappings": [
{
"toAttribute": "Coupon ID",
"fromAttribute": "Coupon Used"
}
]
}
],
"attributes": [
{
"name": "Order ID",
"type": "TEXT",
"identifyAs": {
"key": true,
"index": 0
}
},
{
"name": "Client ID",
"type": "TEXT",
"identifyAs": null
},
{
"name": "Amount",
"type": "NUMBER",
"identifyAs": null
},
{
"name": "Date",
"type": "DATE",
"identifyAs": null
},
{
"name": "Coupon Used",
"type": "TEXT",
"identifyAs": null
},
{
"name": "Return",
"type": "DATE",
"identifyAs": null
},
{
"name": "Return Amount",
"type": "NUMBER",
"identifyAs": null
},
{
"name": "Online Purchase",
"type": "BOOLEAN",
"identifyAs": null
}
]
}
]
}
}
}
Running the query
If you haven't used our API before, see Using the Connect API for instructions. It explains how to authenticate your calls and suggests some tools for testing.
Query structure
Arguments
Add the filter argument to your query. It's an array of objects.
| Field | Values | Definition |
|---|---|---|
field | String. Valid values: - type- dataSetId | The field to use for filtering |
eq | - For the type field, useREFERENCE_SET.- For the dataSetId field, use the ID of the reference set. | The value that the specified field must be equal to |
If you omit the filter, the response will contain all data sets available in your Connect subscription (the audience, the product catalog and behavioral attributes).
Fields
The dataSets query has the nodes array at the top level. The array contains a separate object for each reference set. Here are the fields supported by the objects.
| Field | Values | Required? | Description |
|---|---|---|---|
associations | Array of objects | Optional | If there are data sets linked to the current reference set, you will get a separate object for each of them. |
attributes | Array of objects | Optional | Returns a separate object for each attribute in the reference set |
dataSetId | ID | Required | The ID of the reference set (assigned automatically) |
name | String | Optional | The name of the reference set |
size | Integer | Optional | The size of the reference set |
tracking | Object | Optional | Returns primary history records for the data set. |
type | String | Optional | The type of the data set |
Fields supported by objects within the associations field. All of them are optional.
| Field | Nested field | Definition |
|---|---|---|
to | dataSetId | The ID of the data set connected to the current reference set |
name | The name of the data set set connected to the current reference set | |
type | The type of the data set connected to the current reference set | |
mappings | fromAttribute | The attribute in the current reference set linking to the target reference set |
toAttribute | The attribute in the target reference set linking to the current reference set |
Fields supported by objects within the attributes field
| Field | Nested field | Values | Required? | Definition |
|---|---|---|---|---|
decimalPrecision | Integer | Optional | The number of decimal places after the separator. Applies to numeric attributes. | |
identifyAs | key | Boolean | Optional | If the value is true, it means this is the key attribute in the reference set. |
name | String | Required | The name of the attribute | |
type | One of the following values: - TEXT- NUMBER- BOOLEAN- DATE | Optional | The data format of the attribute |
Fields supported by the tracking object
| Field | Values | Definition |
|---|---|---|
createdAt | A date-time string at UTC, such as 2024-08-21T15:46:51.762Z. | Shows when the reference set was added to Connect. |
createdBy | String | Returns the name of the user that added the reference set to Connect. |
lastModifiedAt | A date-time string at UTC, such as 2024-08-21T15:46:51.762Z. | Shows when the reference set was modified last time. |
lastModifiedBy | String | Returns the name of the user that modified the reference set last time. |