diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 00000000..3bbdd1fd --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,58 @@ +# Command Line Interface + +## Download + +## Usage + +```bash +java -jar sparql.anything-.jar -q [-f ] [-v ... ] [-c ] +[-l ] [-o ] +``` + +### -q,--query +The path to the file storing the query to execute or the query itself. + +### -o,--output +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 +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 +OPTIONAL - Format of the output file. Supported values: JSON, XML, CSV, TEXT, TTL, NT, NQ. [Default: TEXT or TTL] + +### -s,--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 +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 +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: . The argument can be passed multiple times and +the query repeated for each set of values. + +### -c,--configuration +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). Options passed in this way can be overwritten in the SERVICE IRI or in the Basic Graph Pattern. + +### -i,--input (Deprecated) +Superseded by `-v | --values` + +OPTIONAL - The path to a SPARQL result set file to be used as input. When present, the query +is pre-processed by substituting variable names with values from the bindings provided. The query is repeated for each set of bindings +in the input result set. + +## Build from source \ No newline at end of file diff --git a/docs/formats/CSV.md b/docs/formats/CSV.md index 35f7e1e5..1136d4e3 100644 --- a/docs/formats/CSV.md +++ b/docs/formats/CSV.md @@ -298,4 +298,302 @@ WHERE @prefix owl: . @prefix rdf: . @prefix rdfs: . -@prefix rss: . +@prefix vcard: . +@prefix whatwg: . +@prefix xhtml: . +@prefix xsd: . +@prefix xyz: . + +[ rdf:type fx:root ; + rdf:_1 [ rdf:_1 "Sepal_length\tSepal_width\tPetal_length\tPetal_width\tSpecies" ] ; + rdf:_2 [ rdf:_1 "5.1\t3.5\t1.4\t0.2\tI. setosa" ] ; + rdf:_3 [ rdf:_1 "4.9\t3.0\t1.4\t0.2\tI. setosa" ] ; + rdf:_4 [ rdf:_1 "4.7\t3.2\t1.3\t0.2\tI. setosa" ] ; + rdf:_5 [ rdf:_1 "4.6\t3.1\t1.5\t0.2\tI. setosa" ] ; + rdf:_6 [ rdf:_1 "5.0\t3.6\t1.4\t0.2\tI. setosa" ] +] . + +``` + +--- +### `csv.delimiter` + +#### Description + +It sets the column delimiter, usually ,;\t etc. + +#### Valid Values + +Any single character + +#### Default Value + +`,` + +#### Examples + +##### Example 1 + +Compute the maximum petal length of the species having sepal length less than 4.9 + +###### Input + +```CSV +Sepal_length Sepal_width Petal_length Petal_width Species +5.1 3.5 1.4 0.2 I. setosa +4.9 3.0 1.4 0.2 I. setosa +4.7 3.2 1.3 0.2 I. setosa +4.6 3.1 1.5 0.2 I. setosa +5.0 3.6 1.4 0.2 I. setosa + +``` + +https://sparql-anything.cc/examples/simple.tsv + +###### Query + +``` +PREFIX xyz: +PREFIX xsd: +PREFIX fx: + +SELECT (MAX(xsd:float(?petalLength)) AS ?maxPetalLength) +WHERE + { SERVICE + { fx:properties + fx:csv.delimiter "\t" . + ?s xyz:Sepal_length ?length ; + xyz:Petal_length ?petalLength + FILTER ( xsd:float(?length) < 4.9 ) + } + } + +``` + +###### Result + +```turtle +--------------------------------------------------- +| maxPetalLength | +=================================================== +| "1.5"^^ | +--------------------------------------------------- + +``` + +--- +### `csv.quote-char` + +#### Description + +It sets the quoting character + +#### Valid Values + +Any single character + +#### Default Value + +`"` + +#### Examples + +##### Example 1 + +Constructing a Facade-X RDF graph out of the CSV available at https://sparql-anything.cc/examples/csv_with_commas.csv + +###### Input + +```CSV +email,name,surname +laura@example.com,'Laura, Nancy',Grey +craig@example.com,Craig,Johnson +mary@example.com,Mary,Jenkins +jamie@example.com,Jamie,Smith + +``` + +https://sparql-anything.cc/examples/csv_with_commas.csv + +###### Query + +``` +CONSTRUCT + { + ?s ?p ?o . + } +WHERE + { SERVICE + { ?s ?p ?o } + } + +``` + +###### Result + +```turtle +@prefix dc: . +@prefix eg: . +@prefix fx: . +@prefix ja: . +@prefix owl: . +@prefix rdf: . +@prefix rdfs: . +@prefix rss: . +@prefix vcard: . +@prefix whatwg: . +@prefix xhtml: . +@prefix xsd: . +@prefix xyz: . + +[ rdf:type fx:root ; + rdf:_1 [ xyz:email "laura@example.com" ; + xyz:name "Laura, Nancy" ; + xyz:surname "Grey" + ] ; + rdf:_2 [ xyz:email "craig@example.com" ; + xyz:name "Craig" ; + xyz:surname "Johnson" + ] ; + rdf:_3 [ xyz:email "mary@example.com" ; + xyz:name "Mary" ; + xyz:surname "Jenkins" + ] ; + rdf:_4 [ xyz:email "jamie@example.com" ; + xyz:name "Jamie" ; + xyz:surname "Smith" + ] +] . + +``` + +--- +### `csv.null-string` + +#### Description + +It tells the CSV triplifier to not produce triples where the specified string would be in the object position of the triple + +#### Valid Values + +Any String + +#### Default Value + +Not set + +#### Examples + +##### Example 1 + +Retrieving name surname of who doesn't have an email address. + +###### Input + +```CSV +email,name,surname +laura@example.com,Laura,Grey +craig@example.com,Craig,Johnson +,Mary,Jenkins +jamie@example.com,Jamie,Smith + +``` + +https://sparql-anything.cc/examples/simple_with_null.csv + +###### Query + +``` +PREFIX xyz: +PREFIX fx: + +SELECT ?name ?surname +WHERE + { SERVICE + { fx:properties + fx:csv.null-string "" . + ?c xyz:name ?name ; + xyz:surname ?surname + FILTER NOT EXISTS { ?c xyz:email ?email } + } + } + +``` + +###### Result + +```turtle +---------------------- +| name | surname | +====================== +| "Mary" | "Jenkins" | +---------------------- + +``` + +--- +### `csv.ignore-columns-with-no-header` + +#### Description + +It tells the csv triplifier to ignore from the cells of columns having no headers. Note that if the property is set as true when csv.headers is false, the triplifier does not generate any slot (as no headers are collected). -- see [#180](https://github.com/SPARQL-Anything/sparql.anything/issues/180) + +#### Valid Values + +true/false + +#### Default Value + +`false` + +#### Examples + +##### Example 1 + + + +###### Input + + +Inline content + +###### Query + +``` +PREFIX xyz: +PREFIX fx: +PREFIX rdf: + +SELECT DISTINCT ?fred ?sally +WHERE + { SERVICE + { fx:properties + fx:csv.headers true ; + fx:content ",state\nfred,CO\nsally,FL" ; + fx:media-type "text/csv" ; + fx:csv.ignore-columns-with-no-header true . + ?root rdf:type fx:root ; + rdf:_1 _:b0 . + _:b0 rdf:_1 ?fred . + ?root rdf:_2 _:b1 . + _:b1 rdf:_1 ?sally + } + } + +``` + +###### Result + +```turtle +---------------- +| fred | sally | +================ +---------------- + +``` + + + + + diff --git a/docs/formats/Metadata.md b/docs/formats/Metadata.md index ff6c058e..937fb5c0 100644 --- a/docs/formats/Metadata.md +++ b/docs/formats/Metadata.md @@ -122,7 +122,7 @@ WHERE "f/7.1" ; - "Tue Jan 09 12:57:35 +01:00 2024" ; + "Tue Jan 09 14:01:48 +01:00 2024" ; "Canon_40D.jpg" ; diff --git a/formats/CSV.md b/formats/CSV.md index 35f7e1e5..1136d4e3 100644 --- a/formats/CSV.md +++ b/formats/CSV.md @@ -298,4 +298,302 @@ WHERE @prefix owl: . @prefix rdf: . @prefix rdfs: . -@prefix rss: . +@prefix vcard: . +@prefix whatwg: . +@prefix xhtml: . +@prefix xsd: . +@prefix xyz: . + +[ rdf:type fx:root ; + rdf:_1 [ rdf:_1 "Sepal_length\tSepal_width\tPetal_length\tPetal_width\tSpecies" ] ; + rdf:_2 [ rdf:_1 "5.1\t3.5\t1.4\t0.2\tI. setosa" ] ; + rdf:_3 [ rdf:_1 "4.9\t3.0\t1.4\t0.2\tI. setosa" ] ; + rdf:_4 [ rdf:_1 "4.7\t3.2\t1.3\t0.2\tI. setosa" ] ; + rdf:_5 [ rdf:_1 "4.6\t3.1\t1.5\t0.2\tI. setosa" ] ; + rdf:_6 [ rdf:_1 "5.0\t3.6\t1.4\t0.2\tI. setosa" ] +] . + +``` + +--- +### `csv.delimiter` + +#### Description + +It sets the column delimiter, usually ,;\t etc. + +#### Valid Values + +Any single character + +#### Default Value + +`,` + +#### Examples + +##### Example 1 + +Compute the maximum petal length of the species having sepal length less than 4.9 + +###### Input + +```CSV +Sepal_length Sepal_width Petal_length Petal_width Species +5.1 3.5 1.4 0.2 I. setosa +4.9 3.0 1.4 0.2 I. setosa +4.7 3.2 1.3 0.2 I. setosa +4.6 3.1 1.5 0.2 I. setosa +5.0 3.6 1.4 0.2 I. setosa + +``` + +https://sparql-anything.cc/examples/simple.tsv + +###### Query + +``` +PREFIX xyz: +PREFIX xsd: +PREFIX fx: + +SELECT (MAX(xsd:float(?petalLength)) AS ?maxPetalLength) +WHERE + { SERVICE + { fx:properties + fx:csv.delimiter "\t" . + ?s xyz:Sepal_length ?length ; + xyz:Petal_length ?petalLength + FILTER ( xsd:float(?length) < 4.9 ) + } + } + +``` + +###### Result + +```turtle +--------------------------------------------------- +| maxPetalLength | +=================================================== +| "1.5"^^ | +--------------------------------------------------- + +``` + +--- +### `csv.quote-char` + +#### Description + +It sets the quoting character + +#### Valid Values + +Any single character + +#### Default Value + +`"` + +#### Examples + +##### Example 1 + +Constructing a Facade-X RDF graph out of the CSV available at https://sparql-anything.cc/examples/csv_with_commas.csv + +###### Input + +```CSV +email,name,surname +laura@example.com,'Laura, Nancy',Grey +craig@example.com,Craig,Johnson +mary@example.com,Mary,Jenkins +jamie@example.com,Jamie,Smith + +``` + +https://sparql-anything.cc/examples/csv_with_commas.csv + +###### Query + +``` +CONSTRUCT + { + ?s ?p ?o . + } +WHERE + { SERVICE + { ?s ?p ?o } + } + +``` + +###### Result + +```turtle +@prefix dc: . +@prefix eg: . +@prefix fx: . +@prefix ja: . +@prefix owl: . +@prefix rdf: . +@prefix rdfs: . +@prefix rss: . +@prefix vcard: . +@prefix whatwg: . +@prefix xhtml: . +@prefix xsd: . +@prefix xyz: . + +[ rdf:type fx:root ; + rdf:_1 [ xyz:email "laura@example.com" ; + xyz:name "Laura, Nancy" ; + xyz:surname "Grey" + ] ; + rdf:_2 [ xyz:email "craig@example.com" ; + xyz:name "Craig" ; + xyz:surname "Johnson" + ] ; + rdf:_3 [ xyz:email "mary@example.com" ; + xyz:name "Mary" ; + xyz:surname "Jenkins" + ] ; + rdf:_4 [ xyz:email "jamie@example.com" ; + xyz:name "Jamie" ; + xyz:surname "Smith" + ] +] . + +``` + +--- +### `csv.null-string` + +#### Description + +It tells the CSV triplifier to not produce triples where the specified string would be in the object position of the triple + +#### Valid Values + +Any String + +#### Default Value + +Not set + +#### Examples + +##### Example 1 + +Retrieving name surname of who doesn't have an email address. + +###### Input + +```CSV +email,name,surname +laura@example.com,Laura,Grey +craig@example.com,Craig,Johnson +,Mary,Jenkins +jamie@example.com,Jamie,Smith + +``` + +https://sparql-anything.cc/examples/simple_with_null.csv + +###### Query + +``` +PREFIX xyz: +PREFIX fx: + +SELECT ?name ?surname +WHERE + { SERVICE + { fx:properties + fx:csv.null-string "" . + ?c xyz:name ?name ; + xyz:surname ?surname + FILTER NOT EXISTS { ?c xyz:email ?email } + } + } + +``` + +###### Result + +```turtle +---------------------- +| name | surname | +====================== +| "Mary" | "Jenkins" | +---------------------- + +``` + +--- +### `csv.ignore-columns-with-no-header` + +#### Description + +It tells the csv triplifier to ignore from the cells of columns having no headers. Note that if the property is set as true when csv.headers is false, the triplifier does not generate any slot (as no headers are collected). -- see [#180](https://github.com/SPARQL-Anything/sparql.anything/issues/180) + +#### Valid Values + +true/false + +#### Default Value + +`false` + +#### Examples + +##### Example 1 + + + +###### Input + + +Inline content + +###### Query + +``` +PREFIX xyz: +PREFIX fx: +PREFIX rdf: + +SELECT DISTINCT ?fred ?sally +WHERE + { SERVICE + { fx:properties + fx:csv.headers true ; + fx:content ",state\nfred,CO\nsally,FL" ; + fx:media-type "text/csv" ; + fx:csv.ignore-columns-with-no-header true . + ?root rdf:type fx:root ; + rdf:_1 _:b0 . + _:b0 rdf:_1 ?fred . + ?root rdf:_2 _:b1 . + _:b1 rdf:_1 ?sally + } + } + +``` + +###### Result + +```turtle +---------------- +| fred | sally | +================ +---------------- + +``` + + + + + diff --git a/formats/Metadata.md b/formats/Metadata.md index ff6c058e..937fb5c0 100644 --- a/formats/Metadata.md +++ b/formats/Metadata.md @@ -122,7 +122,7 @@ WHERE "f/7.1" ; - "Tue Jan 09 12:57:35 +01:00 2024" ; + "Tue Jan 09 14:01:48 +01:00 2024" ; "Canon_40D.jpg" ;