DataCategoryGroup Metadata Type for Salesforce Knowledge

Why the DataCategoryGroup Metadata Type Governs Knowledge Taxonomy & Visibility#

In Salesforce Service Cloud and Experience Cloud help centers, DataCategoryGroup (datacategorygroups/<Name>.datacategorygroup-meta.xml) defines a hierarchical tree of categories (up to 5 levels deep and 100 categories per group) assigned to Salesforce Knowledge (KnowledgeArticleVersion / Knowledge__kav) and Chatter Questions (Question).

Data Categories serve a dual architectural role:

1. Faceted Search & Navigation: Filtering Knowledge searches by Product Line, Region, or Customer Segment.
2. Article Visibility Security: Restricting which internal agents, partner portal users, or customer community members can view specific Knowledge categories.

Key Metadata Fields on DataCategoryGroup#

Real-World XML Example (datacategorygroups/Product_Taxonomy.datacategorygroup-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<DataCategoryGroup xmlns="http://soap.sforce.com/2006/04/metadata">
    <active>true</active>
    <dataCategory>
        <dataCategory>
            <dataCategory>
                <label>SSO &amp; MFA</label>
                <name>SSO_MFA</name>
            </dataCategory>
            <dataCategory>
                <label>API Gateways</label>
                <name>API_Gateways</name>
            </dataCategory>
            <label>Identity &amp; Security</label>
            <name>Identity_Security</name>
        </dataCategory>
        <dataCategory>
            <label>Billing &amp; Subscriptions</label>
            <name>Billing_Subscriptions</name>
        </dataCategory>
        <label>All Products</label>
        <name>All</name>
    </dataCategory>
    <description>Classifies Knowledge articles by product line and module.</description>
    <label>Product Taxonomy</label>
    <objectUsage>
        <object>KnowledgeArticleVersion</object>
    </objectUsage>
</DataCategoryGroup>

Filtering Knowledge Articles with WITH DATA CATEGORY in SOQL & Apex#

While DataCategoryGroup itself is inspected in Apex using the Schema.DescribeDataCategoryGroupResult API, you filter published Knowledge articles and inspect article categorizations using WITH DATA CATEGORY and Knowledge__DataCategorySelection:

1. Query Published Knowledge Articles Using WITH DATA CATEGORY (ABOVE_OR_BELOW)#

SELECT Id, KnowledgeArticleId, Title, UrlName, Summary, LastPublishedDate
FROM Knowledge__kav
WHERE PublishStatus = 'Online'
  AND Language = 'en_US'
WITH DATA CATEGORY Product_Taxonomy__c BELOW Identity_Security__c

2. Query Data Category Assignments on Specific Articles (Knowledge__DataCategorySelection)#

SELECT Id, ParentId, DataCategoryGroupName, DataCategoryName
FROM Knowledge__DataCategorySelection
WHERE Parent.PublishStatus = 'Online'

Senior Architect Warning: Destructive Category Overwrites#

Frequently asked questions

Why is deploying DataCategoryGroup changes to Production considered high-risk?

When you deploy a DataCategoryGroup XML file to an org where that group already exists, the Metadata API permanently deletes any existing data category not listed in the XML file and moves categorized Knowledge articles up to the parent category!

What are the platform limits on a DataCategoryGroup hierarchy?

Each DataCategoryGroup can contain up to 100 data categories arranged in up to 5 hierarchical levels (including the root All category), and an org can have up to 5 active DataCategoryGroups by default.

How do Data Categories control Knowledge article visibility?

Data Category visibility can be configured per Role, Permission Set, or Profile (All Categories, None, or Custom) or inherited from standard sharing when Lightning Knowledge standard sharing is enabled.

How do you filter Knowledge articles by DataCategoryGroup in SOQL?

In SOQL queries on Knowledge__kav, you append the WITH DATA CATEGORY clause using operators like AT, ABOVE, BELOW, or ABOVE_OR_BELOW (for example, WITH DATA CATEGORY Geography__c BELOW North_America__c).