SPARQL Query Parameter Instantiator

Instantiate SPARQL query templates based on given substitution parameters.

For example, given a SPARQL query template and a CSV file, it can generate multiple instantiations of this template based on the CSV rows.

Template:

SELECT * WHERE { ?s ?p ?o. }

CSV file:

s,p
ex:s1,ex:p1
ex:s2,ex:p2
ex:s3,ex:p3
ex:s4,ex:p4
ex:s5,ex:p5

The resulting queries for the instantiation of ?s for a count of 3:

SELECT * WHERE { <ex:s1> ?p ?o. }

SELECT * WHERE { <ex:s2> ?p ?o. }

SELECT * WHERE { <ex:s3> ?p ?o. }

Queries per template are separated by empty newlines.

Installation

$ npm install -g sparql-query-parameter-instantiator

$ yarn global add sparql-query-parameter-instantiator

Usage

Invoke from the command line

This tool can be used on the command line as sparql-query-parameter-instantiator, which takes as single parameter the path to a config file:

$ sparql-query-parameter-instantiator path/to/config.json

Config file

The config file that should be passed to the command line tool has the following JSON structure:

{
  "@context": "https://linkedsoftwaredependencies.org/bundles/npm/sparql-query-parameter-instantiator/^2.0.0/components/context.jsonld",
  "@id": "urn:sparql-query-parameter-instantiator:default",
  "@type": "QueryInstantiator",
  "count": 5,
  "providers": [
    {
      "@type": "QueryTemplateProvider",
      "templateFilePath": "path/to/template1.sparql",
      "destinationFilePath": "path/to/output.sparql",
      "variables": [
        {
          "@type": "VariableTemplateNamedNode",
          "name": "person",
          "substitutionProvider": {
            "@type": "SubstitutionProviderCsv",
            "csvFilePath": "path/to/params.csv",
            "columnName": "person"
          }
        }
      ]
    }
  ]
}

The important parts in this config file are:

"count": How many times each query template should be instantiated.
"providers" A list of query templates.
"templateFilePath": The path to a SPARQL (text) file.
"destinationFilePath": The path of the text file that will be created with the instantiated queries (seperated by empty lines).
"variables": An array of variables that have to be instantiated.
"*:_substitionProvider": A provider of values for this variable.

Configure

Variable Templates

A variable template indicates a variable in the template query that must be instantiated with certain values.

Named Node Variable Template

A variable template that always produces IRIs.

{
  "variables": [
    {
      "@type": "VariableTemplateNamedNode",
      "name": "person",
      "substitutionProvider": { ... }
    }
  ]
}

Parameters:

"name": The name of the variable in the SPARQL query template to instantiate (without ? prefix).
"substitionProvider": A provider of substitution values.
"valueTransformers": An optional array of value transformers.

Literal Variable Template

A variable template that always produces literals.

{
  "variables": [
    {
      "@type": "VariableTemplateLiteral",
      "name": "person",
      "language": "en-us",
      "datatype": "http://www.w3.org/2001/XMLSchema#number",
      "substitutionProvider": { ... }
    }
  ]
}

Parameters:

"name": The name of the variable in the SPARQL query template to instantiate (without ? prefix).
"language": (Optional) The language for produced literals.
"datatype": (Optional) The datatype for produced literals.
"substitutionProvider": A provider of substitution values.
"valueTransformers": An optional array of value transformers.

Timestamp Variable Template

A template for instantiating RDF xsd:dateTime Literals from a variable value that represents a UNIX timestamp.

{
  "variables": [
    {
      "@type": "VariableTemplateTimestamp",
      "name": "maxDate",
      "substitutionProvider": {
        "@type": "SubstitutionProviderCsv",
        "csvFilePath": "dates.csv",
        "columnName": "maxDate"
      }
    }
  ]
}

Parameters:

"name": The name of the variable in the SPARQL query template to instantiate (without ? prefix).
"datatype": (Optional) The datatype for produced literals. Defaults to xsd:dateTime.
"substitutionProvider": A provider of substitution values.
"valueTransformers": An optional array of value transformers.

List Variable Template

A template for instantiating arrays as RDF Literals concatenated by a given separator. An inner variable template must be passed, which will be invoked for every array value.

{
  "variables": [
    {
      "@type": "VariableTemplateList",
      "name": "tagNames",
      "separator": ", ",
      "substitutionProvider": { ... }
      "innerTemplate": {
        "@type": "VariableTemplateLiteral",
        "name": "tagName"
      }
    }
  ]
}

Parameters:

"name": The name of the variable in the SPARQL query template to instantiate (without ? prefix).
"separator": The separator string.
"innerTemplate": The variable template to apply for each list element.
"substitutionProvider": A provider of substitution values.
"valueTransformers": An optional array of value transformers.

Substitution Providers

Substitution providers supply values for substituting variables in a query template.

CSV Substitution Provider

Provides values from a CSV file.

{
  "substitutionProvider": {
    "@type": "SubstitutionProviderCsv",
    "csvFilePath": "path/to/params.csv",
    "columnName": "person"
  }
}

Parameters:

"csvFilePath": File path to a CSV file.
"columnName": The column name of the CSV file to extract values from.
"separator": (Optional) Column separator.

Static Substitution Provider

Provides values statically by defining them directly in the config file.

{
  "substitutionProvider": {
    "@type": "SubstitutionProviderStatic",
    "values": [
      "value1",
      "value2",
      "value3"
    ]
  }
}

Parameters:

"values": An array of values to provide.

Union Substitution Provider

A substitution provider that takes the union over the values of the given subsitution provider.

{
  "substitutionProvider": {
    "@type": "SubstitutionProviderUnion",
    "substitutionProviders": [
      {
        "@type": "SubstitutionProviderStatic",
        "values": [
          "value1",
          "value2",
          "value3"
        ]
      },
      {
        "@type": "SubstitutionProviderCsv",
        "csvFilePath": "path/to/params.csv",
        "columnName": "person"
      }
    ]
  }
}

Parameters:

"substitutionProviders": The substitution provider to union over.

Shuffle Substitution Provider

A substitution provider that wraps over another substitution provider and shuffles all values based on a seed.

{
  "substitutionProvider": {
    "@type": "SubstitutionProviderShuffle",
    "seed": 12345,
    "substitutionProvider": {
      "@type": "SubstitutionProviderStatic",
      "values": [
        "value1",
        "value2",
        "value3"
      ]
    }
  }
}

Parameters:

"substitutionProvider": The substitution provider to shuffle.
"seed": The random seed for shuffling.

Value Transformers

Value transformers can be attached to variable templates for modifying a value originating from a substitution provider.

Replace IRI Value Transformer

A value transformer that that replaces (parts of) IRIs.

{
  "valueTransformers": [
    {
      "@type": "ValueTransformerReplaceIri",
      "searchRegex": "^http://www.ldbc.eu",
      "replacementString": "http://localhost:3000/www.ldbc.eu"
    }
  ]
}

Options:

"searchRegex": The regex to search for.
"replacementString": The string to replace.

Distribute IRI Value Transformer

A value transformer that that replaces (parts of) IRIs, deterministically distributing the replacements over a list of multiple destination IRI based on a matched number. This is fully compatible with rdf-dataset-fragmenter's QuadTransformerDistributeIri which produces the same deterministic replacements.

{
  "valueTransformers": [
    {
      "@type": "ValueTransformerDistributeIri",
      "searchRegex": "^http://www.ldbc.eu",
      "replacementStrings": [
        "http://localhost:3000/www.ldbc.eu",
        "http://localhost:3030/www.ldbc.eu",
        "http://localhost:3060/www.ldbc.eu"
      ]
    }
  ]
}

This requires at least one group-based replacement, of which the first group must match a number.

The matched number is used to choose one of the replacementStrings in a deterministic way: replacementStrings[number % replacementStrings.length]

{
  "@type": "ValueTransformerDistributeIri",
  "searchRegex": "^http://www.ldbc.eu/data/pers([0-9]*)$",
  "replacementStrings": [
    "https://one.example.com/users$1/profile/card#me",
    "https://two.example.com/users$1/profile/card#me",
    "https://three.example.com/users$1/profile/card#me",
    "https://four.example.com/users$1/profile/card#me"
  ]
}

Options:

"searchRegex": The regex to search for. A group is identified via () in the search regex. There must be at least one group. The first group must match a number.
"replacementStrings": A list of string to use as replacements. A reference to the matched group can be made via $....

Replace IRI Value Transformer

A value transformer that pads strings until a given length.

{
  "valueTransformers": [
    {
      "@type": "ValueTransformerPad",
      "paddingCharacter": "0",
      "paddingLength": "20",
      "start": true
    }
  ]
}

Options:

"paddingCharacter": The character to pad.
"paddingLength": The string length to reach.
"start": If padding should happen at the start of the string, otherwise it will pad from the end.

License

This software is written by Ruben Taelman.

This code is released under the MIT license.