@mavbraba/graphql-ld-querying

GraphQL-LD querying

This package illustrates a practical approach for federated querying linked data sources using GraphQL-LD queries.

This practical approach was originally used in the i-Learn project, but is set available here as a project-agnostic tool.

Installation

Install this npm package globally (to use its command line only)

npm install -g @mavbraba/graphql-ld-querying

or locally as a dependency of your project (to use the Javascript library and optionally also the command line):

cd <your-project-dir>
# if not done earlier, do next line now:
npm init
npm install @mavbraba/graphql-ld-querying

Usage

The tool can be used from the command line (CLI) or as a Javascript library.

The parameters for both methods are common and will be discussed below.

For convenient usage of the example files used below, copy or link the package's example directory to your current working directory.

CLI

Note: the command shown below assumes global installation; for local installation, prepend it with node_modules/.bin/.

Usage is explained by calling the tool with the -h option:

graphql-ld-querying -h
Usage: graphql-ld-querying [options]

Options:
  -v, --version                                output the version number
  -c, --config <configuration>                 configuration (as a JSON string or "@" followed by the name of a JSON file)
  -q, --query <query>                          GraphQL-LD query (query string or "@" followed by the name of a file containing a
                                               query string)
  -p, --parameter-context <parameter-context>  JSON-LD context resolving IRI parameters used in the query (JSON-LD string or "@"
                                               followed by the name of a file containing a JSON-LD string)
  -s, --suppress-context                       Suppress "@context" in the answer
  -l, --logLevel <level>                       logging level (choices: "error", "warn", "info", "verbose", "debug", "silly",
                                               default: "info")
  -h, --help                                   display help for command

An exhaustive command line example:

graphql-ld-querying -c '{
  "dataSources": [
    "examples/1/datasources/ilearn-combined-inferred-v2.ttl"
  ],
  "context": {
    "id": "@id",
    "prefLabel": {"@id": "http://www.w3.org/2004/02/skos/core#prefLabel", "@language": "nl"},
    "member": {"@id": "http://www.w3.org/2004/02/skos/core#member"}
  }
}' -q '{
  id(_:ID) @single
  prefLabel @single
  member @optional {
    id @single
    prefLabel @single
  }
}' -p '{
  "ID": "http://ilearn.ilabt.imec.be/vocab/elem/sleutelcompetenties"
}'

A convenient command line example (with parameters read from file):

graphql-ld-querying -c @examples/1/config.json -q @examples/1/queries/collection_from_id.gql -p @examples/1/paramContexts/collection_from_id.json

Library

(Code valid when placed in this directory):

const {QueryTool} = require('@mavbraba/grapql-ld-querying');

async function main() {
  const config = {
    "dataSources": [
      "examples/1/datasources/ilearn-combined-inferred-v2.ttl"
    ],
    "context": {
      "id": "@id",
      "prefLabel": {"@id": "http://www.w3.org/2004/02/skos/core#prefLabel", "@language": "nl"},
      "member": {"@id": "http://www.w3.org/2004/02/skos/core#member"}
    }
  };
  const query = `
{
  id(_:ID) @single
  prefLabel @single
  member @optional {
    id @single
    prefLabel @single
  }
}`;
  const parameterContext = {
    "ID": "http://ilearn.ilabt.imec.be/vocab/elem/sleutelcompetenties"
  };

  // next instance of the tool may be reused for several queries:
  const queryTool = new QueryTool(config);
  
  // one query:
  const result = await queryTool.queryGraphQlLd(query, parameterContext, false);
  
  console.log(JSON.stringify(result, null, 2));
}

main();

Parameters

config

An object with properties dataSources and context.

dataSources: an array of data sources to be queried. Remote data sources and local files are supported. Local file paths are relative to the working directory.

context: a JSON-LD context.

query

A string according to the syntax for GraphQL-LD queries.

parameterContext

Only required if the query contains one or more elements that are not defined in the context but represent IRIs.

A parameterContext is needed with this query:

{
  id(_:ID) @single
  prefLabel @single
  member @optional {
    id @single
    prefLabel @single
  }
}

because the element in this query (ID) represents an IRI. An accompanying parameterContext resolves this ID. An example value:

{
  "ID": "http://ilearn.ilabt.imec.be/vocab/elem/sleutelcompetenties"
}

suppressContext

If false, the result of a query is a self-contained, complete JSON-LD document of this form:

{
  "@context":
    ...,
  "@graph": [
    ...
  ]
}  

If the caller only needs the "@graph" property, the suppressContext parameter can be set to true. In that case the "@context" property will be omitted from the result.

Examples

The package's examples directory contains example configurations, queries and parameterContexts.

Development

Installation (for development)

• Clone this repository
• cd into the cloned directory
• Install dependencies: npm i
• Build: npm run build

Usage (for development)

See usage above, however:

• execute in the repository root directory
• replace the command with node ./dist/bin/cli.js; nothing to prepend here
• the examples directory is already at the right place: nothing to do here