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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
