<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>Pazpar2 conf</refentrytitle>
<manvolnum>5</manvolnum>
<refmiscinfo class="manual">File formats and conventions</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>pazpar2_conf</refname>
<refpurpose>Pazpar2 Configuration</refpurpose>
</refnamediv>
-
+
<refsynopsisdiv>
<cmdsynopsis>
<command>pazpar2.conf</command>
</cmdsynopsis>
</refsynopsisdiv>
-
+
<refsect1>
<title>DESCRIPTION</title>
<para>
extraction of data elements from incoming result records, for the
purposes of merging, sorting, facet analysis, and display.
</para>
-
+
<para>
The file is specified using the option -f on the Pazpar2 command line.
There is not presently a way to reload the configuration file without
in the future.
</para>
</refsect1>
-
+
<refsect1>
<title>FORMAT</title>
<para>
The configuration file is XML-structured. It must be well-formed XML. All
elements specific to Pazpar2 should belong to the namespace
- <literal>http://www.indexdata.com/pazpar2/1.0</literal>
+ <literal>http://www.indexdata.com/pazpar2/1.0</literal>
(this is assumed in the
following examples). The root element is named "<literal>pazpar2</literal>".
Under the root element are a number of elements which group categories of
information. The categories are described below.
</para>
-
+
<refsect2 id="config-threads">
<title>threads</title>
<para>
in main thread).
</para>
</refsect2>
+ <refsect2 id="config-sockets">
+ <title>sockets</title>
+ <para>
+ This section is optional and is supported for Pazpar2 version 1.13.0 and
+ later . It is identified by element "<literal>sockets</literal>" which
+ may include one attribute "<literal>max</literal>" which specifies
+ the maximum number of sockets to be used by Pazpar2.
+ </para>
+ </refsect2>
+ <refsect2 id="config-file">
+ <title>file</title>
+ <para>
+ This configuration takes one attribute <literal>path</literal> which
+ specifies a path to search for local files, such as XSLTs and settings.
+ The path is a colon separated list of directories. Its default value
+ is "<literal>.</literal>" which is equivalent to the location of the
+ main configuration file (where indeed the file element is given).
+ </para>
+ </refsect2>
<refsect2 id="config-server">
<title>server</title>
<para>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>proxy</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>relevance / sort / mergekey / facet</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>settings</term>
<listitem>
The settings element requires one attribute 'src' which specifies
a settings file or a directory . If a directory is given all
files with suffix <filename>.xml</filename> is read from this
- directory. Refer to
+ directory. Refer to
<xref linkend="target_settings"/> for more information.
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
- <term>service</term>
+ <term id="service_conf">service</term>
<listitem>
<para>
This nested element controls the behavior of Pazpar2 with
ranking, merging, and display of data elements. It supports
the following attributes:
</para>
-
+
<variablelist> <!-- level 3 -->
<varlistentry>
<term>name</term>
<para>
This is the name of the data element. It is matched
against the 'type' attribute of the
- 'metadata' element
+ 'metadata' element
in the normalized record. A warning is produced if
metadata elements with an unknown name are
- found in the
+ found in the
normalized record. This name is also used to
- represent
+ represent
data elements in the records returned by the
webservice API, and to name sort lists and browse
facets.
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>type</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>brief</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>sortkey</term>
<listitem>
articles), and 'no' (no sorting). The default value is
'no'.
</para>
+ <para>
+ When 'skiparticle' is used, some common articles from the
+ English and German languages are ignored. At present the
+ list is: 'the', 'den', 'der', 'die', 'des', 'an', 'a'.
+ </para>
</listitem>
</varlistentry>
-
+
<varlistentry>
- <term>rank</term>
+ <term id="metadata-rank">rank</term>
<listitem>
<para>
Specifies that this element is to be used to
- help rank
+ help rank
records against the user's query (when ranking is
- requested). The value is an integer, used as a
- multiplier against the basic TF*IDF score. A value of
- 1 is the base, higher values give additional
- weight to
+ requested).
+ The valus is of the form
+ <literallayout>
+ M [F N]
+ </literallayout>
+ where M is an integer, used as a
+ weight against the basic TF*IDF score. A value of
+ 1 is the base, higher values give additional weight to
elements of this type. The default is '0', which
excludes this element from the rank calculation.
</para>
+ <para>
+ F is a CCL field and N is the multipler for terms
+ that matches those part of the CCL field in search.
+ The F+N combo allows the system to use a different
+ multipler for a certain field. For example, a rank value of
+ "<literal>1 au 3</literal>" gives a multipler of 3 for
+ all terms part of the au(thor) terms and 1 for everything else.
+ </para>
+ <para>
+ For Pazpar2 1.6.13 and later, the rank may also defined
+ "per-document", by the normalization stylesheet.
+ </para>
+ <para>
+ The per field rank was introduced in Pazpar2 1.6.15. Earlier
+ releases only allowed a rank value M (simple integer).
+ </para>
+ See <xref linkend="relevance_ranking"/> for more
+ about ranking.
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>termlist</term>
<listitem>
termlist, or browse facet. Values are tabulated from
incoming records, and a highscore of values (with
their associated frequency) is made available to the
- client through the webservice API.
+ client through the webservice API.
The possible values
are 'yes' and 'no' (default).
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>merge</term>
<listitem>
all elements), or 'no' (don't merge; this is the
default);
</para>
+ <para>
+ Pazpar 1.6.24 also offers a new value for merge, 'first', which
+ is like 'all' but only takes all from first database that returns
+ the particular metadata field.
+ </para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>mergekey</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
+ <varlistentry>
+ <term id="limitcluster">limitcluster</term>
+ <listitem>
+ <para>
+ Allow a limit on merged metadata. The value of this attribute
+ is the name of actual metadata content to be used for matching
+ (most often same name as metadata name).
+ </para>
+ <note>
+ <para>
+ Requires Pazpar2 1.6.23 or later.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term id="metadata_limitmap">limitmap</term>
+ <listitem>
+ <para>
+ Specifies a default limitmap for this field. This is to avoid mass
+ configuring of targets. However it is important to review/do
+ this on a per target since it is usually target-specific.
+ See limitmap for format.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term id="metadata_facetmap">facetmap</term>
+ <listitem>
+ <para>
+ Specifies a default facetmap for this field. This is to avoid mass
+ configuring of targets. However it is important to review/do
+ this on a per target since it is usually target-specific.
+ See facetmap for format.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term id="icurule">icurule</term>
+ <listitem>
+ <para>
+ Specifies the ICU rule set to be used for normalizing
+ metadata text. The "display" part of the rule is kept
+ in the returned metadata record (record+show commands), the
+ end result - normalized text - is used for performing
+ within-cluster merge (unique, longest, etc). If the icurule is
+ omitted, type generic (text) is converted as follows:
+ any of the characters "<literal> ,/.:([</literal>" are
+ chopped of prefix and suffix of text content
+ <emphasis>unless</emphasis> it includes the
+ characters "<literal>://</literal>" (URL).
+ </para>
+ <note>
+ <para>
+ Requires Pazpar2 1.9.0 or later.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>setting</term>
<listitem>
are allowed. 'no' is the default and doesn't do anything.
'postproc' copies the value of a setting with the same name
into the output of the normalization stylesheet(s). 'parameter'
- makes the value of a setting with the same name available
+ makes the value of a setting with the same name available
as a parameter to the normalization stylesheet, so you
can further process the value inside of the stylesheet, or use
the value to decide how to deal with other data values.
</para>
</listitem>
</varlistentry>
-
+
</variablelist> <!-- attributes to metadata -->
-
+
</listitem>
</varlistentry>
rule set.
Pazpar2 uses the particular rule sets for particular purposes.
Rule set 'relevance' is used to normalize
- terms for relevance ranking. Rule set 'sort' is used to
+ terms for relevance ranking. Rule set 'sort' is used to
normalize terms for sorting. Rule set 'mergekey' is used to
normalize terms for making a mergekey and, finally. Rule set 'facet'
is normally used to normalize facet terms, unless
in any order, except the 'index' element which logically
belongs to the end of the list. The stated tokenization,
transformation and charmapping instructions are performed
- in order from top to bottom.
+ in order from top to bottom.
</para>
<variablelist> <!-- Level 2 -->
<varlistentry>
<para>
The attribute 'rule' defines the direction of the
per-character casemapping, allowed values are "l"
- (lower), "u" (upper), "t" (title).
+ (lower), "u" (upper), "t" (title).
</para>
</listitem>
</varlistentry>
Normalization and transformation of tokens follows
the rules defined in the 'rule' attribute. For
possible values we refer to the extensive ICU
- documentation found at the
+ documentation found at the
<ulink url="&url.icu.transform;">ICU
transformation</ulink> home page. Set filtering
- principles are explained at the
+ principles are explained at the
<ulink url="&url.icu.unicode.set;">ICU set and
filtering</ulink> page.
</para>
'rule' attribute may have the following values:
"s" (sentence), "l" (line-break), "w" (word), and
"c" (character), the later probably not being
- very useful in a pruning Pazpar2 installation.
+ very useful in a pruning Pazpar2 installation.
</para>
</listitem>
</varlistentry>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>relevance</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>sort</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>mergekey</term>
<listitem>
<para>
Specifies ICU tokenization and transformation rules
- for tokens that are used in Pazpar2's mergekey.
+ for tokens that are used in Pazpar2's mergekey.
The child element of 'mergekey' must be 'icu_chain' and the
'id' attribute of the icu_chain is ignored. This
definition is obsolete and should be replaced by the equivalent
</para>
</listitem>
</varlistentry>
-
+
+ <varlistentry>
+ <term>ccldirective</term>
+ <listitem>
+ <para>
+ Customizes the CCL parsing (interpretation of query parameter
+ in search).
+ The name and value of the CCL directive is gigen by attributes
+ 'name' and 'value' respectively. Refer to possible list of names
+ in the
+ <ulink
+ url="http://www.indexdata.com/yaz/doc/tools.html#ccl.directives.table">
+ YAZ manual
+ </ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="service-rank">
+ <term>rank</term>
+ <listitem>
+ <para>
+ Customizes the ranking (relevance) algorithm. Also known as
+ rank tweaks. The rank element
+ accepts the following attributes - all being optional:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>cluster</term>
+ <listitem>
+ <para>
+ Attribute 'cluster' is a boolean
+ that controls whether Pazpar2 should boost ranking for merged
+ records. Is 'yes' by default. A value of 'no' will make
+ Pazpar2 average ranking of each record in a cluster.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>debug</term>
+ <listitem>
+ <para>
+ Attribute 'debug' is a boolean
+ that controls whether Pazpar2 should include details
+ about ranking for each document in the show command's
+ response. Enable by using value "yes", disable by using
+ value "no" (default).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>follow</term>
+ <listitem>
+ <para>
+ Attribute 'follow' is a a floating point number greater than
+ or equal to 0. A positive number will boost weight for terms
+ that occur close to each other (proximity, distance).
+ A value of 1, will double the weight if two terms are in
+ proximity distance of 1 (next to each other). The default
+ value of 'follow' is 0 (order will not affect weight).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>lead</term>
+ <listitem>
+ <para>
+ Attribute 'lead' is a floating point number.
+ It controls if term weight should be reduced by position
+ from start in a metadata field. A positive value of 'lead'
+ will reduce weight as it apperas further away from the lead
+ of the field. Default value is 0 (no reduction of weight by
+ position).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>length</term>
+ <listitem>
+ <para>
+ Attribute 'length' determines how/if term weight should be
+ divided by lenght of metadata field. A value of "linear"
+ divide by length. A value of "log" will divide by log2(length).
+ A value of "none" will leave term weight as is (no division).
+ Default value is "linear".
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Refer to <xref linkend="relevance_ranking"/> to see how
+ these tweaks are used in computation of score.
+ </para>
+ <para>
+ Customization of ranking algorithm was introduced with
+ Pazpar2 1.6.18. The semantics of some of the fields changed
+ in versions up to 1.6.22.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="sort-default">
+ <term>sort-default</term>
+ <listitem>
+ <para>
+ Specifies the default sort criteria (default 'relevance'),
+ which previous was hard-coded as default criteria in search.
+ This is a fix/work-around to avoid re-searching when using
+ target-based sorting. In order for this to work efficient,
+ the search must also have the sort critera parameter; otherwise
+ pazpar2 will do re-searching on search criteria changes, if
+ changed between search and show command.
+ </para>
+ <para>
+ This configuration was added in pazpar2 1.6.20.
+ </para>
+ </listitem>
+ </varlistentry>
+
+<!--
+ <varlistentry>
+ <term>set</term>
+ <listitem>
+ <para>
+ Specifies a variable that will be inherited by all targets defined in settings
+ <screen>
+ <set name="test" value="en"..<set>
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+-->
<varlistentry>
<term>settings</term>
<listitem>
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="service-timeout">
<term>timeout</term>
<listitem>
<para>
Specifies timeout parameters for this service.
The <literal>timeout</literal>
- element supports the following attributes:
+ element supports the following attributes:
<literal>session</literal>, <literal>z3950_operation</literal>,
<literal>z3950_session</literal> which specifies
'session timeout', 'Z39.50 operation timeout',
z3950_operation (30) < session (60) < z3950_session (180) .
The default values are given in parantheses.
</para>
+ <para>
+ The Z39.50 operation timeout may be set per database. Refer to
+ <xref linkend="pztimeout"/>.
+ </para>
</listitem>
</varlistentry>
</variablelist> <!-- Data elements in service directive -->
<server>
<listen port="9004"/>
<service>
+ <rank debug="yes"/>
<metadata name="title" brief="yes" sortkey="skiparticle"
merge="longest" rank="6"/>
<metadata name="isbn" merge="unique"/>
type="year" merge="range" termlist="yes"/>
<metadata name="author" brief="yes" termlist="yes"
merge="longest" rank="2"/>
- <metadata name="subject" merge="unique" termlist="yes" rank="3"/>
+ <metadata name="subject" merge="unique" termlist="yes" rank="3" limitmap="local:"/>
<metadata name="url" merge="unique"/>
<icu_chain id="relevance" locale="el">
<transform rule="[:Control:] Any-Remove"/>
</pazpar2>
]]>
</screen>
- </refsect1>
+ </refsect1>
<refsect1 id="config-include">
<title>INCLUDE FACILITY</title>
<para>
The XML configuration may be partitioned into multiple files by using
the <literal>include</literal> element which takes a single attribute,
- <literal>src</literal>. The of the <literal>src</literal> attribute is
+ <literal>src</literal>. The <literal>src</literal> attribute is
regular Shell like glob-pattern. For example,
<screen><
projects / pazpar2-moved-to-github.git / blobdiff