Idea: an Apollo GraphQL Connector for TypeDB

[davux]

TL;DR: I have a strong intuition that GraphQL and TypeDB would fit greatly together.

What is GraphQL?

GraphQL is an HTTP request pattern that is pretty interesting, albeit younger and less common than REST. It solves several shortcomings of REST by offering a more expressive and flexible request format. In fact, I think GraphQL maps more naturally to TypeDB concepts than REST. The fact that TypeQL was previously called Graql back in Grakn days is also worth a few seconds' thoughts. :)

Anyways. A backend server that provides a GraphQL API, just like a backend server that provides a REST API, stands between HTTP clients (i.e., frontend apps) and the persistence database, with resolution logic that maps HTTP requests into database requests, among other things.

Apollo Server, resolvers and connectors

One widespread implementation of a GraphQL server is Apollo Server, part of Apollo. Apollo Server is lightweight and quite flexible, allowing for any logic for read and write operations to the database. Such logic is written in components that Apollo calls "resolvers".

Due to the similarity between GraphQL and TypeDB concepts, I think it would be useful for developers to come up with a boilerplate implementation of resolvers that naturally translates the one into the other, while obviously allowing developers to override the default logic with their own as needed.

It also looks like Apollo offers a higher-level tool called "connectors", which I'm not quite familiar with, but it looks like it could be useful.

What can we do next?

@flyingsilverfin started to think about how nicely GraphQL could be used in front of a TypeDB model.

I think that having such a tool would make life much easier for web developers who wish to use TypeDB as their persistence layer, hence helping with adoption. I'm curious to know what ideas the community has about that and how we can expand on that idea.

[flyingsilverfin]

AI's suggestion:

GraphQL to TypeQL 3.0 Adapter Design
This document outlines the design for an adapter that translates GraphQL queries and mutations into TypeQL 3.0 queries. The design focuses on generality and common GraphQL patterns.

1. Core Principles
   The adapter acts as a middleware between a GraphQL client and a TypeDB database. It receives GraphQL requests, translates them into TypeQL, executes them against TypeDB, and then formats the TypeDB response back into a GraphQL response.
2. Schema Mapping
   The foundation of the adapter is a clear and consistent mapping between the GraphQL Schema Definition Language (SDL) and the TypeQL conceptual schema.
   2.1. GraphQL type to TypeQL entity
   Each GraphQL type is mapped to a TypeQL entity.
   GraphQL Schema:

type User {
  id: ID!
  name: String!
  email: String
}

TypeQL Schema:

define
  entity user,
    owns id @key,
    owns name,
    owns email;
  attribute id, value string;
  attribute name, value string;
  attribute email, value string;

2.2. GraphQL Fields with Object Types to TypeQL relation
Relationships between GraphQL types are modeled as TypeQL relation types. A convention is needed for naming relations and roles. A good convention is (owner-type, field-name, related-type).
GraphQL Schema:

type User {
  id: ID!
  posts: [Post!]
}

type Post {
  id: ID!
  title: String!
  author: User!
}

TypeQL Schema:

define
  entity user,
    owns id @key,
    plays user-posts:author,
    plays post-author:author;

  entity post,
    owns id @key,
    owns title,
    plays user-posts:post,
    plays post-author:post;

  relation user-posts,
    relates author,
    relates post;

  relation post-author,
    relates post,
    relates author;

  attribute id, value string;
  attribute title, value string;

Note: The dual relation definitions (user-posts and post-author) represent the bidirectional nature of the GraphQL relationship. The adapter can be configured to use a single relation if the relationship is always queried from one direction.

2.3. GraphQL enum to TypeQL attribute
GraphQL enum types are mapped to string attributes in TypeQL. The adapter will be responsible for validating the enum values during insertion and update.
GraphQL Schema:

enum UserRole {
  ADMIN
  EDITOR
  VIEWER
}

type User {
  id: ID!
  role: UserRole!
}

TypeQL Schema:

define
  entity user,
    owns id @key,
    owns role;

  attribute id, value string;
  attribute role, value string @values("ADMIN", "EDITOR", "VIEWER");

2.4. GraphQL interface and union
Interface and Union types can be translated by applying corresponding ownerships and relations one by one

GraphQL Schema:

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String!
}

type Post implements Node {
  id: ID!
  title: String!
}

TypeQL Schema:

define
  entity node @abstract,
    owns id @key;

  entity user,
    owns id @key, # from Node interface
    owns name;

  entity post,
    owns id @key, # from Node interface
    owns title;

  attribute id, value string;
  attribute name, value string;
  attribute title, value string;

3. Read Path: GraphQL Query to TypeQL fetch
   3.1. Basic Query
   A simple GraphQL query for an object by its ID is translated to a match and fetch query in TypeQL.
   GraphQL Query:

query GetUser {
  user(id: "user-123") {
    id
    name
    email
  }
}

Generated TypeQL Query:

match
  $u isa user, has id "user-123";
fetch
  "id": $u.id,
  "name": $u.name,
  "email": $u.email
};

3.2. Nested Query (Relationships)
Nested GraphQL queries are translated into nested fetch queries or more complex match patterns.
GraphQL Query:

query GetUserWithPosts {
  user(id: "user-123") {
    name
    posts {
      title
    }
  }
}

Generated TypeQL Query:

match
  $u isa user, has id "user-123";
fetch {
  "name": $u.name,
  "posts: [
    match user-posts ($u, $p);
    fetch { "title": $p.title };
  ]
};

3.3. Query with Arguments
Arguments in GraphQL fields are translated into conditions in the match clause.
GraphQL Query:

query GetUsersByName {
  users(name: "John Doe") {
    id
    email
  }
}

Generated TypeQL Query:

match
  $u isa user, has name "John Doe";
fetch {
  "id": $u.id,
  "email": $u.email
};

4. Write Path: GraphQL Mutation to TypeQL insert/delete
   4.1. Create Mutation
   A create mutation is translated to a TypeQL insert query.
   GraphQL Mutation:

mutation CreateUser {
  createUser(input: {
    id: "user-456",
    name: "Jane Doe",
    email: "jane.doe@example.com"
  }) {
    id
    name
  }
}

Generated TypeQL Query:

insert
  $u isa user,
    has id "user-456",
    has name "Jane Doe",
    has email "jane.doe@example.com";

The adapter would then perform a fetch query to return the newly created user as requested by the mutation's selection set.
4.2. Update Mutation
Updating in TypeQL is a delete of the old attribute followed by an insert of the new one. The adapter must handle this as a single transaction.
GraphQL Mutation:

mutation UpdateUserEmail {
  updateUser(id: "user-456", input: {
    email: "new.email@example.com"
  }) {
    id
    email
  }
}

Generated TypeQL Query (in a single transaction):

match
  $u isa user, has id "user-456", has email $old_email;
delete
  has $old_email of $u;
insert
  $u has email "new.email@example.com";

4.3. Delete Mutation
A delete mutation is translated to a match and delete query. This should also delete related relations.
GraphQL Mutation:

mutation DeleteUser {
  deleteUser(id: "user-456") {
    id
  }
}

Generated TypeQL Query:

match
  $u isa user, has id "user-456";
  $r links ($u, $x);
delete
  $u;
  $r;

5. Conclusion
   This design provides a solid foundation for a GraphQL to TypeQL 3.0 adapter. The key challenges are in establishing robust conventions for schema mapping and in handling the translation of complex nested queries and updates. The adapter would significantly simplify the development of applications that use a GraphQL frontend with a TypeDB backend, leveraging the strengths of both technologies.