Return-Path: X-Original-To: apmail-incubator-jena-commits-archive@minotaur.apache.org Delivered-To: apmail-incubator-jena-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 9D90D9687 for ; Sat, 5 Nov 2011 01:11:11 +0000 (UTC) Received: (qmail 26154 invoked by uid 500); 5 Nov 2011 01:11:11 -0000 Delivered-To: apmail-incubator-jena-commits-archive@incubator.apache.org Received: (qmail 26131 invoked by uid 500); 5 Nov 2011 01:11:11 -0000 Mailing-List: contact jena-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: jena-dev@incubator.apache.org Delivered-To: mailing list jena-commits@incubator.apache.org Received: (qmail 26124 invoked by uid 99); 5 Nov 2011 01:11:11 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 05 Nov 2011 01:11:11 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 05 Nov 2011 01:10:59 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 1A9D82388978; Sat, 5 Nov 2011 01:10:37 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r1197854 - in /incubator/jena/site/trunk: content/jena/tutorials/ content/jena/tutorials/sparql_data/ templates/ Date: Sat, 05 Nov 2011 01:10:35 -0000 To: jena-commits@incubator.apache.org From: ijd@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20111105011037.1A9D82388978@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: ijd Date: Sat Nov 5 01:10:34 2011 New Revision: 1197854 URL: http://svn.apache.org/viewvc?rev=1197854&view=rev Log: Added SPARQL tutorial material to tutorials section Added: incubator/jena/site/trunk/content/jena/tutorials/index.mdtext incubator/jena/site/trunk/content/jena/tutorials/rdf_api.mdtext - copied unchanged from r1197589, incubator/jena/site/trunk/content/jena/tutorials/index.mdtext incubator/jena/site/trunk/content/jena/tutorials/sparql_basic_patterns.mdtext incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ incubator/jena/site/trunk/content/jena/tutorials/sparql_data.mdtext incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-dft.ttl incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-ng-1.ttl incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-ng-2.ttl incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp1.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp2.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp3.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp4.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-1.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-2.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-3.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-4.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-5.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-f1.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-f2.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt1.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt2.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt3.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt4.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union1.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union1alt.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union2.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union3.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q1.rq incubator/jena/site/trunk/content/jena/tutorials/sparql_data/vc-db-3.ttl incubator/jena/site/trunk/content/jena/tutorials/sparql_datasets.mdtext incubator/jena/site/trunk/content/jena/tutorials/sparql_filters.mdtext incubator/jena/site/trunk/content/jena/tutorials/sparql_optionals.mdtext incubator/jena/site/trunk/content/jena/tutorials/sparql_page.mdtext incubator/jena/site/trunk/content/jena/tutorials/sparql_query1.mdtext incubator/jena/site/trunk/content/jena/tutorials/sparql_results.mdtext incubator/jena/site/trunk/content/jena/tutorials/sparql_union.mdtext Modified: incubator/jena/site/trunk/content/jena/tutorials/sparql.mdtext incubator/jena/site/trunk/templates/sidenav.mdtext Added: incubator/jena/site/trunk/content/jena/tutorials/index.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/index.mdtext?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/index.mdtext (added) +++ incubator/jena/site/trunk/content/jena/tutorials/index.mdtext Sat Nov 5 01:10:34 2011 @@ -0,0 +1,9 @@ +Title: Jena tutorials + +The following tutorials take a step-by-step approach to explaining aspects of +RDF and linked-data applications programming in Jena. For a more task-oriented +description, please see the [getting started](/jena/getting_started/) guide. + +- [RDF core API tutorial](rdf_api.html) +- [SPARQL tutorial](sparql.html) +- [Using Jena with Eclipse](using_jena_with_eclipse.html) Modified: incubator/jena/site/trunk/content/jena/tutorials/sparql.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql.mdtext?rev=1197854&r1=1197853&r2=1197854&view=diff ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql.mdtext (original) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql.mdtext Sat Nov 5 01:10:34 2011 @@ -1,3 +1,47 @@ -Title: SPARQL tutorial +Title: SPARQL Tutorial -Coming soon. +The objective of this SPARQL tutorial is to give a fast course in +SPARQL. The tutorial covers the major features of the query +language through examples but does not aim to be complete. + +If you are looking for a short introduction to SPARQL and Jena try +[Search RDF data with SPARQL](http://www.ibm.com/developerworks/xml/library/j-sparql/) + +SPARQL is a +[query language](http://www.w3.org/TR/rdf-sparql-query/) and a +[protocol](http://www.w3.org/TR/rdf-sparql-protocol/) for accessing +RDF designed by the +[W3C RDF Data Access Working Group](http://www.w3.org/2001/sw/DataAccess/).  + +As a query language, SPARQL is "data-oriented" in that it only +queries the information held in the models; there is no inference +in the query language itself.  Of course, the Jena model may be +'smart' in that it provides the impression that certain triples +exist by creating them on-demand, including OWL reasoning.  SPARQL +does not do anything other than take the description of what the +application wants, in the form of a query, and returns that +information, in the form of a set of bindings or an RDF graph. + +## SPARQL tutorial + +1. [Preliminaries: data!](sparql_data.html) +2. [Executing a simple query](sparql_query1.html) +3. [Basic patterns](sparql_basic_patterns.html) +4. [Value constraints](sparql_filters.html) +5. [Optional information](sparql_optionals.html) +6. [Alternatives](sparql_union.html) +7. [Named Graphs](sparql_datasets.html) +8. [Results](sparql_results.html) + +## Other Material + +- The + [SPARQL query language definition document](http://www.w3.org/TR/rdf-sparql-query/) + itself contains many examples. +- [Search RDF data with SPARQL](http://www.ibm.com/developerworks/xml/library/j-sparql/) + (by Phil McCarthy) - article published on IBM developer works about + SPARQL and Jena. +- [SPARQL reference card](http://www.ilrt.bris.ac.uk/people/cmdjb/2005/04-sparql/) + (by [Dave Beckett](http://www.ilrt.bristol.ac.uk/people/cmdjb/)) + +Detailed [ARQ documentation](/jena/documentation/sparql) Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_basic_patterns.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_basic_patterns.mdtext?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_basic_patterns.mdtext (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_basic_patterns.mdtext Sat Nov 5 01:10:34 2011 @@ -0,0 +1,116 @@ +Title: SPARQL Tutorial - Basic Patterns + +This section covers basic patterns and solutions, the main building +blocks of SPARQL queries. + +## Solutions + +Query solutions are a set of pairs of a variable name with a value. +A `SELECT` query directly exposes the solutions (after +order/limit/offset are applied) as the result set - other query +forms use the solutions to make an graph. The solution is the way +the pattern matched - which values the variables must take for a +pattern to match. + +The first query example had a single solution. Change the pattern +to this second query: ([q-bp1.rq](sparql_data/q-bp1.rq)): + + SELECT ?x ?fname + WHERE {?x ?fname} + +This has 4 solutions, one for each VCARD name property triples in +the data source + + ---------------------------------------------------- + | x | name | + ==================================================== + | | "Becky Smith" | + | | "Sarah Jones" | + | | "John Smith" | + | | "Matt Jones" | + ---------------------------------------------------- + +So far, with triple patterns and basic patterns, every variable +will be defined in every solution. The solutions to a query can be +thought of a table, but in the general case, it is a table where +not every row will have a value for every column. All the solutions +to a given SPARQL query don't have to have values for all the +variables in every solution as we shall see later. + +## Basic Patterns + +A basic pattern is a set of triple patterns. It matches when the +triple patterns all match with the same value used each time the +variable with the same name is used. + + SELECT ?givenName + WHERE + { ?y "Smith" . + ?y ?givenName . + } + +This query ([q-bp2.rq](sparql_data/q-bp2.rq))involves two triple patterns, each +triple ends in a '.' (but the dot after the last one can be omitted +like it was in the one triple pattern example). The variable y has +to be the same for each triple pattern match. The the solutions +are: + + ------------- + | givenName | + ============= + | "John" | + | "Rebecca" | + ------------- + +### QNames + +There is shorthand mechanism for writing long URIs using prefixes. +The query above is more clearly written as the query +([q-bp3.rq](sparql_data/q-bp3.rq)): + + PREFIX vcard: + + SELECT ?givenName + WHERE + { ?y vcard:Family "Smith" . + ?y vcard:Given ?givenName . + } + +This is a prefixing mechanism - the two parts of the URIs, from the +prefix declaration and from the part after the ":" in the qname, +are concatenated together. This is strictly not what an XML qname +is but uses the RDF rule for turning a qname into a URI by +concatenating the parts. + +### Blank Nodes + +Change the query just a little to return y as well +([q-bp4.rq](q-bp4.rq)) : + + PREFIX vcard: + + SELECT ?y ?givenName + WHERE + { ?y vcard:Family "Smith" . + ?y vcard:Given ?givenName . + } + +and the blank nodes appear + + -------------------- + | y | givenName | + ==================== + | _:b0 | "John" | + | _:b1 | "Rebecca" | + -------------------- + +as odd looking qnames starting \_:. This isn't the internal label +for the blank node - it is ARQ printing them out that assigned the +\_:b0, \_:b1 to show when two blank nodes are the same. Here they +are different. It does not reveal the internal label used for the +blank node although that is available when using the Java API. + +[Next: Filters](sparql_filters.html) + + + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data.mdtext?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data.mdtext (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data.mdtext Sat Nov 5 01:10:34 2011 @@ -0,0 +1,102 @@ +Title: SPARQL Tutorial - Data Formats + +First, we need to be clear about what data is being queried. SPARQL +queries RDF graphs. An RDF graph is a set of triples (Jena calls +RDF graphs "models" and triples "statements" because that is what +they were called at the time the Jena API was first designed). + +It is important to realize that it is the triples that matter, not +the serialization. The serialization is just a way to write the +triples down. RDF/XML is the W3C recommendation but it can +difficult to see the triples in this serialized becuae ethere are +multiple ways to encode the same graph.  In this tutorial, we use a +more "triple-like" serialization, called +[Turtle](http://www.ilrt.bris.ac.uk/discovery/2004/01/turtle/) (see +also N3 language described in the +[W3C semantic web primer](http://www.w3.org/2000/10/swap/Primer)). + +We will start with the simple data in [vc-db-1.rdf](sparql_data/vc-db-1.rdf): +this file contains RDF for a number of vCard descriptions of +people.  vCards are described in +[RFC2426](http://www.ietf.org/rfc/rfc2426.txt) and the RDF +translation is described in the W3C note +"[Representing vCard Objects in RDF/XML](http://www.w3.org/TR/vcard-rdf.html)".  +Our example database just contains some name information. + +Graphically, the data looks like: + +![Graph of the vCard database](/jena/images/vc-db.png "Graph of the vCard database") + +In triples, this might look like: + + @prefix vCard: . + @prefix rdf: . + @prefix : <#> . + + + vCard:FN "Matt Jones" ; + vCard:N [ vCard:Family + "Jones" ; + vCard:Given + "Matthew" + ] . + + + vCard:FN "Becky Smith" ; + vCard:N [ vCard:Family + "Smith" ; + vCard:Given + "Rebecca" + ] . + + + vCard:FN "John Smith" ; + vCard:N [ vCard:Family + "Smith" ; + vCard:Given + "John" + ] . + + + vCard:FN "Sarah Jones" ; + vCard:N [ vCard:Family + "Jones" ; + vCard:Given + "Sarah" + ] . + +or even more explicitly as triples: + + @prefix vCard: . + @prefix rdf: . + + vCard:FN "Matt Jones" . + vCard:N _:b0 . + _:b0 vCard:Family "Jones" . + _:b0 vCard:Given "Matthew" . + + + vCard:FN "Becky Smith" . + vCard:N _:b1 . + _:b1 vCard:Family "Smith" . + _:b1 vCard:Given "Rebecca" . + + vCard:FN "John Smith" . + vCard:N _:b2 . + _:b2 vCard:Family "Smith" . + _:b2 vCard:Given "John" . + + vCard:FN "Sarah Jones" . + vCard:N _:b3 . + _:b3 vCard:Family "Jones" . + _:b3 vCard:Given "Sarah" . + +It is important to realize that these are the same RDF graph and +that the triples in the graph are in no particular order.  They are +just written in related groups above for the human reader - the +machine does not care. + +[Next: A Simple Query](sparql_query1.html) + + + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-dft.ttl URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-dft.ttl?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-dft.ttl (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-dft.ttl Sat Nov 5 01:10:34 2011 @@ -0,0 +1,6 @@ +@prefix dc: . +@prefix xsd: . +@prefix web: . + + dc:date "2005-07-14T03:18:56+01:00"^^xsd:dateTime . + dc:date "2005-09-22T05:53:05+01:00"^^xsd:dateTime . Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-ng-1.ttl URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-ng-1.ttl?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-ng-1.ttl (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-ng-1.ttl Sat Nov 5 01:10:34 2011 @@ -0,0 +1,4 @@ +@prefix dc: . + +[] dc:title "Harry Potter and the Philospher's Stone" . +[] dc:title "Harry Potter and the Chamber of Secrets" . Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-ng-2.ttl URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-ng-2.ttl?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-ng-2.ttl (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/ds-ng-2.ttl Sat Nov 5 01:10:34 2011 @@ -0,0 +1,4 @@ +@prefix dc: . + +[] dc:title "Harry Potter and the Sorcerer's Stone" . +[] dc:title "Harry Potter and the Chamber of Secrets" . Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp1.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp1.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp1.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp1.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,4 @@ +SELECT ?x ?name +WHERE + { ?x ?name } + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp2.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp2.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp2.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp2.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,6 @@ +SELECT ?givenName +WHERE + { ?y "Smith" . + ?y ?givenName . + } + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp3.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp3.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp3.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp3.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,8 @@ +PREFIX vcard: + +SELECT ?givenName +WHERE + { ?y vcard:Family "Smith" . + ?y vcard:Given ?givenName . + } + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp4.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp4.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp4.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-bp4.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,8 @@ +PREFIX vcard: + +SELECT ?y ?givenName +WHERE + { ?y vcard:Family "Smith" . + ?y vcard:Given ?givenName . + } + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-1.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-1.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-1.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-1.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,6 @@ +PREFIX xsd: +PREFIX dc: +PREFIX : <.> + +SELECT * +{ ?s ?p ?o } Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-2.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-2.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-2.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-2.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,8 @@ +PREFIX xsd: +PREFIX dc: +PREFIX : <.> + +SELECT * +{ + { ?s ?p ?o } UNION { GRAPH ?g { ?s ?p ?o } } +} Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-3.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-3.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-3.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-3.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,8 @@ +PREFIX dc: +PREFIX : <.> + +SELECT ?title +{ + GRAPH :ds-ng-2.ttl + { ?b dc:title ?title } +} Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-4.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-4.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-4.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-4.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,10 @@ +PREFIX xsd: +PREFIX dc: +PREFIX : <.> + +SELECT ?date ?title +{ + ?g dc:date ?date . FILTER (?date > "2005-08-01T00:00:00Z"^^xsd:dateTime ) + GRAPH ?g + { ?b dc:title ?title } +} Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-5.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-5.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-5.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-ds-5.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,11 @@ +PREFIX xsd: +PREFIX dc: +PREFIX : <.> + +SELECT * +FROM +FROM NAMED +FROM NAMED +{ + { ?s ?p ?o } UNION { GRAPH ?g { ?s ?p ?o } } +} Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-f1.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-f1.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-f1.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-f1.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,6 @@ +PREFIX vcard: + +SELECT ?g +WHERE + { ?y vcard:Given ?g . FILTER regex(?g, "r", "i") } + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-f2.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-f2.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-f2.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-f2.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,8 @@ +PREFIX info: + +SELECT ?resource +WHERE + { + ?resource info:age ?age . + FILTER (?age >= 24) + } Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt1.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt1.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt1.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt1.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,10 @@ +# Optional example +PREFIX info: +PREFIX vcard: + +SELECT ?name ?age +WHERE +{ + ?person vcard:FN ?name . + OPTIONAL { ?person info:age ?age } +} \ No newline at end of file Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt2.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt2.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt2.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt2.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,10 @@ +# Optional example +PREFIX info: +PREFIX vcard: + +SELECT ?name ?age +WHERE +{ + ?person vcard:FN ?name . + ?person info:age ?age . +} \ No newline at end of file Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt3.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt3.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt3.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt3.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,10 @@ +# Optional example +PREFIX info: +PREFIX vcard: + +SELECT ?name ?age +WHERE +{ + ?person vcard:FN ?name . + OPTIONAL { ?person info:age ?age . FILTER ( ?age > 24 ) } +} \ No newline at end of file Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt4.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt4.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt4.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-opt4.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,11 @@ +# Optional example +PREFIX info: +PREFIX vcard: + +SELECT ?name ?age +WHERE +{ + ?person vcard:FN ?name . + OPTIONAL { ?person info:age ?age . } + FILTER ( !bound(?age) || ?age > 24 ) +} \ No newline at end of file Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union1.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union1.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union1.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union1.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,8 @@ +PREFIX foaf: +PREFIX vCard: + +SELECT ?name +WHERE +{ + { [] foaf:name ?name } UNION { [] vCard:FN ?name } +} Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union1alt.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union1alt.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union1alt.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union1alt.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,9 @@ +PREFIX foaf: +PREFIX vCard: + +SELECT ?name +WHERE +{ + [] ?p ?name + FILTER (?p = foaf:name || ?p = vCard:FN) +} Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union2.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union2.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union2.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union2.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,8 @@ +PREFIX foaf: +PREFIX vCard: + +SELECT ?name1 ?name2 +WHERE +{ + { [] foaf:name ?name1 } UNION { [] vCard:FN ?name2 } +} Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union3.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union3.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union3.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q-union3.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,10 @@ +PREFIX foaf: +PREFIX vCard: + +SELECT ?name1 ?name2 +WHERE +{ + ?x a foaf:Person + OPTIONAL { ?x foaf:name ?name1 } + OPTIONAL { ?x vCard:FN ?name2 } +} Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q1.rq URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q1.rq?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q1.rq (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/q1.rq Sat Nov 5 01:10:34 2011 @@ -0,0 +1,4 @@ +SELECT ?x +WHERE + { ?x "John Smith" } + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_data/vc-db-3.ttl URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_data/vc-db-3.ttl?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_data/vc-db-3.ttl (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_data/vc-db-3.ttl Sat Nov 5 01:10:34 2011 @@ -0,0 +1,15 @@ +@prefix foaf: . +@prefix vcard: . + +_:a a foaf:Person ; + foaf:name "Matt Jones" . + +_:b a foaf:Person ; + foaf:name "Sarah Jones" . + +_:c a foaf:Person ; + vcard:FN "Becky Smith" . + +_:d a foaf:Person ; + vcard:FN "John Smith" . + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_datasets.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_datasets.mdtext?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_datasets.mdtext (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_datasets.mdtext Sat Nov 5 01:10:34 2011 @@ -0,0 +1,230 @@ +Title: SPARQL Tutorial - Datasets + +This section covers RDF Datasets - an RDF Dataset is the unit that +is queried by a SPARQL query. It consists of a default graph, and a +number of named graphs. + +## Querying datasets + +The graph matching operation +([basic patterns](sparql_basic_patterns.html), +[`OPTIONAL`s](sparql_optionals.html), and [`UNION`s](sparql_union.html)) work on +one RDF graph.  This starts out being the default graph of the +dataset but it can be changed by the `GRAPH` keyword. + GRAPH uri { ... pattern ... } + + GRAPH var { ... pattern ... } + +If a URI is given, the pattern will be matched against the graph in +the dataset with that name - if there isn't one, the `GRAPH` clause +fails to match at all. + +If a variable is given, all the named graphs (not the default +graph) are tried.  The variable may be used elsewhere so that if, +during execution, it's value is already known for a solution, only +the specific named graph is tried. + +### Example Data + +An RDF dataset can take a variety of forms.  Two common setups are +to have the default graph being the union (the RDF merge) of all +the named graphs and to have the default graph be an inventory of +the named graphs (where they came from, when they were read etc).  +There are no limitations - one graph can be included twice under +different names, or some graphs may share triples with others. + +In the examples below we will use the following dataset that might +occur for an RDF aggregator of book details: + +Default graph ([ds-dft.ttl](sparql_data/ds-dft.ttl)): + + @prefix dc: . + @prefix xsd: . + + dc:date "2005-07-14T03:18:56+0100"^^xsd:dateTime . + dc:date "2005-09-22T05:53:05+0100"^^xsd:dateTime . + +Named graph ([ds-ng-1.ttl](sparql_data/ds-ng-1.ttl)): + + @prefix dc: . + + [] dc:title "Harry Potter and the Philospher's Stone" . + [] dc:title "Harry Potter and the Chamber of Secrets" . + +Named graph ([ds-ng-2.ttl](sparql_data/ds-ng-2.ttl)): + + @prefix dc: . + + [] dc:title "Harry Potter and the Sorcerer's Stone" . + [] dc:title "Harry Potter and the Chamber of Secrets" . + +That is, we have two small graphs describing some books, and we +have a default graph which records when these graphs were last +read + +Queries can be run with the command line application (this would be +all one line): + + java -cp ... arq.sparql + --graph ds-dft.ttl --namedgraph ds-ng-1.ttl --namedgraph ds-ng-2.ttl + --query query file + +Datasets don't have to created just for the lifetime of the query.  +They can be created and stored in a database, as would be more +usual for an aggregator application. + +### Accessing the Dataset + +The first example just accesses the default graph +([q-ds-1.rq](sparql_data/q-ds-1.rq)): + + PREFIX xsd: + PREFIX dc: + PREFIX : <.> + + SELECT * + { ?s ?p ?o } + +(The "`PREFIX : <.>`"  just helps format the output) + + ---------------------------------------------------------------------- + | s | p | o | + ====================================================================== + | :ds-ng-2.ttl | dc:date | "2005-09-22T05:53:05+01:00"^^xsd:dateTime | + | :ds-ng-1.ttl | dc:date | "2005-07-14T03:18:56+01:00"^^xsd:dateTime | + ---------------------------------------------------------------------- + +This is the default graph only - nothing from the named graphs +because they aren't queried unless explicitly indicated via +`GRAPH`. + +We can query for all triples by querying the default graph and the +named graphs ([q-ds-2.rq](sparql_data/q-ds-2.rq)): + + PREFIX xsd: + PREFIX dc: + PREFIX : <.> + + SELECT * + { + { ?s ?p ?o } UNION { GRAPH ?g { ?s ?p ?o } } + } + +giving: + + --------------------------------------------------------------------------------------- + | s | p | o | g | + ======================================================================================= + | :ds-ng-2.ttl | dc:date | "2005-09-22T05:53:05+01:00"^^xsd:dateTime | | + | :ds-ng-1.ttl | dc:date | "2005-07-14T03:18:56+01:00"^^xsd:dateTime | | + | _:b0 | dc:title | "Harry Potter and the Sorcerer's Stone" | :ds-ng-2.ttl | + | _:b1 | dc:title | "Harry Potter and the Chamber of Secrets" | :ds-ng-2.ttl | + | _:b2 | dc:title | "Harry Potter and the Chamber of Secrets" | :ds-ng-1.ttl | + | _:b3 | dc:title | "Harry Potter and the Philospher's Stone" | :ds-ng-1.ttl | + --------------------------------------------------------------------------------------- + +### Querying a specific graph + +If the application knows the name graph, it can directly ask a +query such as finding all the titles in a given graph +([q-ds-3.rq](sparql_data/q-ds-3.rq)): + + PREFIX dc: + PREFIX : <.> + + SELECT ?title + { + GRAPH :ds-ng-2.ttl + { ?b dc:title ?title } + } + +Results: + + --------------------------------------------- + | title | + ============================================= + | "Harry Potter and the Sorcerer's Stone" | + | "Harry Potter and the Chamber of Secrets" | + --------------------------------------------- + +### Querying to find data from graphs that match a pattern + +The name of the graphs to be queried can be determined with the +query itself. The same process for variables applies whether they +are part of a graph pattern or the `GRAPH` form. The query below +([q-ds-4.rq](sparql_data/q-ds-4.rq)) sets a condition on the variable used to +select named graphs, based on information in the default graph. + + PREFIX xsd: + PREFIX dc: + PREFIX : <.> + + SELECT ?date ?title + { + ?g dc:date ?date . FILTER (?date > "2005-08-01T00:00:00Z"^^xsd:dateTime ) + GRAPH ?g + { ?b dc:title ?title } + } + +The results of executing this query on the example dataset are the +titles in one of the graphs, the one with the date later than 1 +August 2005. + + ----------------------------------------------------------------------------------------- + | date | title | + ========================================================================================= + | "2005-09-22T05:53:05+01:00"^^xsd:dateTime | "Harry Potter and the Sorcerer's Stone" | + | "2005-09-22T05:53:05+01:00"^^xsd:dateTime | "Harry Potter and the Chamber of Secrets" | + ----------------------------------------------------------------------------------------- + +## Describing RDF Datasets - `FROM` and `FROM NAMED` + +A query execution can be given the dataset when the execution +object is built or it can be described in the query itself. When +the details are on the command line, a temporary dataset is created +but an application can create datasets and then use them in many +queries. + +When described in the query, `FROM url` is used to identify +the contents to be in the default graph. There can be more than one +`FROM` clause and the default graph is result of reading each file +into the default graph. It is the RDF merge of the individual +graphs. + +Don't be confused by the fact the default graph is described by one +or more URLs in `FROM` clauses. This is where the data is read +from, not the name of the graph. As several FROM clauses can be +given, the data can be read in from several places but none of them +become the graph name. + +`FROM NAMED url` is used to identify a named graph. The +graph is given the name *url* and the data is read from that +location. Multiple `FROM NAMED` clauses cause multiple graphs to be +added to the dataset. + +Note that graphs are loaded with the Jena FileManager which +includes the ability to provide alternative locations for files. +For example, the query may have `FROM NAMED `, +and the data actually be read from `file:local.rdf`. The name of +the graph will be as in the query. + +For example, the query to find all the triples in both default +graph and named graphs could be written as +([q-ds-5.rq](sparql_data/q-ds-5.rq)): + + PREFIX xsd: + PREFIX dc: + PREFIX : <.> + + SELECT * + FROM + FROM NAMED + FROM NAMED + { + { ?s ?p ?o } UNION { GRAPH ?g { ?s ?p ?o } } + } + +[Next: results](sparql_results.html) + + + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_filters.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_filters.mdtext?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_filters.mdtext (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_filters.mdtext Sat Nov 5 01:10:34 2011 @@ -0,0 +1,96 @@ +Title: SPARQL Tutorial - Filters + +Graph matching allows patterns in the graph to be found. This +section describes how the values in a solution can be restricted. +There are many comparisons available - we just cover two cases +here. + +## String Matching + +SPARQL provides an operation to test strings, based on regular +expressions.  This includes the ability to ask SQL "LIKE" style +tests, although the syntax of the regular expression is different +from SQL. + +The syntax is: + + FILTER regex(?x, "pattern" [, "flags"]) + +The flags argument is optional.  The flag "i" means a +case-insensitive pattern match is done. + +The example query ([q-f1.rq](sparql_data/q-f1.rq)) finds given names with an +"r" or "R" in them. + + PREFIX vcard: + + SELECT ?g + WHERE + { ?y vcard:Given ?g . + FILTER regex(?g, "r", "i") } + +with the results: + + ------------- + | g | + ============= + | "Rebecca" | + | "Sarah" | + ------------- + +The regular expression language is the same as the +[XQuery regular expression language](http://www.w3.org/TR/xpath-functions/#regex-syntax) +which is codified version of that found in Perl. + +## Testing Values + +There are times when the application wants to filter on the value +of a variable.  In the data file [vc-db-2.rdf](sparql_data/vc-db-2.rdf), we +have added an extra field for age.  Age is not defined by the vCard +schema so we have created a new property for the purpose of this +tutorial.  RDF allows such mixing of different definitions of +information because URIs are unique. Note also that the `info:age` +property value is typed. + +In this extract of the data, we show the typed value. It can also +be written plain 23. + + + info:age "23"^^xsd:integer ; + vCard:FN "Becky Smith" ; + vCard:N [ vCard:Family "Smith" ; + vCard:Given "Rebecca" ] . + +So, a query ([q-f2.rq](sparql_data/q-f2.rq)) to find the names of people who +are older than 24 is: + + PREFIX info: + + SELECT ?resource + WHERE + { + ?resource info:age ?age . + FILTER (?age >= 24) + } + +The arithmetic expression must be in parentheses (round brackets).  +The only solution is: + + --------------------------------- + | resource | + ================================= + | | + --------------------------------- + +Just one match, resulting in the resource URI for John Smith. +Turning this round to ask for those less than 24 also yields one +match for Rebecca Smith.  Nothing about the Jones's. + +The database contains no age information about the Jones: there are +no info:age properties on these vCards so the variable `age` did +not get a value and so was not tested by the filter. + +[Next: Optionals](sparql_optionals.html) + + + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_optionals.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_optionals.mdtext?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_optionals.mdtext (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_optionals.mdtext Sat Nov 5 01:10:34 2011 @@ -0,0 +1,156 @@ +Title: SPARQL Tutorial - Optional Information + +RDF is semi-structured data so SPARQL has a the ability to query +for data but not to fail query when that data does not exist. The +query is using an optional part to extend the information found in +a query solution but to return the non-optional information +anyway. + +## OPTIONALs + +This query ([q-opt1.rq](sparql_data/q-opt1.rq)) gets the name of a person and +also their age if that piece of information is available. + + PREFIX info: + PREFIX vcard: + + SELECT ?name ?age + WHERE + { + ?person vcard:FN ?name . + OPTIONAL { ?person info:age ?age } + } + +Two of the four people in the data ([vc-db-2.rdf](sparql_data/vc-db-2.rdf))have +age properties so two of the query solutions have that +information.  However, because the triple pattern for the age is +optional, there is a pattern solution for the people who don't have +age information. + + ------------------------ + | name | age | + ======================= + | "Becky Smith" | 23 | + | "Sarah Jones" | | + | "John Smith" | 25 | + | "Matt Jones" | | + ----------------------- + +If the optional clause had not been there, no age information would +have been retrieved. If the triple pattern had been included but +not optional then we would have the query +([q-opt2.rq](sparql_data/q-opt2.rq)): + + PREFIX info: + PREFIX vcard: + + SELECT ?name ?age + WHERE + { + ?person vcard:FN ?name . + ?person info:age ?age . + } + +with only two solutions: + + ----------------------- + | name | age | + ======================= + | "Becky Smith" | 23 | + | "John Smith" | 25 | + ----------------------- + +because the `info:age` property must now be present in a solution. + +## OPTIONALs with FILTERs + +`OPTIONAL` is a binary operator that combines two graph patterns. +The optional pattern is any group pattern and may involve any +SPARQL pattern types.  If the group matches, the solution is +extended, if not, the original solution is given +([q-opt-3.rq](sparql_data/q-opt3.rq)). + + PREFIX info: + PREFIX vcard: + + SELECT ?name ?age + WHERE + { + ?person vcard:FN ?name . + OPTIONAL { ?person info:age ?age . FILTER ( ?age > 24 ) } + } + +So, if we filter for ages greater than 24 in the optional part, we +will still get 4 solutions (from the `vcard:FN` pattern) but only +get ages if they pass the test. + + ----------------------- + | name | age | + ======================= + | "Becky Smith" | | + | "Sarah Jones" | | + | "John Smith" | 25 | + | "Matt Jones" | | + ----------------------- + +No age included for "Becky Smith" because it is less than 24. + +If the filter condition is moved out of the optional part, then it +can influence the number of solutions but it may be necessary to +make the filter more complicated to allow for variable `age` being +unbound ([q-opt4.rq](sparql_data/q-opt4.rq)). + + PREFIX info: + PREFIX vcard: + + SELECT ?name ?age + WHERE + { + ?person vcard:FN ?name . + OPTIONAL { ?person info:age ?age . } + FILTER ( !bound(?age) || ?age > 24 ) + } + +If a solution has an `age` variable, then it must be greater than +24. It can also be unbound.  There are now three solutions: + + ----------------------- + | name | age | + ======================= + | "Sarah Jones" | | + | "John Smith" | 25 | + | "Matt Jones" | | + ----------------------- + +Evaluating an expression which has an unbound variables where a +bound one was expected causes an evaluation exception and the whole +expression fails. + +## OPTIONALs and Order Dependent Queries + +One thing to be careful of is using the same variable in two or +more optional clauses (and not in some basic pattern as well): + + PREFIX foaf: + PREFIX vCard: + + SELECT ?name + WHERE + { + ?x a foaf:Person . + OPTIONAL { ?x foaf:name ?name } + OPTIONAL { ?x vCard:FN ?name } + } + +If the first optional binds `?name` and `?x` to some values, the +second `OPTIONAL` is an attempt to match the ground triples (`?x` +and `?name` have values). If the first optional did not +match the optional part, then the second one is an attempt to match +it's triple with two variables. + +  + +[Next: union queries](sparql_union.html) + + + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_page.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_page.mdtext?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_page.mdtext (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_page.mdtext Sat Nov 5 01:10:34 2011 @@ -0,0 +1,8 @@ +# PAGE + +This section covers ... + +[Next: @@]() + + + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_query1.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_query1.mdtext?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_query1.mdtext (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_query1.mdtext Sat Nov 5 01:10:34 2011 @@ -0,0 +1,113 @@ +Title: SPARQL Tutorial - A First SPARQL Query + +In this section, we look at a simple first query and show how to +execute it with Jena. + +## A "hello world" of queries + +The file "[q1.rq](sparql_data/q1.rq)" contains the following query: + + SELECT ?x + WHERE { ?x "John Smith" } + +executing that query with the command line query application; + + --------------------------------- + | x | + ================================= + | | + --------------------------------- + +This works by matching the triple pattern in the `WHERE` clause +against the triples in the RDF graph. The predicate and object of +the triple are fixed values so the pattern is going to match only +triples with those values. The subject is a variable, and there are +no other restrictions on the variable. The pattern matches any +triples with these predicate and object values, and it matches with +solutions for `x`. + +The item enclosed in <\> is a URI (actually, it's an IRI) and the +item enclosed in "" is a plain literal. Just like Turtle, N3 or +N-triples, typed literals are written with \^\^ and language tags +can be added with @. + +?x is a variable called x. The ? does not form part of the name +which is why it does not appear in the table output. + +There is one match. The query returns the match in the `x` query +variable. The output shown was obtained by using one of ARQ's +command line applications. + +## Executing the query + +There are [helper scripts](/jena/documentation/query/cmds.html) in the ARQ `bat/` and +`bin/` directories of the ARQ distribution. They may not be in a +Jena distribution. You should check these scripts before use. + +### Windows setup + +Set the `ARQROOT` environment variable to the file location of the +ARQ distribution. + + set ARQROOT=c:\MyProjects\ARQ + +The distribution usually has the version number in the directory +name. + +In the ARQ directory, execute: + + bat\sparql.bat --data=doc\Tutorial\vc-db-1.rdf --query=doc\Tutorial\q1.rq + +(TODO we will need to update these once the release structure is clear) + +You can just put the `bat/` directory on your classpath or copy the +programs out of it. They all depend on ARQROOT. + +### bash scripts for Linux/Cygwin/Unix + +Set the `ARQROOT` environment variable to the file location of the +ARQ distribution. + + export ARQROOT=$HOME/MyProjects/ARQ + +The distribution usually has the version number in the directory +name. + +In the ARQ directory, execute: + + bin/sparql --data=doc/Tutorial/vc-db-1.rdf --query=doc/Tutorial/q1.rq + +You can just put the `bin/` directory on your classpath or copy the +programs out of it. They all depend on ARQROOT. + +[Cygwin](http://www.cygwin.com/) is a Linux-like environment for +Windows. + +### Using the Java command line applications directly + +You will need to set the classpath to include *all* the jar files +in the ARQ `lib/` directory. + +For example, on Windows: + + ARQdir\lib\antlr-2.7.5.jar;ARQdir\lib\arq-extra.jar;ARQdir\lib\arq.jar; + ARQdir\lib\commons-logging-1.1.jar;ARQdir\lib\concurrent.jar;ARQdir\lib\icu4j_3_4.jar; + ARQdir\lib\iri.jar;ARQdir\lib\jena.jar;ARQdir\lib\jenatest.jar; + ARQdir\lib\json.jar;ARQdir\lib\junit.jar;ARQdir\lib\log4j-1.2.12.jar; + ARQdir\lib\lucene-core-2.2.0.jar;ARQdir\lib\stax-api-1.0.jar; + ARQdir\lib\wstx-asl-3.0.0.jar;ARQdir\lib\xercesImpl.jar;ARQdir\lib\xml-apis.jar + +(TODO needs updating) + +where `ARQdir` is where you unpacked ARQ. This must be all +one line. + +The names of jar files sometimes changes and new jar files do get +added - do check this list with your version of ARQ. + +The commands themselves are in the `arq` package. + +[Next: basic patterns](sparql_basic_patterns.html) + + + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_results.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_results.mdtext?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_results.mdtext (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_results.mdtext Sat Nov 5 01:10:34 2011 @@ -0,0 +1,97 @@ +Title: Producing Result Sets + +SPARQL has four result forms: + +- SELECT – Return a table of results. +- CONSTRUCT – Return an RDF graph, based on a template in the + query. +- DESCRIBE – Return an RDF graph, based on what the query + processor is configured to return. +- ASK – Ask a boolean query. + +The SELECT form directly returns a table of solutions as a result +set, while DESCRIBE and CONSTRUCT use the outcome of matching to +build RDF graphs. + +## Solution Modifiers + +Pattern matching produces a set of solutions. This set can be +modified in various ways: + +- Projection - keep only selected variables +- OFFSET/LIMIT - chop the number solutions (best used with ORDER + BY) +- ORDER BY - sorted results +- DISTINCT - yield only one row for one combination of variables + and values. + +The solution modifiers OFFSET/LIMIT and ORDER BY always apply to +all result forms.  + +### OFFSET and LIMIT + +A set of solutions can be abbreviated by specifying the offset (the +start index) and the limit (the number of solutions) to be +returned. Using LIMIT alone can be useful to ensure not too many +solutions are returned, to restrict the effect of some unexpected +situation.  LIMIT and OFFSET can be used in conjunction with +sorting to take a defined slice through the solutions found. + +### ORDER BY + +SPARQL solutions are sorted by expression, including custom +functions. + + ORDER BY ?x ?y + + ORDER BY DESC(?x) + + ORDER BY x:func(?x) # Custom sorting condition + +### DISTINCT + +The SELECT result form can take the DISTINCT modifier which ensures +that no two solutions returned are the same - this takes place +after projection to the requested variables. + +  + +## SELECT + +The `SELECT` result form is a projection, with DISTINCT applied, of +the solution set. `SELECT` identifies which named variables are in +the result set.  This may be "`*`" meaning "all named variables" +(blank nodes in the query act like variables for matching but are +never returned). + +## CONSTRUCT + +CONSTRUCT builds an RDF based on a graph template.  The graph +template can have variables which are bound by a WHERE clause.  The +effect is to calculate the graph fragment, given the template, for +each solution from the WHERE clause, after taking into account any +solution modifiers. The graph fragments, one per solution, are +merged into a single RDF graph which is the result. + +Any blank nodes explicitly mentioned in the graph template are +created afresh for each time the template is used for a solution. + +## DESCRIBE + +The CONSTRUCT form, takes an application template for the graph +results. The DESCRIBE form also creates a graph but the form of +that graph is provided the query processor, not the application. +For each URI found, or explicitly mentioned in the DESCRIBE clause, +the query processor should provide a useful fragment of RDF, such +as all the known details of a book. ARQ allows domain-specific +description handlers to be written. + +## ASK + +The ASK result form returns a boolean, true of the pattern matched +otherwise false. + +[Return to index](index.html) + + + Added: incubator/jena/site/trunk/content/jena/tutorials/sparql_union.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/tutorials/sparql_union.mdtext?rev=1197854&view=auto ============================================================================== --- incubator/jena/site/trunk/content/jena/tutorials/sparql_union.mdtext (added) +++ incubator/jena/site/trunk/content/jena/tutorials/sparql_union.mdtext Sat Nov 5 01:10:34 2011 @@ -0,0 +1,140 @@ +Title: SPARQL Tutorial - Alternatives in a Pattern + +Another way of dealing with the semi-structured data is to query +for one of a number of possibilities. This section covers `UNION` +patterns, where one of a number of possibilities is tried. + +## UNION - two ways to the same data + +Both the vCard vocabulary and the FOAF vocabulary have properties +for people's names.  In vCard, it is vCard:FN, the "formatted +name", and in FOAF, it is foaf:name. In this section, we will look +at a small set of data where the names of people can be given by +either the FOAF or the vCard vocabulary. + +Suppose we have [an RDF graph](sparql_data/vc-db-3.ttl) that contains name +information using both the vCard and FOAF vocabularies. + + @prefix foaf: . + @prefix vcard: . + + _:a foaf:name "Matt Jones" . + + _:b foaf:name "Sarah Jones" . + + _:c vcard:FN "Becky Smith" . + + _:d vcard:FN "John Smith" . + +A query to access the name information, when it can be in either +form, could be ([q-union1.rq](sparql_data/q-union1.rq)): + + PREFIX foaf: + PREFIX vCard: + + SELECT ?name + WHERE + { + { [] foaf:name ?name } UNION { [] vCard:FN ?name } + } + +This returns the results: + + ----------------- + | name | + ================= + | "Matt Jones" | + | "Sarah Jones" | + | "Becky Smith" | + | "John Smith" | + ----------------- + +It didn't matter which form of expression was used for the name, +the ?name variable is set. This can be achieved using a `FILTER` as +this query ([q-union-1alt.rq](sparql_data/q-union1alt.rq)) shows: + + PREFIX foaf: + PREFIX vCard: + + SELECT ?name + WHERE + { + [] ?p ?name + FILTER ( ?p = foaf:name || ?p = vCard:FN ) + } + +testing whether the property is one URI or another. The solutions +may not come out in the same order.  The first form is more likely +to be faster, depending on the data and the storage used, because +the second form may have to get all the triples from the graph to +match the triple pattern with unbound variables (or blank nodes) in +each slot, then test each `?p` to see it it matches one of the +values. It will depend on the sophistication of the query optimizer +as to whether it spots that it can perform the query more +efficiently and is able to pass the constraint down as will as to +the storage layer. + +## Union - remembering where the data was found. + +The example above used the same variable in each branch. If +different variables are used, the application can discover which +sub-pattern caused the match ([q-union2.rq](sparql_data/q-union2.rq)): + + PREFIX foaf: + PREFIX vCard: + + SELECT ?name1 ?name2 + WHERE + { + { [] foaf:name ?name1 } UNION { [] vCard:FN ?name2 } + } + + --------------------------------- + | name1 | name2 | + ================================= + | "Matt Jones" | | + | "Sarah Jones" | | + | | "Becky Smith" | + | | "John Smith" | + --------------------------------- + +This second query has retained information of where the name of the +person came from by assigning the name to different variables. + +## OPTIONAL and UNION + +In practice, `OPTIONAL` is more common than `UNION` but they both +have their uses. `OPTIONAL` are useful for augmenting the solutions +found, `UNION` is useful for concatenating the solutions from two +possibilities. They don't necessary return the information in the +same way: + +Query([q-union3.rq](sparql_data/q-union3.rq)): + + PREFIX foaf: + PREFIX vCard: + + SELECT ?name1 ?name2 + WHERE + { + ?x a foaf:Person + OPTIONAL { ?x foaf:name ?name1 } + OPTIONAL { ?x vCard:FN ?name2 } + } + + --------------------------------- + | name1 | name2 | + ================================= + | "Matt Jones" | | + | "Sarah Jones" | | + | | "Becky Smith" | + | | "John Smith" | + --------------------------------- + +but beware of using `?name` in each `OPTIONAL` because that is an +order-dependent query. + +[Next: Named Graphs](sparql_datasets.html) + + + Modified: incubator/jena/site/trunk/templates/sidenav.mdtext URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/templates/sidenav.mdtext?rev=1197854&r1=1197853&r2=1197854&view=diff ============================================================================== --- incubator/jena/site/trunk/templates/sidenav.mdtext (original) +++ incubator/jena/site/trunk/templates/sidenav.mdtext Sat Nov 5 01:10:34 2011 @@ -31,7 +31,8 @@ - [Tell me how to ...](/jena/getting_started/tell_me_how.html) # Tutorials - - [RDF tutorial](/jena/tutorials/index.html) + - [Tutorials index](/jena/tutorials/index.html) + - [RDF tutorial](/jena/tutorials/rdf_api.html) - [SPARQL queries](/jena/tutorials/sparql.html) - [Using Jena with Eclipse](/jena/tutorials/using_jena_with_eclipse.html)