Use the updateDataSet mutation to modify reference set attributes: add new fields, reorganize them by category or remove the fields you no longer need.

Running the mutation

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.

Basic mutation structure

mutation {
  updateDataSet(
    where: {
      dataSetId: "{REFERENCE_SET_ID}"
    }
    to: {
      attributes: {
        create: [
          {
            name: "New attribute"
            type: TEXT
          }
        ]
      }
    }
  ) {
    dataSetId
  }
}

{
  "data": {
    "updateDataSet": {
      "dataSetId": "{REFERENCE_SET_ID}"
    }
  }
}

Mutation arguments

• where (required): Object - Identifies the reference set to update
  • dataSetId (required): String - The ID of the reference set
• to (required): Object - Contains the updates to apply
  • attributes: Object - Attribute operations (see Attributes object below)

Attributes object

The attributes object supports three operations:

• create: Array of objects - Add new attributes to the reference set
• update: Array of objects - Modify existing attributes
• remove: Array of objects - Delete attributes from the reference set

Create attribute fields

• category: String - Assign the attribute to a category. Valid values: "Demographic", "Contact information" and "Location".
• name (required): String - The name of the new attribute
• type (required): Enum - The data type. Valid values: TEXT, NUMBER, DATE, BOOLEAN.

Update attribute fields

• category: String - The name of the category for the attribute. Valid values: "Demographic", "Contact information" and "Location".
• name (required): String - The name of the attribute to update

Remove attribute fields

• name (required): String - The name of the attribute to remove

Response structure

The mutation returns a JSON response with this structure:

• data: Object - Root response object
  • updateDataSet: Object - Contains update results with the following fields:
    • dataSetId: String - The ID of the updated reference set

Examples

Adding new attributes

Add multiple attributes to capture customer order information.

mutation {
  updateDataSet(
    where: {
      dataSetId: "{REFERENCE_SET_ID}"
    }
    to: {
      attributes: {
        create: [
          {
            name: "Order total"
            type: NUMBER
          }
          {
            name: "Order date"
            type: DATE
          }
          {
            name: "Product category"
            type: TEXT
          }
        ]
      }
    }
  ) {
    dataSetId
  }
}

Updating attribute categories

Reorganize attributes by updating their categories.

mutation {
  updateDataSet(
    where: {
      dataSetId: "{REFERENCE_SET_ID}"
    }
    to: {
      attributes: {
        update: [
          {
            name: "Order total"
            category: "Demographic"
          }
          {
            name: "Order date"
            category: "Demographic"
          }
        ]
      }
    }
  ) {
    dataSetId
  }
}

Removing unused attributes

Delete attributes that are no longer needed.

mutation {
  updateDataSet(
    where: {
      dataSetId: "{REFERENCE_SET_ID}"
    }
    to: {
      attributes: {
        remove: [
          {
            name: "Legacy attribute 1"
          }
          {
            name: "Legacy attribute 2"
          }
        ]
      }
    }
  ) {
    dataSetId
  }
}

Combined operations

Add, update and remove attributes in a single operation.

mutation {
  updateDataSet(
    where: {
      dataSetId: "{REFERENCE_SET_ID}"
    }
    to: {
      attributes: {
        create: [
          {
            name: "Discount percentage"
            type: NUMBER
          }
        ]
        update: [
          {
            name: "Order total"
            category: "Demographic"
          }
        ]
        remove: [
          {
            name: "Store address"
          }
        ]
      }
    }
  ) {
    dataSetId
  }
}