This is an automated email from the ASF dual-hosted git repository. andy pushed a commit to branch more-doc in repository https://gitbox.apache.org/repos/asf/jena-site.git
commit 8ea1cfb48a416119238be0d43658555c3569f9d6 Author: Andy Seaborne <[email protected]> AuthorDate: Mon Nov 15 17:04:25 2021 +0000 Query building substitution() --- .gitignore | 3 +- source/documentation/query/arq-query-eval.md | 1 - source/documentation/sparql-apis/__index.md | 47 +++++++++++++++++++++++----- 3 files changed, 42 insertions(+), 9 deletions(-) diff --git a/.gitignore b/.gitignore index 3fb554e..2495e8f 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ target/ .vscode +.#* .hugo* # IntelliJ generated @@ -11,4 +12,4 @@ target/ .java-version # Hugo -.hugo_build.lock \ No newline at end of file +.hugo_build.lock diff --git a/source/documentation/query/arq-query-eval.md b/source/documentation/query/arq-query-eval.md index 4527ea3..51e4ceb 100644 --- a/source/documentation/query/arq-query-eval.md +++ b/source/documentation/query/arq-query-eval.md @@ -446,7 +446,6 @@ custom query engine and overriding `QueryEngineMain.modifyOp`: @Override protected Op modifyOp(Op op) { - // Cope with initial bindings. op = Substitute.substitute(op, initialInput) ; // Use standard optimizations. op = super.modifyOp(op) ; diff --git a/source/documentation/sparql-apis/__index.md b/source/documentation/sparql-apis/__index.md index d26d8d3..67e148f 100644 --- a/source/documentation/sparql-apis/__index.md +++ b/source/documentation/sparql-apis/__index.md @@ -3,7 +3,7 @@ title: Apache Jena SPARQL APIs slug: index --- -Jump to "[Changes](#changes)". +Jump to the "[Changes](#changes)" section. ## Overview @@ -89,12 +89,10 @@ 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 @@ -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 +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/afs/jena/tree/main/jena-arq/src-examples/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. + ## <tt>RDFConnection</tt> [RDFConnection](../rdfconnection/)
