Document POSTing of settings/services PAZ-865

[pazpar2-moved-to-github.git] / doc / pazpar2_conf.xml

diff --git a/doc/pazpar2_conf.xml b/doc/pazpar2_conf.xml
index 8aac27a..57427ca 100644 (file)
--- a/doc/pazpar2_conf.xml
+++ b/doc/pazpar2_conf.xml
@@ -163,7 +163,7 @@
     </varlistentry>
     
     <varlistentry>
     </varlistentry>
     
     <varlistentry>

-     <term>service</term>
+     <term id="service_conf">service</term>

      <listitem>
       <para>
        This nested element controls the behavior of Pazpar2 with
      <listitem>
       <para>
        This nested element controls the behavior of Pazpar2 with

@@ -262,13 +262,35 @@
             Specifies that this element is to be used to
             help rank 
             records against the user's query (when ranking is
             Specifies that this element is to be used to
             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>
             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>
          
           </listitem>
          </varlistentry>
          

@@ -300,6 +322,11 @@
             all elements), or 'no' (don't merge; this is the
             default);
            </para>
             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>
          
           </listitem>
          </varlistentry>
          

@@ -339,6 +366,44 @@
          </varlistentry>
          
          <varlistentry>
          </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>setting</term>
           <listitem>
            <para>
           <term>setting</term>
           <listitem>
            <para>

@@ -521,7 +586,138 @@
         </para>
        </listitem>
        </varlistentry>
         </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>
+       <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>
+          &lt;set name="test" value="en"..&lt;set>
+         </screen>
+        </para>
+       </listitem>
+       </varlistentry>
+-->   

        <varlistentry>
        <term>settings</term>
        <listitem>
        <varlistentry>
        <term>settings</term>
        <listitem>

@@ -583,7 +779,7 @@
              type="year" merge="range" termlist="yes"/>
    <metadata name="author" brief="yes" termlist="yes"
              merge="longest" rank="2"/>
              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"/>
    <metadata name="url" merge="unique"/>
    <icu_chain id="relevance" locale="el">
     <transform rule="[:Control:] Any-Remove"/>

@@ -605,7 +801,7 @@
   <para>
    The XML configuration may be partitioned into multiple files by using
    the <literal>include</literal> element which takes a single attribute,
   <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><![CDATA[
    <include src="/etc/pazpar2/conf.d/*.xml"/>
    regular Shell like glob-pattern. For example,
    <screen><![CDATA[
    <include src="/etc/pazpar2/conf.d/*.xml"/>

@@ -1078,6 +1274,35 @@
      </listitem>
     </varlistentry>
     <varlistentry>
      </listitem>
     </varlistentry>
     <varlistentry>

+     <term>pz:extendrecs</term>
+     <listitem>
+      <para>
+       If a show command goes to the boundary of a result set for a
+       database - depends on sorting - and pz:extendrecs is set to a positive
+       value. then Pazpar2 wait for show to fetch pz:extendrecs more
+       records. This setting is best used if a database does native
+       sorting, because the result set otherwise may be completely
+       re-sorted during extended fetch.
+       The default value of pz:extendrecs is 0 (no extended fetch).
+      </para>
+      <warning>
+       <para>
+       The pz:extendrecs setting appeared in Pazpar2 version 1.6.26.
+       But the bahavior changed with the release of Pazpar2 1.6.29.
+       </para>
+      </warning>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>pz:presentchunk</term>
+     <listitem>
+      <para>
+       Controls the chunk size in present requests. Pazpar2 will 
+       make (maxrecs / chunk) request(s). The default is 20.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>

      <term>pz:id</term>
      <listitem>
       <para>
      <term>pz:id</term>
      <listitem>
       <para>

@@ -1114,7 +1339,7 @@
      <listitem>
       <para>
        This setting enables
      <listitem>
       <para>
        This setting enables

-       <ulink url="&url.sru;">SRU</ulink>/<ulink url="&url.solr;">SOLR</ulink>
+       <ulink url="&url.sru;">SRU</ulink>/<ulink url="&url.solr;">Solr</ulink>

        support.
        It has four possible settings.
        'get', enables SRU access through GET requests. 'post' enables SRU/POST
        support.
        It has four possible settings.
        'get', enables SRU access through GET requests. 'post' enables SRU/POST

@@ -1123,7 +1348,7 @@
        the protocol.
       </para>
       <para>
        the protocol.
       </para>
       <para>

-       A value of 'solr' anables SOLR client support. This is supported
+       A value of 'solr' enables Solr client support. This is supported

        for Pazpar version 1.5.0 and later.
       </para>
      </listitem>
        for Pazpar version 1.5.0 and later.
       </para>
      </listitem>

@@ -1135,7 +1360,7 @@
       <para>
        This allows SRU version to be specified. If unset Pazpar2
        will the default of YAZ (currently 1.2). Should be set
       <para>
        This allows SRU version to be specified. If unset Pazpar2
        will the default of YAZ (currently 1.2). Should be set

-       to 1.1 or 1.2. For SOLR, the current supported/tested version is 1.4
+       to 1.1 or 1.2. For Solr, the current supported/tested version is 1.4 and 3.x.

       </para>
      </listitem>
     </varlistentry>
       </para>
      </listitem>
     </varlistentry>

@@ -1220,7 +1445,6 @@
       </para>
      </listitem>
     </varlistentry>
       </para>
      </listitem>
     </varlistentry>

-

     <varlistentry>
      <term>pz:block_timeout</term>
      <listitem>
     <varlistentry>
      <term>pz:block_timeout</term>
      <listitem>

@@ -1230,6 +1454,29 @@
       </para>
      </listitem>
     </varlistentry>
       </para>
      </listitem>
     </varlistentry>

+    <varlistentry>
+     <term>pz:termlist_term_count</term>
+     <listitem>
+      <para>
+       Specifies number of facet terms to be requested from the target. 
+       The default is unspecified e.g. server-decided. Also see pz:facetmap.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>pz:termlist_term_factor</term>
+     <listitem>
+      <para>
+       Specifies whether to use a factor for pazpar2 generated facets (1) or not (0). 
+       When mixing locallly generated (by the downloaded (pz:maxrecs) samples) 
+       facet with native (target-generated) facets, the later will dominated the dominate the facet list
+       since they are generated based on the complete result set. 
+       By scaling up the facet count using the ratio between total hit count and the sample size, 
+       the total facet count can be approximated and thus better compared with native facets. 
+       This is not enabled by default.
+      </para>
+     </listitem>
+    </varlistentry>

 
     <varlistentry>
      <term>pz:facetmap:<replaceable>name</replaceable></term>
 
     <varlistentry>
      <term>pz:facetmap:<replaceable>name</replaceable></term>

@@ -1241,7 +1488,7 @@
       </para>
       <note>
        <para>
       </para>
       <note>
        <para>

-       At this point only SOLR targets have been tested with this
+       At this point only Solr targets have been tested with this

        facility.
        </para>
       </note>
        facility.
        </para>
       </note>

@@ -1268,6 +1515,12 @@
        by a field a metadata field (default is to use the name of the 
        limitmap itself).
       </para>
        by a field a metadata field (default is to use the name of the 
        limitmap itself).
       </para>

+      <para>
+       For Pazpar2 version 1.6.23 and later the limitmap may include multiple
+       specifications, separated by <literal>,</literal> (comma).
+       For example:
+       <literal>ccl:title,local:ltitle,rpn:@attr 1=4</literal>.
+      </para>

       <note>
        <para>
        The limitmap facility is supported for Pazpar2 version 1.6.0.
       <note>
        <para>
        The limitmap facility is supported for Pazpar2 version 1.6.0.