/usr/share/doc/xapian-doc/remote

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>Remote Backend Protocol</title>
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
  overflow: hidden;
}

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left, object.align-left {
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right, object.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

img.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: inherit }

/* div.align-center * { */
/*   text-align: left } */

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block, pre.math {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="remote-backend-protocol">
<h1 class="title">Remote Backend Protocol</h1>

<p>This document describes <em>version 35.1</em> of the protocol used by Xapian's
remote backend. The major protocol version increased to 35 in Xapian
1.1.5, and the minor protocol version to 1 in Xapian 1.2.4. Clients and
servers must support matching major protocol versions and the client's
minor protocol version must be the same or lower. This means that for a
minor protocol version change, you can upgrade first servers and then
clients and everything should work during the upgrades.</p>
<p>The protocol assumes a reliable two-way connection across which
arbitrary data can be sent - this could be provided by a TCP socket for
example (as it is with xapian-tcpsrv), but any such connection could be
used. For example, you could used xapian-progsrv across an ssh
connection, or even a custom server across a suitable serial connection.</p>
<p>All messages start with a single byte identifying code. A message from
client to server has a <tt class="docutils literal">MSG_XXX</tt> identifying code, while a message
from server to client has a <tt class="docutils literal">REPLY_XXX</tt> identifying code (but note
that a reply might not actually be in response to a message -
REPLY_GREETING isn't - and some messages result in multiple replies).</p>
<p>The identifying code is followed by the encoded length of the contents
followed by the contents themselves.</p>
<p>Inside the contents, strings are generally passed as an encoded length
followed by the string data (this is indicated below by <tt class="docutils literal"><span class="pre">L&lt;...&gt;</span></tt>)
except when the string is the last or only thing in the contents in
which case we know the length because we know the length of the contents
so we don't need to explicitly specify it.</p>
<p>Integers are encoded using the same encoding used for string lengths
(indicated by <tt class="docutils literal"><span class="pre">I&lt;...&gt;</span></tt> below).</p>
<p>Floating pointing values are passed using a bit packed encoding of the
sign and exponent and a base-256 encoding of the mantissa which avoids
any rounding issues (assuming that both machines have FLT_RADIX equal
to some power of 2). This is indicated by <tt class="docutils literal"><span class="pre">F&lt;...&gt;</span></tt> below.</p>
<p>Boolean values are passed as a single byte which is the ASCII character
value for <tt class="docutils literal">0</tt> or <tt class="docutils literal">1</tt>. This is indicated by <tt class="docutils literal"><span class="pre">B&lt;...&gt;</span></tt> below.</p>
<div class="section" id="server-greeting-and-statistics">
<h1>Server greeting and statistics</h1>
<ul class="simple">
<li><tt class="docutils literal">REPLY_GREETING &lt;protocol major version&gt; &lt;protocol minor version&gt; I&lt;db doc count&gt; I&lt;last docid&gt; B&lt;has <span class="pre">positions?&gt;</span> I&lt;db total length&gt; &lt;UUID&gt;</tt></li>
</ul>
<p>The protocol major and minor versions are passed as a single byte each
(e.g. <tt class="docutils literal">'\x1e\x01'</tt> for version 30.1). The server and client must
understand the same protocol major version, and the server protocol
minor version must be greater than or equal to that of the client (this
means that the server understands newer MSG_<em>XXX</em>, but will only send
newer REPLY_<em>YYY</em> in response to an appropriate client message.</p>
</div>
<div class="section" id="exception">
<h1>Exception</h1>
<ul class="simple">
<li><tt class="docutils literal">REPLY_EXCEPTION &lt;serialised <span class="pre">Xapian::Error</span> object&gt;</tt></li>
</ul>
<p>If an unknown exception is caught by the server, this message is sent
but with empty contents.</p>
<p>This message can be sent at any point - the serialised exception is
unserialised by the client and thrown. The server and client both abort
any current sequence of messages.</p>
</div>
<div class="section" id="write-access">
<h1>Write Access</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_WRITEACCESS</tt></li>
<li><tt class="docutils literal">REPLY_UPDATE I&lt;db doc count&gt; I&lt;last docid&gt; B&lt;has <span class="pre">positions?&gt;</span> I&lt;db total length&gt; &lt;UUID&gt;</tt></li>
</ul>
<p>The reply is the same as for <tt class="docutils literal">MSG_UPDATE</tt>. If write access isn't
supported or the database is locked by another writer, then an exception
is thrown.</p>
<p>By default the server is also read-only, even if writing is supported.
If the client wants to be able to write, it needs to request this
explicitly. We do this so that the same server can support multiple
read-only clients and one writing client at once, without the protocol
for read-only clients requiring an extra message. The overhead of an
extra message exchange for a writer is unlikely to matter as indexing is
rarely so real-time critical as searching.</p>
</div>
<div class="section" id="all-terms">
<h1>All Terms</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_ALLTERMS</tt></li>
<li><tt class="docutils literal">REPLY_ALLTERMS I&lt;term freq&gt; L&lt;term name&gt;</tt></li>
<li><tt class="docutils literal">...</tt></li>
<li><tt class="docutils literal">REPLY_DONE</tt></li>
</ul>
</div>
<div class="section" id="term-exists">
<h1>Term Exists</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_TERMEXISTS &lt;term name&gt;</tt></li>
<li><tt class="docutils literal">REPLY_TERMEXISTS</tt> or <tt class="docutils literal">REPLY_TERMDOESNTEXIST</tt></li>
</ul>
</div>
<div class="section" id="term-frequency">
<h1>Term Frequency</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_TERMFREQ &lt;term name&gt;</tt></li>
<li><tt class="docutils literal">REPLY_TERMFREQ I&lt;term freq&gt;</tt></li>
</ul>
</div>
<div class="section" id="collection-frequency">
<h1>Collection Frequency</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_COLLFREQ &lt;term name&gt;</tt></li>
<li><tt class="docutils literal">REPLY_COLLFREQ I&lt;collection freq&gt;</tt></li>
</ul>
</div>
<div class="section" id="document">
<h1>Document</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_DOCUMENT I&lt;document id&gt;</tt></li>
<li><tt class="docutils literal">REPLY_DOCDATA &lt;document data&gt;</tt></li>
<li><tt class="docutils literal">REPLY_VALUE I&lt;value no&gt; &lt;value&gt;</tt></li>
<li><tt class="docutils literal">...</tt></li>
<li><tt class="docutils literal">REPLY_DONE</tt></li>
</ul>
</div>
<div class="section" id="document-length">
<h1>Document Length</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_DOCLENGTH I&lt;document id&gt;</tt></li>
<li><tt class="docutils literal">REPLY_DOCLENGTH I&lt;document length&gt;</tt></li>
</ul>
</div>
<div class="section" id="keep-alive">
<h1>Keep Alive</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_KEEPALIVE</tt></li>
<li><tt class="docutils literal">REPLY_DONE</tt></li>
</ul>
</div>
<div class="section" id="reopen">
<h1>Reopen</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_REOPEN</tt></li>
<li><tt class="docutils literal">REPLY_UPDATE I&lt;db doc count&gt; I&lt;last docid&gt; B&lt;has <span class="pre">positions?&gt;</span> I&lt;db total length&gt; &lt;UUID&gt;</tt></li>
</ul>
<p>The reply is the same as for <tt class="docutils literal">MSG_UPDATE</tt>.</p>
</div>
<div class="section" id="query">
<h1>Query</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_QUERY L&lt;serialised <span class="pre">Xapian::Query</span> object&gt; I&lt;query length&gt; I&lt;collapse max&gt; [I&lt;collapse key number&gt; (if collapse_max <span class="pre">non-zero)]</span> &lt;docid order&gt; I&lt;sort key number&gt; &lt;sort by&gt; B&lt;sort value forward&gt; &lt;percent cutoff&gt; F&lt;weight cutoff&gt; &lt;serialised <span class="pre">Xapian::Weight</span> object&gt; &lt;serialised <span class="pre">Xapian::RSet</span> object&gt; [L&lt;serialised <span class="pre">Xapian::MatchSpy</span> <span class="pre">object&gt;...]</span></tt></li>
<li><tt class="docutils literal">REPLY_STATS &lt;serialised Stats object&gt;</tt></li>
<li><tt class="docutils literal">MSG_GETMSET I&lt;first&gt; I&lt;max items&gt; I&lt;check at least&gt; &lt;serialised global Stats object&gt;</tt></li>
<li><tt class="docutils literal">REPLY_RESULTS L&lt;the result of calling serialise_results() on each <span class="pre">Xapian::MatchSpy&gt;</span> &lt;serialised <span class="pre">Xapian::MSet</span> object&gt;</tt></li>
</ul>
<p>docid order is <tt class="docutils literal">'0'</tt>, <tt class="docutils literal">'1'</tt> or <tt class="docutils literal">'2'</tt>.</p>
<p>sort by is <tt class="docutils literal">'0'</tt>, <tt class="docutils literal">'1'</tt>, <tt class="docutils literal">'2'</tt> or <tt class="docutils literal">'3'</tt>.</p>
</div>
<div class="section" id="termlist">
<h1>Termlist</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_TERMLIST I&lt;document id&gt;</tt></li>
<li><tt class="docutils literal">REPLY_DOCLENGTH I&lt;document length&gt;</tt></li>
<li><tt class="docutils literal">REPLY_TERMLIST I&lt;wdf&gt; I&lt;term freq&gt; L&lt;term name&gt;</tt></li>
<li><tt class="docutils literal">...</tt></li>
<li><tt class="docutils literal">REPLY_DONE</tt></li>
</ul>
</div>
<div class="section" id="positionlist">
<h1>Positionlist</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_POSITIONLIST I&lt;document id&gt; &lt;term name&gt;</tt></li>
<li><tt class="docutils literal">REPLY_POSITIONLIST I&lt;termpos delta - 1&gt;</tt></li>
<li><tt class="docutils literal">...</tt></li>
<li><tt class="docutils literal">REPLY_DONE</tt></li>
</ul>
<p>Since positions must be strictly monotonically increasing, we encode
<tt class="docutils literal">(pos - lastpos - 1)</tt> so that small differences between large position
values can still be encoded compactly. The first position is encoded as
its true value.</p>
</div>
<div class="section" id="postlist">
<h1>Postlist</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_POSTLIST &lt;term name&gt;</tt></li>
<li><tt class="docutils literal">REPLY_POSTLISTSTART I&lt;termfreq&gt; I&lt;collfreq&gt;</tt></li>
<li><tt class="docutils literal">REPLY_POSTLISTITEM I&lt;docid delta - 1&gt; I&lt;wdf&gt; F&lt;document length&gt;</tt></li>
<li><tt class="docutils literal">...</tt></li>
<li><tt class="docutils literal">REPLY_DONE</tt></li>
</ul>
<p>Since document IDs in postlists must be strictly monotonically
increasing, we encode <tt class="docutils literal">(docid - lastdocid - 1)</tt> so that small
differences between large document IDs can still be encoded compactly.
The first document ID is encoded as its true value - 1 (since document
IDs are always &gt; 0).</p>
</div>
<div class="section" id="shut-down">
<h1>Shut Down</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_SHUTDOWN</tt></li>
</ul>
<p>No reply is sent - this message signals that the client has ended the
session.</p>
</div>
<div class="section" id="update">
<h1>Update</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_UPDATE</tt></li>
<li><tt class="docutils literal">REPLY_UPDATE I&lt;db doc count&gt; I&lt;last docid&gt; B&lt;has <span class="pre">positions?&gt;</span> I&lt;db total length&gt; &lt;UUID&gt;</tt></li>
</ul>
<p>Only useful for a <tt class="docutils literal">WritableDatabase</tt> (since the same statistics are
sent when the connection is initiated in the <tt class="docutils literal">REPLY_GREETING</tt> and they
don't change if the database can't change).</p>
</div>
<div class="section" id="add-document">
<h1>Add document</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_ADDDOCUMENT &lt;serialised <span class="pre">Xapian::Document</span> object&gt;</tt></li>
<li><tt class="docutils literal">REPLY_ADDDOCUMENT I&lt;document id&gt;</tt></li>
</ul>
</div>
<div class="section" id="delete-document">
<h1>Delete document</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_DELETEDOCUMENT I&lt;document id&gt;</tt></li>
<li><tt class="docutils literal">REPLY_DONE</tt></li>
</ul>
</div>
<div class="section" id="delete-document-by-term">
<h1>Delete document by term</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_DELETEDOCUMENTTERM &lt;term name&gt;</tt></li>
</ul>
</div>
<div class="section" id="replace-document">
<h1>Replace document</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_REPLACEDOCUMENT I&lt;document id&gt; &lt;serialised <span class="pre">Xapian::Document</span> object&gt;</tt></li>
</ul>
</div>
<div class="section" id="replace-document-by-term">
<h1>Replace document by term</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_REPLACEDOCUMENTTERM L&lt;term name&gt; &lt;serialised <span class="pre">Xapian::Document</span> object&gt;</tt></li>
</ul>
</div>
<div class="section" id="cancel">
<h1>Cancel</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_CANCEL</tt></li>
</ul>
</div>
<div class="section" id="commit">
<h1>Commit</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_COMMIT</tt></li>
<li><tt class="docutils literal">REPLY_DONE</tt></li>
</ul>
</div>
<div class="section" id="set-metadata">
<h1>Set metadata</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_SETMETADATA L&lt;key&gt; &lt;value&gt;</tt></li>
</ul>
</div>
<div class="section" id="get-metadata">
<h1>Get metadata</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_GETMETADATA &lt;key&gt;</tt></li>
<li><tt class="docutils literal">REPLY_METADATA &lt;value&gt;</tt></li>
</ul>
</div>
<div class="section" id="metadata-keys">
<h1>Metadata keys</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_METADATAKEYLIST &lt;prefix&gt;</tt></li>
<li><tt class="docutils literal">REPLY_METADATAKEYLIST &lt;key&gt;</tt></li>
<li><tt class="docutils literal">...</tt></li>
<li><tt class="docutils literal">REPLY_DONE</tt></li>
</ul>
</div>
<div class="section" id="add-spelling">
<h1>Add spelling</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_ADDSPELLING I&lt;freqinc&gt; &lt;word&gt;</tt></li>
</ul>
</div>
<div class="section" id="remove-spelling">
<h1>Remove spelling</h1>
<ul class="simple">
<li><tt class="docutils literal">MSG_REMOVESPELLING I&lt;freqdec&gt; &lt;word&gt;</tt></li>
</ul>
</div>
</div>
</body>
</html>
xapian-doc 1.2.16-2ubuntu1 / usr / share / doc / xapian-doc / remote_protocol.html
