1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
2 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
6 <productname>Metaproxy SPARQL module</productname>
7 <info><orgname>Index Data</orgname></info>
11 <refentrytitle>sparql</refentrytitle>
12 <manvolnum>3mp</manvolnum>
13 <refmiscinfo class="manual">Metaproxy Module</refmiscinfo>
17 <refname>sparql</refname>
19 Metaproxy Module for accessing a triplestore
23 <refsect1><title>DESCRIPTION</title>
25 This module translates Z39.50 operations init, search, present to
26 HTTP requests that accesses a remote triplestore via HTTP
29 This module only inspects Z39.50. HTTP requests are ignored (passed through).
30 When this module is in effect, the result is HTTP packages. Use
31 the <literal>http_client</literal> module after this module in the
32 route in order to contact a remote triplestore via HTTP
35 Configuration consists of an optional defaults section and one or more
39 The default sections is defined with element <literal>defaults</literal>
40 and specifies the URL of the triplestore by attribute
41 <literal>uri</literal>.
44 A database section is defined with element <literal>db</literal>.
45 The <literal>db</literal> element must specify attribute
46 <literal>path</literal> which is the name of the Z39.50 database.
47 It should also include attribute <literal>uri</literal> with the
48 URL of the triplestore; unless already specified in the detaults
50 The element-set-name / schema for the database may be given with
51 attribute <literal>schema</literal>.
52 A db configuration may also include settings from another db section -
53 specified by the <literal>include</literal> attribute.
54 Each database section takes these elements:
56 <varlistentry><term><prefix/></term>
59 Section that maps prefixes and namespaces for RDF vocabularies.
60 The format is prefix followed by colon, followed by value.
64 <varlistentry><term><form/></term>
67 SPARQL Query formulation selection. Should start with one of the
68 query forms: SELECT or CONSTRUCT.
72 <varlistentry><term><criteria/></term>
75 section that allows to map static graph patterns for binding
76 variables, narrowing types, etc, or any other WHERE clause criteria
77 static to the Z39.50/SRU database. The final query conversion logic
78 should be able to deduce which optional criteria should be included
79 in the generated SPARQL by analyzing variables required in the query
80 matching and display fields.
84 <varlistentry><term><index type="attribute"/></term>
87 Section used to declare RPN/Type-1 use attribute strings (indices)
88 and map them to BIBFRAME graph patterns.
89 Items in this section are constructed during RPN query processing and
90 placeholders that are prefixed by a percent sign (<literal>%</literal>)
92 See <xref linkend="expansions">EXPANSIONS</xref>.
93 To map a given use attribute (search field) into
94 multiple entity properties, SPARQL constructs like `OPTIONAL` or
99 <varlistentry><term><present type="attribute"/></term>
102 Section used to declare retrieval for a given element-set-name
103 (SRU schema). The CDATA is SPARQL where <literal>%u</literal> holds
104 the URI of the record. This can be used to construct the resulting
109 <varlistentry><term><modifier/></term>
112 Optional section that allows you to add solution sequences or
121 <refsect1 id="expansions"><title>EXPANSIONS</title>
123 <varlistentry><term><literal>%t</literal></term>
126 The term verbatim as it appears in the Type-1 query.
130 <varlistentry><term><literal>%s</literal></term>
133 Like <literal>%t</literal> but quoted - for general strings.
137 <varlistentry><term><literal>%d</literal></term>
140 Term - expecting an integer.
144 <varlistentry><term><literal>%u</literal></term>
147 Like <literal>%t</literal>, but with prefix <literal><</literal>
148 and suffix <literal>></literal> - for URIs.
152 <varlistentry><term><literal>%v</literal></term>
155 Expands to a SPARQL local variable <literal>?v...</literal>. Allows
156 the use of a local SPARQL variable for each Attribute+Term in the
163 <refsect1><title>SCHEMA</title>
164 <literallayout><xi:include
165 xi:href="filter_sparql.rnc"
167 xmlns:xi="http://www.w3.org/2001/XInclude" />
171 <refsect1><title>EXAMPLE</title>
173 Configuration for database "Default" that allows searching works. Only
174 the field (use attribute) "bf.wtitle" is supported.
176 <filter type="sparql">
178 uri="http://bibframe.indexdata.com/sparql/"
179 schema="sparql-results">
180 <prefix>bf: http://bibframe.org/vocab/</prefix>
181 <form>SELECT ?work ?wtitle</form>
182 <criteria>?work a bf:Work</criteria>
183 <criteria>?work bf:workTitle ?wt</criteria>
184 <criteria>?wt bf:titleValue ?wtitle</criteria>
185 <index type="bf.wtitle">?wt bf:titleValue %v FILTER(contains(%v, %s))</index>
190 The matching is done by a simple case-sensitive substring match. There is
191 no deduplication, so if a work has two titles, we get two rows.
195 <refsect1><title>EXAMPLE</title>
197 A more complex configuration for database "work". This could be included in
198 the same filter section as the "Default" db above.
200 <db path="work" schema="sparql-results">
201 <prefix>bf: http://bibframe.org/vocab/</prefix>
204 (sql:GROUP_DIGEST (?wtitle, ' ; ', 1000, 1)) AS ?title
205 (sql:GROUP_DIGEST (?creatorlabel, ' ; ', 1000, 1))AS ?creator
206 (sql:GROUP_DIGEST (?subjectlabel, ' ; ', 1000, 1))AS ?subject
208 <criteria>?work a bf:Work</criteria>
210 <criteria> OPTIONAL {
211 ?work bf:workTitle ?wt .
212 ?wt bf:titleValue ?wtitle }
214 <criteria> OPTIONAL {
215 ?work bf:creator ?creator .
216 ?creator bf:label ?creatorlabel }
219 ?work bf:subject ?subject .
220 ?subject bf:label ?subjectlabel }
222 <index type="4">?wt bf:titleValue %v FILTER(contains(%v, %s))</index>
223 <index type="1003">?creator bf:label %v FILTER(contains(%v, %s))</index>
224 <index type="21">?subject bf:label %v FILTER(contains(%v, %s))</index>
225 <index type="1016"> {
227 ?child ?op2 %v FILTER(contains(STR(%v), %s))
230 <modifier>GROUP BY $work</modifier>
236 This returns one row for each work. Titles, authors, and subjects
237 are all optional. If they repeat, the repeated values are concatenated
238 into a single field, separated by semicolons. This is done by the
239 GROUP_DIGEST function that is specific to the Virtuoso back end.
242 This example supports use attributes 4 (title), 1003 (author),
243 21 (subject), and 1016 (keyword) which matches any literal in a
244 triplet that refers to the work, so it works for the titleValue in
245 the workTitle, as well as the label in the subject, and what ever
246 else there may be. Like the preceding example, the matching is by a
247 simple substring, case sensitive. A more realistic term matching could
248 be done with regular expressions, at the cost of some readability
249 portability, and performance.
253 <refsect1><title>EXAMPLE</title>
255 Configuration for database "works". This uses CONSTRUCT to produce rdf.
257 <db path="works" schema="rdf">
258 <prefix>bf: http://bibframe.org/vocab/</prefix>
260 ?work bf:title ?wtitle .
261 ?work bf:instanceTitle ?title .
262 ?work bf:author ?creator .
263 ?work bf:subject ?subjectlabel }
265 <criteria>?work a bf:Work</criteria>
267 <criteria>?work bf:workTitle ?wt</criteria>
268 <criteria>?wt bf:titleValue ?wtitle</criteria>
269 <index type="4">?wt bf:titleValue %v FILTER(contains(%v, %s))</index>
270 <criteria>?work bf:creator ?creator</criteria>
271 <criteria>?creator bf:label ?creatorlabel</criteria>
272 <index type="1003">?creator bf:label %v FILTER(contains(%v, %s))</index>
273 <criteria>?work bf:subject ?subject</criteria>
274 <criteria>?subject bf:label ?subjectlabel</criteria>
275 <index type="21">?subject bf:label %v FILTER(contains(%v, %s))</index>
282 <refsect1><title>EXAMPLE</title>
284 Configuration for database "instance". Like "work" above this uses SELECT
285 to return row-based data, this time from the instances.
286 This is not deduplicated, so if an instance has two titles, we get two
287 rows, and if it also has two formats, we get four rows.
288 The DISTINCT in the SELECT
290 <db path="instance" schema="sparql-results">
291 <prefix>bf: http://bibframe.org/vocab/</prefix>
292 <form>SELECT DISTINCT ?instance ?title ?format</form>
293 <criteria>?instance a bf:Instance</criteria>
294 <criteria>?instance bf:title ?title</criteria>
295 <index type="4">?instance bf:title %v FILTER(contains(%v, %s))</index>
296 <criteria>?instance bf:format ?format</criteria>
297 <index type="1013">?instance bf:format %s</index>
305 <refsect1><title>SEE ALSO</title>
308 <refentrytitle>metaproxy</refentrytitle>
309 <manvolnum>1</manvolnum>
316 <!-- Keep this comment at the end of the file