Examples

Here are a number of simple example queries that demonstrate some of the features of HeFQUIN. The queries are organized based on the following categories.

Queries over federations of only RDF-based data sources
Queries over federations that include Web APIs

To run any of these queries, set up the HeFQUIN command-line programs using the latest release and, from the root folder of the extracted release, execute the following command.

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/ExampleQuery1.rq

While the command above is for the first example query, you can simply change the file name of the query file to run any other of the example queries. The given federation description (examples/ExampleFederation.ttl) defines all federation members relevant for the examples.

To get a quick overview of additional arguments that can be passed to the program, execute the following command.

bin/hefquin --help

For a more detailed description of all the arguments refer to the corresponding documentation page.

Queries over Federations of RDF-Based Data Sources

ExampleQuery1

This query demonstrates a join between data from two SPARQL endpoints: the SPARQL endpoint of the DBpedia Knowledge Graph and the SPARQL endpoint of the Wikidata Knowledge Graph. Run the query as follows:

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/ExampleQuery1.rq

Notice that, after deciding the join order and deciding to use the bind-join algorithm, HeFQUIN pushes the FILTER into the request to the DBpedia endpoint. This behavior can be observed by inspecting the physical plan using a command such as the following.

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/ExampleQuery1.rq --printPhysicalPlan --skipExecution

ExampleQuery2

This is essentially the same query as the previous one. The only difference is that, instead of using the SPARQL endpoint of DBpedia, this one uses the TPF server of DBpedia. As a consequence, the query plan will be different because the two triple patterns of the first SERVICE clause cannot be sent as a single request to the TPF server, and also the FILTER needs to be locally now (i.e., by HeFQUIN itself). Run the query (without plan printing) as follows:

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/ExampleQuery2.rq

ExampleQuery3

This is also essentially the same as the previous two queries. The difference now is that this one uses VALUES clauses to specify the federation members. Run the query as follows:

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/ExampleQuery3.rq

Notice that, while there are two separate VALUES clauses in the query, it is also possible to merge them into one VALUE clause:
VALUES (?s1 ?s2) { (<http://dbpedia.org/sparql> <https://query.wikidata.org/sparql>) }

In the query plans for this query (both the logical and the physical plan), you can see that the service IRIs from the VALUES clause(s) become an explicit argument of the corresponding operators (request operators and gpAdd operators). Hence, if there are multiple values for a service variable, HeFQUIN creates separate subplans with dedicated operators for all mentioned federation members, which makes it possible to optimize these subplans differently.

Queries over Federations with Web APIs

OpenMeteoFixed

This query accesses the Web API of the Open-Meteo weather service, with a fixed request URI (requesting the current temperature and wind speed at a fixed location). The graph pattern within the SERVICE clause is evaluated over an RDF view of the JSON data obtained from the API; this RDF view is defined by the RML mapping given in the federation description. Run the query as follows:

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/OpenMeteoFixed.rq

OpenMeteoBind

Like the previous query, this one also retrieves current weather information from the Web API of the Open-Meteo weather service. However, in contrast to using a fixed request URI as done by the previous query, this one creates the request URI at runtime, based on the values provided by the BIND clauses. Run the query as follows:

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/OpenMeteoBind.rq

OpenMeteoJoin

This query accesses the Web API of the Open-Meteo weather service by using requests that are formed based on data obtained from a SPARQL endpoint. More specifically, the query obtains the geographic coordinates of Berlin from the SPARQL endpoint of the DBpedia Knowledge Graph and, then, uses these coordinates to request the current temperature and wind speed in Berlin from the Web API. Hence, the query joins data from the SPARQL endpoint with data from the API. Run the query as follows:

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/OpenMeteoJoin.rq

OpenMeteoCDTMap

This query is similar to the previous one (obtaining weather information from the Web API of the Open-Meteo service, for a location whose geographic coordinates are obtained from DBpedia) but it also demonstrates that the RML processor of HeFQUIN creates cdt:Map literals for cases in which the object map of an RML triples map refers to a JSON object (rather than to scalars value within a JSON object). The BIND clauses at the end of the query apply functions that have been defined for cdt:Map literals. Run the query as follows:

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/OpenMeteoCDTMap.rq

OpenMeteoCDTList

While also similar to the previous queries, this one demonstrates that the RML processor of HeFQUIN creates cdt:List literals for cases in which the object map of an RML triples map refers to a JSON array (rather than to the elements of such an array). Notice that the requested weather information in this case is not the current one but an hourly forecast, because the JSON data with hourly forecasts from the Open-Meteo API does indeed contain arrays. The BIND clauses at the end of the query apply functions that have been defined for cdt:List literals. Run the query as follows:

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/OpenMeteoCDTList.rq

Covid19Stats

This query accesses the Web API of the Open Disease Data service by using requests that are formed based on data obtained from a SPARQL endpoint. More specifically, the query obtains the ISO country codes of all European countries from the SPARQL endpoint of the Wikidata Knowledge Graph and, then, uses these ISO codes to request Covid-19 statistics from the Web API. Run the query as follows:

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/Covid19Stats.rq

Notice that one of the ISO codes obtained from Wikidata is "XK" for Kosovo, which is not recognized by the Web API; that is, the request with this ISO code results in a 404 error. Therefore, the SERVICE clause for the Web API ignores the solution mapping with this ISO code. This behavior can be observed by inspecting the detailed statistics about the query execution process, which is printed when running the query using the following command. In particular, the part of the printed statistics to look at are the entries called numberOfRequestsFailed and errorCodesOfFailedRequests for the corresponding operator of type ExecOpLookupJoinViaWrapperWithParamVars.

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/Covid19Stats.rq --printQueryProcStats

OpenLibraryAPI

This query accesses the Web API of the Open Library Website by using requests that are formed based on data obtained from a SPARQL endpoint. More specifically, the query obtains the names of winners of the Nobel Prize in Literature from the SPARQL endpoint of the DBpedia Knowledge Graph and, then, uses these names to request information about books authored by these winners from the Web API. Run the query as follows:

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/OpenLibraryAPI.rq

CurrencyViaAPIs

This query joins data from two Web APIs. It first obtains data about Japan from the Web API of the REST Countries service, including the currency code of the Japanese currency. Thereafter, the query also obtains the current Euro exchange rate for that currency from the Exchange Rate API. Run the query as follows:

bin/hefquin --federationDescription examples/ExampleFederation.ttl --query examples/CurrencyViaAPIs.rq