Version 0.2
[mp-sparql-moved-to-github.git] / 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>). Each
33    db element takes these elements:
34    Configurable values:
35    <variablelist>
36     <varlistentry><term>&lt;prefix/&gt;</term>
37      <listitem>
38       <para>
39        Section that maps prefixes and namespaces for RDF vocabularies.
40        The format is prefix followed by colon, followed by value.
41       </para>
42      </listitem>
43     </varlistentry>
44     <varlistentry><term>&lt;form/&gt;</term>
45      <listitem>
46       <para>
47        SPARQL Query formulation selection. SHould start with one of the
48        query forms: SELECT or CONSTRUCT.
49       </para>
50      </listitem>
51     </varlistentry>
52     <varlistentry><term>&lt;criteria/&gt;</term>
53      <listitem>
54       <para>
55        section that allows to map static graph patterns for binding
56        variables, narrowing types, etc, or any other WHERE clause criteria
57        static to the Z39.50/SRU database. The final query conversion logic
58        should be able to deduce which optional criteria should be included
59        in the generated SPARQL by analyzing variables required in the query
60        matching and display fields.
61       </para>
62      </listitem>
63     </varlistentry>
64     <varlistentry><term>&lt;index type="attribute"/&gt;</term>
65      <listitem>
66       <para>
67        Section used to declare RPN use attribute strings (indexes) and map
68        them to BIBFRAME graph patterns.
69        Items in this section are expanded during RPN query processing and
70        placeholders (%s, %d) are substituted with query terms.
71        To map a given CQL index (e.g the default keyword index) into
72        multiple entity properties, SPARQL constructs like
73        `OPTIONAL` or `UNION` could be used.
74       </para>
75      </listitem>
76     </varlistentry>
77    </variablelist>
78   </para>
79  </refsect1>
80
81  <refsect1><title>SCHEMA</title>
82    <literallayout><xi:include
83                      xi:href="filter_sparql.rnc"
84                      xi:parse="text"
85                      xmlns:xi="http://www.w3.org/2001/XInclude" />
86    </literallayout>
87  </refsect1>
88
89  <refsect1><title>EXAMPLES</title>
90   <para>
91    Configuration for database "Default" that allows searching works. Only
92    the field (use attribute) "bf.wtitle" is supported.
93    <screen><![CDATA[
94   <filter type="sparql">
95     <db path="Default" uri="http://bibframe.indexdata.com/sparql/">
96       <prefix>rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns</prefix>
97       <prefix>bf: http://bibframe.org/vocab/</prefix>
98       <field>?work ?wtitle</field>
99       <criteria>?work a bf:Work</criteria>
100       <criteria>?work bf:workTitle ?wt</criteria>
101       <criteria>?wt bf:titleValue ?wtitle</criteria>
102       <index type="bf.wtitle">?wt bf:titleValue %v FILTER(contains(%v, %s))</index>
103     </db>
104   </filter>
105 ]]>
106    </screen>
107   </para>
108  </refsect1>
109
110  <refsect1><title>SEE ALSO</title>
111   <para>
112    <citerefentry>
113     <refentrytitle>metaproxy</refentrytitle>
114     <manvolnum>1</manvolnum>
115    </citerefentry>
116   </para>
117  </refsect1>
118
119 </refentry>
120
121 <!-- Keep this comment at the end of the file
122 Local variables:
123 mode: nxml
124 nxml-child-indent: 1
125 End:
126 -->