Skip to content

Commit

Permalink
#201 Update documentation ''
Browse files Browse the repository at this point in the history
  • Loading branch information
@enridaga
enridaga committed Sep 7, 2024
1 parent fba9f9d commit 5b71543
Show file tree
Hide file tree
Showing 5 changed files with 201 additions and 5 deletions.
70 changes: 70 additions & 0 deletions docs/Configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@ WHERE {
| [use-rdfs-member](#use-rdfs-member) | It tells SPARQL Anything to use the (super)property rdfs:member instead of container membership properties (rdf:_1, rdf:_2 ...) | true/false | false |
| [annotate-triples-with-slot-keys](#annotate-triples-with-slot-keys) | It tells SPARQL Anything to annotate slot statements with slot keys (see issue [#378](https://github.com/SPARQL-Anything/sparql.anything/issues/378)) | true/false | false |
| [generate-predicate-labels](#generate-predicate-labels) | It tells SPARQL Anything to create labels for extracted predicates and classes (see issue [#462](https://github.com/SPARQL-Anything/sparql.anything/issues/462)) | true/false | false |
| [audit](#audit) | It tells SPARQL Anything to generate an additional graph containing information for auditing the result of the triplification. The audit graph has the URI <http://sparql.xyz/facade-x/data/audit> | true/false | false |

\* It is mandatory to provide either `location`, `content`, or `command`.

Expand Down Expand Up @@ -1213,6 +1214,75 @@ Result
|-----|
| abc |


### audit

It tells SPARQL Anything to generate an additional graph containing information for auditing the result of the triplification. The audit graph has the URI <http://sparql.xyz/facade-x/data/audit>
For each content graph generated by the triplifier, the audit graph specifies:
- the graph name;
- the number of triples in the content graph;
- whether the graph was retrieved from the cache;
- the datetime when the graph was created;
- a string representation of the SPARQL algebra of the operation that generated the graph.

**Note** Do not use strategy 1 (i.e. triple filtering) for querying the audit graph (specifically, do not add triple patterns matching the audit graph) otherwise the engine will filter out all the triples in the content graph.

#### Valid Values

`true`/`false`

#### Default Value

`false`

#### Examples

```sparql
CONSTRUCT
{
GRAPH ?g
{ ?s ?p ?o .}
}
WHERE
{ SERVICE <x-sparql-anything:content=abc,audit=true,strategy=0>
{ GRAPH ?g
{ ?s ?p ?o }
}
}
```

Result

```turtle
<http://sparql.xyz/facade-x/data/900150983cd24fb0d6963f7d28e17f72#> {
[ a <http://sparql.xyz/facade-x/ns/root>;
<http://www.w3.org/1999/02/22-rdf-syntax-ns#_1>
"abc"
] .
}
<http://sparql.xyz/facade-x/data/audit> {
<http://sparql.xyz/facade-x/data/900150983cd24fb0d6963f7d28e17f72#>
a <http://www.w3.org/ns/sparql-service-description#NamedGraph>;
<http://rdfs.org/ns/void#triples>
"2"^^<http://www.w3.org/2001/XMLSchema#long>;
<http://sparql.xyz/facade-x/ns/cachedGraph>
false;
<http://sparql.xyz/facade-x/ns/cachedGraphCreation>
"2024-09-03T14:32:57.174Z"^^<http://www.w3.org/2001/XMLSchema#dateTime>;
<http://sparql.xyz/facade-x/ns/sparqlAlgebra>
"(service <x-sparql-anything:content=abc,audit=true,strategy=0>\n (graph ?g\n (bgp (triple ?s ?p ?o))))\n";
<http://www.w3.org/ns/sparql-service-description#name>
"http://sparql.xyz/facade-x/data/900150983cd24fb0d6963f7d28e17f72#" .
<http://sparql.xyz/facade-x/data/audit#root>
<http://www.w3.org/ns/sparql-service-description#namedGraph>
<http://sparql.xyz/facade-x/data/900150983cd24fb0d6963f7d28e17f72#> .
}
```

<!--
###
Expand Down
131 changes: 128 additions & 3 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,133 @@

SPARQL Anything is a system for Semantic Web re-engineering that allows users to ... query anything with SPARQL.

Main features:
## Quickstart

One of the most common uses of SPARQL Anything is to start with some structured data (e.g. csv) and produce RDF using a particular ontology (e.g. [gist](https://github.com/semanticarts/gist)).
Here is how that can be done.

```bash
# have java and curl installed
$ curl -L -O 'https://github.com/SPARQL-Anything/sparql.anything/releases/download/0.9.0/sparql-anything-0.9.0.jar'
```

```csv
$ cat some.csv
id,name,height_inches
5,alice,66
2,fred,67
9,william,73
```

```sparql
# first let's write a simple query that just shows us the Facade-X representaion of the csv
$ cat some.rq
PREFIX xyz: <http://sparql.xyz/facade-x/data/>
PREFIX fx: <http://sparql.xyz/facade-x/ns/>
CONSTRUCT { ?s ?p ?o }
WHERE
{ SERVICE <x-sparql-anything:>
{ fx:properties
fx:location "some.csv" ;
fx:csv.headers "true" .
?s ?p ?o
}
}
```

```turtle
$ java -jar sparql-anything-0.9.0.jar --query some.rq
[main] INFO com.github.sparqlanything.cli.SPARQLAnything - SPARQL anything
@prefix fx: <http://sparql.xyz/facade-x/ns/> .
@prefix xyz: <http://sparql.xyz/facade-x/data/> .
- Provides a homogenous view over heterogeneous data sources, thanks to the Facade-X meta-model (see [Facade-X specification](Facade-X.md) )
[ a fx:root ;
<http://www.w3.org/1999/02/22-rdf-syntax-ns#_1>
[ xyz:height_inches "66" ;
xyz:id "5" ;
xyz:name "alice"
] ;
<http://www.w3.org/1999/02/22-rdf-syntax-ns#_2>
[ xyz:height_inches "67" ;
xyz:id "2" ;
xyz:name "fred"
] ;
<http://www.w3.org/1999/02/22-rdf-syntax-ns#_3>
[ xyz:height_inches "73" ;
xyz:id "9" ;
xyz:name "william"
]
] .
```

```sparql
# and now you can use everything you know about SPARQL to construct the RDF you want
# by transforming the Facade-X representation into the desired RDF
$ cat some.rq
PREFIX xyz: <http://sparql.xyz/facade-x/data/>
PREFIX fx: <http://sparql.xyz/facade-x/ns/>
PREFIX ex: <http://example.com/>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
PREFIX gist: <https://w3id.org/semanticarts/ns/ontology/gist/>
CONSTRUCT {
?person a gist:Person ;
gist:name ?name ;
gist:hasMagnitude ?height_magnitude .
?height_magnitude a gist:Extent ;
gist:hasUnitOfMeasure gist:_inch ;
gist:numericValue ?height .
}
WHERE
{ SERVICE <x-sparql-anything:>
{ fx:properties
fx:location "some.csv" ;
fx:csv.headers "true" .
?row xyz:height_inches ?height_string .
?row xyz:id ?id_string .
?row xyz:name ?name .
bind(bnode() as ?height_magnitude)
bind(xsd:float(?height_string) as ?height)
bind(iri(concat(str(ex:),"Person/",?id_string)) as ?person)
}
}
```

```turtle
$ java -jar sparql-anything-0.9.0.jar --query some.rq
@prefix ex: <http://example.com/> .
@prefix fx: <http://sparql.xyz/facade-x/ns/> .
@prefix gist: <https://w3id.org/semanticarts/ns/ontology/gist/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix xyz: <http://sparql.xyz/facade-x/data/> .
<http://example.com/Person/9>
a gist:Person ;
gist:hasMagnitude [ a gist:Extent ;
gist:hasUnitOfMeasure gist:_inch ;
gist:numericValue "73"^^xsd:float
] ;
gist:name "william" .
<http://example.com/Person/2>
a gist:Person ;
gist:hasMagnitude [ a gist:Extent ;
gist:hasUnitOfMeasure gist:_inch ;
gist:numericValue "67"^^xsd:float
] ;
gist:name "fred" .
<http://example.com/Person/5>
a gist:Person ;
gist:hasMagnitude [ a gist:Extent ;
gist:hasUnitOfMeasure gist:_inch ;
gist:numericValue "66"^^xsd:float
] ;
gist:name "alice" .
```

## Main features

- Provides a homogeneous view over heterogeneous data sources, thanks to the Facade-X meta-model (see [Facade-X specification](Facade-X.md) and [System overview](SystemOverview.md) )
- Query files in plain SPARQL 1.1, via the `SERVICE <x-sparql-anything:>` (see [configuration](#Configuration)) and
build knowledge graphs with `CONSTRUCT` queries
- [Supported formats](#supported-formats): XML, JSON, CSV, HTML, Excel, Text, Binary, EXIF, File System, Zip/Tar,
Expand All @@ -29,7 +153,7 @@ Main features:
and [#203](https://github.com/SPARQL-Anything/sparql.anything/issues/203))
- Supports an [on-disk option](#Configuration) (with Apache Jena TDB2)

## Quickstart
## Introduction

SPARQL Anything uses a single generic abstraction for all data source formats called Facade-X.

Expand Down Expand Up @@ -298,6 +422,7 @@ WHERE {
| [use-rdfs-member](Configuration.md#use-rdfs-member) | It tells SPARQL Anything to use the (super)property rdfs:member instead of container membership properties (rdf:_1, rdf:_2 ...) | true/false | false |
| [annotate-triples-with-slot-keys](Configuration.md#annotate-triples-with-slot-keys) | It tells SPARQL Anything to annotate slot statements with slot keys (see issue [#378](https://github.com/SPARQL-Anything/sparql.anything/issues/378)) | true/false | false |
| [generate-predicate-labels](Configuration.md#generate-predicate-labels) | It tells SPARQL Anything to create labels for extracted predicates and classes (see issue [#462](https://github.com/SPARQL-Anything/sparql.anything/issues/462)) | true/false | false |
| [audit](Configuration.md#audit) | It tells SPARQL Anything to generate an additional graph containing information for auditing the result of the triplification. The audit graph has the URI &lt;http://sparql.xyz/facade-x/data/audit&gt; | true/false | false |

\* If `read-from-std-in` is set to false, it is mandatory to provide either `location`, `content`, or `command`.

Expand Down
1 change: 1 addition & 0 deletions docs/SystemOverview.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# System overview
2 changes: 1 addition & 1 deletion docs/formats/Metadata.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ WHERE
<http://sparql.xyz/facade-x/data/F-Number>
"f/7.1";
<http://sparql.xyz/facade-x/data/File%20Modified%20Date>
"Mon Aug 26 14:45:56 +02:00 2024";
"Sat Sept 07 11:22:18 +01:00 2024";
<http://sparql.xyz/facade-x/data/File%20Name>
"Canon_40D.jpg";
<http://sparql.xyz/facade-x/data/File%20Size>
Expand Down
2 changes: 1 addition & 1 deletion formats/Metadata.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ WHERE
<http://sparql.xyz/facade-x/data/F-Number>
"f/7.1";
<http://sparql.xyz/facade-x/data/File%20Modified%20Date>
"Mon Aug 26 14:45:56 +02:00 2024";
"Sat Sept 07 11:22:18 +01:00 2024";
<http://sparql.xyz/facade-x/data/File%20Name>
"Canon_40D.jpg";
<http://sparql.xyz/facade-x/data/File%20Size>
Expand Down

0 comments on commit 5b71543

Please sign in to comment.