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 Configuration consists of one or more db elements. Each db element
30 describes how to access a specific database. The db element takes
31 attributes name of Z39.50 database (<literal>path</literal>) and
32 HTTP access point of triplestore (<literal>uri</literal>).
33 Optionally, the schema for the database may be given with attribute
34 <literal>schema</literal>.
36 db element takes these elements:
39 <varlistentry><term><prefix/></term>
42 Section that maps prefixes and namespaces for RDF vocabularies.
43 The format is prefix followed by colon, followed by value.
47 <varlistentry><term><form/></term>
50 SPARQL Query formulation selection. SHould start with one of the
51 query forms: SELECT or CONSTRUCT.
55 <varlistentry><term><criteria/></term>
58 section that allows to map static graph patterns for binding
59 variables, narrowing types, etc, or any other WHERE clause criteria
60 static to the Z39.50/SRU database. The final query conversion logic
61 should be able to deduce which optional criteria should be included
62 in the generated SPARQL by analyzing variables required in the query
63 matching and display fields.
67 <varlistentry><term><index type="attribute"/></term>
70 Section used to declare RPN use attribute strings (indexes) and map
71 them to BIBFRAME graph patterns.
72 Items in this section are expanded during RPN query processing and
73 placeholders (<literal>%s</literal>, <literal>%d</literal>,
74 <literal>%t</literal>) are substituted with query terms.
75 To map a given CQL index (e.g the default keyword index) into
76 multiple entity properties, SPARQL constructs like
77 `OPTIONAL` or `UNION` could be used.
81 <varlistentry><term><present type="attribute"/></term>
84 Section used to declare retrieval for a given element-set
85 (SRU schema). The CDATA is SPARQL where <literal>%u</literal> holds
86 the URI of the record. This can be used to construct the resulting
91 <varlistentry><term><modifier/></term>
94 Optional section that allows you to add solution sequences or
104 <refsect1><title>SCHEMA</title>
105 <literallayout><xi:include
106 xi:href="filter_sparql.rnc"
108 xmlns:xi="http://www.w3.org/2001/XInclude" />
112 <refsect1><title>EXAMPLE</title>
114 Configuration for database "Default" that allows searching works. Only
115 the field (use attribute) "bf.wtitle" is supported.
117 <filter type="sparql">
119 uri="http://bibframe.indexdata.com/sparql/"
120 schema="sparql-results">
121 <prefix>rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns</prefix>
122 <prefix>bf: http://bibframe.org/vocab/</prefix>
123 <form>SELECT ?work ?wtitle</form>
124 <criteria>?work a bf:Work</criteria>
125 <criteria>?work bf:workTitle ?wt</criteria>
126 <criteria>?wt bf:titleValue ?wtitle</criteria>
127 <index type="bf.wtitle">?wt bf:titleValue %v FILTER(contains(%v, %s))</index>
132 The matching is done by a simple case-sensitive substring match. There is
133 no deduplication, so if a work has two titles, we get two rows.
137 <refsect1><title>EXAMPLE</title>
139 A more complex configuration for database "work". This could be included in
140 the same filter section as the "Default" db above.
142 <db path="work" schema="sparql-results">
143 <prefix>rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns</prefix>
144 <prefix>bf: http://bibframe.org/vocab/</prefix>
147 (sql:GROUP_DIGEST (?wtitle, ' ; ', 1000, 1)) AS ?title
148 (sql:GROUP_DIGEST (?creatorlabel, ' ; ', 1000, 1))AS ?creator
149 (sql:GROUP_DIGEST (?subjectlabel, ' ; ', 1000, 1))AS ?subject
151 <criteria>?work a bf:Work</criteria>
153 <criteria> OPTIONAL {
154 ?work bf:workTitle ?wt .
155 ?wt bf:titleValue ?wtitle }
157 <criteria> OPTIONAL {
158 ?work bf:creator ?creator .
159 ?creator bf:label ?creatorlabel }
162 ?work bf:subject ?subject .
163 ?subject bf:label ?subjectlabel }
165 <index type="4">?wt bf:titleValue %v FILTER(contains(%v, %s))</index>
166 <index type="1003">?creator bf:label %v FILTER(contains(%v, %s))</index>
167 <index type="21">?subject bf:label %v FILTER(contains(%v, %s))</index>
168 <index type="1016"> {
170 ?child ?op2 %v FILTER(contains(STR(%v), %s))
173 <modifier>GROUP BY $work</modifier>
179 This returns one row for each work. Titles, authors, and subjects
180 are all optional. If they repeat, the repeated values are concatenated into
181 a single field, separated by semicolons. This is done by the GROUP_DIGEST
182 function that is specific to the Virtuoso back end.
185 This example supports use attributes 4 (title), 1003 (author), 21 (subject),
186 and 1016 (keyword) which matches any literal in a triplet that refers to the
187 work, so it works for the titleValue in the workTitle, as well as the label
188 in the subject, and what ever else there may be. Like the preceding example,
189 the matching is by a simple substring, case sensitive. A more realistic term
190 matching could be done with regular expressions, at the cost of some readability
191 portability, and performance.
195 <refsect1><title>EXAMPLE</title>
197 Configuration for database "works". This uses CONSTRUCT to produce rdf.
199 <db path="works" schema="rdf">
200 <prefix>rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns</prefix>
201 <prefix>bf: http://bibframe.org/vocab/</prefix>
203 ?work bf:title ?wtitle .
204 ?work bf:instanceTitle ?title .
205 ?work bf:author ?creator .
206 ?work bf:subject ?subjectlabel }
208 <criteria>?work a bf:Work</criteria>
210 <criteria>?work bf:workTitle ?wt</criteria>
211 <criteria>?wt bf:titleValue ?wtitle</criteria>
212 <index type="4">?wt bf:titleValue %v FILTER(contains(%v, %s))</index>
213 <criteria>?work bf:creator ?creator</criteria>
214 <criteria>?creator bf:label ?creatorlabel</criteria>
215 <index type="1003">?creator bf:label %v FILTER(contains(%v, %s))</index>
216 <criteria>?work bf:subject ?subject</criteria>
217 <criteria>?subject bf:label ?subjectlabel</criteria>
218 <index type="21">?subject bf:label %v FILTER(contains(%v, %s))</index>
225 <refsect1><title>EXAMPLE</title>
227 Configuration for database "instance". Like "work" above this uses SELECT
228 to return row-based data, this time from the instances. This is not deduplicated,
229 so if an instance has two titles, we get two rows, and if it also has
230 two formats, we get four rows. The DISTINCT in the SELECT
232 <db path="instance" schema="sparql-results">
233 <prefix>rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns</prefix>
234 <prefix>bf: http://bibframe.org/vocab/</prefix>
235 <form>SELECT DISTINCT ?instance ?title ?format</form>
236 <criteria>?instance a bf:Instance</criteria>
237 <criteria>?instance bf:title ?title</criteria>
238 <index type="4">?instance bf:title %v FILTER(contains(%v, %s))</index>
239 <criteria>?instance bf:format ?format</criteria>
240 <index type="1013">?instance bf:format %s</index>
249 <refsect1><title>SEE ALSO</title>
252 <refentrytitle>metaproxy</refentrytitle>
253 <manvolnum>1</manvolnum>
260 <!-- Keep this comment at the end of the file