GraphQL: Add layered navigation documentation

_data/toc/graphql.yml

@@ -13,15 +13,12 @@ pages:
         - label: Get customer authorization token
           url: /graphql/get-customer-authorization-token.html
 
-        - label: Queries
-          url: /graphql/queries.html
-
-        - label: Mutations
-          url: /graphql/mutations.html
-
         - label: GraphQL Caching
           url: /graphql/caching.html
 
+        - label: Filtering with custom attributes
+          url: /graphql/custom-filters.html
+
     - label: Development
       children:
         - label: Define the GraphQL schema for a module
@@ -47,6 +44,10 @@ pages:
 
     - label: Queries
       children:
+
+        - label: Using queries
+          url: /graphql/queries/index.html
+
         - label: cart query
           url: /graphql/queries/cart.html
 
@@ -98,9 +99,12 @@ pages:
         - label: isEmailAvailable query
           url: /graphql/queries/is-email-available.html
 
-        - label: products query
+        - label: products query (2.3.3)
           url: /graphql/queries/products.html
 
+        - label: products query (2.3.4)
+          url: /graphql/queries/products-234.html
+
         - label: storeConfig query
           url: /graphql/queries/store-config.html
 
@@ -112,6 +116,10 @@ pages:
 
     - label: Mutations
       children:
+
+        - label: Using mutations
+          url: /graphql/mutations/index.html
+
         - label: addConfigurableProductsToCart mutation
           url: /graphql/mutations/add-configurable-products.html
 

_data/whats-new.yml

@@ -1093,7 +1093,7 @@ entries:
   date: March 26, 2019
   link: https://github.com/magento/devdocs/pull/3867
 - description: The "Searches and Pagination" topic  has been expanded to include more
-    information about queries and renamed to ["Queries"](https://devdocs.magento.com/guides/v2.3/graphql/queries.html).
+    information about queries and renamed to ["Queries"](https://devdocs.magento.com/guides/v2.3/graphql/queries/index.html).
   versions: 2.3.1
   type: Major update
   date: March 26, 2019
@@ -1119,7 +1119,7 @@ entries:
   type: Major update
   date: March 26, 2019
   link: https://github.com/magento/devdocs/pull/3851
-- description: Added a topic on [GraphQL mutations](https://devdocs.magento.com/guides/v2.3/graphql/mutations.html)
+- description: Added a topic on [GraphQL mutations](https://devdocs.magento.com/guides/v2.3/graphql/mutations/index.html)
   versions: 2.3.1
   type: New topic
   date: March 26, 2019

guides/v2.3/graphql/custom-filters.md

@@ -0,0 +1,88 @@
+---
+group: graphql
+title: Filtering with custom attributes
+---
+
+As of Magento 2.3.4, the `filter` attribute of the [`products`]({{page.baseurl}}/graphql/queries/products-234.html) query accepts the `ProductAttributeFilterInput` object. (In previous versions, the `filter` attribute required a `ProductFilterInput` object. This object contained a hard-coded list of filterable attributes, and you could not filter on a custom attribute or any other attribute that was not on the list.)
+
+## Prerequisites
+
+To enable a custom attribute (or any attribute that is not listed by default in the `ProductAttributeFilterInput` object) for filtering, select the attribute on the **Stores** > Attributes > **Product** page in the Admin and edit the following fields:
+
+Field | Setting
+--- | ---
+**Use in Search** | Yes
+**Visible in Advanced Search** | Yes
+**Use in Layered Navigation** | Filterable (with results) or Filterable (no results)
+**Use in Search Results Layered Navigation** | Yes
+
+## Define the filter for your query
+
+The [`filter`]({{page.baseurl}}/graphql/queries/products-234.html#filter) definition for your custom attribute requires one of the following input data types:
+
+-  `FilterEqualTypeInput` - Specify this data type when the **Catalog Input Type for Store Owner** field for your custom attribute is set to Yes/No, Select, or Multiple select. Your filter can contain the `eq` or `in` attribute. Use the `eq` attribute to exactly match the specified string. Use the `in` attribute to filter on a comma-separated list of values.
+-  `FilterMatchTypeInput` - Specify this data type when the the **Catalog Input Type for Store Owner** field for your custom attribute is set to Text Field or Text Area. Your filter must contain the `match` attribute, which will return all items that exactly match the specified string.
+-  `FilterRangeTypeInput` - Specify this data type when the the **Catalog Input Type for Store Owner** field for your custom attribute is set to Price or Date. Your filter can contain one or both of the `to` and `from` attributes, which serve to provide a range of values to filter on.
+
+## Example
+
+In this example, the custom attribute `volume` was assigned to the `bags` attribute group. Running the [`customAttributeMetadata` query]({{page.baseurl}}/graphql/queries/custom-attribute-metadata.html) on this custom attribute reveals that the `label` and `value` values for the attribute's options are as follows:
+
+`label` | `value`
+--- | ---
+`Large` | `216`
+`Medium` | `217`
+`Small` | `218`
+
+In this scenario, a `products` search filtered to return items where the `volume` attribute is set to `Large` would be similar to the following:
+
+**Request**
+
+```graphql
+{
+  products(filter: { volume: { eq: "216" } }) {
+    total_count
+    items {
+      name
+      sku
+    }
+  }
+}
+```
+
+**Response**
+
+The response might be similar to the following:
+
+```json
+{
+  "data": {
+    "products": {
+      "total_count": 1,
+      "items": [
+        {
+          "name": "Wayfarer Messenger Bag",
+          "sku": "24-MB05"
+        }
+      ]
+    }
+  }
+}
+```
+
+## Output attributes
+
+When a product requires a filter attribute that is not a field on its output schema, inject the attribute name into the class in a module's `di.xml` file.
+
+```xml
+<type name="Magento\CatalogGraphQl\Model\Resolver\Products\FilterArgument\ProductEntityAttributesForAst" >
+  <arguments>
+    <argument name="additionalAttributes" xsi:type="array">
+      <item name="field_to_sort" xsi:type="string">field</item>
+      <item name="other_field_to_sort" xsi:type="string">other_field</item>
+    </argument>
+  </arguments>
+</type>
+```
+
+This example adds `field_to_sort` and `other_field_to_sort` attributes to the `additionalAttributes` array defined in the `ProductEntityAttributesForAst` class. The array already contains the `min_price`, `max_price`, and `category_ids` attributes.

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

@@ -22,16 +22,16 @@ The base `schema.graphqls` file, located in the `app/code/Magento/GraphQl/etc/`
 
 A query definition can be one line, or it can be complex. If your module's query implements `searchCriteria`, then you must define arguments that define filters and pagination information, all of which adds complexity. However, if you expect a single result from your query, then its definition can be simple.
 
-The following example shows the `products` query. The `type` is defined as a `Query`.  The `products` definitions define the keywords that are used to construct a query, as shown in [Queries]({{ page.baseurl }}/graphql/queries.html). The parameter definitions will be discussed in [Specify output attributes](#specify-output-attributes).
+The following example shows the `products` query. The `type` is defined as a `Query`.  The `products` definitions define the keywords that are used to construct a query, as shown in [Using queries]({{ page.baseurl }}/graphql/queries/index.html). The parameter definitions will be discussed in [Specify output attributes](#specify-output-attributes).
 
 ```text
 type Query {
     products (
-        search: String,
-        filter: ProductFilterInput,
-        pageSize: Int = 20,
-        currentPage: Int = 1,
-        sort: ProductSortInput
+        search: String
+        filter: ProductAttributeFilterInput
+        pageSize: Int = 20
+        currentPage: Int = 1
+        sort: ProductAttributeSortInput
     ): Products @resolver(class: "Magento\\CatalogGraphQl\\Model\\Resolver\\Products")
 }
 ```

guides/v2.3/graphql/index.md

@@ -48,7 +48,7 @@ GraphiQL is an in-browser tool for writing, validating, and testing GraphQL quer
 
 ![GraphiQL browser]({{ page.baseurl }}/graphql/images/graphql-browser.png)
 
-To begin using GraphiQL, set the GraphQL endpoint by entering `http://<magento2-3-server>/graphql` in the URL bar, then click **Set endpoint**. You can use the browser in the right column to determine how to set up a query. Additional examples are also available in [Queries]({{ page.baseurl }}/graphql/queries.html).
+To begin using GraphiQL, set the GraphQL endpoint to `http://<magento2-3-server>/graphql` in the URL bar, then click **Set endpoint**. You can use the browser in the right column to determine how to set up a query. Additional examples are also available in [Using queries]({{ page.baseurl }}/graphql/queries/index.html).
 
 {:.bs-callout .bs-callout-info}
 You can access the GraphQL introspection feature only if your Magento instance is in developer mode. [Set the Magento mode]({{ page.baseurl }}/config-guide/cli/config-cli-subcommands-mode.html) describes how to check and change the mode.

guides/v2.3/graphql/mutations.md → guides/v2.3/graphql/mutations/index.md

@@ -1,6 +1,8 @@
 ---
 group: graphql
 title: Mutations
+redirect from:
+  - /guides/v2.3/graphql/mutations.html
 ---
 
 While GraphQL queries perform read operations, mutations change the data. A mutation can create, update, or delete objects and fields. In REST terminology, queries operate like `GET` requests, while mutations are similar to `POST`, `PUT`, and `DELETE`.