X-Git-Url: http://git.indexdata.com/?p=mp-sparql-moved-to-github.git;a=blobdiff_plain;f=doc%2Fsparql.xml;h=a43fbaedb7bfa0814fa9e964788899b39ab1e255;hp=ba4eca7f8526e783ded7eca44ecdc2585f757e5e;hb=43063c1e0a4e9d1cf9347d7bdefe8ee99dbb14cb;hpb=e5b5ae2b4836f76d84aae25c0edf4312b761dae4 diff --git a/doc/sparql.xml b/doc/sparql.xml index ba4eca7..a43fbae 100644 --- a/doc/sparql.xml +++ b/doc/sparql.xml @@ -26,15 +26,32 @@ HTTP requests that accesses a remote triplestore via HTTP - Configuration consists of one or more db elements. Each db element - describes how to access a specific database. The db element takes - attributes name of Z39.50 database (path) and - HTTP access point of triplestore (uri). - Optionally, the schema for the database may be given with attribute - schema. - Each - db element takes these elements: - Configurable values: + This module only inspects Z39.50. HTTP requests are ignored (passed through). + When this module is in effect, the result is HTTP packages. Use + the http_client module after this module in the + route in order to contact a remote triplestore via HTTP + + + Configuration consists of an optional defaults section and one or more + database sections. + + + The default sections is defined with element defaults + and specifies the URL of the triplestore by attribute + uri. + + + A database section is defined with element db. + The db element must specify attribute + path which is the name of the Z39.50 database. + It should also include attribute uri with the + URL of the triplestore; unless already specified in the detaults + section. + The element-set-name / schema for the database may be given with + attribute schema. + A db configuration may also include settings from another db section - + specified by the include attribute. + Each database section takes these elements: <prefix/> @@ -47,7 +64,7 @@ <form/> - SPARQL Query formulation selection. SHould start with one of the + SPARQL Query formulation selection. Should start with one of the query forms: SELECT or CONSTRUCT. @@ -67,29 +84,91 @@ <index type="attribute"/> - Section used to declare RPN use attribute strings (indexes) and map - them to BIBFRAME graph patterns. - Items in this section are expanded during RPN query processing and - placeholders (%s, %d) are substituted with query terms. - To map a given CQL index (e.g the default keyword index) into - multiple entity properties, SPARQL constructs like - `OPTIONAL` or `UNION` could be used. + Section used to declare RPN/Type-1 use attribute strings (indices) + and map them to BIBFRAME graph patterns. + Items in this section are constructed during RPN query processing and + placeholders that are prefixed by a percent sign (%) + are expanded. + See EXPANSIONS. + To map a given use attribute (search field) into + multiple entity properties, SPARQL constructs like `OPTIONAL` or + `UNION` can be used. + <present type="attribute"/> + + + Section used to declare retrieval for a given element-set-name + (SRU schema). The CDATA is SPARQL where %u holds + the URI of the record. This can be used to construct the resulting + record. + + + + <modifier/> + + + Optional section that allows you to add solution sequences or + modifiers. + + + + - - SCHEMA - EXPANSIONS + + %t + + + The term verbatim as it appears in the Type-1 query. + + + + %s + + + Like %t but quoted - for general strings. + + + + %d + + + Term - expecting an integer. + + + + %u + + + Like %t, but with prefix < + and suffix > - for URIs. + + + + %v + + + Expands to a SPARQL local variable ?v.... Allows + the use of a local SPARQL variable for each Attribute+Term in the + Type-1 query. + + + + + + SCHEMA + - EXAMPLES + EXAMPLE Configuration for database "Default" that allows searching works. Only the field (use attribute) "bf.wtitle" is supported. @@ -97,11 +176,9 @@ - rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns + schema="sparql-results"> bf: http://bibframe.org/vocab/ - SELECT ?work ?wtitle +
SELECT ?work ?wtitle
?work a bf:Work ?work bf:workTitle ?wt ?wt bf:titleValue ?wtitle @@ -110,9 +187,121 @@ ]]> + The matching is done by a simple case-sensitive substring match. There is + no deduplication, so if a work has two titles, we get two rows. + EXAMPLE + + A more complex configuration for database "work". This could be included in + the same filter section as the "Default" db above. + + bf: http://bibframe.org/vocab/ +
SELECT + ?work + (sql:GROUP_DIGEST (?wtitle, ' ; ', 1000, 1)) AS ?title + (sql:GROUP_DIGEST (?creatorlabel, ' ; ', 1000, 1))AS ?creator + (sql:GROUP_DIGEST (?subjectlabel, ' ; ', 1000, 1))AS ?subject +
+ ?work a bf:Work + + OPTIONAL { + ?work bf:workTitle ?wt . + ?wt bf:titleValue ?wtitle } + + OPTIONAL { + ?work bf:creator ?creator . + ?creator bf:label ?creatorlabel } + + OPTIONAL { + ?work bf:subject ?subject . + ?subject bf:label ?subjectlabel } + + ?wt bf:titleValue %v FILTER(contains(%v, %s)) + ?creator bf:label %v FILTER(contains(%v, %s)) + ?subject bf:label %v FILTER(contains(%v, %s)) + { + ?work ?op1 ?child . + ?child ?op2 %v FILTER(contains(STR(%v), %s)) + } + + GROUP BY $work + +]]> + + + + This returns one row for each work. Titles, authors, and subjects + are all optional. If they repeat, the repeated values are concatenated + into a single field, separated by semicolons. This is done by the + GROUP_DIGEST function that is specific to the Virtuoso back end. + + + This example supports use attributes 4 (title), 1003 (author), + 21 (subject), and 1016 (keyword) which matches any literal in a + triplet that refers to the work, so it works for the titleValue in + the workTitle, as well as the label in the subject, and what ever + else there may be. Like the preceding example, the matching is by a + simple substring, case sensitive. A more realistic term matching could + be done with regular expressions, at the cost of some readability + portability, and performance. + + + + EXAMPLE + + Configuration for database "works". This uses CONSTRUCT to produce rdf. + + bf: http://bibframe.org/vocab/ +
CONSTRUCT { + ?work bf:title ?wtitle . + ?work bf:instanceTitle ?title . + ?work bf:author ?creator . + ?work bf:subject ?subjectlabel } +
+ ?work a bf:Work + + ?work bf:workTitle ?wt + ?wt bf:titleValue ?wtitle + ?wt bf:titleValue %v FILTER(contains(%v, %s)) + ?work bf:creator ?creator + ?creator bf:label ?creatorlabel + ?creator bf:label %v FILTER(contains(%v, %s)) + ?work bf:subject ?subject + ?subject bf:label ?subjectlabel + ?subject bf:label %v FILTER(contains(%v, %s)) + + ]]> + + + + + EXAMPLE + + Configuration for database "instance". Like "work" above this uses SELECT + to return row-based data, this time from the instances. + This is not deduplicated, so if an instance has two titles, we get two + rows, and if it also has two formats, we get four rows. + The DISTINCT in the SELECT + + bf: http://bibframe.org/vocab/ +
SELECT DISTINCT ?instance ?title ?format
+ ?instance a bf:Instance + ?instance bf:title ?title + ?instance bf:title %v FILTER(contains(%v, %s)) + ?instance bf:format ?format + ?instance bf:format %s + + ]]> + + + + + SEE ALSO