---
schema_version: "1"
id: 90198577c47bcf409c53aabc9484b734038826ef8e1b777da87747e99f567414
title: WITH DATA CATEGORY DataCategorySpec
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/service-cloud/knowledge/guides/sforce-api-calls-sosl-with-data-category.md
canonical_url: https://developer.salesforce.com/docs/service/salesforce-knowledge-dev-guide/guide/sforce-api-calls-sosl-with-data-category.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: e6e29a00a120a8b25d47bf18306d624b6f90b09594534dc895effffe6007068c
products:
  - Salesforce Knowledge Developer Guide
  - Service Cloud 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` to query the specified data category, `ABOVE` to query the specified data category and all of its parent categories, `BELOW` to query the specified data category and all of its subcategories, or `ABOVE_OR_BELOW` to query 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 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_.

**tip:** You can also search for articles by ID, without using the `WITH DATA CATEGORY` clause.