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    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
  33   </para>
  34   <para>
  35    Configuration consists of an optional defaults section and one or more
  36    database sections.
  37   </para>
  38   <para>
  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>.
  42   </para>
  43   <para>
  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
  49    section.
  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:
  55    <variablelist>
  56     <varlistentry><term>&lt;prefix/&gt;</term>
  57      <listitem>
  58       <para>
  59        Section that maps prefixes and namespaces for RDF vocabularies.
  60        The format is prefix followed by colon, followed by value.
  61       </para>
  62      </listitem>
  63     </varlistentry>
  64     <varlistentry><term>&lt;form/&gt;</term>
  65      <listitem>
  66       <para>
  67        SPARQL Query formulation selection. Should start with one of the
  68        query forms: SELECT or CONSTRUCT.
  69       </para>
  70      </listitem>
  71     </varlistentry>
  72     <varlistentry><term>&lt;criteria/&gt;</term>
  73      <listitem>
  74       <para>
  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.
  81       </para>
  82      </listitem>
  83     </varlistentry>
  84     <varlistentry><term>&lt;index type="attribute"/&gt;</term>
  85      <listitem>
  86       <para>
  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>)
  91        are expanded.
  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
  95        `UNION` can be used.
  96       </para>
  97      </listitem>
  98     </varlistentry>
  99     <varlistentry><term>&lt;present type="attribute"/&gt;</term>
 100      <listitem>
 101       <para>
 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
 105        record.
 106       </para>
 107      </listitem>
 108     </varlistentry>
 109     <varlistentry><term>&lt;modifier/&gt;</term>
 110      <listitem>
 111       <para>
 112        Optional section that allows you to add solution sequences or
 113        modifiers.
 114       </para>
 115      </listitem>
 116     </varlistentry>
 117
 118    </variablelist>
 119   </para>
 120  </refsect1>
 121  <refsect1 id="expansions"><title>EXPANSIONS</title>
 122    <variablelist>
 123     <varlistentry><term><literal>%t</literal></term>
 124      <listitem>
 125       <para>
 126        The term verbatim as it appears in the Type-1 query.
 127       </para>
 128      </listitem>
 129     </varlistentry>
 130     <varlistentry><term><literal>%s</literal></term>
 131      <listitem>
 132       <para>
 133        Like <literal>%t</literal> but quoted - for general strings.
 134       </para>
 135      </listitem>
 136     </varlistentry>
 137     <varlistentry><term><literal>%d</literal></term>
 138      <listitem>
 139       <para>
 140        Term - expecting an integer.
 141       </para>
 142      </listitem>
 143     </varlistentry>
 144     <varlistentry><term><literal>%u</literal></term>
 145      <listitem>
 146       <para>
 147        Like <literal>%t</literal>, but with prefix <literal>&lt;</literal>
 148        and suffix <literal>&gt;</literal> - for URIs.
 149       </para>
 150      </listitem>
 151     </varlistentry>
 152     <varlistentry><term><literal>%v</literal></term>
 153      <listitem>
 154       <para>
 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
 157        Type-1 query.
 158       </para>
 159      </listitem>
 160     </varlistentry>
 161    </variablelist>
 162   </refsect1>
 163   <refsect1><title>SCHEMA</title>
 164   <literallayout><xi:include
 165                      xi:href="filter_sparql.rnc"
 166                      xi:parse="text"
 167                      xmlns:xi="http://www.w3.org/2001/XInclude" />
 168    </literallayout>
 169  </refsect1>
 170
 171  <refsect1><title>EXAMPLE</title>
 172   <para>
 173    Configuration for database "Default" that allows searching works. Only
 174    the field (use attribute) "bf.wtitle" is supported.
 175    <screen><![CDATA[
 176   <filter type="sparql">
 177     <db path="Default"
 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>
 186     </db>
 187   </filter>
 188 ]]>
 189    </screen>
 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.
 192   </para>
 193  </refsect1>
 194
 195  <refsect1><title>EXAMPLE</title>
 196   <para>
 197    A more complex configuration for database "work". This could be included in
 198    the same filter section as the "Default" db above.
 199    <screen><![CDATA[
 200     <db path="work" schema="sparql-results">
 201       <prefix>bf: http://bibframe.org/vocab/</prefix>
 202       <form>SELECT
 203               ?work
 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
 207       </form>
 208       <criteria>?work a bf:Work</criteria>
 209
 210       <criteria> OPTIONAL {
 211           ?work bf:workTitle ?wt .
 212           ?wt bf:titleValue ?wtitle }
 213       </criteria>
 214       <criteria> OPTIONAL {
 215           ?work bf:creator ?creator .
 216           ?creator bf:label ?creatorlabel }
 217       </criteria>
 218       <criteria>OPTIONAL {
 219           ?work bf:subject ?subject .
 220           ?subject bf:label ?subjectlabel }
 221       </criteria>
 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"> {
 226             ?work ?op1 ?child .
 227             ?child ?op2 %v FILTER(contains(STR(%v), %s))
 228           }
 229       </index>
 230       <modifier>GROUP BY $work</modifier>
 231     </db>
 232 ]]>
 233    </screen>
 234    </para>
 235    <para>
 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.
 240    </para>
 241    <para>
 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.
 250    </para>
 251  </refsect1>
 252
 253  <refsect1><title>EXAMPLE</title>
 254    <para>
 255     Configuration for database "works". This uses CONSTRUCT to produce rdf.
 256    <screen><![CDATA[
 257     <db path="works" schema="rdf">
 258       <prefix>bf: http://bibframe.org/vocab/</prefix>
 259       <form>CONSTRUCT {
 260           ?work bf:title ?wtitle .
 261           ?work bf:instanceTitle ?title .
 262           ?work bf:author ?creator .
 263           ?work bf:subject ?subjectlabel }
 264       </form>
 265       <criteria>?work a bf:Work</criteria>
 266
 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>
 276     </db>
 277  ]]>
 278    </screen>
 279   </para>
 280  </refsect1>
 281
 282  <refsect1><title>EXAMPLE</title>
 283    <para>
 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
 289    <screen><![CDATA[
 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>
 298     </db>
 299  ]]>
 300    </screen>
 301   </para>
 302
 303  </refsect1>
 304
 305  <refsect1><title>SEE ALSO</title>
 306   <para>
 307    <citerefentry>
 308     <refentrytitle>metaproxy</refentrytitle>
 309     <manvolnum>1</manvolnum>
 310    </citerefentry>
 311   </para>
 312  </refsect1>
 313
 314 </refentry>
 315
 316 <!-- Keep this comment at the end of the file
 317 Local variables:
 318 mode: nxml
 319 nxml-child-indent: 1
 320 End:
 321 -->