xapian-core/docs/serialisation.rst

   1
   2 .. Copyright (C) 2009 Lemur Consulting Ltd
   3 .. Copyright (C) 2009 Olly Betts
   4
   5 ======================================
   6 Serialisation of Queries and Documents
   7 ======================================
   8
   9 .. contents:: Table of contents
  10
  11 Introduction
  12 ============
  13
  14 In order to pass Query and Document objects to or from remote databases, Xapian
  15 includes support for serialising these objects to strings, and then converting
  16 these strings back into objects.  This support may be accessed directly, and
  17 used for storing persistent representations of Query and Document objects.
  18
  19 Be aware that the serialised representation may occasionally change between
  20 releases.  This will be clearly noted in the release notes.
  21
  22 Serialising Documents
  23 =====================
  24
  25 To get a serialised document, simply call the ``Document::serialise()`` method
  26 on the instance of the document::
  27
  28     std::string serialise() const;
  29
  30 Documents are often lazily fetched from databases: this method will first force
  31 the full document contents to be fetched from the database, in order to
  32 serialise them.  The serialised document will have identical contents (data,
  33 terms, positions, values) to the original document.
  34
  35 To get a document from a serialised form, call the static
  36 ``Document::unserialise()`` method, passing it the string returned from
  37 ``serialise()``::
  38
  39     static Document unserialise(const std::string &s);
  40
  41 Serialising Queries
  42 ===================
  43
  44 Serialisation of queries is very similar to serialisation of documents: there
  45 is a ``Query::serialise()`` method to produce a serialised Query, and a
  46 corresponding ``Query::unserialise()`` method to produce a Query from a
  47 serialised representation::
  48
  49     std::string serialise() const;
  50     static Query unserialise(const std::string &s);
  51
  52 However, there is a wrinkle.  Queries can contain arbitrary user-defined
  53 PostingSource subqueries.  In order to serialise and unserialise such queries,
  54 all the PostingSource subclasses used in the query must implement the
  55 ``name()``, ``serialise()`` and ``unserialise()`` methods (see the
  56 `postingsource topic document <postingsource.html>`_ for details of these).
  57 In addition, a special form of unserialise must be used::
  58
  59     static Query unserialise(const std::string & s, const Registry & registry);
  60
  61 The ``Registry`` passed to this method must know about all the
  62 custom posting sources used in the query.  You can tell a Registry
  63 about a custom posting source using the
  64 ``Registry::register_posting_source`` method::
  65
  66     void register_posting_source(const Xapian::PostingSource &source);
  67
  68 Note that Registry objects always know about built-in posting sources
  69 (such as ``ValueWeightPostingSource``), so you don't need to call
  70 ``register_posting_source()`` for them.