GraphQL support (Phase 1)

[lvca]

Discussed in #55

^{Originally posted by lvca September 17, 2021}

SUMMARY

Status: 1st implementation
Progress: Design 50% -> Development & Unit Tests 50% -> Integration Tests 30%
Currently Assigned: @antarcticgiraffe and @lvca
ETA: 10 days

---

I'd love to support GraphQL in ArcadeDB. It looks like most of the people are using graphql to retrieve data as graph in efficient way, so I'd like to start with the support of the following concepts:

GraphQL as a pluggable query engine

Since ArcadeDB already supports multiple query languages (SQL, Gremlin, Cypher and MongoDB), the smoother integration is creating a new Query Language Engine implementation. In this way from Java API, HTTP, Redis, Postgres, etc. will be possible to execute a GraphQL query by specifying the query language.

HTTP API

The /command and /query' existent API can be used by specifying graphql` as query language.

curl -X POST http://localhost:2480/api/v1/command/school
     -d '{ "language": "graphql", "command": "{ human( id: "1000" ) { name height } }"
     -H "Content-Type: application/json"
     --user root:root

Defining the schema for graphs

GraphQL schema doesn't support the edges directly, so you have to specify how a relationship is mapped in ArcadeDB. For example, the vertex type Account has relationships to vertices of type Post through the edge type WRITTEN, direction from Account to Post:

type Account {
    id: String
    firstName: String
    lastName: String
    posts: [Post] @relationship(type: "WRITTEN", direction: OUT)
}

Traversing relationships with the document model

If you're using the document model with links to connect documents, then the GraphQL model is 1-to-1 with the Document model. You don't need to sue the @relationship directive like with graphs.

Queries

This is the most common use case for GraphQL, a query with one or more filters and the declaration of the returning data:

lookup {
  Account(firstName: "Jay") {
    id
    firstName
    lastName
    posts {
      date
      content
     }
   }
}

This example will return records of type "Account" where the firstName is Jay. The returning Account will contain only the properties enlisted between {}. By using lookup you're asking for matching of specific property/values. You can also use a lookup by RecordId (RID), like with the following statement where the article's content is returned for the record with RID #13:55:

lookup {
  Article(@rid: "#13:55") {
    content
  }
}

ArcadeDB will support complex conditions by using where and the SQL statement. Example:

query {
  User(where: "firstName = 'Jay' and lastName = 'Miner'") {
    company {
      name
      employees
    }
  }
}

The query supports also ordering, by using the orderBy and limit properties:

query {
  User(where: "suspended = false", orderBy:"lastName, firstName", limit: 10) {
    id
    firstName
    lastName
  }
}

Mutation

Mutations, such as update and delete operations, will be supported after this initial 1st phase.

[lvca]

Docs: https://docs.arcadedb.com/#GraphQL