sparql-query-parameter-instantiator
v2.6.0
Published
Instantiate SPARQL query templates based on given substitution parameters
Downloads
462
Maintainers
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/^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 toxsd: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.