README
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
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.