New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update documentation with guidance on the use of aggregates and projections with Spring Data #264

Closed

mp911de wants to merge 3 commits into spring-projects:main from mp911de:data-documentation

Member

mp911de commented Jan 19, 2022

Closes gh-248


          Describe aggregates and projections in the data section

6f803e3

mp911de added type: documentation in: data labels

rstoyanchev assigned rstoyanchev and mp911de

rstoyanchev added this to the 1.0.0-M6 milestone

rstoyanchev mentioned this pull request

Improve guidance on use of projections with Querydsl and Query By Example #248

Closed

rstoyanchev changed the title ~~Describe aggregates and projections in the data section~~ Update documentation with guidance on the use of aggregates and projections with Spring Data

jord1e suggested changes

View reviewed changes

Contributor

jord1e left a comment

Found some points that may need to be looked after

Regarding operation instead of query:
https://spec.graphql.org/draft/#sel-FAFRHABAB3Bw0O

There are three types of operations that GraphQL models:

query – [...]
mutation – [...]
subscription – [...]

Query is extra confusing because we are talking about database interactions in this section ("... that translates GraphQL queries into SQL or a JSON query" for example)

spring-graphql-docs/src/docs/asciidoc/index.adoc Outdated

+              Sometimes, an already reduced set of fields can be useful when exposing data. Also, some
+              arrangements might require transformations to be applied before data is returned for a
+              GraphQL query. Spring Data supports for these scenarios projections: Interface and DTO

Contributor

jord1e Jan 20, 2022

Suggested change

      
            GraphQL query. Spring Data supports for these scenarios projections: Interface and DTO
          
            GraphQL operation. Spring Data supports for these scenarios projections: Interface and DTO

spring-graphql-docs/src/docs/asciidoc/index.adoc

+              Projections.
+              Interface projections define a fixed set of properties to expose. Properties may or may
+              not be `null`, depending on the query result. A plain, https://docs.spring.io/spring-data/commons/docs/current/reference/html/#projections.interfaces.closed[closed interface projection]

Contributor

jord1e Jan 20, 2022

Suggested change

      
            not be `null`, depending on the query result. A plain, https://docs.spring.io/spring-data/commons/docs/current/reference/html/#projections.interfaces.closed[closed interface projection]
          
            not be `null`, depending on the operation result. A plain, https://docs.spring.io/spring-data/commons/docs/current/reference/html/#projections.interfaces.closed[closed interface projection]

Member Author

mp911de Jan 21, 2022

query is here the database query.

spring-graphql-docs/src/docs/asciidoc/index.adoc Outdated

Comment on lines 527 to 530

+              DTO projections materialize from a query where the individual projections are
+              determined by the projection itself. DTO projections are commonly used with full-args
+              constructors (e.g. Java Records) and therefore they can be only constructed if all
+              required fields (or columns) are part of the query result.

Contributor

jord1e Jan 20, 2022

Suggested change

      
            DTO projections materialize from a query where the individual projections are
          
            determined by the projection itself. DTO projections are commonly used with full-args
          
            constructors (e.g. Java Records) and therefore they can be only constructed if all
          
            required fields (or columns) are part of the query result.
          
            DTO projections materialize from a GraphQL operation, where the individual projections are
          
            determined by the projection itself. DTO projections are commonly used with full-args
          
            constructors (e.g. Java records) and therefore they can only be constructed if all
          
            required fields (or columns) are part of the operation result.

This paragraph reads a bit confusingly for me, what does it mean exactly?
where the individual projections are determined by the projection itself
required fields (or columns) are part of the operation/query result - should this be the operation's selection set?

Member Author

mp911de Jan 21, 2022

query is here the database query.

individual projections are should be individual properties are

spring-graphql-docs/src/docs/asciidoc/index.adoc Outdated

Comment on lines 499 to 502

+              The advantage of using aggregates is that you do not require additional code to expose
+              data through repositories. When processing a query, the integration layer transforms the
+              query selection into property paths. It provides these hints of which properties to
+              materialize to the underlying Spring Data module that limits the field (or column) selection.

Contributor

jord1e Jan 20, 2022

Suggested change

      
            The advantage of using aggregates is that you do not require additional code to expose
          
            data through repositories. When processing a query, the integration layer transforms the
          
            query selection into property paths. It provides these hints of which properties to
          
            materialize to the underlying Spring Data module that limits the field (or column) selection.
          
            The advantage of using aggregates is that you do not require additional code to expose
          
            data through repositories. When processing a GraphQL operation, the integration layer transforms the
          
            operation's selection set into property paths. It provides these hints of which properties to
          
            materialize to the underlying Spring Data module that limits the field (or column) selection.

spring-graphql-docs/src/docs/asciidoc/index.adoc Outdated

@@ @@ -480,6 +480,57 @@ assertThat(books.get(0).getName()).isEqualTo("..."); @@
               [[data]]
               == Data Integration
+              Spring for GraphQL is, in contrast to other GraphQL technologies that surface persistent
+              data, not a data gateway that translates GraphQL queries into SQL or a JSON query.

Contributor

jord1e Jan 20, 2022

Suggested change

      
            data, not a data gateway that translates GraphQL queries into SQL or a JSON query.
          
            data, not a data gateway that translates GraphQL queries into SQL, or JSON queries.

spring-graphql-docs/src/docs/asciidoc/index.adoc Outdated

Comment on lines 495 to 497

+              With Spring Data you can chose whether you want to let your aggregate participate as
+              underlying data model directly to be exposed as GraphQL result or whether you want to
+              apply projections to your data model before returning it as GraphQL query result.

Contributor

jord1e Jan 20, 2022

Suggested change

      
            With Spring Data you can chose whether you want to let your aggregate participate as
          
            underlying data model directly to be exposed as GraphQL result or whether you want to
          
            apply projections to your data model before returning it as GraphQL query result.
          
            With Spring Data you can choose whether you want to let your aggregate participate as
          
            an underlying data model to be directly exposed as a GraphQL result, or whether you want to
          
            apply projections to your data model before returning it as a GraphQL operation result.

mp911de added 2 commits

January 21, 2022 13:56


          Address review comments

63406e8


          Add code examples for Spring Data projections

a53f3c8

rstoyanchev pushed a commit that referenced this pull request


          Describe aggregates and projections

f34da25

See gh-264

rstoyanchev closed this in

4a031ba

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

in: data type: documentation