Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Commit e53feed

Browse files
keharperkeharper
authored
GraphQL: Add categoryList query (#5562)
* checkpoint * review draft * fix linting errors * add to list of cached queries * update example to show usage of * clarify match filters * Apply suggestions from code review Added review comments Co-Authored-By: Jeff Matthews <[email protected]> * update sample * rename file * review comment from Dan * developer feedback
1 parent 374842c commit e53feed

File tree

4 files changed

+383
-1
lines changed

4 files changed

+383
-1
lines changed

‎_data/toc/graphql.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,9 @@ pages:
5454
- label: category query
5555
url: /graphql/queries/category.html
5656

57+
- label: categoryList query
58+
url: /graphql/queries/category-list.html
59+
5760
- label: checkoutAgreements query
5861
url: /graphql/queries/checkout-agreements.html
5962

‎guides/v2.3/graphql/caching.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ The definitions for some queries include cache tags. Full page caching uses thes
1111

1212
Magento caches the following queries:
1313

14-
* `category`
14+
* `category` (deprecated)
15+
* `categoryList`
1516
* `cmsBlocks`
1617
* `cmsPage`
1718
* `products`

‎guides/v2.3/graphql/queries/category-list.md‎

Lines changed: 375 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,375 @@
1+
---
2+
group: graphql
3+
title: categoryList query
4+
---
5+
6+
The `categoryList` query searches for categories that match the criteria specified in filters. It replaces the deprecated `category` query, which allowed you to search by category ID only.
7+
8+
The `categoryList` query supports the following types of filters. You can specify multiple filters in a query.
9+
10+
- Category ID
11+
- Category name
12+
- URL Key
13+
14+
If you do not provide any filter input, the query returns the root category.
15+
16+
The query returns a `CategoryTree` object. 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.
17+
18+
{:.bs-callout-info}
19+
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.
20+
21+
Use the `breadcrumbs` attribute to return information about the parent categories of the queried category.
22+
23+
## Syntax
24+
25+
```graphql
26+
categoryList (
27+
filters: CategoryFilterInput
28+
): CategoryTree
29+
```
30+
31+
## Example usage
32+
33+
### Return the category tree of a top-level category
34+
35+
The following query returns information about category IDs `11` and `20` and two levels of subcategories. In the sample data, category IDs `11` and `20` are assigned to the `Men` and `Women` categories, respectively.
36+
37+
**Request**
38+
39+
```graphql
40+
{
41+
categoryList(filters: {ids: {in: ["11", "20"]}}) {
42+
children_count
43+
children {
44+
id
45+
level
46+
name
47+
path
48+
url_path
49+
url_key
50+
children {
51+
id
52+
level
53+
name
54+
path
55+
url_path
56+
url_key
57+
}
58+
}
59+
}
60+
}
61+
```
62+
63+
**Response**
64+
65+
```json
66+
{
67+
"data": {
68+
"categoryList": [
69+
{
70+
"children_count": "8",
71+
"children": [
72+
{
73+
"id": 13,
74+
"level": 3,
75+
"name": "Bottoms",
76+
"path": "1/2/11/13",
77+
"url_path": "men/bottoms-men",
78+
"url_key": "bottoms-men",
79+
"children": [
80+
{
81+
"id": 18,
82+
"level": 4,
83+
"name": "Pants",
84+
"path": "1/2/11/13/18",
85+
"url_path": "men/bottoms-men/pants-men",
86+
"url_key": "pants-men"
87+
},
88+
{
89+
"id": 19,
90+
"level": 4,
91+
"name": "Shorts",
92+
"path": "1/2/11/13/19",
93+
"url_path": "men/bottoms-men/shorts-men",
94+
"url_key": "shorts-men"
95+
}
96+
]
97+
},
98+
{
99+
"id": 12,
100+
"level": 3,
101+
"name": "Tops",
102+
"path": "1/2/11/12",
103+
"url_path": "men/tops-men",
104+
"url_key": "tops-men",
105+
"children": [
106+
{
107+
"id": 14,
108+
"level": 4,
109+
"name": "Jackets",
110+
"path": "1/2/11/12/14",
111+
"url_path": "men/tops-men/jackets-men",
112+
"url_key": "jackets-men"
113+
},
114+
{
115+
"id": 15,
116+
"level": 4,
117+
"name": "Hoodies & Sweatshirts",
118+
"path": "1/2/11/12/15",
119+
"url_path": "men/tops-men/hoodies-and-sweatshirts-men",
120+
"url_key": "hoodies-and-sweatshirts-men"
121+
},
122+
{
123+
"id": 16,
124+
"level": 4,
125+
"name": "Tees",
126+
"path": "1/2/11/12/16",
127+
"url_path": "men/tops-men/tees-men",
128+
"url_key": "tees-men"
129+
},
130+
{
131+
"id": 17,
132+
"level": 4,
133+
"name": "Tanks",
134+
"path": "1/2/11/12/17",
135+
"url_path": "men/tops-men/tanks-men",
136+
"url_key": "tanks-men"
137+
}
138+
]
139+
}
140+
]
141+
},
142+
{
143+
"children_count": "8",
144+
"children": [
145+
{
146+
"id": 22,
147+
"level": 3,
148+
"name": "Bottoms",
149+
"path": "1/2/20/22",
150+
"url_path": "women/bottoms-women",
151+
"url_key": "bottoms-women",
152+
"children": [
153+
{
154+
"id": 27,
155+
"level": 4,
156+
"name": "Pants",
157+
"path": "1/2/20/22/27",
158+
"url_path": "women/bottoms-women/pants-women",
159+
"url_key": "pants-women"
160+
},
161+
{
162+
"id": 28,
163+
"level": 4,
164+
"name": "Shorts",
165+
"path": "1/2/20/22/28",
166+
"url_path": "women/bottoms-women/shorts-women",
167+
"url_key": "shorts-women"
168+
}
169+
]
170+
},
171+
{
172+
"id": 21,
173+
"level": 3,
174+
"name": "Tops",
175+
"path": "1/2/20/21",
176+
"url_path": "women/tops-women",
177+
"url_key": "tops-women",
178+
"children": [
179+
{
180+
"id": 23,
181+
"level": 4,
182+
"name": "Jackets",
183+
"path": "1/2/20/21/23",
184+
"url_path": "women/tops-women/jackets-women",
185+
"url_key": "jackets-women"
186+
},
187+
{
188+
"id": 24,
189+
"level": 4,
190+
"name": "Hoodies & Sweatshirts",
191+
"path": "1/2/20/21/24",
192+
"url_path": "women/tops-women/hoodies-and-sweatshirts-women",
193+
"url_key": "hoodies-and-sweatshirts-women"
194+
},
195+
{
196+
"id": 25,
197+
"level": 4,
198+
"name": "Tees",
199+
"path": "1/2/20/21/25",
200+
"url_path": "women/tops-women/tees-women",
201+
"url_key": "tees-women"
202+
},
203+
{
204+
"id": 26,
205+
"level": 4,
206+
"name": "Bras & Tanks",
207+
"path": "1/2/20/21/26",
208+
"url_path": "women/tops-women/tanks-women",
209+
"url_key": "tanks-women"
210+
}
211+
]
212+
}
213+
]
214+
}
215+
]
216+
}
217+
}
218+
```
219+
220+
### Return breadcrumb information
221+
222+
The following query returns breadcrumb information about categories that have the name `Tops`.
223+
224+
**Request**
225+
226+
```graphql
227+
{
228+
categoryList(filters: {name: {match: "Tops"}}) {
229+
id
230+
level
231+
name
232+
breadcrumbs {
233+
category_id
234+
category_name
235+
category_level
236+
category_url_key
237+
}
238+
}
239+
}
240+
```
241+
242+
**Response**
243+
244+
```json
245+
{
246+
"data": {
247+
"categoryList": [
248+
{
249+
"id": 12,
250+
"level": 3,
251+
"name": "Tops",
252+
"breadcrumbs": [
253+
{
254+
"category_id": 11,
255+
"category_name": "Men",
256+
"category_level": 2,
257+
"category_url_key": "men"
258+
}
259+
]
260+
},
261+
{
262+
"id": 21,
263+
"level": 3,
264+
"name": "Tops",
265+
"breadcrumbs": [
266+
{
267+
"category_id": 20,
268+
"category_name": "Women",
269+
"category_level": 2,
270+
"category_url_key": "women"
271+
}
272+
]
273+
}
274+
]
275+
}
276+
}
277+
```
278+
279+
## Input attributes
280+
281+
You must specify the `filters` attribute as input to your query.
282+
283+
Attribute | Data type | Description
284+
--- | --- | ---
285+
`filters` | CategoryFilterInput | Contains filter definitions
286+
287+
### CategoryFilterInput object
288+
289+
The `CategoryFilterInput` object defines the filters to be used in this query.
290+
291+
Attribute | Data type | Description
292+
--- | --- | ---
293+
`ids` | FilterEqualTypeInput | Filters by the specified category IDs
294+
`name` | FilterMatchTypeInput | Filters by the display name of the category
295+
`url_key` | FilterEqualTypeInput | Filters by the part of the URL that identifies the category
296+
297+
### FilterEqualTypeInput object
298+
299+
Use the `FilterEqualTypeInput` object to construct filters that search by category ID or URL key.
300+
301+
Attribute | Data type | Description
302+
--- | --- | ---
303+
`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`
304+
`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"]`
305+
306+
### FilterMatchTypeInput object
307+
308+
Use the `FilterMatchTypeInput` object to construct a filter that matches the specified display name.
309+
310+
Attribute | Data type | Description
311+
--- | --- | ---
312+
`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`
313+
314+
## Output attributes {#Categories}
315+
316+
The query returns a `CategoryTree` object, which implements `CategoryInterface`. It can contain the following top-level attributes:
317+
318+
Attribute | Data type | Description
319+
--- | --- | ---
320+
`breadcrumbs` | `Breadcrumb` | A `Breadcrumb` object contains information about the categories that comprise the breadcrumb trail for the specified category
321+
`children` | `CategoryTree` | A `CategoryTree` object that contains information about a child category. You can specify up to 10 levels of child categories
322+
`created_at`| String | Timestamp indicating when the category was created
323+
`default_sort_by`| String | The attribute to use for sorting
324+
`description`| String | An optional description of the category
325+
`id` | Int | An ID that uniquely identifies the category
326+
`level` | Int | Indicates the depth of the category within the tree
327+
`name`| String | The display name of the category
328+
`path_in_store`| String | The category path in the store
329+
`path`| String | The path to the category, as a string of category IDs, separated by slashes (/). For example, `1/2/20`
330+
`position`| Int | The position of the category relative to other categories at the same level in tree
331+
`product_count`| Int | The number of products in the category
332+
`products(<attributes>)` | `CategoryProducts` | The list of products assigned to the category
333+
`updated_at`| String | Timestamp indicating when the category was updated
334+
`url_key`| String | The URL key assigned to the category
335+
`url_path`| String | The URL path assigned to the category
336+
`url_suffix` | String | The part of the URL that is appended to the `url_key`, such as `.html`. This attribute is defined in the `CatalogUrlRewriteGraphQl` module
337+
338+
### CategoryProducts object
339+
340+
The `products` attribute can contain the following attributes:
341+
342+
Attribute | Data type | Description
343+
--- | --- | ---
344+
`currentPage` | Int | Specifies which page of results to return. The default value is 1
345+
`pageSize` | Int | Specifies the maximum number of results to return at once. This attribute is optional. The default value is 20
346+
`sort` | `ProductSortInput` | Specifies which attribute to sort on, and whether to return the results in ascending or descending order. [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) describes sort orders
347+
348+
The `CategoryProducts` object contains the following attributes:
349+
350+
Attribute | Data type | Description
351+
--- | --- | ---
352+
`items` | [[ProductInterface]]({{ page.baseurl }}/graphql/product/product-interface.html) | An array of products that are assigned to the category
353+
`page_info` | `SearchResultPageInfo` | An object that includes the `page_info` and `currentPage` values specified in the query
354+
`total_count` | Int | The number of products returned
355+
356+
### Breadcrumb object
357+
358+
A breadcrumb trail is a set of links that shows customers where they are in relation to other pages in the
359+
store.
360+
361+
Attribute | Data type | Description
362+
--- | --- | ---
363+
`category_id` | Int | An ID that uniquely identifies the category
364+
`category_level` | Int | Indicates the depth of the category within the tree
365+
`category_name` | String | The display name of the category
366+
`category_url_key` | String | The url key assigned to the category
367+
`category_url_path` | String | The URL path of the category
368+
369+
### CategoryTree object
370+
371+
This `CategoryTree` object contains information about the next level of subcategories of the category specified in the original query.
372+
373+
Attribute | Data type | Description
374+
--- | --- | ---
375+
`children` | [CategoryTree] | An array containing the next level of subcategories

0 commit comments

Comments
 (0)