SPARQL profiles¶

A profile is one SPARQL endpoint that SHMARQL talks to, with a name and some settings. Profiles are listed in a YAML file, named by PROFILES_PATH (default profiles.yaml). A site can have as many profiles as it likes: the query editor, entity viewer and story editor let you switch between them.

The Wikidata profile, line by line¶

This is config/profiles.yaml from this documentation:

default: wikidata                 # (1)

profiles:
  - name: wikidata                # (2)
    title: Wikidata               # (3)
    description: The Wikidata Query Service (WDQS)
    endpoint: https://query.wikidata.org/sparql   # (4)
    headers:                      # (5)
      User-Agent: "my-shmarql-site/1.0 (https://example.org/; webmaster@example.org)"
    timeout: 60                   # (6)
    uri_prefixes:                 # (7)
      - http://www.wikidata.org/entity/
    display:                      # (8)
      construct_query: "CONSTRUCT { {subject_uris} ?p ?o . } WHERE { {subject_uris} ?p ?o . }"
      show_inverse_relations: false
      fallback_languages: [mul, en]
    sparnatural: sparnatural/wikidata.ttl   # (9)
    graph_explorer:               # (10)
      defaultDirection: outgoing
      defaultDepth: 1
      maxNodes: 60
      maxEdgesPerNode: 25
      includeLiterals: false
      includeBlankNodes: false

1. default — the profile served at /sparql and used when nothing else is chosen. Give its name, its key or its endpoint address. Without it, the first profile is the default.
2. name — a short id. Data stories refer to profiles by name (kg="wikidata"), and so does the story editor. Pick it once and keep it.
3. title and description — what people see in the profile choosers.
4. endpoint — the SPARQL endpoint address. Required. It is never shown to browsers. Two profiles can't have the same address.
5. headers — extra HTTP headers sent with every request, for example a User-Agent (which Wikimedia requires) or an Authorization header for a protected endpoint.
6. timeout — seconds to wait for this endpoint (default: SPARQL_TIMEOUT).
7. uri_prefixes — IRIs starting with one of these open in this profile in the entity viewer.
8. display — entity viewer settings for this profile.
9. sparnatural — a Sparnatural configuration file (SHACL, in Turtle), relative to the profiles file. It switches on the Visual Query Builder in the story editor's SPARQL nodes. See below.
10. graph_explorer — defaults for Graph Explorer nodes in the story editor.

Other options:

• allow_update: true lets SPARQL Update requests through /sparql/<key>. The default is false: updates get 403 Forbidden.

Keys¶

Each profile gets a key: the first 12 hex characters of the SHA-256 hash of its endpoint address (Wikidata's is 479c34c9a197). Keys are used in addresses, and they don't reveal the upstream endpoint:

The key changes only when the endpoint address changes. List the keys with uv run shmarql profiles or GET /api/profiles.

Several profiles¶

Add more entries under profiles:. A site with Wikidata and DBpedia:

default: wikidata
profiles:
  - name: wikidata
    title: Wikidata
    endpoint: https://query.wikidata.org/sparql
    headers: {User-Agent: "my-shmarql-site/1.0 (me@example.org)"}
    uri_prefixes: [http://www.wikidata.org/entity/]
    display:
      construct_query: "CONSTRUCT { {subject_uris} ?p ?o . } WHERE { {subject_uris} ?p ?o . }"
      show_inverse_relations: false

  - name: dbpedia
    title: DBpedia
    endpoint: https://dbpedia.org/sparql
    uri_prefixes: [http://dbpedia.org/resource/]
    display:
      namespaces:
        dbo: http://dbpedia.org/ontology/
        dbr: http://dbpedia.org/resource/

Now /entity?uri=http://dbpedia.org/resource/Rembrandt opens in DBpedia and Wikidata IRIs open in Wikidata, without a profile= parameter.

The quick way: ENDPOINT¶

The ENDPOINT setting names an endpoint address:

ENDPOINT=https://query.wikidata.org/sparql uv run shmarql

• If a profile with that address exists, it becomes the default, overriding default: in the YAML.
• If there are no profiles at all (no file, or an empty profiles: list), a profile for that address is created and made the default.

That's handy for trying things out. Use a profiles file once you need names, headers or settings.

Entity viewer settings (display)¶

display: can be set for one profile, or globally at the top of the file (next to default:) for all profiles. The settings are those of ldview, in lower case. The most useful ones:

Story editor settings¶

Graph Explorer defaults¶

graph_explorer: sets the defaults of new Graph Explorer nodes, using LODEON's names:

The Visual Query Builder configuration¶

The sparnatural: file describes, in SHACL, which classes and properties the Visual Query Builder offers. The example config/sparnatural/wikidata.ttl offers Painting, Painter, Museum or collection and Country, with properties such as painted by, in the collection of, made in (year) and has the title.

Wikidata doesn't use rdf:type, so each class says how to recognise its members with an sh:target:

this:Painting a sh:NodeShape ;
  rdfs:label "Painting"@en ;
  sh:target [
    a sh:SPARQLTarget ;
    sh:select """PREFIX wd: <http://www.wikidata.org/entity/>
PREFIX wdt: <http://www.wikidata.org/prop/direct/>
SELECT $this WHERE { $this wdt:P31 wd:Q3305213 . }"""
  ] ;
  sh:property this:Painting_creator .

this:Painting_creator
  sh:path wdt:P170 ;
  sh:name "painted by"@en ;
  sh:node this:Painter ;
  dash:searchWidget core:NonSelectableProperty .

The builder writes ?Painting_1 rdf:type this:Painting while you click. When you use the query, that line is replaced by the body of the sh:select, so the query that runs uses wdt:P31. Learn more about Sparnatural configurations at https://docs.sparnatural.eu/.

The configuration is served to the editor at /api/knowledge-graphs/<name>/sparnatural.