Customize schema generation for Neo4j annotations

[claymccoy]

I'd like to use the Kotlin Schema Generator to generate my GraphQL schema from Kotlin classes. I have existing classes that persist to Neo4j using the Neo4j OGM annotations:

@NodeEntity
data class Artifact(
        val groupId: String,
        val artifactId: String,
        val version: String,
        @Relationship(type = "IN_REPO", direction = Relationship.OUTGOING) val repo: ArtifactoryRepo?,
        @Relationship(type = "DEPENDS_ON", direction = Relationship.OUTGOING) val dependencies: Set<Artifact>,
        @Relationship(type = "DEPENDS_ON", direction = Relationship.INCOMING) val consumers: Set<Artifact>
) {
    @Id val id: String = "$groupId:$artifactId:$version"
    val name: String = "$artifactId:$version"
}

My GraphQL schema will look almost the same:

type Artifact {
            id: ID!
            name: String!
            groupId: String!
            artifactId: String!
            version: String!
            repo: ArtifactoryRepo @relation(name:"IN_REPO", direction:OUT)
            dependencies: [Artifact] @relation(name:"DEPENDS_ON", direction:OUT)
            consumers: [Artifact] @relation(name:"DEPENDS_ON", direction:IN)
        }

So I want to modify the generation to use the Neo4j annotations. For example:

@Relationship(type = "DEPENDS_ON", direction = Relationship.OUTGOING)
becomes
@relation(name:"DEPENDS_ON", direction:OUT)

@Id val id: String becomes id: ID!

I read through the docs, but didn't see what I was looking for. What is the best way to do this type of customization with your library? Thanks!

[smyrick]

@claymccoy First off thank you for checking out the library, it is interesting to see the many different ways people are using GraphQL

My first recommendation would be to not actually expose your database objects as part of your API. I know it may seem that GraphQL is a perfect match for graph databases, but GraphQL is just poorly named. It is neither graph based, nor does it provide a fully feature query language like SQL. It is just another way for you to expose your API contract to your clients. If you wanted to build this API in REST would you expose the same exact objects as your DB? For most people APIs exists to add abstractions on your raw domain objects so you are free to change them later and not have clients tied directly to your data implementations.

That being said, I know there are some useful ways of just exposing your DB schema in an API that has a schema itself (GraphQL, gRPC). This should be possible using the custom hooks when you are adding a type or field.

graphql-kotlin/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/hooks/SchemaGeneratorHooks.kt

Lines 64 to 68 in 1804e6a

	/**
	* Called after using reflection to generate the graphql object type but before returning it to the schema builder.
	* This allows for modifying the type info, like description or directives
	*/
	fun willAddGraphQLTypeToSchema(type: KType, generatedType: GraphQLType): GraphQLType = generatedType

Here you can inspect the KType and determine if the class has any extra annotations on it that are not @GraphQLDirective annotations and add those as new directives on the GraphQLType

[smyrick]

Actually taking a second look what would really help here is a new hook for specifically generating a new GraphQLOutputType like willAddGraphQLOutputTypeToSchema or maybe we should just be calling willAddGraphQLTypeToSchema when we add properties or functions to the schema. They are called on the field type, but not on the field itself

[smyrick]

I think this still could be resolved with the existing hook onRewireGraphQLType

graphql-kotlin/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/hooks/SchemaGeneratorHooks.kt

Lines 120 to 125 in 1804e6a

	/**
	* Called after `willGenerateGraphQLType` and before `didGenerateGraphQLType`.
	* Enables you to change the wiring, e.g. apply directives to alter the target type.
	*/
	fun onRewireGraphQLType(generatedType: GraphQLSchemaElement, coordinates: FieldCoordinates? = null, codeRegistry: GraphQLCodeRegistry.Builder? = null): GraphQLSchemaElement =
	wiringFactory.onWire(generatedType, coordinates, codeRegistry)

[claymccoy]

I appreciate the advice on separating the db and api abstractions, and normally I would agree. But this is a bit different. Since Neo 4j is a graph database it matches up much better than something like a SQL database would. Graphql is a tree which is a type of graph. So they actually match up perfectly. It is true that you might still want an abstraction in the middle so that you could change the db without affecting the API, but I actually want them to be the same. I basically want to use graphql to query neo rather than cypher. I do all the abstracting I need to do with how I ingest the data into neo4j, not when I read it out.

Check it out, there is a Neo4j extension that lets you query it with GraphQL instead of Cypher.
https://github.com/neo4j-graphql/neo4j-graphql

My app basically does the same thing as that extension. Querying Neo using GraphQL. Unfortunately, that extension is EOL, but they broke out the part that converts a GraphQL query to Cypher into a library.
https://github.com/neo4j-graphql/neo4j-graphql-java

Your library makes a perfect companion to neo4j-graphql-java because your it allows me to generate the schema and have the neo4j model be the source of truth.

graphql-kotlin: Neo4j model -> GraphQL Schema
neo4j-graphql-java: Cypher -> Neo4j

I'm surprised these two projects aren't used together in apps. But they aren't. Unfortunately, neo4j-graphql-java has an outdated version of graphql-java and it doesn't play well with your library.

I spent today trying to fix that rather than making use of SchemaGeneratorHooks.
neo4j-graphql/neo4j-graphql-java#118

But I'm hoping to dive into that next.

[claymccoy]

I got this working using onRewireGraphQLType(). I use reflection on the data class myself and construct directives from the annotations on the class. Let me know if you see improvements with the way I am using your library. I'm pretty sure I am not using enum types as intended, but it works! :)

import com.expediagroup.graphql.hooks.SchemaGeneratorHooks
import graphql.Scalars
import graphql.schema.*
import org.neo4j.ogm.annotation.Id
import org.neo4j.ogm.annotation.Relationship
import java.lang.IllegalArgumentException
import kotlin.reflect.KClass

class CypherSchemaGeneratorHooks(model: Collection<KClass<*>>) : SchemaGeneratorHooks {

    val modelClassesByName = model.associateBy { it.simpleName }

    val directionOut = GraphQLEnumType.newEnum()
            .name("OUT")
            .value("OUT")
            .build()

    val directionIn = GraphQLEnumType.newEnum()
            .name("IN")
            .value("IN")
            .build()

    val directionBoth = GraphQLEnumType.newEnum()
            .name("BOTH")
            .value("BOTH")
            .build()

    override fun onRewireGraphQLType(generatedType: GraphQLSchemaElement, coordinates: FieldCoordinates?, codeRegistry: GraphQLCodeRegistry.Builder?): GraphQLSchemaElement {
        val rewiredType = super.onRewireGraphQLType(generatedType, coordinates, codeRegistry)
        if (rewiredType is GraphQLFieldDefinition) {
            val typeBuilder = GraphQLFieldDefinition.newFieldDefinition(rewiredType)
            val field = coordinates?.let { fieldCoordinates ->
                modelClassesByName[fieldCoordinates.typeName]?.let { klass ->
                    klass.java.declaredFields.find { it.name == fieldCoordinates.fieldName }
                }
            }
            field?.let {
                field.getAnnotation(Relationship::class.java)?.let {
                    typeBuilder.withDirective(constructRelationDirective(it))
                }
                field.getAnnotation(Id::class.java)?.let {
                    var idType: GraphQLOutputType = Scalars.GraphQLID
                    if (rewiredType.type is GraphQLNonNull) {
                        idType = GraphQLNonNull.nonNull(idType)
                    }
                    typeBuilder.type(idType)
                }
            }
            return typeBuilder.build()
        }
        return rewiredType
    }

    private fun constructRelationDirective(relationship: Relationship) : GraphQLDirective {
        val direction = when (relationship.direction) {
            Relationship.OUTGOING -> directionOut
            Relationship.INCOMING -> directionIn
            Relationship.UNDIRECTED -> directionBoth
            else -> throw IllegalArgumentException("Invalid relationship direction: ${relationship.direction}")
        }
        return GraphQLDirective.newDirective()
                .name("relation")
                .argument(GraphQLArgument.newArgument()
                        .type(Scalars.GraphQLString)
                        .name("name")
                        .value(relationship.type))
                .argument(GraphQLArgument.newArgument()
                        .type(direction)
                        .name("direction")
                        .value(direction.name))
                .build()
    }

}

This is a unit tests the demonstrates what I am trying to do. I am turning my neo4j data classes into a GraphQL schema with the neo4j directives.

import dev.minutest.junit.JUnit5Minutests
import dev.minutest.rootContext
import org.neo4j.ogm.annotation.Id
import org.neo4j.ogm.annotation.NodeEntity
import org.neo4j.ogm.annotation.Relationship
import strikt.api.expectThat
import strikt.assertions.isEqualTo

class SchemaGeneratorTest : JUnit5Minutests {

    val generator = SchemaGenerator()

    @NodeEntity
    data class TestArtifact(
            val groupId: String,
            val artifactId: String,
            val version: String,
            @Relationship(type = "IN_REPO", direction = Relationship.OUTGOING) val repo: TestRepo?,
            @Relationship(type = "DEPENDS_ON", direction = Relationship.OUTGOING) val dependencies: List<TestArtifact>,
            @Relationship(type = "DEPENDS_ON", direction = Relationship.INCOMING) val consumers: List<TestArtifact>
    ) {
        @Id
        val id: String = "$groupId:$artifactId:$version"
        val name: String = "$artifactId:$version"
    }

    @NodeEntity
    data class TestRepo(
            val name: String,
            @Id val url: String,
            @Relationship(type = "IN_REPO", direction = Relationship.INCOMING) val artifacts: List<TestArtifact>?
    )

    fun tests() = rootContext {
        test("convertClassesToSchema") {
            val generatedSchema = generator.generateSchema(setOf(
                    TestArtifact::class,
                    TestRepo::class
            ))
            expectThat(generatedSchema).isEqualTo("""
            type TestArtifact {
              artifactId: String!
              consumers: [TestArtifact!]! @relation(direction : IN, name : "DEPENDS_ON")
              dependencies: [TestArtifact!]! @relation(direction : OUT, name : "DEPENDS_ON")
              groupId: String!
              id: ID!
              name: String!
              repo: TestRepo @relation(direction : OUT, name : "IN_REPO")
              version: String!
            }

            type TestRepo {
              artifacts: [TestArtifact!] @relation(direction : IN, name : "IN_REPO")
              name: String!
              url: ID!
            }
            """.trimIndent())
        }
    }
}