From dd7b4bbbd20da16b7c5a7482cf608efed203b497 Mon Sep 17 00:00:00 2001 From: Claus Stadler Date: Wed, 18 Sep 2024 17:41:58 +0200 Subject: [PATCH] more work on documentation --- {doc => docs/examples}/README.md | 7 +++++++ {doc => docs/examples}/csv.sparql | 0 {doc => docs/examples}/data.csv | 0 {doc => docs/examples}/example-data/data.csv | 0 {doc => docs/examples}/example-data/data.ttl | 0 .../examples}/example-data/people.csv | 0 .../examples}/fs-list-all-files.sparql | 0 .../examples}/fs-list-rdf-files.sparql | 0 .../examples}/fs-query-rdf-files.sparql | 0 {doc => docs/examples}/fs-test.sparql | 0 {doc => docs/examples}/hashbang.sparql | 0 {doc => docs/examples}/io.sparql | 0 {doc => docs/examples}/json-by-index.sparql | 0 .../examples}/json-hello-world.sparql | 0 .../examples}/json-path-inline.sparql | 0 {doc => docs/examples}/json-path1.sparql | 0 .../examples}/json-unnest-by-index.sparql | 0 {doc => docs/examples}/json-unnest.sparql | 0 {doc => docs/examples}/json-zip-arrays.sparql | 0 {doc => docs/examples}/test-zip-arrays.sparql | 0 {doc => docs/examples}/test.nt | 0 {doc => docs/examples}/test.sparql | 0 {doc => docs/examples}/test2.sparql | 0 {doc => docs/examples}/test3.sparql | 0 {doc => docs/examples}/test4.sparql | 0 {doc => docs/examples}/url-local-file.sparql | 0 {doc => docs/examples}/workloads.sparql | 0 {doc => docs/examples}/xml-attribute.sparql | 0 {doc => docs/examples}/xml-unnest.sparql | 0 docs/graphql/demo.md | 6 ++++-- docs/graphql/index.md | 2 +- docs/graphql/reference/index-directive.md | 2 +- docs/graphql/reference/join.md | 4 ++-- docs/graphql/reference/one-and-many.md | 4 ++-- docs/graphql/reference/prefix.md | 19 ++++++++++--------- docs/integrate/canned-queries.md | 2 +- docs/integrate/sparql-extensions.md | 13 +++++++++++++ 37 files changed, 41 insertions(+), 18 deletions(-) rename {doc => docs/examples}/README.md (99%) rename {doc => docs/examples}/csv.sparql (100%) rename {doc => docs/examples}/data.csv (100%) rename {doc => docs/examples}/example-data/data.csv (100%) rename {doc => docs/examples}/example-data/data.ttl (100%) rename {doc => docs/examples}/example-data/people.csv (100%) rename {doc => docs/examples}/fs-list-all-files.sparql (100%) rename {doc => docs/examples}/fs-list-rdf-files.sparql (100%) rename {doc => docs/examples}/fs-query-rdf-files.sparql (100%) rename {doc => docs/examples}/fs-test.sparql (100%) rename {doc => docs/examples}/hashbang.sparql (100%) rename {doc => docs/examples}/io.sparql (100%) rename {doc => docs/examples}/json-by-index.sparql (100%) rename {doc => docs/examples}/json-hello-world.sparql (100%) rename {doc => docs/examples}/json-path-inline.sparql (100%) rename {doc => docs/examples}/json-path1.sparql (100%) rename {doc => docs/examples}/json-unnest-by-index.sparql (100%) rename {doc => docs/examples}/json-unnest.sparql (100%) rename {doc => docs/examples}/json-zip-arrays.sparql (100%) rename {doc => docs/examples}/test-zip-arrays.sparql (100%) rename {doc => docs/examples}/test.nt (100%) rename {doc => docs/examples}/test.sparql (100%) rename {doc => docs/examples}/test2.sparql (100%) rename {doc => docs/examples}/test3.sparql (100%) rename {doc => docs/examples}/test4.sparql (100%) rename {doc => docs/examples}/url-local-file.sparql (100%) rename {doc => docs/examples}/workloads.sparql (100%) rename {doc => docs/examples}/xml-attribute.sparql (100%) rename {doc => docs/examples}/xml-unnest.sparql (100%) create mode 100644 docs/integrate/sparql-extensions.md diff --git a/doc/README.md b/docs/examples/README.md similarity index 99% rename from doc/README.md rename to docs/examples/README.md index 86b0d8f..87e7625 100644 --- a/doc/README.md +++ b/docs/examples/README.md @@ -1,3 +1,10 @@ +--- +title: Examples +parent: RDF/SPARQL Processing +layout: default +nav_order: 10 +--- + # SPARQL Integrate examples diff --git a/doc/csv.sparql b/docs/examples/csv.sparql similarity index 100% rename from doc/csv.sparql rename to docs/examples/csv.sparql diff --git a/doc/data.csv b/docs/examples/data.csv similarity index 100% rename from doc/data.csv rename to docs/examples/data.csv diff --git a/doc/example-data/data.csv b/docs/examples/example-data/data.csv similarity index 100% rename from doc/example-data/data.csv rename to docs/examples/example-data/data.csv diff --git a/doc/example-data/data.ttl b/docs/examples/example-data/data.ttl similarity index 100% rename from doc/example-data/data.ttl rename to docs/examples/example-data/data.ttl diff --git a/doc/example-data/people.csv b/docs/examples/example-data/people.csv similarity index 100% rename from doc/example-data/people.csv rename to docs/examples/example-data/people.csv diff --git a/doc/fs-list-all-files.sparql b/docs/examples/fs-list-all-files.sparql similarity index 100% rename from doc/fs-list-all-files.sparql rename to docs/examples/fs-list-all-files.sparql diff --git a/doc/fs-list-rdf-files.sparql b/docs/examples/fs-list-rdf-files.sparql similarity index 100% rename from doc/fs-list-rdf-files.sparql rename to docs/examples/fs-list-rdf-files.sparql diff --git a/doc/fs-query-rdf-files.sparql b/docs/examples/fs-query-rdf-files.sparql similarity index 100% rename from doc/fs-query-rdf-files.sparql rename to docs/examples/fs-query-rdf-files.sparql diff --git a/doc/fs-test.sparql b/docs/examples/fs-test.sparql similarity index 100% rename from doc/fs-test.sparql rename to docs/examples/fs-test.sparql diff --git a/doc/hashbang.sparql b/docs/examples/hashbang.sparql similarity index 100% rename from doc/hashbang.sparql rename to docs/examples/hashbang.sparql diff --git a/doc/io.sparql b/docs/examples/io.sparql similarity index 100% rename from doc/io.sparql rename to docs/examples/io.sparql diff --git a/doc/json-by-index.sparql b/docs/examples/json-by-index.sparql similarity index 100% rename from doc/json-by-index.sparql rename to docs/examples/json-by-index.sparql diff --git a/doc/json-hello-world.sparql b/docs/examples/json-hello-world.sparql similarity index 100% rename from doc/json-hello-world.sparql rename to docs/examples/json-hello-world.sparql diff --git a/doc/json-path-inline.sparql b/docs/examples/json-path-inline.sparql similarity index 100% rename from doc/json-path-inline.sparql rename to docs/examples/json-path-inline.sparql diff --git a/doc/json-path1.sparql b/docs/examples/json-path1.sparql similarity index 100% rename from doc/json-path1.sparql rename to docs/examples/json-path1.sparql diff --git a/doc/json-unnest-by-index.sparql b/docs/examples/json-unnest-by-index.sparql similarity index 100% rename from doc/json-unnest-by-index.sparql rename to docs/examples/json-unnest-by-index.sparql diff --git a/doc/json-unnest.sparql b/docs/examples/json-unnest.sparql similarity index 100% rename from doc/json-unnest.sparql rename to docs/examples/json-unnest.sparql diff --git a/doc/json-zip-arrays.sparql b/docs/examples/json-zip-arrays.sparql similarity index 100% rename from doc/json-zip-arrays.sparql rename to docs/examples/json-zip-arrays.sparql diff --git a/doc/test-zip-arrays.sparql b/docs/examples/test-zip-arrays.sparql similarity index 100% rename from doc/test-zip-arrays.sparql rename to docs/examples/test-zip-arrays.sparql diff --git a/doc/test.nt b/docs/examples/test.nt similarity index 100% rename from doc/test.nt rename to docs/examples/test.nt diff --git a/doc/test.sparql b/docs/examples/test.sparql similarity index 100% rename from doc/test.sparql rename to docs/examples/test.sparql diff --git a/doc/test2.sparql b/docs/examples/test2.sparql similarity index 100% rename from doc/test2.sparql rename to docs/examples/test2.sparql diff --git a/doc/test3.sparql b/docs/examples/test3.sparql similarity index 100% rename from doc/test3.sparql rename to docs/examples/test3.sparql diff --git a/doc/test4.sparql b/docs/examples/test4.sparql similarity index 100% rename from doc/test4.sparql rename to docs/examples/test4.sparql diff --git a/doc/url-local-file.sparql b/docs/examples/url-local-file.sparql similarity index 100% rename from doc/url-local-file.sparql rename to docs/examples/url-local-file.sparql diff --git a/doc/workloads.sparql b/docs/examples/workloads.sparql similarity index 100% rename from doc/workloads.sparql rename to docs/examples/workloads.sparql diff --git a/doc/xml-attribute.sparql b/docs/examples/xml-attribute.sparql similarity index 100% rename from doc/xml-attribute.sparql rename to docs/examples/xml-attribute.sparql diff --git a/doc/xml-unnest.sparql b/docs/examples/xml-unnest.sparql similarity index 100% rename from doc/xml-unnest.sparql rename to docs/examples/xml-unnest.sparql diff --git a/docs/graphql/demo.md b/docs/graphql/demo.md index b664699..89e0444 100644 --- a/docs/graphql/demo.md +++ b/docs/graphql/demo.md @@ -1,6 +1,6 @@ --- title: Online demo -parent: GraphQL +parent: GraphQL over SPARQL nav_order: 90 layout: default --- @@ -10,5 +10,7 @@ Inspect the source code to see the underlying queries. * A simple [WikiData Movies Browser.](https://smartdataanalytics.github.io/RdfProcessingToolkit/demos/movies/). This is a HTML one-pager that queries the GraphQL endpoint of a demo RPT instance loaded with movies from Wikidata. -* A simple [GraphQL-to-GeoJSON Demo.](https://smartdataanalytics.github.io/RdfProcessingToolkit/demos/leaflet-graphql/). This is a HTML one-pager that uses GraphQL to transform GeoSPARQL data to a customizable GeoJSON structure. +* A simple [GraphQL-to-GeoJSON Demo.](https://smartdataanalytics.github.io/RdfProcessingToolkit/demos/leaflet-graphql/). This is a HTML one-pager that uses GraphQL to transform GeoSPARQL data to a customizable GeoJSON structure. It also demonstrates: + * Ad-hoc simplification of GeoSPARQL polygons using our `geof:simplifyDp` extension function. + * Use of caching cardinalities of properties across a dataset using `SERVICE `, which is part of Apache Jena's [Service Enhancer extension](https://jena.apache.org/documentation/query/service_enhancer.html). diff --git a/docs/graphql/index.md b/docs/graphql/index.md index 2d3c309..6b17592 100644 --- a/docs/graphql/index.md +++ b/docs/graphql/index.md @@ -1,5 +1,5 @@ --- -title: GraphQL +title: GraphQL over SPARQL has_children: true nav_order: 100 layout: default diff --git a/docs/graphql/reference/index-directive.md b/docs/graphql/reference/index-directive.md index 091de7f..f473ccb 100644 --- a/docs/graphql/reference/index-directive.md +++ b/docs/graphql/reference/index-directive.md @@ -1,6 +1,6 @@ --- title: index -parent: GraphQL +parent: GraphQL over SPARQL nav_order: 150 layout: default --- diff --git a/docs/graphql/reference/join.md b/docs/graphql/reference/join.md index 66aa004..20a51e9 100644 --- a/docs/graphql/reference/join.md +++ b/docs/graphql/reference/join.md @@ -1,6 +1,6 @@ --- title: join -parent: Reference +parent: GraphQL over SPARQL nav_order: 140 layout: default --- @@ -18,7 +18,7 @@ While implicit joins automatically connect a parent’s target variables with a #### Arguments - **`parent`** (`String | [String]`): Specifies the parent field's variable(s) to be joined. -- **`this`** (`String | [String]`): Specifies the child field's variable(s) that should be connected with the parent’s variable(s). +- **`this`** (`String | [String]`): Specifies `this` field's variable(s) that should be connected with its parent’s variable(s). #### Usage diff --git a/docs/graphql/reference/one-and-many.md b/docs/graphql/reference/one-and-many.md index 378d8b6..3f77604 100644 --- a/docs/graphql/reference/one-and-many.md +++ b/docs/graphql/reference/one-and-many.md @@ -1,13 +1,13 @@ --- title: one and many -parent: GraphQL +parent: GraphQL over SPARQL nav_order: 130 layout: default --- ## GraphQL Directives: `@one` and `@many` -The `@one` and `@many` directives control the cardinality of a field within a GraphQL schema. These directives are particularly useful in RDF and SPARQL-based contexts, where fields often correspond to graph patterns that involve relationships with varying cardinalities. +The `@one` and `@many` directives control the cardinality of a field within a GraphQL query or schema. These directives are particularly useful in RDF and SPARQL-based contexts, where fields often correspond to graph patterns that involve relationships with varying cardinalities. ### Purpose diff --git a/docs/graphql/reference/prefix.md b/docs/graphql/reference/prefix.md index 7013281..f0dd78f 100644 --- a/docs/graphql/reference/prefix.md +++ b/docs/graphql/reference/prefix.md @@ -1,13 +1,13 @@ --- title: prefix -parent: GraphQL +parent: GraphQL over SPARQL nav_order: 100 layout: default --- ## GraphQL Directive: `@prefix` -The `@prefix` directive is designed to manage and define namespace prefixes in a GraphQL schema. This directive can be used to either specify a single prefix with an IRI or map multiple prefixes to their corresponding IRIs. +The `@prefix` directive is designed to manage and define namespace prefixes in a GraphQL query or schema. This directive can be used to either specify a single prefix with an IRI or map multiple prefixes to their corresponding IRIs. ### Usage @@ -32,25 +32,26 @@ The `@prefix` directive accepts two possible configurations: { field @prefix(name: "rdf", iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#") + @prefix(name: "owl", iri: "http://www.w3.org/2002/07/owl#") } ``` 2. **Multiple Prefix Mapping** - Define multiple prefixes using the `map` argument: + Define multiple prefixes using the `map` argument. As GraphQL does not allow the empty string `""` as a key, the `name/iri` form can be used in conjunction with map: ```graphql + query MyQuery + @prefix(map: { + rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#", + rdfs: "http://www.w3.org/2000/01/rdf-schema#" + }, name: "", iri: "http://my.domain/ontology/) { - field - @prefix(map: { - rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#", - rdfs: "http://www.w3.org/2000/01/rdf-schema#" - }) + # ... } ``` #### Notes - When using the `map` argument, you can define multiple prefix-to-IRI mappings in a single directive instance. -- The `name` and `iri` arguments should not be used together with the `map` argument; choose one configuration based on your needs. diff --git a/docs/integrate/canned-queries.md b/docs/integrate/canned-queries.md index 083fcde..234ff61 100644 --- a/docs/integrate/canned-queries.md +++ b/docs/integrate/canned-queries.md @@ -1,7 +1,7 @@ --- title: Canned Queries parent: RDF/SPARQL Processing -nav_order: 10 +nav_order: 30 layout: default --- diff --git a/docs/integrate/sparql-extensions.md b/docs/integrate/sparql-extensions.md new file mode 100644 index 0000000..2b9efae --- /dev/null +++ b/docs/integrate/sparql-extensions.md @@ -0,0 +1,13 @@ +--- +title: SPARQL Extensions +nav_order: 20 +layout: default +--- + +## SPARQL Extensions +RPT's SPARQL extensions are provided by our unofficial [JenaX Jena eXtenions project](https://scaseco.github.io/jenax/). + +* A function reference is available at [http://jsa.aksw.org/fn/](http://jsa.aksw.org/fn/). + Note, that the functions are being consolidated into the new `norse` (Not Only Rdf Sparql Extensions) namespace `norse: `. +* Additional extensions are detailed at our [JenaX ARQ Plugins documentation](https://scaseco.github.io/jenax/jenax-arq-parent/jenax-arq-plugins-parent/README.html). +