Skip to content

SPARQL Select query¤

The SPARQL SELECT plugin is a task for executing SPARQL SELECT queries on an RDF data source. It can be used in a workflow, connecting an input to an output. A SPARQL 1.1 SELECT query is supported; the simplest example is SELECT * WHERE { ?s ?p ?o }.

Input and output¤

The input depends on the configuration:

  • By default, the query is executed against the connected input, which must be a SPARQL endpoint (i.e. an RDF dataset).
  • When Use fallback RDF dataset (useDefaultDataset) is enabled, the query is executed against the fallback RDF dataset (as configured in dataset.defaultRdf) instead. The input port then depends on what the template references:
    • If the template references input entity properties (input.entity.*), the task accepts an entity input and generates one query per input entity.
    • If it references only parameters of the input task (input.config.*), an input connection is still required — it supplies the parameter values — but the query is rendered and executed only once.
    • If it references neither, the task has no input port.

The output is an entity table built from the query’s SPARQL results: each projected variable becomes a column, and each result binding becomes a row.

The result size can be capped with the limit parameter, and a query timeout (in milliseconds) can be set via sparqlTimeout.

Automatic FROM clause injection¤

If the SPARQL source is defined on a specific graph, a FROM clause will be added to the query at execution time, except when there already exists a GRAPH or FROM clause in the query. FROM NAMED clauses are not injected.

Templating¤

The select query is rendered by a template engine before execution. Jinja is the default and is described below; for the deprecated Simple and Velocity Engine modes, see “Legacy template engines” at the end.

Jinja uses {{ ... }} for value expressions and {% ... %} for control flow such as conditionals.

Template variables¤

The following variables are available:

  • input.config.<param>: a parameter of the task connected to the input port. <param> is a parameter id of that task’s plugin, e.g. graph on a SPARQL dataset.
  • output.config.<param>: a parameter of the task the output is connected to.
  • input.entity.<property>: the value(s) of the given property of the current input entity. Only available with Use fallback RDF dataset enabled, since only then the task receives input entities (see Input and output above).
  • project.<key>: a project-scoped template variable.
  • global.<key>: a global template variable.

A single-valued entity property is inserted as a plain string. A multi-valued property can be iterated with {% for value in input.entity.<property> %}; inserting it directly concatenates all values without a separator. Referencing a variable that is not available at execution time — an unknown parameter name or an entity property without a value — fails the query generation with an error.

Parameter, property and variable names must be valid Jinja identifiers ([a-zA-Z_][a-zA-Z0-9_]*); bracket-subscript access such as input.entity["urn:prop:label"] is not supported.

For example, to query the named graph that is configured on the input dataset:

SELECT * WHERE { GRAPH <{{ input.config.graph | validate_uri }}> { ?s ?p ?o } }

Default scope¤

The defaultScope parameter declares one scope whose variables are additionally exposed at the top level of the template context, so they can be referenced without the scope prefix. It defaults to input.entity, which means a template may write {{ property }} as a shorthand for {{ input.entity.property }}:

{{ property }}   ≡   {{ input.entity.property }}

Both forms resolve to the same value. Set defaultScope to the empty string to disable this aliasing and require every variable to be addressed with its full scope.

Filters¤

Values are inserted verbatim by default, so URI brackets (<...>) and quotation marks around literals must be written in the template. The following filters are provided to render values safely:

  • validate_uri: validates that the value is a valid absolute IRI and returns it unchanged. Throws a validation error otherwise. Wrap the output in <...> in the template.
  • escape_literal: escapes backslashes, quotes, newlines, carriage returns and tabs so the value can be used inside a short-form SPARQL string literal ("..." or '...'). No enclosing quotes are added.
  • escape_multiline_literal: escapes backslashes and breaks any run of three or more consecutive single or double quotes. Use for values that are wrapped in triple-quoted SPARQL literals ("""...""" or '''...''').

All transformer plugins are also available as Jinja filters under their plugin id (for example lowerCase, trim, urlEncode).

Input schema inference¤

The input schema (the entity properties the task expects) is derived by scanning the raw template for input.entity.<property> references (or bare references resolved via defaultScope). This scan operates on the template text before rendering, so SPARQL line comments (# ...) are not stripped: a commented-out line such as

# {{ input.entity.property }}

will still cause property to appear in the inferred input schema.

Output schema inference¤

The output schema is derived from the raw template by a heuristic, without rendering it. The heuristic takes the projection between SELECT and the first WHERE, FROM or {, drops a leading DISTINCT / REDUCED, and then:

  • For SELECT *, collects every distinct ?var token in the query.
  • Otherwise, collects each top-level ?var and the trailing AS ?alias from parenthesised expressions (e.g. (COUNT(?s) AS ?count) yields count).

Each variable becomes a string-typed path. If no variables can be detected (e.g. the projection is produced by a Jinja expression), the output port is reported with an unknown schema.

Validation¤

At task creation, the Jinja template is checked against the available template variables:

  • Every project.<...> or global.<...> reference must resolve to a known variable, matched on the full scoped name (so e.g. project.metaData.label is looked up at that exact scope).
  • Every input.<...> or output.<...> reference must use config or entity as its second segment.

Bare references are resolved through defaultScope before applying the same rules. The template is not rendered and the resulting SPARQL is not parsed.

Legacy template engines¤

In addition to Jinja, two deprecated template engines are supported for backwards compatibility: Simple and Velocity Engine. Their syntax is identical to the one used by the SPARQL Update operator and is documented there.

Parameter¤

Select query¤

A SPARQL 1.1 select query. The query supports Jinja templating. Parameters of the connected input and output tasks can be accessed via ‘input.config.’ and ‘output.config.‘. Project and global template variables are available as ‘project.’ and ‘global.‘. Example: SELECT * WHERE { GRAPH <{{ input.config.graph }}> { ?s ?p ?o } }

  • ID: selectQuery
  • Datatype: code-sparql
  • Default Value: None

Result limit¤

If set to a positive integer, the number of results is limited. The limit is applied per query: if one query is generated per input entity, it caps the results of each query, not the combined total.

  • ID: limit
  • Datatype: string
  • Default Value: None

Optional SPARQL dataset¤

An optional SPARQL dataset that can be used for example data, so e.g. the transformation editor shows mapping examples.

  • ID: optionalInputDataset
  • Datatype: SPARQL endpoint
  • Default Value: None

Use fallback RDF dataset¤

If enabled, the query executes against the configured fallback RDF dataset (as configured in dataset.defaultRdf) when no RDF dataset is connected. If the query template references input entities, one query is generated per input entity.

  • ID: useDefaultDataset
  • Datatype: boolean
  • Default Value: false

Templating mode¤

The templating mode for the template engine.

  • ID: templatingMode
  • Datatype: string
  • Default Value: jinja

Default scope¤

Variables from this scope can be accessed without the scope prefix in Jinja. For example, with default scope ‘input.entity’, a template may reference ‘{{ property }}’ instead of ‘{{ input.entity.property }}’. Leave empty to disable.

  • ID: defaultScope
  • Datatype: string
  • Default Value: input.entity

Advanced Parameter¤

SPARQL query timeout (ms)¤

SPARQL query timeout (select/update) in milliseconds. A value of zero means that there is no timeout set explicitly. If a value greater zero is specified this overwrites possible default timeouts.

  • ID: sparqlTimeout
  • Datatype: int
  • Default Value: 0
  • sparqlEndpoint — This plugin executes a SELECT query against a SPARQL endpoint; a SPARQL endpoint dataset in the workflow provides that endpoint. The SPARQL Update query plugin uses the same kind of dataset as a write target rather than a read source.
  • sparqlUpdateOperator — The SPARQL Update query plugin turns entity input into update statements that modify a SPARQL store; this plugin reads from the same kind of store by executing a SELECT query and returning the results as an entity table.

Comments