doc/sparql.xml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
   2     "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
   3 ]>
   4 <refentry id="sparql">
   5  <refentryinfo>
   6   <productname>Metaproxy SPARQL module</productname>
   7   <info><orgname>Index Data</orgname></info>
   8  </refentryinfo>
   9
  10  <refmeta>
  11   <refentrytitle>sparql</refentrytitle>
  12   <manvolnum>3mp</manvolnum>
  13   <refmiscinfo class="manual">Metaproxy Module</refmiscinfo>
  14  </refmeta>
  15
  16  <refnamediv>
  17   <refname>sparql</refname>
  18   <refpurpose>
  19    Metaproxy Module for accessing a triplestore
  20   </refpurpose>
  21  </refnamediv>
  22
  23  <refsect1><title>DESCRIPTION</title>
  24   <para>
  25    This module translates Z39.50 operations init, search, present to
  26    HTTP requests that accesses a remote triplestore via HTTP
  27   </para>
  28   <para>
  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>.
  35    Each
  36    db element takes these elements:
  37    Configurable values:
  38    <variablelist>
  39     <varlistentry><term>&lt;prefix/&gt;</term>
  40      <listitem>
  41       <para>
  42        Section that maps prefixes and namespaces for RDF vocabularies.
  43        The format is prefix followed by colon, followed by value.
  44       </para>
  45      </listitem>
  46     </varlistentry>
  47     <varlistentry><term>&lt;form/&gt;</term>
  48      <listitem>
  49       <para>
  50        SPARQL Query formulation selection. SHould start with one of the
  51        query forms: SELECT or CONSTRUCT.
  52       </para>
  53      </listitem>
  54     </varlistentry>
  55     <varlistentry><term>&lt;criteria/&gt;</term>
  56      <listitem>
  57       <para>
  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.
  64       </para>
  65      </listitem>
  66     </varlistentry>
  67     <varlistentry><term>&lt;index type="attribute"/&gt;</term>
  68      <listitem>
  69       <para>
  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.
  78       </para>
  79      </listitem>
  80     </varlistentry>
  81     <varlistentry><term>&lt;present type="attribute"/&gt;</term>
  82      <listitem>
  83       <para>
  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
  87        record.
  88       </para>
  89      </listitem>
  90     </varlistentry>
  91     <varlistentry><term>&lt;modifier/&gt;</term>
  92      <listitem>
  93       <para>
  94        Optional section that allows you to add solution sequences or
  95        modifiers.
  96       </para>
  97      </listitem>
  98     </varlistentry>
  99
 100    </variablelist>
 101   </para>
 102  </refsect1>
 103
 104  <refsect1><title>SCHEMA</title>
 105    <literallayout><xi:include
 106                      xi:href="filter_sparql.rnc"
 107                      xi:parse="text"
 108                      xmlns:xi="http://www.w3.org/2001/XInclude" />
 109    </literallayout>
 110  </refsect1>
 111
 112  <refsect1><title>EXAMPLE</title>
 113   <para>
 114    Configuration for database "Default" that allows searching works. Only
 115    the field (use attribute) "bf.wtitle" is supported.
 116    <screen><![CDATA[
 117   <filter type="sparql">
 118     <db path="Default"
 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>
 128     </db>
 129   </filter>
 130 ]]>
 131    </screen>
 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.
 134   </para>
 135  </refsect1>
 136
 137  <refsect1><title>EXAMPLE</title>
 138   <para>
 139    A more complex configuration for database "work". This could be included in
 140    the same filter section as the "Default" db above.
 141    <screen><![CDATA[
 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>
 145       <form>SELECT
 146               ?work
 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
 150       </form>
 151       <criteria>?work a bf:Work</criteria>
 152
 153       <criteria> OPTIONAL {
 154           ?work bf:workTitle ?wt .
 155           ?wt bf:titleValue ?wtitle }
 156       </criteria>
 157       <criteria> OPTIONAL {
 158           ?work bf:creator ?creator .
 159           ?creator bf:label ?creatorlabel }
 160       </criteria>
 161       <criteria>OPTIONAL {
 162           ?work bf:subject ?subject .
 163           ?subject bf:label ?subjectlabel }
 164       </criteria>
 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"> {
 169             ?work ?op1 ?child .
 170             ?child ?op2 %v FILTER(contains(STR(%v), %s))
 171           }
 172       </index>
 173       <modifier>GROUP BY $work</modifier>
 174     </db>
 175 ]]>
 176    </screen>
 177    </para>
 178    <para>
 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.
 183    </para>
 184    <para>
 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.
 192    </para>
 193  </refsect1>
 194
 195  <refsect1><title>EXAMPLE</title>
 196    <para>
 197     Configuration for database "works". This uses CONSTRUCT to produce rdf.
 198    <screen><![CDATA[
 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>
 202       <form>CONSTRUCT {
 203           ?work bf:title ?wtitle .
 204           ?work bf:instanceTitle ?title .
 205           ?work bf:author ?creator .
 206           ?work bf:subject ?subjectlabel }
 207       </form>
 208       <criteria>?work a bf:Work</criteria>
 209
 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>
 219     </db>
 220  ]]>
 221    </screen>
 222   </para>
 223  </refsect1>
 224
 225  <refsect1><title>EXAMPLE</title>
 226    <para>
 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
 231    <screen><![CDATA[
 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>
 241     </db>
 242  ]]>
 243    </screen>
 244   </para>
 245
 246
 247  </refsect1>
 248
 249  <refsect1><title>SEE ALSO</title>
 250   <para>
 251    <citerefentry>
 252     <refentrytitle>metaproxy</refentrytitle>
 253     <manvolnum>1</manvolnum>
 254    </citerefentry>
 255   </para>
 256  </refsect1>
 257
 258 </refentry>
 259
 260 <!-- Keep this comment at the end of the file
 261 Local variables:
 262 mode: nxml
 263 nxml-child-indent: 1
 264 End:
 265 -->