sparql-query-parameter-instantiator
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    SPARQL Query Parameter Instantiator

    Build Status Coverage Status npm version

    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

    or

    $ 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/^1.0.0/components/context.jsonld",
      "@id": "urn:sparql-query-parameter-instantiator:default",
      "@type": "QueryInstantiator",
      "QueryInstantiator:_count": 5,
      "QueryInstantiator:_providers": [
        {
          "@type": "QueryTemplateProvider",
          "QueryTemplateProvider:_templateFilePath": "path/to/template1.sparql",
          "QueryTemplateProvider:_destinationFilePath": "path/to/output.sparql",
          "QueryTemplateProvider:_variables": [
            {
              "@type": "VariableTemplateNamedNode",
              "VariableTemplateNamedNode:_name": "person",
              "VariableTemplateNamedNode:_substitutionProvider": {
                "@type": "SubstitutionProviderCsv",
                "SubstitutionProviderCsv:_csvFilePath": "path/to/params.csv",
                "SubstitutionProviderCsv:_columnName": "person"
              }
            }
          ]
        }
      ]
    }
    

    The important parts in this config file are:

    • "QueryInstantiator:_count": How many times each query template should be instantiated.
    • "QueryInstantiator:_providers" A list of query templates.
    • "QueryTemplateProvider:_templateFilePath": The path to a SPARQL (text) file.
    • "QueryTemplateProvider:_destinationFilePath": The path of the text file that will be created with the instantiated queries (seperated by empty lines).
    • "QueryTemplateProvider:_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.

    {
      "QueryTemplateProvider:_variables": [
        {
          "@type": "VariableTemplateNamedNode",
          "VariableTemplateNamedNode:_name": "person",
          "VariableTemplateNamedNode:_substitutionProvider": { ... }
        }
      ]
    }

    Parameters:

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

    Literal Variable Template

    A variable template that always produces literals.

    {
      "QueryTemplateProvider:_variables": [
        {
          "@type": "VariableTemplateLiteral",
          "VariableTemplateLiteral:_name": "person",
          "VariableTemplateLiteral:_language": "en-us",
          "VariableTemplateLiteral:_datatype": "http://www.w3.org/2001/XMLSchema#number",
          "VariableTemplateLiteral:_substitutionProvider": { ... }
        }
      ]
    }

    Parameters:

    • "VariableTemplateLiteral:_name": The name of the variable in the SPARQL query template to instantiate (without ? prefix).
    • "VariableTemplateLiteral:_language": (Optional) The language for produced literals.
    • "VariableTemplateLiteral:_datatype": (Optional) The datatype for produced literals.
    • "VariableTemplateLiteral:_substitutionProvider": A provider of substitution values.
    • "VariableTemplateLiteral:_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.

    {
      "VariableTemplateNamedNode:_substitutionProvider": {
        "@type": "SubstitutionProviderCsv",
        "SubstitutionProviderCsv:_csvFilePath": "path/to/params.csv",
        "SubstitutionProviderCsv:_columnName": "person"
      }
    }

    Parameters:

    • "SubstitutionProviderCsv:_csvFilePath": File path to a CSV file.
    • "SubstitutionProviderCsv:_columnName": The column name of the CSV file to extract values from.
    • "SubstitutionProviderCsv:_separator": (Optional) Column separator.

    Static Substitution Provider

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

    {
      "VariableTemplateNamedNode:_substitutionProvider": {
        "@type": "SubstitutionProviderStatic",
        "SubstitutionProviderStatic:_values": [
          "value1",
          "value2",
          "value3"
        ]
      }
    }

    Parameters:

    • "SubstitutionProviderStatic:_values": An array of values to provide.

    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.

    {
      "VariableTemplateNamedNode:_valueTransformers": [
        {
          "@type": "ValueTransformerReplaceIri",
          "ValueTransformerReplaceIri:_searchRegex": "^http://www.ldbc.eu",
          "ValueTransformerReplaceIri:_replacementString": "http://localhost:3000/www.ldbc.eu"
        }
      ]
    }

    Options:

    • "ValueTransformerReplaceIri:_searchRegex": The regex to search for.
    • "ValueTransformerReplaceIri:_replacementString": The string to replace.

    License

    This software is written by Ruben Taelman.

    This code is released under the MIT license.

    Install

    npm i sparql-query-parameter-instantiator

    DownloadsWeekly Downloads

    19

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    56.5 kB

    Total Files

    47

    Last publish

    Collaborators

    • avatar