[docs] information about execution and how to return partial data (#542)

* [docs] information about execution and how to return partial data

* review comments

Author: dariuszkuc

docs/execution/contextual-data.md

@@ -15,7 +15,8 @@ build context per query execution through
 [GraphQLContextFactory](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/GraphQLContextFactory.kt).
 Once context factory bean is available in the Spring application context it will then be used in a corresponding
 [ContextWebFilter](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/ContextWebFilter.kt)
-to populate GraphQL context based on the incoming request and make it available during query execution.
+to populate GraphQL context based on the incoming request and make it available during query execution. See [graphql-kotlin-spring-server documentation](../spring-server/spring-graphql-context)
+for additional details
 
 Once your application is configured to build your custom `MyGraphQLContext`, simply add `@GraphQLContext` annotation to
 any function argument and the corresponding GraphQL context from the environment will be automatically injected during

docs/execution/data-fetching-environment.md

@@ -1,29 +1,31 @@
----
-id: data-fetching-environment 
-title: Data Fetching Environment
----
-Each resolver has a `DataFetchingEnvironment` that can be accessed from graphql-java:
-https://www.graphql-java.com/documentation/v13/data-fetching/
-
-You can access this info by including the `DataFetchingEnvironment` as one of the arguments to a Kotlin function. This
-argument will not be included in the schema.
-
-```kotlin
-class Query {
-    fun printEnvironmentInfo(environment: DataFetchingEnvironment, value: Int): String {
-        // Access env data
-    }
-}
-```
-
-This will produce the following schema
-
-```graphql
-type Query {
-  printEnvironmentInfo(value: Int!): String!
-}
-```
-
-You can also use this to retrieve arguments and query information from higher up the query chain. You can see a working
-example in the `graphql-kotlin-spring-example` module
-[link](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/query/EnvironmentQuery.kt)].
+---
+id: data-fetching-environment
+title: Data Fetching Environment
+---
+Each resolver has access to a `DataFetchingEnvironment` that provides additional information about the currently executed query including information about what data is requested
+as well as details about current execution state. For more details on the `DataFetchingEnvironment` please refer to [graphql-java documentation](https://www.graphql-java.com/documentation/v13/data-fetching/)
+
+You can access this info by including the `DataFetchingEnvironment` as one of the arguments to a Kotlin function. This argument will be automatically populated and injected
+during the query execution but will not be included in the schema definition.
+
+```kotlin
+class Query {
+    fun printEnvironmentInfo(environment: DataFetchingEnvironment): String {
+        // access env data
+    }
+}
+```
+
+This will produce the following schema
+
+```graphql
+type Query {
+  printEnvironmentInfo: String!
+}
+```
+
+You can also use this to retrieve arguments and query information from higher up the query chain. You can see a working
+example in the `graphql-kotlin-spring-example` module
+[[link](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/query/EnvironmentQuery.kt)].
+
+

docs/execution/exceptions.md

@@ -0,0 +1,27 @@
+---
+id: exceptions
+title: Exceptions and Partial Data
+---
+
+Exceptions thrown during execution of a query will result in a GraphQLError that is added to a list of errors of the result. See
+[graphql-java documentation](https://www.graphql-java.com/documentation/v13/execution/) for more details on how to customize your exception handling.
+
+### Partial Data
+
+GraphQL allows you to return both data and errors in a single response. Depending on the criticality of the encountered error you may want to return
+partial data together with the corresponding errors. In Kotlin, functions return only a single value, which means that in order to return both data
+and errors you have to explicitly return them wrapped in a `DataFetcherResult` object.
+
+```kotlin
+class DataAndErrorsQuery {
+  fun returnDataAndErrors(): DataFetcherResult<String> {
+    // some logic here to populate data and capture error
+    return DataFetcherResult.newResult<String>()
+      .data(myData)
+      .error(myError)
+      .build()
+  }
+}
+```
+
+An example of a query returning partial data is available in our [spring example app](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/query/DataAndErrorsQuery.kt).

docs/execution/fetching-data.md

@@ -0,0 +1,56 @@
+---
+id: fetching-data
+title: Fetching Data
+---
+
+Each field exposed through a GraphQL query has a corresponding resolver (aka data fetcher) associated with it. `graphql-kotlin-schema-generator` generates GraphQL schema
+directly from the source code automatically mapping all the fields either to use
+[FunctionDataFetcher](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/execution/FunctionDataFetcher.kt)
+to resolve underlying functions or a [PropertyDataFetcher](https://www.graphql-java.com/documentation/v13/data-fetching/) to read a value from an underlying Kotlin property.
+
+While all the fields in a GraphQL query are resolved independently to produce a final result, whether field is backed by a function or a property can have significant
+performance repercussions. For example, given the following schema:
+
+```graphql
+type Query {
+  product(id: Int!): Product
+}
+
+type Product {
+  id: Int!
+  name: String!
+  reviews: [Review!]!
+}
+
+type Review {
+  id: Int!
+  text: String!
+}
+```
+
+We can define `Product` as
+
+```kotlin
+data class Product(val id: Int, val name: String, reviews: List<Review>)
+```
+
+or
+
+```kotlin
+class Product(val id: Int, val name: String) {
+  suspend fun reviews(): List<Reviews> {
+     // logic to fetch reviews here
+  }
+}
+```
+
+If we expose the `reviews` field as a property it will always be populated regardless whether or not your client actually asks for it. On the other hand if `reviews` is backed
+by a function, it will only be called if your client asks for this data. In order to minimize the over-fetching of data from your underlying data sources we recommend to
+expose all your GraphQL fields that require some additional computations through functions.
+
+### Customizing Default Behavior
+
+You can provide your own custom data fetchers to resolve functions and properties by providing an instance of
+[KotlinDataFetcherFactoryProvider](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/execution/KotlinDataFetcherFactoryProvider.kt#L31)
+to your [SchemaGeneratorConfig](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/SchemaGeneratorConfig.kt).
+See our [spring example app](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/spring) for an example of `CustomDataFetcherFactoryProvider`.

docs/execution/subscriptions.md

@@ -34,4 +34,6 @@ validation of subscriptions the same as queries and mutations.
 
 ### Server Implementation
 
-The server that runs your GraphQL schema will have to support some method for subscriptions, like WebSockets. `graphql-kotlin-spring-server` provides default WebSocket based implementation. See more details in the [server documentation](../server/subscriptions)
+The server that runs your GraphQL schema will have to support some method for subscriptions, like WebSockets.
+`graphql-kotlin-spring-server` provides a default WebSocket based implementation. See more details in the
+[server documentation](../spring-server/subscriptions).

docs/writing-schemas/scalars.md

@@ -27,7 +27,7 @@ extended scalar types provided by `graphql-java`.
 GraphQL supports a the scalar type ID, a unique identifier that is not intended to be human readable. ID's are
 serialized as a String. To mark given field as an ID field you have to annotate it with `@GraphQLID` annotation.
 
-> NOTE: `graphql-java` supports other types (`String`, `Int`, `Long`, or `UUID`) but [due to serialization issues](https://github.com/ExpediaGroup/graphql-kotlin/issues/317) we can only directly support Strings. You can still use a type like UUID internally just as long as you convert or parse the value yourself and handle the errors.
+> NOTE: `graphql-java` supports additional types (`String`, `Int`, `Long`, or `UUID`) but [due to serialization issues](https://github.com/ExpediaGroup/graphql-kotlin/issues/317) we can only directly support Strings. You can still use a type like UUID internally just as long as you convert or parse the value yourself and handle the errors.
 
 ```kotlin
 data class Person(

…/graphql/examples/query/DataAndErrors.kt …hql/examples/query/DataAndErrorsQuery.ktexamples/spring/src/main/kotlin/com/expediagroup/graphql/examples/query/DataAndErrors.kt renamed to examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/query/DataAndErrorsQuery.kt examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/query/DataAndErrors.kt renamed to examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/query/DataAndErrorsQuery.kt

@@ -25,7 +25,7 @@ import org.springframework.stereotype.Component
 import java.util.concurrent.CompletableFuture
 
 @Component
-class DataAndErrors : Query {
+class DataAndErrorsQuery : Query {
 
     fun returnDataAndErrors(): DataFetcherResult<String> {
         val error = SimpleKotlinGraphQLError(RuntimeException(), listOf(SourceLocation(1, 1)), ExecutionPath.rootPath().toList())

website/sidebars.json

@@ -37,9 +37,11 @@
         "type": "subcategory",
         "label": "Execution",
         "ids": [
+          "execution/fetching-data",
+          "execution/async-models",
+          "execution/exceptions",
           "execution/data-fetching-environment",
           "execution/contextual-data",
-          "execution/async-models",
           "execution/subscriptions"
         ]
       }