--- schema_version: "1" id: bda6fce9edffe853cea6edfdd2a1e84749133e6de98f537b49bc7fe5509efa31 title: WITH DATA CATEGORY DataCategorySpec collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/platform/salesforce-soql-sosl/guides/soql-sosl/sforce-api-calls-sosl-with-data-category.md canonical_url: https://developer.salesforce.com/docs/platform/salesforce-soql-sosl/guide/sforce-api-calls-sosl-with-data-category.html source_site: developer.salesforce.com content_type: documentation content_hash: f97601e707f5a94b058187ec2c6c71fb3051348be8efc6136f55e5168cc83a5a products: - SOQL and SOSL Reference - Platform Developer Content --- # WITH DATA CATEGORY DataCategorySpec `WITH DATA CATEGORY` is an optional clause that can be added to a SOSL query to filter all search results that are associated with one or more data categories and are visible to users. This clause is used in searches of Salesforce Knowledge articles and questions. The `WITH DATA CATEGORY` clause can be used in API version 18.0 or later. ## Syntax The `WITH DATA CATEGORY` syntax is: ```soql WITH DATA CATEGORY DataCategorySpec [logicalOperator DataCategorySpec2 ... ] ``` Where DataCategorySpec consists of a groupName, Operator, and category. | Name | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `groupName` | The name of the data category group to filter. For information on category groups, see “Create and Modify Category Groups” in the Salesforce Help. | | `Operator` | Use one of the following operators: `AT`—Queries the specified data category; `ABOVE`—Queries the specified data category and all of its parent categories; `BELOW`—Queries the specified data category and all of its subcategories; or `ABOVE_OR_BELOW`—Queries the specified data category, all of its parent categories, and all of its subcategories. | | `category` | The name of the category to filter. To include multiple data categories, enclose them in parentheses, separated by commas. For information on categories, see “Add Data Categories to Category Groups” in the Salesforce Help. | You can add multiple data category specifiers by using the logical operator `AND`. Other operators, such as `OR` and `AND NOT`, are not supported. A SOSL statement using the `WITH DATA CATEGORY` clause must also include a `RETURNING ObjectTypeName` clause, with a `WHERE` clause that filters on the PublishStatus field. In the `RETURNING` clause, specify one of the following for ObjectTypeName: - To search a specific article type, use the article type name with the suffix _\_\_kav_ - To search all article types, use [KnowledgeArticleVersion](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_knowledgearticleversion.htm) - To search questions, use [Question](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_question.htm) For information on article types, see “Knowledge Article Types” in the Salesforce Help. The `WHERE` clause must use one of the following publish statuses: - `WHERE PublishStatus='online'` for published articles - `WHERE PublishStatus='archived'` for archived articles - `WHERE PublishStatus='draft'` for draft articles ## Examples | Search Type | Example | | --------------------------------------------------------------------------------------------------- | ------- | | Search all published (online)Salesforce Knowledge articles with a category from one category group. | Example | | Search online FAQ articles with categories from two category groups. | Example | | Search archived FAQ articles from one category group. | Example | | Search all draft Salesforce Knowledge articles from one category group. | Example | Search all published (online) Salesforce Knowledge articles with a category from one category group: ```soql FIND {tourism} RETURNING KnowledgeArticleVersion (Id, Title WHERE PublishStatus='online') WITH DATA CATEGORY Location__c AT America__c ``` Search online FAQ articles with categories from two category groups: ```soql FIND {tourism} RETURNING FAQ__kav (Id, Title WHERE PublishStatus='online') WITH DATA CATEGORY Geography__c ABOVE France__c AND Product__c AT mobile_phones__c ``` Search archived FAQ articles from one category group: ```soql FIND {tourism} RETURNING FAQ__kav (Id, Title WHERE PublishStatus='archived') WITH DATA CATEGORY Geography__c AT Iceland__c ``` Search all draft Salesforce Knowledge articles from one category group: ```soql FIND {tourism} RETURNING KnowledgeArticleVersion (Id, Title WHERE PublishStatus='draft') WITH DATA CATEGORY Geography__c BELOW Europe__c ``` For information on the `WITH DATA CATEGORY` clause, see the [`WITH DATA CATEGORY` filteringExpression](https://developer.salesforce.com/docs/platform/salesforce-soql-sosl/guide/sforce-api-calls-soql-select-with-datacategory.md). You can also search for articles by ID, without using the `WITH DATA CATEGORY` clause. For more information, see [Example WHERE Clauses](https://developer.salesforce.com/docs/platform/salesforce-soql-sosl/guide/sforce-api-calls-sosl-where.md).