eliasdb/graphql.md

EliasDB GraphQL

EliasDB supports GraphQL to search nodes in a partition of the graph database. A simple GraphQL query has the following structure:

{
  <node kind> : {
    <attr1>
    <attr2>
    <attr3>
  }
}

It reads: "Get all graph nodes of a certain node kind and fetch attr1, attr2 and attr3 of every node".

Filtering results

It is possible to reduce the number of resulting nodes by defining a condition using the matches argument.

The simplest case is to retrieve a node with a specific value:

query {
  Person(matches: {
    name : "John"
  }) {
    name
  }
}

Multiple values can be matched by specifying a list:

query {
  Person(matches: {
    name : ["John", "Frank"]
  }) {
    name
  }
}

For more complex cases it is also possible to use a Regex. For example to get all Person nodes where the name starts with the letters Jo you could write:

query {
  Person(matches: {
    name : "^Jo.*"
  }) {
    name
  }
}

The condition can be inverted by prefixing with not_. To get all Person nodes where the name does NOT start with Jo:

query {
  Person(matches: {
    not_name : "^Jo.*"
  }) {
    name
  }
}

To retrieve a specific node with a known key it is possible to do a direct lookup by key:

query {
  Person(key: "john") {
    name
  }
}

Sorting and limiting

To manage potentially large results and avoid overwhelming a client with data it is possible to sort and limit the result.

To sort a result in ascending or descending order use the arguments ascending or descending with the ordering attribute. Ordering is only possible for attributes which are part of the query. To order all Person nodes in ascending name write:

query {
  Person(ascending: "name") {
    name
  }
}

To limit the result to the last n entries use the argument last. To limit the result to a range use from to define the start position (default is 0) and items to define how many entries should be returned:

query {
  Person(ascending: "name", last:10) {
    name
  }
}

Traversal

To traverse the graph you can add the traverse argument on a field of the selection set. For example to get the friends of a Person write:

query {
  Person(ascending: "name") {
    name
    friends(traverse: ":Friend::Person") {
      name
    }
  }
}

If the traversal route does not matter (e.g. a traversal wildcard would be used above :::Person) then a shortcut is available:

query {
  Person(ascending: "name") {
    name
    friends: Person {
      name
    }
  }
}

Fragments

Fragments allow repeated selections to be defined once and be reused via a label:

{
  Station(ascending:key) {
    ...stationFields
    Station(ascending:key) {
      ...stationFields
    }
  }
}
fragment stationFields on Station {
  key
  name
  zone
}

Fragments can also be used as type conditions to query different attributes dependent on the encountered node kind:

{
  Station(ascending:key) {
    ...stationFields
    StationAndLines(traverse: ":::", ascending:key) {
      ...stationFields
      ... on Line {
        key
        name
      }
    }
  }
}
fragment stationFields on Station {
  key
  name
  zone
}

The example above shows a combination of a separate fragment definition and an inline fragment.

Data modification

If the endpoint support mutation of data then you can store and remove nodes and edges. Node and edge storage (create or update) requires all attributes to be specified (nodes and edges are overwritten):

mutation {
  Person(storeNode: {
      key: "hans"
      name: "Hans"
    }) {
    name
    friends(traverse: ":Friend::Person") {
      name
    }
  }
}

Possible arguments are storeNode, storeEdge, removeNode and removeEdge. The operation allows retrieval of nodes as well (i.e. the single operation will insert AND retrieve data). Removal of edges requires only the key and kind to be specified. Removal of nodes requires only the kind to be specified. Using removeNodes with a missing key will remove all nodes of the kind.

Variables

To avoid parsing issues and possible security risks it is advisable to always use variables to pass data to EliasDB especially if it is a user-provided value. EliasDB supports all GraphQL default types: string, integer, float

mutation($name: string) {
    Person(storeNode: {
        key: "hans"
        name: $name
    }) {
        key
        name
    }
}

The type name (in the example string) is not evaluated in EliasDB's GraphQL interpreter. The values should be send in a separate variables datastructure:

{
  name: "Hans"
}

Variables can be used in combination with fragments and the directives @skip and @include to modify queries:

query Stations($expandedInfo: boolean=true){
  Station(ascending:key) {
    ...stationFields
    Station(ascending:key) {
      ...stationFields
      ... on Station @include(if: $expandedInfo) {
        zone
      }
    }
  }
}
fragment stationFields on Station {
  key
  name
}

Subscription to updates

EliasDB's implementation of GraphQL supports also subscriptions which involve using Websockets for bidirectional communication. See the examples for further details (in code). A subscription is basically a normal query for example:

subscription {
  Person(ascending: "name") {
    name
  }
}

which receives continuous from the server as the underlying data changes.