1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
5 <!ENTITY % local SYSTEM "local.ent">
7 <!ENTITY manref SYSTEM "manref.xml">
8 <!ENTITY gpl2 SYSTEM "gpl-2.0.xml">
9 <!ENTITY % idcommon SYSTEM "common/common.ent">
14 <title>MP-SPARQL - User's Guide and Reference</title>
17 <firstname>Adam</firstname><surname>Dickmeiss</surname>
20 <firstname>Heikki</firstname><surname>Levanto</surname>
23 <firstname>Jakub</firstname><surname>Skoczen</surname>
26 <releaseinfo>&version;</releaseinfo>
28 <year>2014-2015</year>
29 <holder>Index Data</holder>
33 This manual is part of MP-SPARQL version &version;.
36 MP-XQuery is a Metaproxy module that converts Type-1/RPN Queries
40 MP-SPARQL is covered by the GNU General Public License version 2.
45 <imagedata fileref="common/id.png" format="PNG"/>
48 <imagedata fileref="common/id.eps" format="EPS"/>
54 <chapter id="introduction">
55 <title>Introduction</title>
57 MP-SPARQL is a <ulink url="&url.metaproxy;">Metaproxy</ulink> module
58 that converts Type-1/RPN queries to <ulink url="http://www.w3.org/TR/rdf-sparql-query/">SPARQL</ulink>.
61 <chapter id="installation">
62 <title>Installation</title>
64 MP-SPARQL is available as packages for CentOS/RHEL and most
65 recent Ubuntu/Debian versions. For other systems, the module must be build
68 <sect1 id="installation.packages">
69 <title>Installing packages</title>
71 You need to enable the relevant software repositories.
72 For setting up refer to one of:
74 url="http://ftp.indexdata.dk/pub/mp-sparql/redhat/centos/5.5/README">CentOS 5</ulink>,
76 url="http://ftp.indexdata.dk/pub/mp-sparql/redhat/centos/6/README">CentOS 6</ulink>
79 url="http://ftp.indexdata.dk/pub/mp-sparql/redhat/centos/7/README">CentOS 7</ulink>
82 url="http://ftp.indexdata.dk/pub/mp-sparql/ubuntu/README">Ubuntu</ulink>
85 url="http://ftp.indexdata.dk/pub/mp-sparql/debian/README">Debian</ulink>
88 The package is called <literal>mp-sparql</literal> on RHEL/Debian systems.
89 Install that package and you are ready to use filter "sparql" in your
93 mp-sparql depends on a number of packages created by Index Data and
94 system-provided ones, such as Libxml2. For external software Zorba, no
95 system package exist so Index Data has packaged that separately. This
96 package is called <literal>idzorba</literal>. All these dependences should
97 be automatically installed when the Index Data software repository is
101 <sect1 id="installation.source">
102 <title>Installing from source</title>
104 To build from source, you need metaproxy development
105 packages. Metaproxy can be installed as follows:
111 Refer to the Metaproxy documentation for requirements and options.
114 We are now ready to build the MP-SPARQL module with:
117 make MP_CONFIG=/usr/local/bin/mp-config
119 Adjust <literal>MP_CONFIG</literal> value
120 above for the correct location of installed
121 Metaproxy's mp-config. <literal>MP_CONFIG</literal> can be omitted
122 if Metaproxy was installed in the system <filename>PATH</filename>.
125 You can now install the <filename>metaproxy_filter_sparql.so</filename>
126 in a directory searched by Metaproxy daemon.
127 Specifically, that's the directories
128 given by the <literal>dlpath</literal> configuration.
131 If dlpath includes <filename>/usr/lib/metaproxy6/modules</filename>,
132 the module can be installed with:
134 cp src/metaproxy_filter_sparql.so /usr/lib/metaproxy6/modules
139 For RHEL/CentOS systems on 64-bit architectures, the correct paths is:
140 <filename>/usr/lib64/metaproxy6/modules</filename>.
144 <sect1 id="configuration">
145 <title>Configuration</title>
147 If you have installed mp-sparql as a package or have executed
148 <literal>make install</literal> from source, sample configuration
149 can be found in <filename>/usr/share/mp-sparql/bibframe</filename> or
150 <filename>/usr/local/share/mp-sparql/bibframe</filename>. In the
151 the following /usr/share prefix assumed. Adjust accordingly.
152 The directory contains these files:
155 <term><filename>triplestore.xml</filename></term>
158 A mature PQF to SPARQL configuration illustrating a lot of the
159 configuration facilities that are described in the manual
160 page of <xref linkend="sparql"/>.
165 <term><filename>config-sparql.xml</filename></term>
168 A full metaproxy configuration file that includes
169 <filename>triplestore.xml</filename> cofiguration for the
170 mp-sparql filter, enables SRU and CQL to PQF conversion.
175 <term><filename>filter-sparql.xml</filename></term>
178 A partial metaproxy configuration suitable to be enabled in
179 <filename>/etc/metaproxy/filters-enabled</filename>.
180 This includes <filename>triplestore.xml</filename> as well.
187 If you want to use the package layout and modular configuration we
188 suggest you use filter-sparql.xml and perform something along the lines of:
190 cp /usr/share/mp-sparql/bibframe/filter-sparql.xml /etc/metaproxy/filters-available
191 cp /usr/share/mp-sparql/bibframe/triplestore.xml /etc/metaproxy
192 vi /etc/metaproxy/triplestore.xml
193 ln -s ../filters-available/filter-sparql.xml /etc/metaproxy/filters-enabled
194 service metaproxy restart
196 A copy of triplestore.xml is made. Adjust the
197 <literal><defaults uri=.. </literal> value to the URI of your
201 If you want to create your own top-level configuration, you can copy
202 <filename>config-sparql.xml</filename> to any location you like and
203 run metaproxy with that. Something like this:
206 cp /usr/share/mp-sparql/bibframe/* /etc/myconfig
207 sudo vi /etc/myconfig/triplestore.xml
208 metaproxy -c /etc/myconfig/config-sparql.xml
210 Again, a copy of triplestore.xml is made. Adjust the
211 <literal><defaults uri=.. </literal> value to the URI of your
216 Do not edit files in <filename>/usr/share/mp-sparql/bibframe</filename>.
217 They are only samples and will be overwritten by a package update.
218 Instead copy the files away from there if you need to modify them.
223 <title>Using the service</title>
225 Either way, unless you have adjusted the metaproxy configuration,
226 Metaproxy can be reached on port 9000. Example using yaz-client and
229 adam@tuna:~$ yaz-client localhost:9000/work
232 Connection accepted by v3 target.
235 Version: 1.9.0/5.14.6 87faebe8ef5cab8f6df86f387e8b919b7b9897a8
236 Options: search present namedResultSets
238 Z> f @attr 1=bf.anytitle water
240 Received SearchResponse.
241 Search was a success.
242 Number of hits: 1, setno 1
246 Sent presentRequest (1+1).
248 [work]Record type: XML
249 <?xml version="1.0" encoding="utf-8" ?>
251 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
252 xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
253 xmlns:ns2="http://bibframe.org/vocab/" >
254 <rdf:Description rdf:about="http://bibframe.org/resources/sample-lc-2/15513351">
257 </rdf:RDF>nextResultSetPosition = 0
263 <ulink url="http://localhost:9000/work?query=bf.anytitle%3Dwater&maximumRecords=1"/>
267 <reference id="reference">
268 <title>Reference</title>
269 <partintro id="reference-introduction">
271 The material in this chapter is drawn directly from the individual
278 <appendix id="license">
279 <title>License</title>
281 Copyright (C) 2014-2015 Index Data
285 Metaproxy is free software; you can redistribute it and/or modify it under
286 the terms of the GNU General Public License as published by the Free
287 Software Foundation; either version 2, or (at your option) any later
292 Metaproxy is distributed in the hope that it will be useful, but WITHOUT ANY
293 WARRANTY; without even the implied warranty of MERCHANTABILITY or
294 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
299 You should have received a copy of the GNU General Public License
300 along with Metaproxy; see the file LICENSE. If not, write to the
301 Free Software Foundation,
302 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
310 <!-- Keep this comment at the end of the file