Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sparna-git/Sparnatural
Sparnatural : Typescript visual SPARQL query builder for knowledge graphs
https://github.com/sparna-git/Sparnatural
knowledge-graph linked-data owl rdf sparql typescript yasgui
Last synced: 4 months ago
JSON representation
Sparnatural : Typescript visual SPARQL query builder for knowledge graphs
- Host: GitHub
- URL: https://github.com/sparna-git/Sparnatural
- Owner: sparna-git
- License: lgpl-3.0
- Created: 2018-08-31T10:48:44.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-04-13T20:13:37.000Z (8 months ago)
- Last Synced: 2024-04-14T10:50:43.893Z (8 months ago)
- Topics: knowledge-graph, linked-data, owl, rdf, sparql, typescript, yasgui
- Language: JavaScript
- Homepage: http://sparnatural.eu
- Size: 45.1 MB
- Stars: 194
- Watchers: 12
- Forks: 34
- Open Issues: 82
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Sparnatural SPARQL query builder
Sparnatural is a **visual client-side SPARQL query builder** for exploring and navigating RDF Knowledge Graphs. It is written in Typescript.
It supports the creation of basic graph patterns with the selection of values with autocomplete search or dropdown lists, or other widgets. It can be configured through an OWL or SHACL configuration file that defines the classes and properties to be presented in the component.
You can play with **online demos at http://sparnatural.eu#demos**.
# Getting Started
To get started :
1. Read the following README;
2. Have a look at the [online DBPedia demo](https://sparnatural.eu/demos/demo-dbpedia-v2/)
3. Read [the documentation](https://docs.sparnatural.eu):
- follow the [_Hello sparnatural tutorial_](https://docs.sparnatural.eu/hello-sparnatural/Hello-Sparnatural.html) to setup your environment
- follow the [_SHACL configuration guide_](https://docs.sparnatural.eu/how-to-configure-shacl/How-to-configure-Sparnatural-shacl.html) to understand how the configuration can be expressed in SHACL
- have a look at the [_technical integration documentation_](https://docs.sparnatural.eu/Javascript-integration.html) to understand how to integrate the webcomponent in your webpage
# Features
## Query Structure
### Basic query pattern
Select the type of entity to search...
... then select the type of the related entity.
In this case there is only one possible type of relation that can connect the 2 entities, so it gets selected automatically. Then select a value for the related entity, in this case in a dropdown list :
Congratulations, your first SPARQL query criteria is complete !
Now you can fetch the generated SPARQL query :
### "WHERE"
This enables to navigate the graph :
### "AND"
Combine criterias :
### "OR"
Select multiple values for a criteria :
(UNIONs are not supported)
## Values selection
Sparnatural offers currently 9 ways of selecting a value for a criteria :
- dropdown list widget
- autocomplete search field
- tree browsing widget
- map selection widget
- string search widget, searched as regex or as exact string
- date range widget (year or date precision)
- numeric values widget
- boolean widget
- no value selection (useful for 'intermediate' entities)
### Dropdown list widget
### Autocomplete search widget
### Tree browsing widget
### Map selection widget
### String search widget (text search)
### Date range widget (year or date precision)
### Numeric values widget
### Boolean widget
### No value selection
This is useful when a type a of entity is used only to navigate the graph, but without the ability to select an instance of these entities.
## Multilingual
Sparnatural is multilingual and supports displaying labels of classes and properties in multiple languages.
## Support for OPTIONAL and FILTER NOT EXISTS
Sparnatural supports the `OPTIONAL` and `FILTER NOT EXISTS {}` keywords applied to a whole "branch" of the query.
See here how to search for French Museums and the name of Italian painters they display, _if any_ :
## Support for SERVICE keyword
There is currently an [experimental support for the SERVICE keyword](http://docs.sparnatural.eu/Federated-querying.html) for federated querying.
## Support for Aggregation queries
Since version 9.0.0, Sparnatural supports `COUNT` queries and other aggregation functions.
## Limitations
### No UNION or BIND
Sparnatural does not support the creation of UNION, BIND
### SPARQL endpoint needs to be CORS-enabled
To send SPARQL queries to a service that is not hosted on the same domain name as the web page in which Sparnatural is included, the SPARQL endpoint needs to allow [Cross-Origin Resource Sharing (CORS)](https://enable-cors.org/). But we have a [SPARQL proxy](http://docs.sparnatural.eu/SPARQL-proxy.html) for those who are not, don't worry ;-)
# Integration in a webpage
1. Look at the [hello-sparnatural folder](https://github.com/sparna-git/Sparnatural/tree/master/hello-sparnatural) that demonstrates a simple integration
2. Read [this page in the documentation](https://docs.sparnatural.eu/Javascript-integration).
3. Look at a [typical demo page on DBPedia](https://github.com/sparna-git/sparnatural.eu/tree/main/demos/demo-dbpedia-v2)
# Configuration
## Specification of classes and properties
Since 9.0.0, the preferred way to configure Sparnatural is with a **SHACL specification**. Look at the [supported SHACL features in the documentation](http://docs.sparnatural.eu/SHACL-based-configuration.html).
The component is also configurable using a an [OWL configuration file](https://docs.sparnatural.eu/OWL-based-configuration) editable in Protégé. Look at the specification files of [the demos](https://github.com/sparna-git/sparnatural.eu/tree/main/demos) to get an idea.
### SHACL-based config
To give you an idea, here is an annotated SHACL-based configuration snippet below. The [SHACL configuration guide](https://docs.sparnatural.eu/how-to-configure-shacl/How-to-configure-Sparnatural-shacl.html) explains how this file can be generated from an Excel template - no need to write that file by hands:
```turtle
a owl:Ontology .
# This is an entity declaration in Sparnatural
this:Artwork a sh:NodeShape;
# order of display in the list
sh:order "1"^^xsd:integer;
# icon code
volipi:iconName "fa-solid fa-paint-brush";
# corresponding target class in the underlying knowledge graph
sh:targetClass dbpedia:Artwork;
sh:nodeKind sh:IRI;
# label and tooltips to be displayed in the UI
rdfs:label "Artwork"@en, "Oeuvre"@fr;
sh:description "A piece of art that can be displayed in a museum"@en, "Une Œuvre qui peut être exposée dans un musée"@fr;
# link to the properties that apply on this entity
sh:property this:Artwork_label, this:Artwork_author, this:Artwork_creationYear, this:Artwork_displayedAt,
this:Artwork_thumbnail .
# a property in the config applying to Artwork
this:Artwork_label
# the corresponding predicate in the underlying knowledge graph
sh:path rdfs:label;
# label displayed in the UI
sh:name "label"@en, "libellé"@fr;
# cardinality
sh:minCount "1"^^xsd:integer;
sh:nodeKind sh:Literal;
sh:datatype rdf:langString;
# This is a reference to the target Entity that will be used as a range in the UI
sh:node this:Text;
# the widget to use for users to enter their search criteria
dash:searchWidget core:SearchProperty;
# indicates this is the main label property for Artworks
dash:propertyRole dash:LabelRole;
# indicates that no optional or negative options should be proposed for this property in the UI
core:enableOptional "false"^^xsd:boolean;
core:enableNegation "false"^^xsd:boolean .
this:Artwork_author
sh:path dbpedia:author;
sh:name "author"@en, "auteur"@fr;
sh:description "the artist, painter or sculptor who created the artwork"@en, "l'artiste, le peintre ou le sculpteur qui a créé l'œuvre"@fr;
sh:nodeKind sh:IRI;
# authors apply to Artworks and have Persons as values
sh:class dbpedia:Person;
# the Persons can be searched with an autocomplete search field
dash:searchWidget core:AutocompleteProperty;
# the autocomplete search field will use a SPARQL query using Virtuoso bif:contains searching on the rdfs:label proerty
datasources:datasource datasources:search_rdfslabel_bifcontains;
core:enableOptional "true"^^xsd:boolean;
core:enableNegation "true"^^xsd:boolean .
this:Artwork_creationYear sh:path dbpedia:creationYear;
sh:name "creationYear"@en, "année de création"@fr;
sh:nodeKind sh:Literal;
sh:datatype xsd:gYear;
sh:node this:Date;
# this will use a calendar selection widget
dash:searchWidget core:TimeProperty-Year;
core:enableOptional "true"^^xsd:boolean;
core:enableNegation "true"^^xsd:boolean .
this:Artwork_displayedAt
# This is special : the property "displayedAt" in the config is actually translated to dbpedia:museum|^dbpedia:displays
# This illustrates how what is displayed to the user is different than the underlying knowledge graph
sh:path [ sh:alternativePath (dbpedia:museum [sh:inversePath dbpedia:displays])];
sh:name "displayed at"@en, "exposée à"@fr;
sh:nodeKind sh:IRI;
sh:class dbpedia:Museum;
dash:searchWidget core:AutocompleteProperty;
datasources:datasource datasources:search_rdfslabel_bifcontains;
core:enableOptional "true"^^xsd:boolean;
core:enableNegation "true"^^xsd:boolean .
this:Artwork_thumbnail sh:path dbpedia:thumbnail;
sh:name "thumbnail"@en, "vignette"@fr;
sh:nodeKind sh:IRI;
sh:node this:Image;
# This cannot be searched (only selected as a column in the result set)
dash:searchWidget core:NonSelectableProperty;
core:enableOptional "true"^^xsd:boolean;
core:enableNegation "true"^^xsd:boolean .
```
### OWL-based config
#### Class definition in OWL
```turtle
:Museum rdf:type owl:Class ;
rdfs:subClassOf core:SparnaturalClass ;
core:faIcon "fad fa-university" ;
core:sparqlString "" ;
core:tooltip "A DBPedia Museum"@en ,
"Un Musée DBPedia"@fr ;
rdfs:label "Museum"@en ,
"Musée"@fr .
```
#### Property definitions with domains and ranges in OWL
```turtle
:displayedAt rdf:type owl:ObjectProperty ;
rdfs:subPropertyOf core:AutocompleteProperty ;
owl:inverseOf :displays ;
rdfs:domain :Artwork ;
rdfs:range :Museum ;
core:sparqlString "" ;
datasources:datasource datasources:search_rdfslabel_bifcontains ;
rdfs:label "displayed at"@en ,
"exposée à"@fr .
```
#### Using font-awesome icons
It is possible to directly reference an icon class from font-awesome if you embed them in your application :
```turtle
:Person rdf:type owl:Class ;
core:faIcon "fad fa-male" ;
```
#### Map the query structure to a different graph structure
The OWL file to use is **different** from your knowledge graph ontology definition. You should create a different OWL file. You can refer to the [documentation page](https://docs.sparnatural.eu/OWL-based-configuration.html) for more details.
Classes or properties in the config can either:
- use the same URI as a class or a property in your knowledge graph.
- be mapped to a corresponding SPARQL property path or a corresponding class URI, using the `core:sparqlString` annotation.
Here is an example of a simple property in a Sparnatural configuration that is mapped to a property path in the underlying knowledge graph:
```turtle
:bornIn rdf:type owl:ObjectProperty ;
rdfs:subPropertyOf core:ListProperty ;
rdfs:domain :Person ;
rdfs:range :Country ;
core:sparqlString "/" ;
```