categories query

The categories query returns a list of categories that match the specified filter. This query differs from the categoryList query in that it supports pagination.

The categories query supports the following types of filters. You can specify multiple filters in a query.

  • Category ID
  • Category name
  • URL key
  • URL path

The query returns a CategoryResult object, which contains pagination information and an array of CategoryTree items. The top level of the CategoryTree object provides details about the queried category. This object includes the children attribute, which contains an array of its immediate subcategories. To return multiple category levels in a single call, define the response so that it contains up to ten nested children options.

You cannot return the entire category tree if it contains more than ten sublevels unless the queryDepth parameter in the GraphQL di.xml file has been reconfigured.

Use the breadcrumbs attribute to return information about the parent categories of the queried category.

Syntax

1
categories(filters: CategoryFilterInput pageSize: Int currentPage: Int): CategoryResult

Example usage

The following query returns the top-level categories (as well as two levels of children) displayed on the Luma storefront. Because the currentPage attribute is set to 2, the second page of results are returned.

Request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  categories(filters: {ids: {in: ["3", "9", "11", "20", "37", "38"]}} pageSize:3 currentPage: 2){
    total_count
    items {
      id
      level
      name
      path
      children_count
      children {
        id
        level
        name
        path
        children_count
        children {
          id
          level
          name
          path
        }
      }
    }
    page_info {
      current_page
      page_size
      total_pages
    }
  }
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
{
  "data": {
    "categories": {
      "total_count": 6,
      "items": [
        {
          "id": 20,
          "level": 2,
          "name": "Women",
          "path": "1/2/20",
          "children_count": "8",
          "children": [
            {
              "id": 22,
              "level": 3,
              "name": "Bottoms",
              "path": "1/2/20/22",
              "children_count": "2",
              "children": [
                {
                  "id": 27,
                  "level": 4,
                  "name": "Pants",
                  "path": "1/2/20/22/27"
                },
                {
                  "id": 28,
                  "level": 4,
                  "name": "Shorts",
                  "path": "1/2/20/22/28"
                }
              ]
            },
            {
              "id": 21,
              "level": 3,
              "name": "Tops",
              "path": "1/2/20/21",
              "children_count": "4",
              "children": [
                {
                  "id": 23,
                  "level": 4,
                  "name": "Jackets",
                  "path": "1/2/20/21/23"
                },
                {
                  "id": 24,
                  "level": 4,
                  "name": "Hoodies & Sweatshirts",
                  "path": "1/2/20/21/24"
                },
                {
                  "id": 25,
                  "level": 4,
                  "name": "Tees",
                  "path": "1/2/20/21/25"
                },
                {
                  "id": 26,
                  "level": 4,
                  "name": "Bras & Tanks",
                  "path": "1/2/20/21/26"
                }
              ]
            }
          ]
        },
        {
          "id": 37,
          "level": 2,
          "name": "Sale",
          "path": "1/2/37",
          "children_count": "0",
          "children": []
        },
        {
          "id": 38,
          "level": 2,
          "name": "What's New",
          "path": "1/2/38",
          "children_count": "0",
          "children": []
        }
      ],
      "page_info": {
        "current_page": 2,
        "page_size": 3,
        "total_pages": 2
      }
    }
  }
}

Input attributes

If you omit the filters attribute, the query returns the store’s default root category.

Attribute Data type Description
filters CategoryFilterInput Contains filter definitions
pageSize Int Specifies the maximum number of results to return at once. The default value is 20
currentPage Int Specifies which page of results to return. The default value is 1

CategoryFilterInput object

The CategoryFilterInput object defines the filters to be used in this query.

Attribute Data type Description
ids FilterEqualTypeInput Filters by the specified category IDs
name FilterMatchTypeInput Filters by the display name of the category
url_key FilterEqualTypeInput Filters by the part of the URL that identifies the category
url_path FilterEqualTypeInput Filters by the URL path for the category

FilterEqualTypeInput object

Use the FilterEqualTypeInput object to construct filters that search by category ID or URL key.

Attribute Data type Description
eq String Use this attribute to exactly match the specified string. For example, to filter on a specific URL key, specify a value like shorts-women
in [String] Use this attribute to filter on an array of values. For example, to filter on category IDs 4, 5, and 6, specify a value of ["4", "5", "6"]

FilterMatchTypeInput object

Use the FilterMatchTypeInput object to construct a filter that matches the specified display name.

Attribute Data type Description
match String Use this attribute to perform a fuzzy match on the specified string. For example, to filter on a specific category name, specify a value such as Tops

Output attributes

The categories query returns a CategoryResult object, which contains the following attributes:

Attribute Data type Description
items [CategoryTree] A list of categories that match filter criteria
page_info SearchResultPageInfo An object that includes the page_info and currentPage values specified in the query.
total_count Int The total number of categories that match the criteria

CategoryTree attributes

The items attribute contains a CategoryTree object, which implements CategoryInterface. The CategoryTree object can contain the following attribute and all attributes defined in CategoryInterface:

Attribute Data type Description
children CategoryTree An array containing the next level of subcategories. By default, you can specify up to 10 levels of child categories

SearchResultPageInfo

Attribute Data type Description
current_page Int Specifies which page of results to return
page_size Int Specifies the maximum number of items to return
total_pages Int Total pages