You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@jena.apache.org by GitBox <gi...@apache.org> on 2021/11/15 19:56:39 UTC
[GitHub] [jena-site] afs opened a new pull request #79: More documentation
afs opened a new pull request #79:
URL: https://github.com/apache/jena-site/pull/79
* Examples moved
* xloader linked in
* Query execution building and substitution
This aligns with PR apache/jena#1110.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [jena-site] kinow commented on a change in pull request #79: More documentation
Posted by GitBox <gi...@apache.org>.
kinow commented on a change in pull request #79:
URL: https://github.com/apache/jena-site/pull/79#discussion_r762622539
##########
File path: source/documentation/sparql-apis/__index.md
##########
@@ -89,26 +89,59 @@ objects have been removed.
* Deprecate modifying `QueryExecution` after it is built.
-* Parameterization for remote queries.
- Parameterization - replacing variables by values before sending
- a query - makes the query into a template. The same applies to updates.
- This is also provided uniformly for local queries and should be used in
- preference to the local-only "initial binding" approach which is
- similarly but not identical.
+* Substitution of variables for concrete values in query and update execution.
+ This is a form of paramterization that works in both local and remnote usage
+ (unlike "intial bindings" which are only available for lcoal query execution).
Review comment:
s/lcoal/local
##########
File path: source/documentation/sparql-apis/__index.md
##########
@@ -89,26 +89,59 @@ objects have been removed.
* Deprecate modifying `QueryExecution` after it is built.
-* Parameterization for remote queries.
- Parameterization - replacing variables by values before sending
- a query - makes the query into a template. The same applies to updates.
- This is also provided uniformly for local queries and should be used in
- preference to the local-only "initial binding" approach which is
- similarly but not identical.
+* Substitution of variables for concrete values in query and update execution.
+ This is a form of paramterization that works in both local and remnote usage
Review comment:
Also s/remnote/remote
##########
File path: source/documentation/sparql-apis/__index.md
##########
@@ -89,26 +89,59 @@ objects have been removed.
* Deprecate modifying `QueryExecution` after it is built.
-* Parameterization for remote queries.
- Parameterization - replacing variables by values before sending
- a query - makes the query into a template. The same applies to updates.
- This is also provided uniformly for local queries and should be used in
- preference to the local-only "initial binding" approach which is
- similarly but not identical.
+* Substitution of variables for concrete values in query and update execution.
+ This is a form of paramterization that works in both local and remnote usage
Review comment:
s/paramterization/parameterization (I think)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [jena-site] kinow commented on a change in pull request #79: More documentation
Posted by GitBox <gi...@apache.org>.
kinow commented on a change in pull request #79:
URL: https://github.com/apache/jena-site/pull/79#discussion_r762622838
##########
File path: source/documentation/tdb/faqs.md
##########
@@ -18,6 +19,15 @@ title: TDB FAQs
- [What is the *Unable to check TDB lock owner, the lock file contents appear to be for a TDB2 database. Please try loading this location as a TDB2 database* error?](#tdb2-lock)
- [My question isn't answered here?](#not-answered)
+<a name="tdb1-tdb2></a>
+## TDB1 and TDB2
+
+TDB2 is a later generation of database for Jena. It is more robust and can
+handle large update transactions.
+
+These are different databases systems - the have different on-disk file formats
Review comment:
s/the have/they have ?
##########
File path: source/documentation/sparql-apis/__index.md
##########
@@ -89,26 +89,59 @@ objects have been removed.
* Deprecate modifying `QueryExecution` after it is built.
-* Parameterization for remote queries.
- Parameterization - replacing variables by values before sending
- a query - makes the query into a template. The same applies to updates.
- This is also provided uniformly for local queries and should be used in
- preference to the local-only "initial binding" approach which is
- similarly but not identical.
+* Substitution of variables for concrete values in query and update execution.
+ This is a form of paramterization that works in both local and remnote usage
+ (unlike "intial bindings" which are only available for lcoal query execution).
+ See the [substitution section](#substitution) section below.
* `HttpOp`, using `java.net.http.HttpClient`, is split into `HttpRDF` for
GET/POST/PUT/DELETE of graphs and datasets and new `HttpOp` for packaged-up
common patterns of HTTP usage.
* The previous `HttpOp` is available as `HttpOp1` and Apache HttpClient is still
- a dependency. Eventually, `HttpOp`` and dependecy on Apache HttpClient will be removed.
+ a dependency. Eventually, `HttpOp` and dependency on Apache HttpClient will be removed.
* GSP - support for dataset operations as well as graphs (also supported by Fuseki).
* `DatasetAccessor`s removed - previously these were deprecated. `GSP` and
`ModelStore` are the replacement for remote operations. `RDFConnection` and
`RDFLink` provide APIs.
+## Substitution
+
+All query and update builders provide operations to use a query and substitute
+variables for concrete RDF terms in the execution.
+
+Unlike "initial bindings" substitution is provided in query and update builders
+for both local and remote cases.
+
+Substitution is always "replace variable with RDF term" in a query or update
+that is correct syntax. This means is does not apply to `INSERT DATA` or `DELETE
+DATA` but can be used with `INSERT { ?s ?p ?o } WHERE {}` and
+`DELETE { ?s ?p ?o } WHERE {}`.
+
+Full example:
+[ExQuerySubstitute_01.java](https://github.com/apache/jena/tree/main/jena-examples/src/main/java/arq/examples/ExQuerySubstitute_01.java).
+
+```
+ ResultSet resultSet1 = QueryExecution.dataset(dataset)
+ .query(prefixes+"SELECT * { ?person foaf:name ?name }")
+ .substitution("name", name1)
+ .select();
+ ResultSetFormatter.out(resultSet1);
+```
+
+Substitution is to be preferred over "initial bindings" because it is clearly
+defined and applies to both query and update in both local and remote uses.
+
+"Substitution" and "initial bindings" are similar but not identical.
+
+See also
+* [Parameterized Queries](documentation/query/parameterized-sparql-strings.html)
+* [Jena Query Builder](https://jena.apache.org/documentation/extras/querybuilder/index.html)
+
+which provide a different ways to build a query.
Review comment:
s/a different ways/a different way (or /different ways/)
##########
File path: source/documentation/sparql-apis/__index.md
##########
@@ -89,26 +89,59 @@ objects have been removed.
* Deprecate modifying `QueryExecution` after it is built.
-* Parameterization for remote queries.
- Parameterization - replacing variables by values before sending
- a query - makes the query into a template. The same applies to updates.
- This is also provided uniformly for local queries and should be used in
- preference to the local-only "initial binding" approach which is
- similarly but not identical.
+* Substitution of variables for concrete values in query and update execution.
+ This is a form of paramterization that works in both local and remnote usage
+ (unlike "intial bindings" which are only available for lcoal query execution).
+ See the [substitution section](#substitution) section below.
* `HttpOp`, using `java.net.http.HttpClient`, is split into `HttpRDF` for
GET/POST/PUT/DELETE of graphs and datasets and new `HttpOp` for packaged-up
common patterns of HTTP usage.
* The previous `HttpOp` is available as `HttpOp1` and Apache HttpClient is still
- a dependency. Eventually, `HttpOp`` and dependecy on Apache HttpClient will be removed.
+ a dependency. Eventually, `HttpOp` and dependency on Apache HttpClient will be removed.
* GSP - support for dataset operations as well as graphs (also supported by Fuseki).
* `DatasetAccessor`s removed - previously these were deprecated. `GSP` and
`ModelStore` are the replacement for remote operations. `RDFConnection` and
`RDFLink` provide APIs.
+## Substitution
+
+All query and update builders provide operations to use a query and substitute
+variables for concrete RDF terms in the execution.
+
+Unlike "initial bindings" substitution is provided in query and update builders
+for both local and remote cases.
+
+Substitution is always "replace variable with RDF term" in a query or update
+that is correct syntax. This means is does not apply to `INSERT DATA` or `DELETE
Review comment:
s/This means is/This means it
##########
File path: source/documentation/tdb/tdb-xloader.md
##########
@@ -30,22 +34,24 @@ or
`tdb1.xloader --loc DIRECTORY` FILE...
-Additioally, there is an argument `--tmpdir` to use a different directory for
+Additionally, there is an argument `--tmpdir` to use a different directory for
temporary files.
-`FILE` is any RDF syntax supported by Jena.
+`FILE` is any RDF syntax supported by Jena. Syntax is detemined by file
+extension and can include an addtional ".gz" or ".bz2" for compresses files.
Review comment:
s/compresses/compressed ?
##########
File path: source/documentation/tdb/tdb-xloader.md
##########
@@ -30,22 +34,24 @@ or
`tdb1.xloader --loc DIRECTORY` FILE...
-Additioally, there is an argument `--tmpdir` to use a different directory for
+Additionally, there is an argument `--tmpdir` to use a different directory for
temporary files.
-`FILE` is any RDF syntax supported by Jena.
+`FILE` is any RDF syntax supported by Jena. Syntax is detemined by file
+extension and can include an addtional ".gz" or ".bz2" for compresses files.
### Advice
-`xloader` uses a lot of temporary disk space.
-
To avoid a load failing due to a syntax or other data error, it is advisable to
run `riot --check` on the data first. Parsing is faster than loading.
-If desired, the data can be converted to [RDF Thrift](../io/rdf-binary.html) at
-this stage by adding `--stream rdf-thrift` to the riot checking run.
-Parsing RDF Thrift is faster than parsing N-Triples although the bulk of the loading process is not limited by parser speed.
+The TDB databases will take up a lot of disk space and in addition during
+loading `xloader` uses a significant amout of temporary disk space.
Review comment:
s/amout/amount
##########
File path: source/documentation/tdb/tdb-xloader.md
##########
@@ -30,22 +34,24 @@ or
`tdb1.xloader --loc DIRECTORY` FILE...
-Additioally, there is an argument `--tmpdir` to use a different directory for
+Additionally, there is an argument `--tmpdir` to use a different directory for
temporary files.
-`FILE` is any RDF syntax supported by Jena.
+`FILE` is any RDF syntax supported by Jena. Syntax is detemined by file
Review comment:
s/detemined/determined
##########
File path: source/documentation/tdb/tdb-xloader.md
##########
@@ -3,20 +3,24 @@ title: TDB xloader
---
TDB xloader ("x" for external) is a bulkloader for very large datasets. The goal
-is stability and reliability for long running loading, running on modest and
+is stability and reliability for long running loading, running on modest
+hardware and can load to storage of rotating disk or SSD.
Review comment:
I didn't understand the "can load to storage of rotating disk", but might be just lack of coffee :coffee: :laughing:
##########
File path: source/documentation/sparql-apis/__index.md
##########
@@ -89,26 +89,59 @@ objects have been removed.
* Deprecate modifying `QueryExecution` after it is built.
-* Parameterization for remote queries.
- Parameterization - replacing variables by values before sending
- a query - makes the query into a template. The same applies to updates.
- This is also provided uniformly for local queries and should be used in
- preference to the local-only "initial binding" approach which is
- similarly but not identical.
+* Substitution of variables for concrete values in query and update execution.
+ This is a form of paramterization that works in both local and remnote usage
+ (unlike "intial bindings" which are only available for lcoal query execution).
Review comment:
Also s/intial/initial
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [jena-site] afs commented on pull request #79: More documentation
Posted by GitBox <gi...@apache.org>.
afs commented on pull request #79:
URL: https://github.com/apache/jena-site/pull/79#issuecomment-986319624
@kinow - thanks for the prompt review.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [jena-site] afs merged pull request #79: More documentation
Posted by GitBox <gi...@apache.org>.
afs merged pull request #79:
URL: https://github.com/apache/jena-site/pull/79
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [jena-site] rvesse commented on a change in pull request #79: More documentation
Posted by GitBox <gi...@apache.org>.
rvesse commented on a change in pull request #79:
URL: https://github.com/apache/jena-site/pull/79#discussion_r750082483
##########
File path: source/documentation/tdb/faqs.md
##########
@@ -77,11 +88,22 @@ As noted above to resolve this problem you **must** rebuild your database from t
be repaired. This is why we **strongly** recommend you use [transactions](tdb_transactions.html) since this protects your dataset against
corruption.
+## What is `tdb.xloader`?
+
+`tdb1.xloader` and `tdb2.xloader` are bulk laodrs for very large dataset that
Review comment:
Typo `laodrs` -> `loaders`
Also `dataset` should be `datasets`
##########
File path: source/documentation/tdb/faqs.md
##########
@@ -4,6 +4,8 @@ title: TDB FAQs
## FAQs
+
+- [What are TDB1 and TDB2?](#tdv1-tdb2)
Review comment:
Typo in anchor link `tdv1` -> `tdb1`
##########
File path: source/documentation/sparql-apis/__index.md
##########
@@ -109,6 +107,41 @@ objects have been removed.
`ModelStore` are the replacement for remote operations. `RDFConnection` and
`RDFLink` provide APIs.
+## Substitution
+
+All query and update builders provide operations to uses a query and substitute
Review comment:
Typo - `uses` -> `use`
##########
File path: source/documentation/tdb/tdb-xloader.md
##########
@@ -7,16 +7,19 @@ is stability and reliability for long running loading, running on modest and
xloader is not a replacement for regular TDB1 and TDB2 loaders.
-"tdb1.xloader" was called "tdbloader2" and has some improvements.
+There are two scripts to load data using the xlaoder subsystem.
+
+"tdb1.xloader", which was called "tdbloader2" and has some improvements.
It is not as fast as other TDB loaders on dataset where the general loaders work
on without encountering progressive slowdown.
-The xloaders for TDB1 and TDB2 are not identical. The TDB2 is more capable; it
-is based on the same design approach with further refinements to building the
-node table and to reduce the total amount of temporary file space used.
+The xloaders for TDB1 and TDB2 are not identical. The TDB2 xlaoder is more
Review comment:
Typo `xlaoder` -> `xloader`
##########
File path: source/documentation/tdb/tdb-xloader.md
##########
@@ -7,16 +7,19 @@ is stability and reliability for long running loading, running on modest and
xloader is not a replacement for regular TDB1 and TDB2 loaders.
-"tdb1.xloader" was called "tdbloader2" and has some improvements.
+There are two scripts to load data using the xlaoder subsystem.
Review comment:
Typo `xlaoder` -> `xloader`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [jena-site] afs commented on a change in pull request #79: More documentation
Posted by GitBox <gi...@apache.org>.
afs commented on a change in pull request #79:
URL: https://github.com/apache/jena-site/pull/79#discussion_r762630497
##########
File path: source/documentation/tdb/tdb-xloader.md
##########
@@ -3,20 +3,24 @@ title: TDB xloader
---
TDB xloader ("x" for external) is a bulkloader for very large datasets. The goal
-is stability and reliability for long running loading, running on modest and
+is stability and reliability for long running loading, running on modest
+hardware and can load to storage of rotating disk or SSD.
Review comment:
Or too much coffee (in my timezone)!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org