Merge pull request #3840 from magento/kh_query-variables

keharper · web-flow · commit 62ed99a29c8b · 2019-03-05T16:34:44.000-06:00
Updating search and pagination topic
diff --git a/_data/toc/graphql.yml b/_data/toc/graphql.yml
@@ -10,8 +10,8 @@ pages:
         - label: GraphQL request headers
           url: /graphql/send-request.html
 
-        - label: Searches and pagination
-          url: /graphql/search-pagination.html
+        - label: Queries
+          url: /graphql/queries.html
 
         - label: Mutations
           url: /graphql/mutations.html
diff --git a/guides/v2.3/graphql/develop/create-graphqls-file.md b/guides/v2.3/graphql/develop/create-graphqls-file.md
@@ -23,7 +23,7 @@ To illustrate how to configure the `schema.graphqls` file, let's suppose you hav
 
 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 [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.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 [Queries]({{ page.baseurl }}/graphql/queries.html). The parameter definitions will be discussed in [Specify output attributes](#specify-output-attributes).
 
 ``` php
 type Query {
diff --git a/guides/v2.3/graphql/index.md b/guides/v2.3/graphql/index.md
@@ -51,7 +51,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 at [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html).
+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).
 
 
 {:.bs-callout .bs-callout-info}
diff --git a/guides/v2.3/graphql/mutations.md b/guides/v2.3/graphql/mutations.md
@@ -5,6 +5,8 @@ title: Mutations
 
 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`.
 
+## Structure of a mutation
+
 A mutation contains the following elements:
 
 * The keyword `mutation`
@@ -23,7 +25,7 @@ mutation myCreateCustomer{
 }
 ```
 
-In this example, `myCreateCustomer` identifies your implementation.  `CustomerInput` is a non-nullable object that defines a customer. (The exclamation point indicates the value is non-nullable.) `CustomerOutput` defines which fields to return. 
+In this example, `myCreateCustomer` identifies your implementation.  `CustomerInput` is a non-nullable object that defines a customer. (The exclamation point indicates the value is non-nullable.) The `CustomerOutput` object defines which fields to return. 
 
 Now let's take a look at a fully-defined mutation. This time, we'll specify the minimum fields needed as input to create a customer (`firstname`, `lastname`, `email`, and `password`). We could include the same fields in the output, but GraphQL allows you to return only the data you need, which is the customer `id`.
 
@@ -78,7 +80,7 @@ mutation myGenerateCustomerToken{
 
 ## Mutation variables
 
-Specifying variables in a mutation can help increase code re-use. Consider the following steps when creating a mutation that contains one or more variables:
+Specifying variables in a mutation can help increase code re-use. Consider the following requirements when generating a mutation that contains one or more variables:
 
 * All variables must be declared up-front, immediately after the operation name.
 * Variables are typed: they can be scalar or an object.
diff --git a/guides/v2.3/graphql/queries.md b/guides/v2.3/graphql/queries.md
@@ -1,71 +1,205 @@
 ---
 group: graphql
-title: Searches and pagination in GraphQL
+title: Queries
+redirect_from:
+  - /guides/v2.3/graphql/search-pagination.html
 ---
 
-A GraphQL search query can contain the following components:
+A GraphQL query retrieves data from the Magento server in a similar manner as a REST GET call. The current set of Magento GraphQL queries allow a mobile app or browser to render a wide variety of information, including the following:
+
+* A set of products to be displayed. This can include the entire catalog or those that match customer-specified criteria.
+* Customer data. With a customer token, a query can retrieve basic information about a customer as well as billing and shipping addresses, wishlists, order history, and other sensitive data.
+* Shopping cart contents. GraphQL supports both guest and logged-in customer carts.
+* Store configuration values, including theme and CMS settings, the currency code, and supported countries.
+
+The Magento REST GET endpoints retrieve a wide variety of information on behalf of the merchant. Many of these endpoints are for retrieving backend information. For example, the `GET /V1/customers/search` endpoint can be used to find a subset of customers that meet certain criteria, such as those that live in a particular state or have a birthday this month.  Likewise, the `GET /V1/invoices` endpoint can return all the recently-generated invoices. This type of functionality is not required for the frontend, so it is not available in GraphQL queries. The queries are designed to improve the customer's user experience by quickly retrieving the data needed to render pages.
+
+Over time, the Magento GraphQL queries will duplicate the functionality of all storefront-facing GET calls, while making it possible to query more data in one request. The main difference will be that GraphQL will support storefront use cases, while REST will support admin use cases.
+
+## Structure of a query
+
+A query contains the following elements:
+
+* The optional keyword `query`. If no keyword is specified at the beginning of a request, the processor assumes the request is a query.
+* An operation name for your local implementation. This name is required if you include variables. Otherwise, it is optional.
+* The query name
+* The terms to search for. The terms can be in the form of objects, attributes, or a combination. Queries that don't require search terms obtain their context from the customer's authorization token or store ID, both of which are specified in the header of the call.
+* The output object, which specifies which data the query returns.
+
+The following example shows the structure of the `cart` query:
+
+```text
+query myCartQuery{
+  cart(cart_id: String!): Cart
+}
+```
+
+In the preceding example, `myCartQuery` identifies your implementation of the `cart` query.  `cart_id` is a non-nullable string that defines the cart to query. (The exclamation point indicates the value is non-nullable.) The `Cart` output object defines which fields to return.
+
+Now let's fully define a query:
+
+```text
+query myCartQuery{
+  cart(cart_id: "1WxKm8WUm3uFKXLlHXezew5WREfVRPAn") {
+    cart_id
+    items {
+      id
+      qty
+    }
+    billing_address {
+      firstname
+      lastname
+      postcode
+      }
+    shipping_addresses {
+      firstname
+      lastname
+      postcode
+    }
+  }
+}
+```
+
+In this example, we've supplied a cart ID as input, (which was generated by the `createEmptyCart` mutation). The output includes the `cart_id` as well as selected information about the items in the cart and the billing and shipping addresses.
+
+The following example shows the query response:
+
+```json
+{
+  "data": {
+    "cart": {
+      "cart_id": "1WxKm8WUm3uFKXLlHXezew5WREfVRPAn",
+      "items": [
+        {
+          "id": "5",
+          "qty": 1
+        }
+      ],
+      "billing_address": {
+        "firstname": "Veronica",
+        "lastname": "Costello",
+        "postcode": "49628-7978"
+      },
+      "shipping_addresses": [
+        {
+          "firstname": "Veronica",
+          "lastname": "Costello",
+          "postcode": "49628-7978"
+        }
+      ]
+    }
+  }
+}
+```
+
+{:.bs-callout .bs-callout-tip}
+Magento will not run a query that is too complex. The number of fields, objects, and nodes are factors in determining the complexity of a query.
+
+## Query variables
+
+Specifying variables in a query can help increase code re-use. Consider the following requirements when generating a query that contains one or more variables:
+
+* All variables must be declared up-front, immediately after the operation name.
+* Variables are typed: they can be scalar or an object.
+* You must use all declared variables. Object variables are defined in JSON.
+
+The following example declares the `$cart_id` variable. It is referenced in the `input` statement.
+
+```text
+query myCartQueryWithVariable($cart_id: String!) {
+  cart(cart_id: $cart_id) {
+    cart_id
+    items {
+      id
+      qty
+    }
+    billing_address {
+      firstname
+      lastname
+      postcode
+    }
+    shipping_addresses {
+      firstname
+      lastname
+      postcode
+    }
+  }
+}
+```
+
+Variables are defined separately in JSON:
+
+```json
+{
+  "cart_id": "1WxKm8WUm3uFKXLlHXezew5WREfVRPAn"
+}
+```
+
+## Product search queries
+
+A product search query can contain the following components:
 
 * A full text search keyword
 * Filters (search criteria)
 * Pagination information
 * Sorting instructions
 
-## Specifying full text search keywords
+### Specifying full text search keywords
 
 The `search` element causes Magento to perform a full text search on the specified keywords. (This is the same type of search that is performed from the storefront. If multiple keywords are specified, each keyword is evaluated separately.)
 
 The `search` element is optional, but it can be used with or without filters. Each query must contain a `search` or `filter` element.
 
-## Specifying filters
+### Specifying filters
 
 The `filter` element defines which search criteria to use to find the desired results. As with a REST call, each filter defines the field to be searched, the condition type, and the search value.
 
 Search filters are logically ANDed unless an `or` statement is specified. The search query can contain unlimited number of nested `or` clauses. However, you cannot perform a logical `or` across two AND clauses, such as (A AND B) OR (X AND Y).
 
-### Search fields
+#### Search fields
 
 Each object type defines which fields can be searched. See the object-specific documentation for details.
 
 {:.bs-callout .bs-callout-info}
 You cannot specify the same search field twice in a GraphQL query.
 
-### Condition types and search values
+#### Condition types and search values
 
 The following table lists available condition types and provides the SQL statement equivalents.
 
 Magento GraphQL clause | SQL equivalent
 --- | ---
-`eq: "value"`	| <code><i>field</i> = 'value'</code>
+`eq: "value"` | <code><i>field</i> = 'value'</code>
 `neq: "value"` |<code><i>field</i> != 'value'</code>
-`like: "value%"`	| <code><i>field</i> LIKE 'value%'</code>
-`nlike: "value%"`	|<code><i>field</i> NOT LIKE 'value%'</code>
-`in: [1, 2, 3] `	| <code><i>field</i> IN (1, 2, 3)</code>
-`nin: [1, 2, 3]`	| <code><i>field</i> NOT IN (1, 2, 3)</code>
-`notnull: true`	| <code><i>field</i> IS NOT NULL</code>
-`null: true`	| <code><i>field</i> IS NULL</code>
-`lt: "value"`	| <code><i>field</i> < 'value'</code>
-`gt: "value"`	| <code><i>field</i> > 'value'</code>
-`gteq: "value"`	| <code><i>field</i> >= 'value'</code>
-`lteq: "value"`	| <code><i>field</i> <= 'value'</code>
+`like: "value%"` | <code><i>field</i> LIKE 'value%'</code>
+`nlike: "value%"` |<code><i>field</i> NOT LIKE 'value%'</code>
+`in: [1, 2, 3]` | <code><i>field</i> IN (1, 2, 3)</code>
+`nin: [1, 2, 3]` | <code><i>field</i> NOT IN (1, 2, 3)</code>
+`notnull: true` | <code><i>field</i> IS NOT NULL</code>
+`null: true` | <code><i>field</i> IS NULL</code>
+`lt: "value"` | <code><i>field</i> < 'value'</code>
+`gt: "value"` | <code><i>field</i> > 'value'</code>
+`gteq: "value"` | <code><i>field</i> >= 'value'</code>
+`lteq: "value"` | <code><i>field</i> <= 'value'</code>
 `moreq: "value"` | <code><i>field</i> >= 'value'</code>
 `from: "value1"` `to: "value2"` | <code><i>field</i> BETWEEN 'value1' AND 'value2'</code>
-`finset: [1, 2, 3]`	| <code>FINSET(<i>field</i>, '1, 2, 3')</code>
+`finset: [1, 2, 3]` | <code>FINSET(<i>field</i>, '1, 2, 3')</code>
 
 `to` and `from` must always be used together. These condition types can be used in the same search term. For example, `qty: {from: "10" to: "20"}`.
 
 `gt` and `lt` can be used in the same search term. For example, `qty: {gt: "10" lt: "20"}`.
 
-## Specifying pagination
+### Specifying pagination
 
 Magento's GraphQL implementation of pagination uses offsets so that it operates in the same manner as REST and SOAP API requests.
 
-The `pageSize` attribute specifies the maximum number of items to return. If no value is specified, 20 items are returned. 
+The `pageSize` attribute specifies the maximum number of items to return. If no value is specified, 20 items are returned.
 
 The `currentPage` attribute specifies which page of results to return. If no value is specified, the first page is returned. If you specify a value that is greater than the number of available pages, an error is returned.
 
 You can include the `total_pages` attribute in the `page_info` section of the output definition to indicate how many pages were returned for the query.
 
-## Sorting instructions
+### Sorting instructions
 
 The `sort` object allows you to specify which field or fields to use for sorting the results. If you specify more than one field, Magento sorts by the first field listed. Then, if any items have the same value, those items will be sorted by the secondary field.  The value for each field can be set to either `ASC` or `DESC`.
 
@@ -78,11 +212,11 @@ sort: {
 }
 ```
 
-## Example Searches
+### Example Product Searches
 
 The following sections provide examples of each type of search. These examples use the Magento Open Source sample data.
 
-### Full text search
+#### Full text search
 
 The following search returns items that contain the word `yoga` or `pants`. The Catalog Search index contains search terms taken from the product `name`, `description`, `short_description` and related attributes.
 
@@ -116,7 +250,7 @@ The following search returns items that contain the word `yoga` or `pants`. The
 
 The search returns 45 items.
 
-### Full text search with filters
+#### Full text search with filters
 
 The following sample query returns a list of products that meets the following criteria:
 
@@ -212,7 +346,7 @@ The query returns the following:
 }
 ```
 
-### Simple search using a timestamp
+#### Simple search using a timestamp
 
 The following search finds all products that were added after the specified time (midnight, November 1, 2017).
 
@@ -251,7 +385,7 @@ The following search finds all products that were added after the specified time
 }
 ```
 
-### Simple Logical OR search
+#### Simple Logical OR search
 
 The following example searches for all products whose `sku` begins with the string `24-MB` or whose `name` ends with `Bag`.
 
@@ -297,7 +431,7 @@ The following example searches for all products whose `sku` begins with the stri
 
 The query returns 8 items.
 
-### Logical AND and OR search
+#### Logical AND and OR search
 
 This query searches for products that have `name` that ends with `Orange` or has a `sku` that indicates the product is a pair of women’s shorts in size 29 (`WSH%29%`). The system performs a logical AND to restrict the results to those that cost from $40 to $49.99.
 
@@ -343,4 +477,4 @@ This query searches for products that have `name` that ends with `Orange` or has
 }
 ```
 
-The query returns 4 items.
+The query returns 4 items.
diff --git a/guides/v2.3/graphql/reference/products.md b/guides/v2.3/graphql/reference/products.md
@@ -21,11 +21,11 @@ Each query attribute is defined below:
 
 Attribute |  Description
 --- | ---
-`search` | Performs a full-text search using the specified key words. This attribute is optional. See [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) for more information.
+`search` | Performs a full-text search using the specified key words. This attribute is optional. See [Queries]({{ page.baseurl }}/graphql/queries.html) for more information.
 `filter` | Identifies which attributes to search for and return. This attribute is required. See [ProductFilterInput](#ProductFilterInput) for more information.
-`pageSize` | Specifies the maximum number of results to return at once. The default value is 20. See [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) for more information.
-`currentPage` | Specifies which page of results to return. The default value is 1. See [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) for more information.
-`sort` | Specifies which attribute to sort on, and whether to return the results in ascending or descending order. See [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) for more information.
+`pageSize` | Specifies the maximum number of results to return at once. The default value is 20. See [Queries]({{ page.baseurl }}/graphql/queries.html) for more information.
+`currentPage` | Specifies which page of results to return. The default value is 1. See [Queries]({{ page.baseurl }}/graphql/queries.html) for more information.
+`sort` | Specifies which attribute to sort on, and whether to return the results in ascending or descending order. See [Queries]({{ page.baseurl }}/graphql/queries.html) for more information.
 `Products` | An output object that contains the results of the query. See [Response](#Response) for details.
 {:style="table-layout:auto;"}
 
@@ -44,7 +44,7 @@ filter: {
 }
 ```
 
-See [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) for more information about the operators.
+See [Queries]({{ page.baseurl }}/graphql/queries.html) for more information about the operators.
 
 Magento processes the attribute values specified in  a `ProductFilterInput` as  simple data types (strings, integers, booleans). However, returned attributes can be a different, complex, data type. For example, in a response, `price` is an object that contains a monetary value and a currency code.
 
@@ -378,7 +378,7 @@ Field | Type | Description
 
 ## Sample query
 
-You can review several general interest `products` queries at [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html).
+You can review several general interest `products` queries at [Queries]({{ page.baseurl }}/graphql/queries.html).
 
 The following query returns layered navigation for products that have a `sku` containing the string `24-WB`.
 
