Use the dataSets query to retrieve the structure of your product catalog, including the catalog ID and available product attributes.

Typical usage:

Get the catalog ID required for product import mutations
Review available product attributes before importing data
Check attribute data types and validation rules

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.

Basic query structure

query {
  dataSets(filter: { field: "type", eq: "PRODUCT_CATALOG" }) {
    nodes {
      dataSetId
      name
      attributes {
        name
        type
      }
    }
  }
}

Query arguments

filter: Array of objects - Filter to retrieve only the product catalog (excludes audience and reference sets)

Filter object

To query the product catalog specifically, use these filter fields:

field (required): String - The dataset field to filter by. Valid value: type.
eq (required): String - The value to match. Valid value: PRODUCT_CATALOG.

Query fields

nodes (required): Array - Contains the product catalog object (see Product catalog object below).

Product catalog object

attributes: Array of objects - The list of default and custom product attributes available in the product catalog. Each object represents a single attribute (see Attribute object below). Supports an optional parameter:
- selectByName: Array of strings - Filter to return only attributes with these names
dataSetId: String - The catalog ID (required for product mutations)
name: String - The name of the product catalog
tracking: Object - Audit information (see Tracking object below)
type: Enum - The dataset type. Valid value: PRODUCT_CATALOG.

Attribute object

defaultDisplayText: String or null - The attribute name as displayed in the Connect application. Applies only to predefined attributes. Returns null for custom attributes.
name: String - The attribute name used in API calls
tracking: Object - Audit information (see Attribute tracking object below)
type: Enum - The data type. Valid values: TEXT, NUMBER, DATE, BOOLEAN, JSON, ARRAY.
validateAs: Enum or null - Specifies validation rules for attribute values. Applies only to TEXT and ARRAY type attributes. Valid values for text attributes: TEXT, URL, null. Valid values for array attributes: TEXT, NUMBER, BOOLEAN, DATE, URL, null.

Tracking object

createdAt: String - ISO 8601 timestamp when the product catalog was created. Example: 2025-06-16T14:14:54.574Z.
createdBy: String - The user who created the product catalog
lastModifiedAt: String - ISO 8601 timestamp when the product catalog was last modified. Example: 2025-11-20T15:40:51.247Z.
lastModifiedBy: String - The user who last modified the product catalog

Attribute tracking object

createdAt: String - ISO 8601 timestamp when the attribute was created. Example: 2025-06-16T14:14:54.574Z.
createdBy: String - The user who created the attribute
lastModifiedAt: String - ISO 8601 timestamp when the attribute was last modified. Example: 2025-11-20T15:40:51.247Z.
lastModifiedBy: String - The user who last modified the attribute

Response structure

The dataSets query returns a JSON response with this structure:

data: Object - Root response object
- dataSets: Object - Contains query results with the following field:
  - nodes: Array - Contains the product catalog object with all fields from the query

Examples

Getting complete product catalog structure

Before importing products, verify your catalog structure to ensure you're mapping data to the correct attribute names and using appropriate data types.

query {
  dataSets(filter: { field: "type", eq: "PRODUCT_CATALOG" }) {
    nodes {
      dataSetId
      name
      attributes {
        name
        type
        validateAs
        defaultDisplayText
      }
    }
  }
}

{
  "data": {
    "dataSets": {
      "nodes": [
        {
          "dataSetId": "CAT-2025YG",
          "name": "Product Catalog",
          "attributes": [
            {
              "name": "category",
              "type": "TEXT",
              "validateAs": null,
              "defaultDisplayText": "Category"
            },
            {
              "name": "productId",
              "type": "TEXT",
              "validateAs": null,
              "defaultDisplayText": "Product Id"
            },
            {
              "name": "productName",
              "type": "TEXT",
              "validateAs": null,
              "defaultDisplayText": "Product Name"
            },
            {
              "name": "productDescription",
              "type": "TEXT",
              "validateAs": null,
              "defaultDisplayText": "Product Description"
            },
            {
              "name": "imageUrls",
              "type": "ARRAY",
              "validateAs": "URL",
              "defaultDisplayText": "Image URLs"
            },
            {
              "name": "productUrls",
              "type": "ARRAY",
              "validateAs": "URL",
              "defaultDisplayText": "Product URLs"
            },
            {
              "name": "brandName",
              "type": "TEXT",
              "validateAs": null,
              "defaultDisplayText": "Brand Name"
            },
            {
              "name": "brandDescription",
              "type": "TEXT",
              "validateAs": null,
              "defaultDisplayText": "Brand Description"
            },
            {
              "name": "model",
              "type": "TEXT",
              "validateAs": null,
              "defaultDisplayText": "Model"
            },
            {
              "name": "unitPrice",
              "type": "NUMBER",
              "validateAs": null,
              "defaultDisplayText": "Unit Price"
            },
            {
              "name": "discount",
              "type": "NUMBER",
              "validateAs": null,
              "defaultDisplayText": "Discount"
            },
            {
              "name": "msrp",
              "type": "NUMBER",
              "validateAs": null,
              "defaultDisplayText": "MSRP"
            },
            {
              "name": "currency",
              "type": "TEXT",
              "validateAs": null,
              "defaultDisplayText": "Currency"
            },
            {
              "name": "inventoryQuantity",
              "type": "NUMBER",
              "validateAs": null,
              "defaultDisplayText": "Inventory Quantity"
            },
            {
              "name": "sku",
              "type": "TEXT",
              "validateAs": null,
              "defaultDisplayText": "SKU"
            },
            {
              "name": "productStatus",
              "type": "TEXT",
              "validateAs": null,
              "defaultDisplayText": "Product Status"
            },
            {
              "name": "availability",
              "type": "TEXT",
              "validateAs": null,
              "defaultDisplayText": "Availability"
            },
            {
              "name": "productRating",
              "type": "NUMBER",
              "validateAs": null,
              "defaultDisplayText": "Product Rating"
            },
            {
              "name": "dateAdded",
              "type": "DATE",
              "validateAs": null,
              "defaultDisplayText": "Date Added"
            },
            {
              "name": "tags",
              "type": "ARRAY",
              "validateAs": "TEXT",
              "defaultDisplayText": "Tags"
            },
            {
              "name": "Available Offline",
              "type": "BOOLEAN",
              "validateAs": null,
              "defaultDisplayText": null
            },
            {
              "name": "Offline Stores",
              "type": "ARRAY",
              "validateAs": "TEXT",
              "defaultDisplayText": null
            }
          ]
        }
      ]
    }
  }
}

Filtering specific attributes

Check the data types and validation rules for specific attributes you plan to use in your product import, without retrieving the entire attribute list.

query {
  dataSets(filter: { field: "type", eq: "PRODUCT_CATALOG" }) {
    nodes {
      attributes(selectByName: ["productUrls", "Offline Stores"]) {
        name
        type
        validateAs
        defaultDisplayText
        tracking {
          createdBy
          createdAt
          lastModifiedAt
          lastModifiedBy
        }
      }
    }
  }
}

{
  "data": {
    "dataSets": {
      "nodes": [
        {
          "attributes": [
            {
              "name": "productUrls",
              "type": "ARRAY",
              "validateAs": "URL",
              "defaultDisplayText": "Product URLs",
              "tracking": {
                "createdBy": "productUpgrade",
                "createdAt": "2025-06-16T14:14:54.574Z",
                "lastModifiedAt": "2025-06-16T14:14:54.574Z",
                "lastModifiedBy": "productUpgrade"
              }
            },
            {
              "name": "Offline Stores",
              "type": "ARRAY",
              "validateAs": "TEXT",
              "defaultDisplayText": null,
              "tracking": {
                "createdBy": "[email protected]",
                "createdAt": "2025-11-20T15:40:51.247Z",
                "lastModifiedAt": "2025-11-20T15:40:51.247Z",
                "lastModifiedBy": "[email protected]"
              }
            }
          ]
        }
      ]
    }
  }
}

💡 Pay attention to the difference between the custom and default attributes in the response.

The custom attribute "Offline Stores" was created by a user ([email protected]). The default attribute "productUrls" was created by the system (productUpgrade).
Unlike the default attribute, the custom attribute "Offline Stores" doesn't have a separate display name.