Flexo GraphQL

SonarCloud

Requirements

• Deno
• (optional) https://velociraptor.run/ (script runner for Deno projects)

Running the GraphQL server

Using docker

Build or fetch the image:

docker build -t flexo-graphql .
## OR ##
docker pull openmbee/flexo-graphql

Run the container. Mount a directory to /data where the app can find context.json and schema.graphql:

For example, if the host cwd looks like:

.
├── README.md
├── res
│   ├── context.json
│   ├── schema.graphql

Then the docker command to run a container mounting the /res directory might look like this:

docker run -it --rm -v $(pwd)/res:/data -e 'SPARQL_ENDPOINT=http://localhost:7200/repositories/${org}-${repo}' graphql

Without docker

Install

vr install

Configure the SPARQL endpoint

Define a SPARQL_ENDPOINT environment variable that binds a pattern for the URL. The server will make the following substitutions in the pattern:

• ${org} -- replaced with the target orgId the user is querying
• ${repo} -- replaced with the target repoId the user is querying
• ${branch} -- replaced with the target branchId the user is querying

For example:

# notice the use of single quotes to prevent shell substitution of ${..}
SPARQL_ENDPOINT='http://localhost:7200/repositories/${org}-${repo}'

With this configuratino, a request to https://graphql-server/orgs/mms/repos/test/branches/master would forward a SPARQL request to http://localhost:7200/repositories/mms-test.

Run the server

Usage: vr serve [OPTIONS]

Options:
  -c, --context PATH  [required] path to JSON-LD context file
  -s, --schema PATH   [required] path to GraphQL schema file
  -p, --port VALUE    [optional] port number to bind server

Example

vr serve -c context.json -s schema.graphql

By default, the server attempts to bind to port 3001.

The GraphQL endpoint will be available (via POST requests) at: /orgs/${org}/repos/${repo}/branches/${branch}/graphql

Additionally, a GraphiQL interface is exposed at: /orgs/${org}/repos/${repo}/branches/${branch}/

Documentation

The endpoint provides schema introspection to help clients validate their queries.

`@filter`` directive

Can be used to apply a filter on scalar values:

{
  item {
    # select items where the `name` property is exactly "Batman"
    name @filter(is: "Batman")
  }
}

The sole named argument provided to the @filter directive should be one of the following:

Keyword	Argument type	Comments
is	String	exact match
not	String	not exact match
in	[String]	value appears in list
notIn	[String]	value not in list
contains	String	value contains substring
notContains	String	(negated)
startsWith	String	value starts with string
notStartsWith	String	(negated)
endsWith	String	value ends with string
notEndsWith	String	(negated)
regex	String	regular expression match
notRegex	String	(negated)
equals	Float	numeric equals
notEquals	Float	(negated)
lessThan	Float	numeric less than
notLessThan	Float	(negated)
greaterThan	Float	numeric greater than
notGreaterThan	Float	(negated)
lessThanOrEqualTo	Float	...
notLessThanOrEqualTo	Float	(negated)
greaterThanOrEqualTo	Float	...
notGreaterThanOrEqualTo	Float	(negated)

@many directive

Tells the service where to collate results:

{
  pickLists {
    # Picklist:PickListOptions is a 1:many relation
    options: _inv_pickList @many {
      ...on PickListOption {
        name
      }
    }
  }
}

@paginate directive

Only allowed at the query level, limits the number of rows returned by the SPARQL query so that large results can be paginated. Keep in mind, this only makes sense for queries that do not contain any uses of the @many directive.

query Example @paginate(limit: 200, offset: 100) {
  # ...
}

Inverse predicates

Properties that are prefixed by _inv_ signify an incoming relationship from another object:

{
  user {
    # select a user by their email
    email @filter(is: "jdoe@ex.org")

    # find items that were "createdBy" this user
    item: _inv_createdBy {
      name  # the item's name
    }
  }
}

Wildcard predicates

The special _any property can be used to select any predicate (including ones not defined in the schema):

{
  item {
    # `_any` is a wildcard, assign it the alias "version" in the results
    version: _any {
      # specify the intended type (i.e. a Version instance) using an inline fragment
      ...on Version {
        id  # the version's id
      }
    }
  }
}

Contributing

Development tools/dependencies are managed using yarn and package.json.

To set up the development environment:

yarn install

Checking for updates to the development dependencies:

yarn dev-update-check

Applying updates to the development dependencies:

yarn dev-upgrade