Skip to content
Integrations
Guides
Datasets
Editing SaaS Datasets

Editing SaaS Datasets

SaaS integration datasets are automatically generated when you configure a SaaS integration. However, you may need to customize these datasets — for example, to add data categories, update field descriptions, or remove fields that are not relevant to your use case.

This guide explains how to edit a SaaS dataset using the Fides API, what changes are allowed, and what happens to your customizations when the integration is updated.

Dataset edits are scoped to a single connection. If you have multiple connections of the same integration type (e.g., two Stripe connections), changes to one connection's dataset will not affect the other. Each connection maintains its own independent dataset.

Prerequisites

  • A running Fides instance with a configured SaaS integration
  • The connection_key for the connection whose dataset you want to edit
  • API access to your Fides instance

Editing a SaaS dataset via the API

To update a SaaS dataset, use the PATCH endpoint for connection datasets:

PATCH /api/v1/connection/{connection_key}/dataset

Pass the updated dataset as the request body. For example, to add a data category to a field:

[
  {
    "fides_key": "my_saas_instance",
    "collections": [
      {
        "name": "user",
        "fields": [
          {
            "name": "email",
            "data_categories": ["user.contact.email"]
          }
        ]
      }
    ]
  }
]
To retrieve the current dataset for reference before editing, use GET /api/v1/connection/{connection_key}/dataset.

Editing rules

Only the collections section of a SaaS dataset is mutable. The following table summarizes what you can and cannot change:

ActionAllowed?Notes
Add or update data_categories on a fieldYes
Add or update the description of a fieldYes
Modify fides_meta.data_type on a fieldYes
Remove a non-protected fieldYes
Remove a protected fieldNoRestored from template automatically
Add new collectionsNoIgnored during execution, discarded on update
Add references or identitiesNoMust be defined in the SaaS config
Change top-level metadata (fides_key, name, description, data_categories, organization_fides_key, meta)NoRestored to original value with a warning
Protected fields are collection fields referenced by the SaaS config (e.g., in param_values or postprocessors). You can modify their metadata (data categories, descriptions, etc.) but you cannot delete them. To check which fields are protected, use GET /api/v1/connection/{connection_key}/dataset/{dataset_key}/protected-fields.

Behavior on integration update

When a SaaS integration template is updated, Fides performs a three-way merge to reconcile your customizations with the new template. How the update is triggered depends on the template type:

  • Built-in templates are updated automatically when Fides is upgraded to a version that includes a new template.
  • Custom templates are only updated when you re-upload the template. A Fides version upgrade will not modify datasets for custom integrations. See Custom Integration Templates for details.

In both cases, the merge is performed between your current dataset (with your customizations), the previously stored template (the baseline), and the new template (the update).

ScenarioBehavior
You modified a fieldYour version is preserved, even if the template also changed it
You did not modify a fieldUpdated to the new template version
You deleted a non-protected fieldStays deleted
You deleted a protected fieldRestored from the new template
Template adds a new fieldAdded to your dataset
Template removes a fieldRemoved from your dataset

Example

Suppose the original template has a user collection with fields email, name, and product_id.

Your edits:

  • Add data_categories: ["user.contact.email"] to email
  • Change the data_type on product_id
  • Delete the name field

New template changes:

  • Changes the data_type on product_id
  • Adds a new created_at field

Result after merge:

FieldOutcome
emailKeeps your data category annotation
product_idKeeps your data_type (your change takes priority)
nameRemains deleted (not a protected field)
created_atAdded from the new template

Next steps

Linking DatasetsIndex