Overview

This guide describes an approach that allows graph developers to maintain their own databases while also allowing users to query data from any subset or all of those databases at once without having to know which database actually stores the data. This is an alternative to writing federated queries using the SERVICE function in queries, which requires users to know which triples to query from each remote database.

This approach maps one or more named graphs or contexts from a remote Stardog database as a virtual graph that can be queried by the local Stardog database. Then, using named graph aliases and/or setting a default query context in the local database, users can write SPARQL queries against a query scope that could include any combination of local and virtualized data (including data residing in a remote Stardog database). 

The examples below will demonstrate how to create a new virtual graph to query data that lives in another Stardog database. In both examples, we'll create a virtual graph that connects to a Stardog SPARQL endpoint, with the first example using the CLI and the second using the HTTP API (useful if you don’t have CLI access).

Example 1: Stardog SPARQL Endpoint

In this example, we will connect to the local database enterprise_kg and query data virtualized from the default context in a remote Stardog database called virtualized_db on the same Stardog endpoint.

Step 1

Create and name a properties file to create a virtual graph. In this example, we will name it self_as_vg.properties since Stardog is creating a virtual graph from a connection to itself.

sparql.url=http://localhost:5820/virtualized_db/query
sparql.username=admin
sparql.password=admin
sparql.graphname=tag:stardog:api:context:default
sparql.statsbasedoptimization=true

Note: The port must be specified in the sparql.url or it will default to 5820.

Step 2

Add the virtual graph via CLI.

stardog-admin virtual add --database enterprise_kg self_as_vg.properties

At this point, you should be able to select that virtual graph and query it while connected to the enterprise_kg database. However, if you want to make it easy to query from several virtual graphs (or virtualized databases) at once, you can proceed with the next steps to create a named graph alias.

Step 3

Enable graph.aliases in the database properties for the database you'll query from. Then create a graph alias to refer to the query scope you want, including any named graphs, contexts, or virtual graphs.

INSERT DATA {
        GRAPH <tag:stardog:api:graph:aliases> {
                <urn:stardog_vgs> <tag:stardog:api:graph:alias> <virtual://self_as_vg>, <virtual://express_music_as_vg> , stardog:context:local .
        }
}

select *
from <urn:stardog_vgs>
{
    ?s ?p ?o
}

POST https://localhost:5820/admin/data_sources
Authorization: Basic <credentials>
Content-Type: application/json

{
  "name": "exp_as_vg",
  "options": {
    "sparql.url": "https://express.stardog.cloud:5820/kit-music/query",
    "sparql.username": "anonymous",
    "sparql.password": "anonymous",
    "sparql.graphname": "urn:stardog:marketplace:tutorials:music:1.0"
  }
}

POST https://localhost:5820/admin/virtual_graphs
Authorization: Basic <credentials>
Content-Type: application/json

{
  "name": "exp_music_as_vg",
  "data_source": "exp_as_vg",
  "db": "enterprise_kg",
  "mappings": "",
  "options": {
    "sparql.url": "https://express.stardog.cloud:5820/kit-music/query",
    "sparql.username": "anonymous",
    "sparql.password": "anonymous",
    "sparql.graphname": "urn:stardog:marketplace:tutorials:music:1.0",
    "sparql.statsbasedoptimization": true
  }
}

POST https://solutions-demo.stardog.cloud:5820/enterprise_kg/query
Authorization: Basic <credentials>
Content-Type: application/sparql-query

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
SELECT *
FROM <virtual://exp_music_as_vg>
{
  ?s ?p ?o
}
LIMIT 10

For more information on virtual graphs, please see the docs.