Skip to content

Commit

Permalink
#201 Update documentation '#511'
Browse files Browse the repository at this point in the history
  • Loading branch information
@luigi-asprino
luigi-asprino committed Oct 28, 2024
1 parent 1d49e24 commit dcaac92
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 78 deletions.
170 changes: 92 additions & 78 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -554,67 +554,71 @@ The jar can be executed as follows:
usage: java -jar sparql.anything-<version> -q query [-f <output format>] [-v
<filepath | name=value> ... ] [-c option=value] [-l path] [-o
filepath]
-q,--query <query> The path to the file storing the
query to execute or the query
itself.
-o,--output <file> OPTIONAL - The path to the output
file. [Default: STDOUT]
-a,--append OPTIONAL - Should output to file be
appended? WARNING: this option does
not ensure that the whole file is
valid -- that is up to the user to
set up the conditions (such as
using NQ serialization and not
using blank nodes)
-e,--explain OPTIONAL - Explain query execution
-l,--load <load> OPTIONAL - The path to one RDF file
or a folder including a set of
files to be loaded. When present,
the data is loaded in memory and
the query executed against it.
-f,--format <string> OPTIONAL - Format of the output
file. Supported values: JSON, XML,
CSV, TEXT, TTL, NT, NQ. [Default:
TEXT or TTL]
-s,--strategy <strategy> OPTIONAL - Strategy for query
evaluation. Possible values: '1' -
triple filtering (default), '0' -
triplify all data. The system
fallbacks to '0' when the strategy
is not implemented yet for the
given resource type.
-p,--output-pattern <outputPattern> OPTIONAL - Output filename pattern,
e.g. 'my-file-?friendName.json'.
Variables should start with '?' and
refer to bindings from the input
file. This option can only be used
in combination with 'input' and is
ignored otherwise. This option
overrides 'output'.
-v,--values <values> OPTIONAL - Values passed as input
parameter to a query template. When
present, the query is pre-processed
by substituting variable names with
the values provided. The argument
can be used in two ways. (1)
Providing a single SPARQL ResultSet
file. In this case, the query is
executed for each set of bindings
in the input result set. Only 1
file is allowed. (2) Named variable
bindings: the argument value must
follow the syntax:
var_name=var_value. The argument
can be passed multiple times and
the query repeated for each set of
values.
-c,--configuration <option=value> OPTIONAL - Configuration to be
passed to the SPARQL Anything
engine (this is equivalent to
define them in the SERVICE IRI).
The argument can be passed multiple
times (one for each option to be
set).
-q,--query <query or URL or filepath> The path or the URL to the file
storing the query to execute or
the query itself.
-o,--output <filepath> OPTIONAL - The path to the output
file. [Default: STDOUT]
-a,--append OPTIONAL - Should output to file
be appended? WARNING: this option
does not ensure that the whole
file is valid -- that is up to
the user to set up the conditions
(such as using NQ serialization
and not using blank nodes)
-e,--explain OPTIONAL - Explain query
execution
-l,--load <load> OPTIONAL - The path to one RDF
file or a folder including a set
of files to be loaded. When
present, the data is loaded in
memory and the query executed
against it.
-f,--format <string> OPTIONAL - Format of the output
file. Supported values: JSON,
XML, CSV, TEXT, TTL, NT, NQ.
[Default: TEXT or TTL]
-s,--strategy <strategy> OPTIONAL - Strategy for query
evaluation. Possible values: '1'
- triple filtering (default), '0'
- triplify all data. The system
fallbacks to '0' when the
strategy is not implemented yet
for the given resource type.
-p,--output-pattern <outputPattern> OPTIONAL - Output filename
pattern, e.g.
'my-file-?friendName.json'.
Variables should start with '?'
and refer to bindings from the
input file. This option can only
be used in combination with
'input' and is ignored otherwise.
This option overrides 'output'.
-v,--values <values> OPTIONAL - Values passed as input
parameter to a query template.
When present, the query is
pre-processed by substituting
variable names with the values
provided. The argument can be
used in two ways. (1) Providing a
single SPARQL ResultSet file. In
this case, the query is executed
for each set of bindings in the
input result set. Only 1 file is
allowed. (2) Named variable
bindings: the argument value must
follow the syntax:
var_name=var_value. The argument
can be passed multiple times and
the query repeated for each set
of values.
-c,--configuration <option=value> OPTIONAL - Configuration to be
passed to the SPARQL Anything
engine (this is equivalent to
define them in the SERVICE IRI).
The argument can be passed
multiple times (one for each
option to be set).
```

Logging can be configured adding the following option (SLF4J).
Expand Down Expand Up @@ -681,31 +685,41 @@ SPARQL Anything is distributed under [Apache 2.0 License](LICENSE)

**For citing SPARQL Anything in academic papers please use:**

Luigi Asprino, Enrico Daga, Aldo Gangemi, and Paul Mulholland. 2022. Knowledge Graph Construction with a façade: a
unified method to access heterogeneous data sources on the Web. ACM Trans. Internet Technol. Just Accepted (2022)
Luigi Asprino, Enrico Daga, Aldo Gangemi, and Paul Mulholland. "Knowledge Graph Construction with a façade: a
unified method to access heterogeneous data sources on the Web". ACM Transactions on Internet Technology (2022)
. https://doi.org/10.1145/3555312 [Preprint](https://sparql.xyz/FacadeX_TOIT.pdf)

```bibtex
@article{10.1145/3555312,
author = {Asprino, Luigi and Daga, Enrico and Gangemi, Aldo and Mulholland, Paul},
title = {Knowledge Graph Construction with a Fa\c{c}ade: A Unified Method to Access Heterogeneous Data Sources on the Web},
year = {2022},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
issn = {1533-5399},
url = {https://doi.org/10.1145/3555312},
doi = {10.1145/3555312},
abstract = {Data integration is the dominant use case for RDF Knowledge Graphs. However, Web resources come in formats with weak semantics (for example CSV and JSON), or formats specific to a given application (for example BibTex, HTML, and Markdown). To solve this problem, Knowledge Graph Construction (KGC) is gaining momentum due to its focus on supporting users in transforming data into RDF. However, using existing KGC frameworks result in complex data processing pipelines, which mix structural and semantic mappings, whose development and maintenance constitute a significant bottleneck for KG engineers. Such frameworks force users to rely on different tools, sometimes based on heterogeneous languages, for inspecting sources, designing mappings, and generating triples, thus making the process unnecessarily complicated. We argue that it is possible and desirable to equip KG engineers with the ability of interacting with Web data formats by relying on their expertise in RDF and the well-established SPARQL query language&nbsp;[2]. In this article, we study a unified method for data access to heterogeneous data sources with Facade-X, a meta-model implemented in a new data integration system called SPARQL Anything. We demonstrate that our approach is theoretically sound, since it allows a single meta-model, based on RDF, to represent data from (a) any file format expressible in BNF syntax, as well as (b) any relational database. We compare our method to state-of-the-art approaches in terms of usability (cognitive complexity of the mappings) and general performance. Finally, we discuss the benefits and challenges of this novel approach by engaging with the reference user community.},
journal = {ACM Trans. Internet Technol.},
keywords = {RDF, SPARQL, Meta-model, Re-engineering}
author = {Asprino, Luigi and Daga, Enrico and Gangemi, Aldo and Mulholland, Paul},
title = {Knowledge Graph Construction with a Fa\c{c}ade: A Unified Method to Access Heterogeneous Data Sources on the Web},
year = {2022},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
issn = {1533-5399},
url = {https://doi.org/10.1145/3555312},
doi = {10.1145/3555312},
abstract = {Data integration is the dominant use case for RDF Knowledge Graphs. However, Web resources come in formats with weak semantics (for example CSV and JSON), or formats specific to a given application (for example BibTex, HTML, and Markdown). To solve this problem, Knowledge Graph Construction (KGC) is gaining momentum due to its focus on supporting users in transforming data into RDF. However, using existing KGC frameworks result in complex data processing pipelines, which mix structural and semantic mappings, whose development and maintenance constitute a significant bottleneck for KG engineers. Such frameworks force users to rely on different tools, sometimes based on heterogeneous languages, for inspecting sources, designing mappings, and generating triples, thus making the process unnecessarily complicated. We argue that it is possible and desirable to equip KG engineers with the ability of interacting with Web data formats by relying on their expertise in RDF and the well-established SPARQL query language&nbsp;[2]. In this article, we study a unified method for data access to heterogeneous data sources with Facade-X, a meta-model implemented in a new data integration system called SPARQL Anything. We demonstrate that our approach is theoretically sound, since it allows a single meta-model, based on RDF, to represent data from (a) any file format expressible in BNF syntax, as well as (b) any relational database. We compare our method to state-of-the-art approaches in terms of usability (cognitive complexity of the mappings) and general performance. Finally, we discuss the benefits and challenges of this novel approach by engaging with the reference user community.},
journal = {ACM Transactions on Internet Technology},
keywords = {RDF, SPARQL, Meta-model, Re-engineering}
}
```

Conference paper mainly focussing on system requirements:
Paul Warren, Paul Mulholland, Enrico Daga, and Luigi Asprino. "Path-based and triplification approaches to mapping data into RDF: user behaviours and recommendations". In: Semantic Web (2024), to appear [Pre-print](https://content.iospress.com/articles/semantic-web/sw243585)

Daga, Enrico; Asprino, Luigi; Mulholland, Paul and Gangemi, Aldo (2021). Facade-X: An Opinionated Approach to SPARQL
Anything. In: Alam, Mehwish; Groth, Paul; de Boer, Victor; Pellegrini, Tassilo and Pandit, Harshvardhan J. eds. Volume
53: Further with Knowledge Graphs, Volume 53. IOS Press, pp. 58–73.
```bibtex
@article{Warren2024,
title={Path-based and triplification approaches to mapping data into RDF: User behaviours and recommendations},
author={Warren, Paul and Mulholland, Paul and Daga, Enrico and Asprino, Luigi},
journal={Semantic Web},
number={(to appear)},
publisher={IOS Press}
}
```



Enrico Daga, Luigi Asprino, Paul Mulholland, and Aldo Gangemi. "Facade-X: An Opinionated Approach to SPARQL Anything". In: Alam, Mehwish; Groth, Paul; de Boer, Victor; Pellegrini, Tassilo and Pandit, Harshvardhan J. eds. Volume 53: Further with Knowledge Graphs, Volume 53. IOS Press, pp. 58–73.

DOI: https://doi.org/10.3233/ssw210035 | [PDF](http://oro.open.ac.uk/78973/1/78973.pdf)

Expand Down
1 change: 1 addition & 0 deletions docs/TUTORIALS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Here is a list of step-by-step tutorials covering several features of SPARQL Any
- [Construct a KG from YAML annotations in Markdown file headers](https://github.com/SPARQL-Anything/showcase-polifonia-ecosystem): A short but complex case demonstrating how to chain multiple transformations starting from a set of Markdown files, queried to extract the YAML header, which is in turn queried to derive the annotations, that are in turn projected into a KG!
- [Populate a Music Ontology from MusicXML files](https://github.com/SPARQL-Anything/showcase-musicxml): An advanced application of SPARQL Anything to query MusicXML files and derive note sequences, computing n-grams, and populating a Music Notation ontology.
- [Querying a Relational Database](https://github.com/justin2004/weblog/blob/master/relational_as_graph/README.md): this tutorials shows you how to query a relational database by using SPARQL Anything (even if the tool does not support yet this feature natively).
- [How cool would it be to have a single query to get an overview of the content of any input sources?](https://colab.research.google.com/drive/1R5zeIx4IutF0cc4oTc45CrXjdTSGP4eW?usp=sharing#scrollTo=MgVgJ526sd3e): This is a Colab notebook describing how to build a SPARQL Anything query to get an overview of the schema of any source. The query is plain SPARQL 1.1 but thanks to Facade-X model and SPARQL Anything it also works with any format. Related Discussion: [#508](https://github.com/SPARQL-Anything/sparql.anything/discussions/508)


# Online presentations
Expand Down

0 comments on commit dcaac92

Please sign in to comment.