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

Commit f793cf9

Browse files
sathiyaaakeharper
sathiyaaa
and
keharper
authored
Added more details to define Graphql schema for better understanding (#8232)
* rebased to master branch * Update create-graphqls-file.md * Update create-graphqls-file.md * Update create-graphqls-file.md * Update create-graphqls-file.md * Update create-graphqls-file.md * Update create-graphqls-file.md Co-authored-by: Kevin Harper <keharper@users.noreply.github.com>
1 parent e2d20aa commit f793cf9

File tree

2 files changed

+255
-2
lines changed

2 files changed

+255
-2
lines changed

‎src/guides/v2.3/graphql/develop/create-graphqls-file.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,18 +50,145 @@ If all your module's attributes are extension attributes for existing modules, t
5050

5151
You must explicitly define each attribute that can be used as input in a GraphQL query. In the simplest cases, you can create a single `type` definition that includes all the input, output, and sorting attributes for an object. This might not be possible if your module performs calculations, or otherwise has attributes that aren't available at the time of the query.
5252

53+
The following example shows the `products` query, which has multiple optional attributes:
54+
55+
```graphql
56+
products(
57+
search: String
58+
filter: ProductAttributeFilterInput
59+
pageSize: Int
60+
currentPage: Int
61+
sort: ProductAttributeSortInput
62+
): Products
63+
```
64+
65+
The `ProductAttributeFilterInput` object used in the `filter` attribute is a custom input type that determines which attributes can be used to narrow the results in a `products` query. The attributes of this object are of type `FilterEqualTypeInput`. (These entities are defined in the `etc/schema.graphqls` files of the `GraphQl` and `CatalogGraphQl` modules). In other use cases, you would be required to create your own input type in the `<magento_root>/app/code/<vendor_name>/<module_name>/etc/schema.graphqls` file.
66+
67+
The following attributes can be used as filters using the `ProductAttributeFilterInput` object.
68+
69+
```graphql
70+
input ProductAttributeFilterInput {
71+
category_id: FilterEqualTypeInput
72+
}
73+
```
74+
75+
The `FilterEqualTypeInput` type defines a filter that matches the input exactly.
76+
77+
```graphql
78+
input FilterEqualTypeInput {
79+
in: [String]
80+
eq: String
81+
}
82+
```
83+
84+
The following example filter searches for products whose `category_id` equals 1.
85+
86+
```graphql
87+
{
88+
products(filter: {category_id: {eq: "1"}}) {
89+
total_count
90+
items {
91+
name
92+
}
93+
}
94+
}
95+
```
96+
97+
The search returns products whose `category_id` equals 1.
98+
99+
```json
100+
{
101+
"data": {
102+
"products": {
103+
"total_count": 2,
104+
"items": [
105+
{
106+
"name": "Josie Yoga Jacket"
107+
},
108+
{
109+
"name": "Selene Yoga Hoodie"
110+
}
111+
]
112+
}
113+
}
114+
}
115+
```
116+
53117
### Specify output attributes {#specify-output-attributes}
54118

55119
You must know the data type of each attribute, whether it is scalar or an object, and whether it can be part of an array. In addition, each attribute within an object must be defined in the same manner.
56120

57121
In a `schema.graphqls` file, the output `Interface` defines top-level attributes. Each object returned is defined in a `type` definition.
58122

123+
The following example shows the `products` query. The query returns a `Products` object containing the attributes of the specified data types.
124+
125+
Attribute | Data type | Description
126+
--- | --- | ---
127+
`aggregations` | [[Aggregation]]({{ page.baseurl }}/graphql/queries/products.html#Aggregation) | Layered navigation aggregations
128+
`items` | [[ProductInterface]]({{ page.baseurl }}/graphql/queries/products.html#ProductInterface) | An array of products that match the specified search criteria
129+
`page_info` | [SearchResultPageInfo]({{ page.baseurl }}/graphql/queries/products.html#SearchResultPageInfo) | An object that includes the `page_info` and `currentPage` values specified in the query
130+
`sort_fields` | [SortFields]({{ page.baseurl }}/graphql/queries/products.html#SortFields) | An object that includes the default sort field and all available sort fields
131+
`total_count` | Int | The number of products in the category that are marked as visible. By default, in complex products, parent products are visible, but their child products are not
132+
59133
### Define the output interface
60134

61135
In many cases, the response contains data that was either not available as input, or was transformed in some manner from the input. For example, when you specify a price in an input filter, Magento evaluates it as a Float value. However, `Price` output objects contain a Float value, a currency value, and possibly minimum/maximum values and tax adjustments. You can define a `typeResolver` to point to the Resolver object, which interprets the GraphQL query. If your module contains only attributes that extend another module, then this parameter is optional. Otherwise, it is required. See [Resolvers]({{ page.baseurl }}/graphql/develop/resolvers.html) for more information.
62136

63137
Output types that represent entities that can be manipulated (created, updated, or removed) and/or can be cached on the client MUST have `id` field. The type of the field SHOULD be `ID`.
64138

139+
The following example shows the `products` query. The `page_info` attribute contains the `SearchResultPageInfo` data type which is defined in the `schema.graphqls` file under `ModuleGraphQl`. In other use cases, you would be required to create your own output type in the `<magento_root>/app/code/<vendor_name>/<module_name>/etc/schema.graphqls` file.
140+
141+
The SearchResultPageInfo provides navigation for the query response.
142+
143+
```graphql
144+
type SearchResultPageInfo {
145+
page_size: Int
146+
current_page: Int
147+
total_pages: Int
148+
}
149+
```
150+
151+
The following example uses the `page_info` output attribute which is of `SearchResultPageInfo` type to get all the information related to the page.
152+
153+
```graphql
154+
{
155+
products(search: "Yoga pants", pageSize: 2) {
156+
total_count
157+
items {
158+
name
159+
}
160+
page_info {
161+
page_size
162+
current_page
163+
}
164+
}
165+
}
166+
```
167+
168+
The search returns 45 items, but only the first two items are returned on the current page and all the information regarding the page is returned.
169+
170+
```json
171+
{
172+
"data": {
173+
"products": {
174+
"total_count": 45,
175+
"items": [
176+
{
177+
"name": "Josie Yoga Jacket"
178+
},
179+
{
180+
"name": "Selene Yoga Hoodie"
181+
}
182+
],
183+
"page_info": {
184+
"page_size": 2,
185+
"current_page": 1
186+
}
187+
}
188+
}
189+
}
190+
```
191+
65192
## Define mutations
66193

67194
A mutation definition contains the following information:

‎src/guides/v2.4/graphql/develop/create-graphqls-file.md

Lines changed: 128 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,20 +50,146 @@ If all your module's attributes are extension attributes for existing modules, t
5050

5151
You must explicitly define each attribute that can be used as input in a GraphQL query. In the simplest cases, you can create a single `type` definition that includes all the input, output, and sorting attributes for an object. This might not be possible if your module performs calculations, or otherwise has attributes that aren't available at the time of the query.
5252

53+
The following example shows the `products` query, which has multiple optional attributes:
54+
55+
```graphql
56+
products(
57+
search: String
58+
filter: ProductAttributeFilterInput
59+
pageSize: Int
60+
currentPage: Int
61+
sort: ProductAttributeSortInput
62+
): Products
63+
```
64+
65+
The `ProductAttributeFilterInput` object used in the `filter` attribute is a custom input type that determines which attributes can be used to narrow the results in a `products` query. The attributes of this object are of type `FilterEqualTypeInput`. (These entities are defined in the `etc/schema.graphqls` files of the `GraphQl` and `CatalogGraphQl` modules). In other use cases, you would be required to create your own input type in the `<magento_root>/app/code/<vendor_name>/<module_name>/etc/schema.graphqls` file.
66+
67+
The following attributes can be used as filters using the `ProductAttributeFilterInput` object.
68+
69+
```graphql
70+
input ProductAttributeFilterInput {
71+
category_id: FilterEqualTypeInput
72+
}
73+
```
74+
75+
The `FilterEqualTypeInput` type defines a filter that matches the input exactly.
76+
77+
```graphql
78+
input FilterEqualTypeInput {
79+
in: [String]
80+
eq: String
81+
}
82+
```
83+
84+
The following example filter searches for products whose `category_id` equals 1.
85+
86+
```graphql
87+
{
88+
products(filter: {category_id: {eq: "1"}}) {
89+
total_count
90+
items {
91+
name
92+
}
93+
}
94+
}
95+
```
96+
97+
The search returns products whose `category_id` equals 1.
98+
99+
```json
100+
{
101+
"data": {
102+
"products": {
103+
"total_count": 2,
104+
"items": [
105+
{
106+
"name": "Josie Yoga Jacket"
107+
},
108+
{
109+
"name": "Selene Yoga Hoodie"
110+
}
111+
]
112+
}
113+
}
114+
}
115+
```
116+
53117
### Specify output attributes {#specify-output-attributes}
54118

55119
You must know the data type of each attribute, whether it is scalar or an object, and whether it can be part of an array. In addition, each attribute within an object must be defined in the same manner.
56120

57121
In a `schema.graphqls` file, the output `Interface` defines top-level attributes. Each object returned is defined in a `type` definition.
58122

123+
The following example shows the `products` query. The query returns a `Products` object containing the attributes of the specified data types.
124+
125+
Attribute | Data type | Description
126+
--- | --- | ---
127+
`aggregations` | [[Aggregation]]({{ page.baseurl }}/graphql/queries/products.html#Aggregation) | Layered navigation aggregations
128+
`items` | [[ProductInterface]]({{ page.baseurl }}/graphql/queries/products.html#ProductInterface) | An array of products that match the specified search criteria
129+
`page_info` | [SearchResultPageInfo]({{ page.baseurl }}/graphql/queries/products.html#SearchResultPageInfo) | An object that includes the `page_info` and `currentPage` values specified in the query
130+
`sort_fields` | [SortFields]({{ page.baseurl }}/graphql/queries/products.html#SortFields) | An object that includes the default sort field and all available sort fields
131+
`total_count` | Int | The number of products in the category that are marked as visible. By default, in complex products, parent products are visible, but their child products are not
132+
59133
### Define the output interface
60134

61135
In many cases, the response contains data that was either not available as input, or was transformed in some manner from the input. For example, when you specify a price in an input filter, Magento evaluates it as a Float value. However, `Price` output objects contain a Float value, a currency value, and possibly minimum/maximum values and tax adjustments. You can define a `typeResolver` to point to the Resolver object, which interprets the GraphQL query. If your module contains only attributes that extend another module, then this parameter is optional. Otherwise, it is required. See [Resolvers]({{ page.baseurl }}/graphql/develop/resolvers.html) for more information.
62136

63137
Output types that represent entities that can be manipulated (created, updated, or removed) and/or can be cached on the client MUST have `id` field. The type of the field SHOULD be `ID`.
64138

65-
## Define mutations
139+
The following example shows the `products` query. The `page_info` attribute contains the `SearchResultPageInfo` data type which is defined in the `schema.graphqls` file under `ModuleGraphQl`. In other use cases, you would be required to create your own output type in the `<magento_root>/app/code/<vendor_name>/<module_name>/etc/schema.graphqls` file.
140+
141+
The SearchResultPageInfo provides navigation for the query response.
142+
143+
```text
144+
type SearchResultPageInfo {
145+
page_size: Int
146+
current_page: Int
147+
total_pages: Int
148+
}
149+
```
66150

151+
The following example uses the `page_info` output attribute which is of `SearchResultPageInfo` type to get all the information related to the page.
152+
153+
```graphql
154+
{
155+
products(search: "Yoga pants", pageSize: 2) {
156+
total_count
157+
items {
158+
name
159+
}
160+
page_info {
161+
page_size
162+
current_page
163+
}
164+
}
165+
}
166+
```
167+
168+
The search returns 45 items, but only the first two items are returned on the current page and all the information regarding the page is returned.
169+
170+
```json
171+
{
172+
"data": {
173+
"products": {
174+
"total_count": 45,
175+
"items": [
176+
{
177+
"name": "Josie Yoga Jacket"
178+
},
179+
{
180+
"name": "Selene Yoga Hoodie"
181+
}
182+
],
183+
"page_info": {
184+
"page_size": 2,
185+
"current_page": 1
186+
}
187+
}
188+
}
189+
}
190+
```
191+
192+
## Define mutations
67193
A mutation definition contains the following information:
68194

69195
* The mutation name
@@ -73,7 +199,7 @@ A mutation definition contains the following information:
73199

74200
The following mutation creates a customer.
75201

76-
``` text
202+
```text
77203
type Mutation {
78204
createCustomer (input: CustomerInput!): CustomerOutput @resolver(class: "\\Magento\\CustomerGraphQl\\Model\\Resolver\\CreateCustomer") @doc(description:"Create customer account")
79205
}

0 commit comments

Comments
 (0)