Sphinx 0.9.8.1 reference manual
===============================

Free open-source SQL full-text search engine
--------------------------------------------

Copyright (c) 2001-2008 Andrew Aksyonoff, <shodan(at)shodan.ru>

----------------------------------------------------------------------------

Table of Contents

1. Introduction
   1.1. About
   1.2. Sphinx features
   1.3. Where to get Sphinx
   1.4. License
   1.5. Author and contributors
   1.6. History

2. Installation
   2.1. Supported systems
   2.2. Required tools
   2.3. Installing Sphinx
   2.4. Known installation issues
   2.5. Quick Sphinx usage tour

3. Indexing
   3.1. Data sources
   3.2. Attributes
   3.3. MVA (multi-valued attributes)
   3.4. Indexes
   3.5. Restrictions on the source data
   3.6. Charsets, case folding, and translation tables
   3.7. SQL data sources (MySQL, PostgreSQL)
   3.8. xmlpipe data source
   3.9. xmlpipe2 data source
   3.10. Live index updates
   3.11. Index merging

4. Searching
   4.1. Matching modes
   4.2. Boolean query syntax
   4.3. Extended query syntax
   4.4. Weighting
   4.5. Sorting modes
   4.6. Grouping (clustering) search results
   4.7. Distributed searching
   4.8. searchd query log format

5. API reference
   5.1. General API functions
      5.1.1. GetLastError
      5.1.2. GetLastWarning
      5.1.3. SetServer
      5.1.4. SetRetries
      5.1.5. SetArrayResult

   5.2. General query settings
      5.2.1. SetLimits
      5.2.2. SetMaxQueryTime

   5.3. Full-text search query settings
      5.3.1. SetMatchMode
      5.3.2. SetRankingMode
      5.3.3. SetSortMode
      5.3.4. SetWeights
      5.3.5. SetFieldWeights
      5.3.6. SetIndexWeights

   5.4. Result set filtering settings
      5.4.1. SetIDRange
      5.4.2. SetFilter
      5.4.3. SetFilterRange
      5.4.4. SetFilterFloatRange
      5.4.5. SetGeoAnchor

   5.5. GROUP BY settings
      5.5.1. SetGroupBy
      5.5.2. SetGroupDistinct

   5.6. Querying
      5.6.1. Query
      5.6.2. AddQuery
      5.6.3. RunQueries
      5.6.4. ResetFilters
      5.6.5. ResetGroupBy

   5.7. Additional functionality
      5.7.1. BuildExcerpts
      5.7.2. UpdateAttributes
      5.7.3. BuildKeywords
      5.7.4. EscapeString

6. MySQL storage engine (SphinxSE)
   6.1. SphinxSE overview
   6.2. Installing SphinxSE
      6.2.1. Compiling MySQL 5.0.x with SphinxSE
      6.2.2. Compiling MySQL 5.1.x with SphinxSE
      6.2.3. Checking SphinxSE installation

   6.3. Using SphinxSE

7. Reporting bugs
8. sphinx.conf options reference
   8.1. Data source configuration options
      8.1.1. type
      8.1.2. sql_host
      8.1.3. sql_port
      8.1.4. sql_user
      8.1.5. sql_pass
      8.1.6. sql_db
      8.1.7. sql_sock
      8.1.8. mysql_connect_flags
      8.1.9. sql_query_pre
      8.1.10. sql_query
      8.1.11. sql_query_range
      8.1.12. sql_range_step
      8.1.13. sql_attr_uint
      8.1.14. sql_attr_bool
      8.1.15. sql_attr_timestamp
      8.1.16. sql_attr_str2ordinal
      8.1.17. sql_attr_float
      8.1.18. sql_attr_multi
      8.1.19. sql_query_post
      8.1.20. sql_query_post_index
      8.1.21. sql_ranged_throttle
      8.1.22. sql_query_info
      8.1.23. xmlpipe_command
      8.1.24. xmlpipe_field
      8.1.25. xmlpipe_attr_uint
      8.1.26. xmlpipe_attr_bool
      8.1.27. xmlpipe_attr_timestamp
      8.1.28. xmlpipe_attr_str2ordinal
      8.1.29. xmlpipe_attr_float
      8.1.30. xmlpipe_attr_multi

   8.2. Index configuration options
      8.2.1. type
      8.2.2. source
      8.2.3. path
      8.2.4. docinfo
      8.2.5. mlock
      8.2.6. morphology
      8.2.7. stopwords
      8.2.8. wordforms
      8.2.9. exceptions
      8.2.10. min_word_len
      8.2.11. charset_type
      8.2.12. charset_table
      8.2.13. ignore_chars
      8.2.14. min_prefix_len
      8.2.15. min_infix_len
      8.2.16. prefix_fields
      8.2.17. infix_fields
      8.2.18. enable_star
      8.2.19. ngram_len
      8.2.20. ngram_chars
      8.2.21. phrase_boundary
      8.2.22. phrase_boundary_step
      8.2.23. html_strip
      8.2.24. html_index_attrs
      8.2.25. html_remove_elements
      8.2.26. local
      8.2.27. agent
      8.2.28. agent_connect_timeout
      8.2.29. agent_query_timeout
      8.2.30. preopen

   8.3. indexer program configuration options
      8.3.1. mem_limit
      8.3.2. max_iops
      8.3.3. max_iosize

   8.4. searchd program configuration options
      8.4.1. address
      8.4.2. port
      8.4.3. log
      8.4.4. query_log
      8.4.5. read_timeout
      8.4.6. max_children
      8.4.7. pid_file
      8.4.8. max_matches
      8.4.9. seamless_rotate
      8.4.10. preopen_indexes
      8.4.11. unlink_old

A. Sphinx revision history

1. Introduction
===============

1.1. About
----------

Sphinx is a full-text search engine, distributed under GPL version 2.
Commercial licensing (eg. for embedded use) is also available upon request.

Generally, it's a standalone search engine, meant to provide fast,
size-efficient and relevant full-text search functions to other
applications. Sphinx was specially designed to integrate well with SQL
databases and scripting languages.

Currently built-in data source drivers support fetching data either via
direct connection to MySQL, or PostgreSQL, or from a pipe in a custom XML
format. Adding new drivers (eg. to natively support some other DBMSes) is
designed to be as easy as possible.

Search API is natively ported to PHP, Python, Perl, Ruby, Java, and also
available as a pluggable MySQL storage engine. API is very lightweight so
porting it to new language is known to take a few hours.

As for the name, Sphinx is an acronym which is officially decoded as SQL
Phrase Index. Yes, I know about CMU's Sphinx project.

1.2. Sphinx features
--------------------

   * high indexing speed (upto 10 MB/sec on modern CPUs);
   * high search speed (avg query is under 0.1 sec on 2-4 GB text
     collections);
   * high scalability (upto 100 GB of text, upto 100 M documents on
     a single CPU);
   * provides good relevance ranking through combination of phrase
     proximity ranking and statistical (BM25) ranking;
   * provides distributed searching capabilities;
   * provides document exceprts generation;
   * provides searching from within MySQL through pluggable storage engine;
   * supports boolean, phrase, and word proximity queries;
   * supports multiple full-text fields per document (upto 32 by default);
   * supports multiple additional attributes per document (ie. groups,
     timestamps, etc);
   * supports stopwords;
   * supports both single-byte encodings and UTF-8;
   * supports English stemming, Russian stemming, and Soundex for
     morphology;
   * supports MySQL natively (MyISAM and InnoDB tables are both supported);
   * supports PostgreSQL natively.

1.3. Where to get Sphinx
------------------------

Sphinx is available through its official Web site at
http://www.sphinxsearch.com/.

Currently, Sphinx distribution tarball includes the following software:

   * indexer: an utility which creates fulltext indexes;
   * search: a simple command-line (CLI) test utility which searches
     through fulltext indexes;
   * searchd: a daemon which enables external software (eg. Web
     applications) to search through fulltext indexes;
   * sphinxapi: a set of searchd client API libraries for popular Web
     scripting languages (PHP, Python, Perl, Ruby).

1.4. License
------------

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version. See COPYING file for details.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA

If you don't want to be bound by GNU GPL terms (for instance, if you would
like to embed Sphinx in your software, but would not like to disclose its
source code), please contact the author to obtain a commercial license.

1.5. Author and contributors
----------------------------

Author
------

Sphinx initial author and current primary developer is:

   * Andrew Aksyonoff, <shodan(at)shodan.ru>

Contributors
------------

People who contributed to Sphinx and their contributions (in no particular
order) are:

   * Robert "coredev" Bengtsson (Sweden), initial version of PostgreSQL
     data source;
   * Len Kranendonk, Perl API
   * Dmytro Shteflyuk, Ruby API

Many other people have contributed ideas, bug reports, fixes, etc. Thank
you!

1.6. History
------------

Sphinx development was started back in 2001, because I didn't manage to
find an acceptable search solution (for a database driven Web site) which
would meet my requirements. Actually, each and every important aspect was
a problem:

   * search quality (ie. good relevance)

      * statistical ranking methods performed rather bad, especially on
        large collections of small documents (forums, blogs, etc)

   * search speed

      * especially if searching for phrases which contain stopwords, as in
        "to be or not to be"

   * moderate disk and CPU requirements when indexing

      * important in shared hosting enivronment, not to mention the
        indexing speed.

Despite the amount of time passed and numerous improvements made in the
other solutions, there's still no solution which I personally would be
eager to migrate to.

Considering that and a lot of positive feedback received from Sphinx users
during last years, the obvious decision is to continue developing Sphinx
(and, eventually, to take over the world).

2. Installation
===============

2.1. Supported systems
----------------------

Most modern UNIX systems with a C++ compiler should be able to compile and
run Sphinx without any modifications.

Currently known systems Sphinx has been successfully running on are:

   * Linux 2.4.x, 2.6.x (various distributions)
   * Windows 2000, XP
   * FreeBSD 4.x, 5.x, 6.x
   * NetBSD 1.6, 3.0
   * Solaris 9, 11
   * Mac OS X

CPU architectures known to work include X86, X86-64, SPARC64.

I hope Sphinx will work on other Unix platforms as well. If the platform
you run Sphinx on is not in this list, please do report it.

At the moment, Windows version of Sphinx is not intended to be used in
production, but rather for testing and debugging only. Two most prominent
issues are missing concurrent queries support (client queries are stacked
on TCP connection level instead), and missing index data rotation support.
There are succesful production installations which workaround these issues.
However, running high-volume search service under Windows is still not
recommended.

2.2. Required tools
-------------------

On UNIX, you will need the following tools to build and install Sphinx:

   * a working C++ compiler. GNU gcc is known to work.
   * a good make program. GNU make is known to work.

On Windows, you will need Microsoft Visual C/C++ Studio .NET 2003 or 2005.
Other compilers/environments will probably work as well, but for the time
being, you will have to build makefile (or other environment specific
project files) manually.

2.3. Installing Sphinx
----------------------

   1. Extract everything from the distribution tarball (haven't you
      already?) and go to the sphinx subdirectory:

      | $ tar xzvf sphinx-0.9.7.tar.gz
      | $ cd sphinx

   2. Run the configuration program:

      | $ ./configure

      There's a number of options to configure. The complete listing may be
      obtained by using --help switch. The most important ones are:

      * --prefix, which specifies where to install Sphinx;
      * --with-mysql, which specifies where to look for MySQL include and
        library files, if auto-detection fails;
      * --with-pgsql, which specifies where to look for PostgreSQL include
        and library files.

   3. Build the binaries:

      | $ make

   4. Install the binaries in the directory of your choice:

      | $ make install

2.4. Known installation issues
------------------------------

If configure fails to locate MySQL headers and/or libraries, try checking
for and installing mysql-devel package. On some systems, it is not
installed by default.

If make fails with a message which look like

   | /bin/sh: g++: command not found
   | make[1]: *** [libsphinx_a-sphinx.o] Error 127

try checking for and installing gcc-c++ package.

If you are getting compile-time errors which look like

   | sphinx.cpp:67: error: invalid application of `sizeof' to
   |     incomplete type `Private::SizeError<false>'

this means that some compile-time type size check failed. The most probable
reason is that off_t type is less than 64-bit on your system. As a quick
hack, you can edit sphinx.h and replace off_t with DWORD in a typedef for
SphOffset_t, but note that this will prohibit you from using full-text
indexes larger than 2 GB. Even if the hack helps, please report such
issues, providing the exact error message and compiler/OS details, so
I could properly fix them in next releases.

If you keep getting any other error, or the suggestions above do not seem
to help you, please don't hesitate to contact me.

2.5. Quick Sphinx usage tour
----------------------------

All the example commands below assume that you installed Sphinx in
/usr/local/sphinx.

To use Sphinx, you will need to:

   1. Create a configuration file.

      Default configuration file name is sphinx.conf. All Sphinx programs
      look for this file in current working directory by default.

      Sample configuration file, sphinx.conf.dist, which has all the
      options documented, is created by configure. Copy and edit that
      sample file to make your own configuration:

      | $ cd /usr/local/sphinx/etc
      | $ cp sphinx.conf.dist sphinx.conf
      | $ vi sphinx.conf

      Sample configuration file is setup to index documents table from
      MySQL database test; so there's example.sql sample data file to
      populate that table with a few documents for testing purposes:

      | $ mysql -u test < /usr/local/sphinx/etc/example.sql

   2. Run the indexer to create full-text index from your data:

      | $ cd /usr/local/sphinx/etc
      | $ /usr/local/sphinx/bin/indexer

   3. Query your newly created index!

To query the index from command line, use search utility:

   | $ cd /usr/local/sphinx/etc
   | $ /usr/local/sphinx/bin/search test

To query the index from your PHP scripts, you need to:

   1. Run the search daemon which your script will talk to:

      | $ cd /usr/local/sphinx/etc
      | $ /usr/local/sphinx/bin/searchd

   2. Run the attached PHP API test script (to ensure that the daemon was
      succesfully started and is ready to serve the queries):

      | $ cd sphinx/api
      | $ php test.php test

   3. Include the API (it's located in api/sphinxapi.php) into your own
      scripts and use it.

Happy searching!

3. Indexing
===========

3.1. Data sources
-----------------

The data to be indexed can generally come from very different sources: SQL
databases, plain text files, HTML files, mailboxes, and so on. From Sphinx
point of view, the data it indexes is a set of structured documents, each
of which has the same set of fields. This is biased towards SQL, where each
row correspond to a document, and each column to a field.

Depending on what source Sphinx should get the data from, different code is
required to fetch the data and prepare it for indexing. This code is called
data source driver (or simply driver or data source for brevity).

At the time of this writing, there are drivers for MySQL and PostgreSQL
databases, which can connect to the database using its native C/C++ API,
run queries and fetch the data. There's also a driver called xmlpipe, which
runs a specified command and reads the data from its stdout. See
Section 3.8, <<xmlpipe data source>> section for the format description.

There can be as many sources per index as necessary. They will be
sequentially processed in the very same order which was specifed in index
definition. All the documents coming from those sources will be merged as
if they were coming from a single source.

3.2. Attributes
---------------

Attributes are additional values associated with each document that can be
used to perform additional filtering and sorting during search.

It is often desired to additionally process full-text search results based
not only on matching document ID and its rank, but on a number of other
per-document values as well. For instance, one might need to sort news
search results by date and then relevance, or search through products
within specified price range, or limit blog search to posts made by
selected users, or group results by month. To do that efficiently, Sphinx
allows to attach a number of additional attributes to each document, and
store their values in the full-text index. It's then possible to use stored
values to filter, sort, or group full-text matches.

A good example would be a forum posts table. Assume that only title and
contentfields need to be full-text searchable - but that sometimes it is
also required to limit search to a certain author or a sub-forum (ie.
search only those rows that have some specific values of author_id or
forum_id columns in the SQL table); or to sort matches by post_date column;
or to group matching posts by month of the post_date and calculate
per-group match counts.

This can be achieved by specifying all the mentioned columns (excluding
title and content, that are full-text fields) as attributes, indexing them,
and then using API calls to setup filtering, sorting, and grouping. Here as
an example.

Example sphinx.conf part:
-------------------------

   | ...
   | sql_query = SELECT id, title, content, \
   | 	author_id, forum_id, post_date FROM my_forum_posts
   | sql_attr_uint = author_id
   | sql_attr_uint = forum_id
   | sql_attr_timestamp = post_date
   | ...

Example application code (in PHP):
----------------------------------

   | // only search posts by author whose ID is 123
   | $cl->SetFilter ( "author_id", array ( 123 ) );
   | 
   | // only search posts in sub-forums 1, 3 and 7
   | $cl->SetFilter ( "forum_id", array ( 1,3,7 ) );
   | 
   | // sort found posts by posting date in descending order
   | $cl->SetSortMode ( SPH_SORT_ATTR_DESC, "post_date" );

Attributes are named. Attribute names are case insensitive. Attributes are
not full-text indexed; they are stored in the index as is. Currently
supported attribute types are:

   * unsigned integers (1-bit to 32-bit wide);
   * UNIX timestamps;
   * floating point values (32-bit, IEEE 754 single precision);
   * string ordinals (specially computed integers);
   * MVA, multi-value attributes (variable-length lists of 32-bit unsigned
     integers).

The complete set of per-document attribute values is sometimes referred to
as docinfo. Docinfos can either be

   * stored separately from the main full-text index data ("extern"
     storage, in .spa file), or
   * attached to each occurence of document ID in full-text index data
     ("inline" storage, in .spd file).

When using extern storage, a copy of .spa file (with all the attribute
values for all the documents) is kept in RAM by searchd at all times. This
is for performance reasons; random disk I/O would be too slow. On the
contrary, inline storage does not require any additional RAM at all, but
that comes at the cost of greatly inflating the index size: remember that
it copies all attribute value every time when the document ID is mentioned,
and that is exactly as many times as there are different keywords in the
document. Inline may be the only viable option if you have only a few
attributes and need to work with big datasets in limited RAM. However, in
most cases extern storage makes both indexing and searching much more
efficient.

Search-time memory requirements for extern storage are
(1+number_of_attrs)*number_of_docs*4 bytes, ie. 10 million docs with
2 groups and 1 timestamp will take (1+2+1)*10M*4 = 160 MB of RAM. This is
PER DAEMON, not per query. searchd will allocate 160 MB on startup, read
the data and keep it shared between queries. The children will NOT allocate
any additional copies of this data.

3.3. MVA (multi-valued attributes)
----------------------------------

MVAs, or multi-valued attributes, are an important special type of
per-document attributes in Sphinx. MVAs make it possible to attach lists of
values to every document. They are useful for article tags, product
categories, etc. Filtering and group-by (but not sorting) on MVA attributes
is supported.

Currently, MVA list entries are limited to unsigned 32-bit integers. The
list length is not limited, you can have an arbitrary number of values
attached to each document as long as RAM permits (.spm file that contains
the MVA values will be precached in RAM by searchd). The source data can be
taken either from a separate query, or from a document field; see source
type in sql_attr_multi. In the first case the query will have to return
pairs of document ID and MVA values, in the second one the field will be
parsed for integer values. There are absolutely no requirements as to
incoming data order; the values will be automatically grouped by document
ID (and internally sorted within the same ID) during indexing anyway.

When filtering, a document will match the filter on MVA attribute if any of
the values satisfy the filtering condition. (Therefore, documents that pass
through exclude filters will not contain any of the forbidden values.) When
grouping by MVA attribute, a document will contribute to as many groups as
there are different MVA values associated with that document. For instance,
if the collection contains exactly 1 document having a 'tag' MVA with
values 5, 7, and 11, grouping on 'tag' will produce 3 groups with '@count'
equal to 1 and '@groupby' key values of 5, 7, and 11 respectively. Also
note that grouping by MVA might lead to duplicate documents in the result
set: because each document can participate in many groups, it can be chosen
as the best one in in more than one group, leading to duplicate IDs. PHP
API historically uses ordered hash on the document ID for the resulting
rows; so you'll also need to use SetArrayResult() in order to employ
group-by on MVA with PHP API.

3.4. Indexes
------------

To be able to answer full-text search queries fast, Sphinx needs to build
a special data structure optimized for such queries from your text data.
This structure is called index; and the process of building index from text
is called indexing.

Different index types are well suited for different tasks. For example,
a disk-based tree-based index would be easy to update (ie. insert new
documents to existing index), but rather slow to search. Therefore, Sphinx
architecture allows for different index types to be implemented easily.

The only index type which is implemented in Sphinx at the moment is
designed for maximum indexing and searching speed. This comes at a cost of
updates being really slow; theoretically, it might be slower to update this
type of index than than to reindex it from scratch. However, this very
frequently could be worked around with muiltiple indexes, see Section 3.10,
<<Live index updates>> for details.

It is planned to implement more index types, including the type which would
be updateable in real time.

There can be as many indexes per configuration file as necessary. indexer
utility can reindex either all of them (if --all option is specified), or
a certain explicitly specified subset. searchd utility will serve all the
specified indexes, and the clients can specify what indexes to search in
run time.

3.5. Restrictions on the source data
------------------------------------

There are a few different restrictions imposed on the source data which is
going to be indexed by Sphinx, of which the single most important one is:

ALL DOCUMENT IDS MUST BE UNIQUE UNSIGNED NON-ZERO INTEGER NUMBERS (32-BIT
OR 64-BIT, DEPENDING ON BUILD TIME SETTINGS).

If this requirement is not met, different bad things can happen. For
instance, Sphinx can crash with an internal assertion while indexing; or
produce strange results when searching due to conflicting IDs. Also,
a 1000-pound gorilla might eventually come out of your display and start
throwing barrels at you. You've been warned.

3.6. Charsets, case folding, and translation tables
---------------------------------------------------

When indexing some index, Sphinx fetches documents from the specified
sources, splits the text into words, and does case folding so that "Abc",
"ABC" and "abc" would be treated as the same word (or, to be pedantic,
term).

To do that properly, Sphinx needs to know

   * what encoding is the source text in;
   * what characters are letters and what are not;
   * what letters should be folded to what letters.

This should be configured on a per-index basis using charset_type and
charset_table options. charset_type specifies whether the document encoding
is single-byte (SBCS) or UTF-8. charset_table specifies the table that maps
letter characters to their case folded versions. The characters that are
not in the table are considered to be non-letters and will be treated as
word separators when indexing or searching through this index.

Note that while default tables do not include space character (ASCII code
0x20, Unicode U+0020) as a letter, it's in fact perfectly legal to do so.
This can be useful, for instance, for indexing tag clouds, so that
space-separated word sets would index as a single search query term.

Default tables currently include English and Russian characters. Please do
submit your tables for other languages!

3.7. SQL data sources (MySQL, PostgreSQL)
-----------------------------------------

With all the SQL drivers, indexing generally works as follows.

   * connection to the database is established;
   * pre-query (see Section 8.1.9, <<sql_query_pre>>) is executed to
     perform any necessary initial setup, such as setting per-connection
     encoding with MySQL;
   * main query (see Section 8.1.10, <<sql_query>>) is executed and the
     rows it returns are indexed;
   * post-query (see Section 8.1.19, <<sql_query_post>>) is executed to
     perform any necessary cleanup;
   * connection to the database is closed;
   * indexer does the sorting phase (to be pedantic, index-type specific
     post-processing);
   * connection to the database is established again;
   * post-index query (see Section 8.1.20, <<sql_query_post_index>>) is
     executed to perform any necessary final cleanup;
   * connection to the database is closed again.

Most options, such as database user/host/password, are straightforward.
However, there are a few subtle things, which are discussed in more detail
here.

Ranged queries
--------------

Main query, which needs to fetch all the documents, can impose a read lock
on the whole table and stall the concurrent queries (eg. INSERTs to MyISAM
table), waste a lot of memory for result set, etc. To avoid this, Sphinx
supports so-called ranged queries. With ranged queries, Sphinx first
fetches min and max document IDs from the table, and then substitutes
different ID intervals into main query text and runs the modified query to
fetch another chunk of documents. Here's an example.

Example 1. Ranged query usage example

   | # in sphinx.conf
   | 
   | sql_query_range	= SELECT MIN(id),MAX(id) FROM documents
   | sql_range_step = 1000
   | sql_query = SELECT * FROM documents WHERE id>=$start AND id<=$end

If the table contains document IDs from 1 to, say, 2345, then sql_query
would be run three times:

   1. with $start replaced with 1 and $end replaced with 1000;
   2. with $start replaced with 1001 and $end replaced with 2000;
   3. with $start replaced with 2000 and $end replaced with 2345.

Obviously, that's not much of a difference for 2000-row table, but when it
comes to indexing 10-million-row MyISAM table, ranged queries might be of
some help.

sql_post vs. sql_post_index
---------------------------

The difference between post-query and post-index query is in that
post-query is run immediately when Sphinx received all the documents, but
further indexing may still fail for some other reason. On the contrary, by
the time the post-index query gets executed, it is guaranteed that the
indexing was succesful. Database connection is dropped and re-established
because sorting phase can be very lengthy and would just timeout otherwise.

3.8. xmlpipe data source
------------------------

xmlpipe data source was designed to enable users to plug data into Sphinx
without having to implement new data sources drivers themselves. It is
limited to 2 fixed fields and 2 fixed attributes, and is deprecated in
favor of Section 3.9, <<xmlpipe2 data source>> now. For new streams, use
xmlpipe2.

To use xmlpipe, configure the data source in your configuration file as
follows:

   | source example_xmlpipe_source
   | {
   |     type = xmlpipe
   |     xmlpipe_command = perl /www/mysite.com/bin/sphinxpipe.pl
   | }

The indexer will run the command specified in xmlpipe_command, and then
read, parse and index the data it prints to stdout. More formally, it opens
a pipe to given command and then reads from that pipe.

indexer will expect one or more documents in custom XML format. Here's the
example document stream, consisting of two documents:

Example 2. XMLpipe document stream

   | <document>
   | <id>123</id>
   | <group>45</group>
   | <timestamp>1132223498</timestamp>
   | <title>test title</title>
   | <body>
   | this is my document body
   | </body>
   | </document>
   | 
   | <document>
   | <id>124</id>
   | <group>46</group>
   | <timestamp>1132223498</timestamp>
   | <title>another test</title>
   | <body>
   | this is another document
   | </body>
   | </document>

Legacy xmlpipe legacy driver uses a builtin parser which is pretty fast but
really strict and does not actually fully support XML. It requires that all
the fields must be present, formatted exactly as in this example, and occur
exactly in the same order. The only optional field is timestamp; it
defaults to 1.

3.9. xmlpipe2 data source
-------------------------

xmlpipe2 lets you pass arbitrary full-text and attribute data to Sphinx in
yet another custom XML format. It also allows to specify the schema (ie.
the set of fields and attributes) either in the XML stream itself, or in
the source settings.

When indexing xmlpipe2 source, indexer runs the given command, opens a pipe
to its stdout, and expects well-formed XML stream. Here's sample stream
data:

Example 3. xmlpipe2 document stream

   | <?xml version="1.0" encoding="utf-8"?>
   | <sphinx:docset>
   | 
   | <sphinx:schema>
   | <sphinx:field name="subject"/> 
   | <sphinx:field name="content"/>
   | <sphinx:attr name="published" type="timestamp"/>
   | <sphinx:attr name="author_id" type="int" bits="16" default="1"/>
   | </sphinx:schema>
   | 
   | <sphinx:document id="1234">
   | <content>this is the main content <![CDATA[[and this <cdata> entry must be handled properly by xml parser lib]]></content>
   | <published>1012325463</published>
   | <subject>note how field/attr tags can be in <b class="red">randomized</b> order</subject>
   | <misc>some undeclared element</misc>
   | </sphinx:document>
   | 
   | <!-- ... more documents here ... -->
   | 
   | </sphinx:docset>

Arbitrary fields and attributes are allowed. They also can occur in the
stream in arbitrary order within each document; the order is ignored. There
is a restriction on maximum field length; fields longer than 2 MB will be
truncated to 2 MB (this limit can be changed in the source).

The schema, ie. complete fields and attributes list, must be declared
before any document could be parsed. This can be done either in the
configuration file using xmlpipe_field and xmlpipe_attr_XXX settings, or
right in the stream using <sphinx:schema> element. <sphinx:schema> is
optional. It is only allowed to occur as the very first sub-element in
<sphinx:docset>. If there is no in-stream schema definition, settings from
the configuration file will be used. Otherwise, stream settings take
precedence.

Unknown tags (which were not declared neither as fields nor as attributes)
will be ignored with a warning. In the example above, <misc> will be
ignored. All embedded tags and their attributes (such as <b> in <subject>
in the example above) will be silently ignored.

Support for incoming stream encodings depends on whether iconv is installed
on the system. xmlpipe2 is parsed using libexpat parser that understands
US-ASCII, ISO-8859-1, UTF-8 and a few UTF-16 variants natively. Sphinx
configure script will also check for libiconv presence, and utilize it to
handle other encodings. libexpat also enforces the requirement to use UTF-8
charset on Sphinx side, because the parsed data it returns is always in
UTF-8.

XML elements (tags) recognized by xmlpipe2 (and their attributes where
applicable) are:

sphinx:docset
   Mandatory top-level element, denotes and contains xmlpipe2 document set.

sphinx:schema
   Optional element, must either occur as the very first child of
   sphinx:docset, or never occur at all. Declares the document schema.
   Contains field and attribute declarations. If present, overrides
   per-source settings from the configuration file.

sphinx:field
   Optional element, child of sphinx:schema. Declares a full-text field.
   The only recognized attribute is "name", it specifies the element name
   that should be treated as a full-text field in the subsequent documents.

sphinx:attr
   Optional element, child of sphinx:schema. Declares an attribute. Known
   attributes are:

      * "name", specifies the element name that should be treated as an
        attribute in the subsequent documents.
      * "type", specifies the attribute type. Possible values are "int",
        "timestamp", "str2ordinal", "bool", and "float".
      * "bits", specifies the bit size for "int" attribute type. Valid
        values are 1 to 32.
      * "default", specifies the default value for this attribute that
        should be used if the attribute's element is not present in the
        document.

sphinx:document
   Mandatory element, must be a child of sphinx:docset. Contains arbitrary
   other elements with field and attribute values to be indexed, as
   declared either using sphinx:field and sphinx:attr elements or in the
   configuration file. The only known attribute is "id" that must contain
   the unique integer document ID.

3.10. Live index updates
------------------------

There's a frequent situation when the total dataset is too big to be
reindexed from scratch often, but the amount of new records is rather
small. Example: a forum with a 1,000,000 archived posts, but only 1,000 new
posts per day.

In this case, "live" (almost real time) index updates could be implemented
using so called "main+delta" scheme.

The idea is to set up two sources and two indexes, with one "main" index
for the data which only changes rarely (if ever), and one "delta" for the
new documents. In the example above, 1,000,000 archived posts would go to
the main index, and newly inserted 1,000 posts/day would go to the delta
index. Delta index could then be reindexed very frequently, and the
documents can be made available to search in a matter of minutes.

Specifying which documents should go to what index and reindexing main
index could also be made fully automatical. One option would be to make
a counter table which would track the ID which would split the documents,
and update it whenever the main index is reindexed.

Example 4. Fully automated live updates

   | # in MySQL
   | CREATE TABLE sph_counter
   | (
   |     counter_id INTEGER PRIMARY KEY NOT NULL,
   |     max_doc_id INTEGER NOT NULL
   | );
   | 
   | # in sphinx.conf
   | source main
   | {
   |     # ...
   |     sql_query_pre = SET NAMES utf8
   |     sql_query_pre = REPLACE INTO sph_counter SELECT 1, MAX(id) FROM documents
   |     sql_query = SELECT id, title, body FROM documents \
   |         WHERE id<=( SELECT max_doc_id FROM sph_counter WHERE counter_id=1 )
   | }
   | 
   | source delta : main
   | {
   |     sql_query_pre = SET NAMES utf8
   |     sql_query = SELECT id, title, body FROM documents \
   |         WHERE id>( SELECT max_doc_id FROM sph_counter WHERE counter_id=1 )
   | }
   | 
   | index main
   | {
   |     source = main
   |     path = /path/to/main
   |     # ... all the other settings
   | }
   | 
   | # note how all other settings are copied from main,
   | # but source and path are overridden (they MUST be)
   | index delta : main
   | {
   |     source = delta
   |     path = /path/to/delta
   | }

Note how we're overriding sql_query_pre in the delta source. We need to
explicitly have that override. Otherwise REPLACE query would be run when
indexing delta source too, effectively nullifying it. However, when we
issue the directive in the inherited source for the first time, it removes
all inherited values, so the encoding setup is also lost. So sql_query_pre
in the delta can not just be empty; and we need to issue the encoding setup
query explicitly once again.

3.11. Index merging
-------------------

Merging two existing indexes can be more efficient that indexing the data
from scratch, and desired in some cases (such as merging 'main' and 'delta'
indexes instead of simply reindexing 'main' in 'main+delta' partitioning
scheme). So indexer has an option to do that. Merging the indexes is
normally faster than reindexing but still not instant on huge indexes.
Basically, it will need to read the contents of both indexes once and write
the result once. Merging 100 GB and 1 GB index, for example, will result in
202 GB of IO (but that's still likely less than the indexing from scratch
requires).

The basic command syntax is as follows:

   | indexer --merge DSTINDEX SRCINDEX [--rotate]

Only the DSTINDEX index will be affected: the contents of SRCINDEX will be
merged into it. --rotate switch will be required if DSTINDEX is already
being served by searchd. The initially devised usage pattern is to merge
a smaller update from SRCINDEX into DSTINDEX. Thus, when merging the
attributes, values from SRCINDEX will win if duplicate document IDs are
encountered. Note, however, that the "old" keywords will not be
automatically removed in such cases. For example, if there's a keyword
"old" associated with document 123 in DSTINDEX, and a keyword "new"
associated with it in SRCINDEX, document 123 will be found by both keywords
after the merge. You can supply an explicit condition to remove documents
from DSTINDEX to mitigate that; the relevant switch is --merge-dst-range:

   | indexer --merge main delta --merge-dst-range deleted 0 0

This switch lets you apply filters to the destination index along with
merging. There can be several filters; all of their conditions must be met
in order to include the document in the resulting mergid index. In the
example above, the filter passes only those records where 'deleted' is 0,
eliminating all records that were flagged as deleted (for instance, using
UpdateAttributes() call).

4. Searching
============

4.1. Matching modes
-------------------

There are the following matching modes available:

   * SPH_MATCH_ALL, matches all query words (default mode);
   * SPH_MATCH_ANY, matches any of the query words;
   * SPH_MATCH_PHRASE, matches query as a phrase, requiring perfect match;
   * SPH_MATCH_BOOLEAN, matches query as a boolean expression (see
     Section 4.2, <<Boolean query syntax>>);
   * SPH_MATCH_EXTENDED, matches query as an expression in Sphinx internal
     query language (see Section 4.3, <<Extended query syntax>>).

There also is a special "full scan" mode that will be automatically
activated when the following conditions are met:

   1. The query string is empty (ie. its length is zero).
   2. docinfo storage is set to extern.

In full scan mode, all the indexed documents will be considered as
matching. Such queries will still apply filters, sorting, or group by, but
will not perform any real full-text searching. This can be useful to unify
full-text and non-full-text searching code, or to offload SQL server (there
are cases when Sphinx scans will perform better than analogous MySQL
queries).

4.2. Boolean query syntax
-------------------------

Boolean queries allow the following special operators to be used:

   * explicit operator AND:

      | hello & world

   * operator OR:

      | hello | world

   * operator NOT:

      | hello -world
      | hello !world

   * grouping:

      | ( hello world )

Here's an example query which uses all these operators:

Example 5. Boolean query example

   | ( cat -dog ) | ( cat -mouse)

There always is implicit AND operator, so "hello world" query actually
means "hello & world".

OR operator precedence is higher than AND, so "looking for cat | dog |
mouse" means "looking for ( cat | dog | mouse )" and not "(looking for cat)
| dog | mouse".

Queries like "-dog", which implicitly include all documents from the
collection, can not be evaluated. This is both for technical and
performance reasons. Technically, Sphinx does not always keep a list of all
IDs. Performance-wise, when the collection is huge (ie. 10-100M documents),
evaluating such queries could take very long.

4.3. Extended query syntax
--------------------------

The following special operators can be used when using the extended
matching mode:

   * operator OR:

      | hello | world

   * operator NOT:

      | hello -world
      | hello !world

   * field search operator:

      | @title hello @body world

   * phrase search operator:

      | "hello world"

   * proximity search operator:

      | "hello world"~10

   * quorum matching operator:

      | "the world is a wonderful place"/3

Here's an example query which uses most of these operators:

Example 6. Extended query example

   | "hello world" @title "example program"~5 @body python -(php|perl)

There always is implicit AND operator, so "hello world" means that both
"hello" and "world" must be present in matching document.

OR operator precedence is higher than AND, so "looking for cat | dog |
mouse" means "looking for ( cat | dog | mouse )" and not "(looking for cat)
| dog | mouse".

Proximity distance is specified in words, adjusted for word count, and
applies to all words within quotes. For instance, "cat dog mouse"~5 query
means that there must be less than 8-word span which contains all 3 words,
ie. "CAT aaa bbb ccc DOG eee fff MOUSE" document will not match this query,
because this span is exactly 8 words long.

Quorum matching operator introduces a kind of fuzzy matching. It will only
match those documents that pass a given threshold of given words. The
example above ("the world is a wonderful place"/3) will match all documents
that have at least 3 of the 6 specified words.

Nested brackets, as in queries like

   | aaa | ( bbb ccc | ( ddd eee ) )

are not allowed yet, but this will be fixed.

Negation (ie. operator NOT) is only allowed on top level and not within
brackets (ie. groups). This isn't going to change, because supporting
nested negations would make phrase ranking implementation way too
complicated.

4.4. Weighting
--------------

Specific weighting function (currently) depends on the search mode.

There are these major parts which are used in the weighting functions:

   1. phrase rank,
   2. statistical rank.

Phrase rank is based on a length of longest common subsequence (LCS) of
search words between document body and query phrase. So if there's
a perfect phrase match in some document then its phrase rank would be the
highest possible, and equal to query words count.

Statistical rank is based on classic BM25 function which only takes word
frequencies into account. If the word is rare in the whole database (ie.
low frequency over document collection) or mentioned a lot in specific
document (ie. high frequency over matching document), it receives more
weight. Final BM25 weight is a floating point number between 0 and 1.

In all modes, per-field weighted phrase ranks are computed as a product of
LCS multiplied by per-field weight speficifed by user. Per-field weights
are integer, default to 1, and can not be set lower than 1.

In SPH_MATCH_BOOLEAN mode, no weighting is performed at all, every match
weight is set to 1.

In SPH_MATCH_ALL and SPH_MATCH_PHRASE modes, final weight is a sum of
weighted phrase ranks.

In SPH_MATCH_ANY mode, the idea is essentially the same, but it also adds
a count of matching words in each field. Before that, weighted phrase ranks
are additionally mutliplied by a value big enough to guarantee that higher
phrase rank in any field will make the match ranked higher, even if it's
field weight is low.

In SPH_MATCH_EXTENDED mode, final weight is a sum of weighted phrase ranks
and BM25 weight, multiplied by 1000 and rounded to integer.

This is going to be changed, so that MATCH_ALL and MATCH_ANY modes use BM25
weights as well. This would improve search results in those match spans
where phrase ranks are equal; this is especially useful for 1-word queries.

The key idea (in all modes, besides boolean) is that better subphrase
matches are ranked higher, and perfect matches are pulled to the top.
Author's experience is that this phrase proximity based ranking provides
noticeably better search quality than any statistical scheme alone (such as
BM25, which is commonly used in other search engines).

4.5. Sorting modes
------------------

There are the following result sorting modes available:

   * SPH_SORT_RELEVANCE mode, that sorts by relevance in descending order
     (best matches first);
   * SPH_SORT_ATTR_DESC mode, that sorts by an attribute in descending
     order (bigger attribute values first);
   * SPH_SORT_ATTR_ASC mode, that sorts by an attribute in ascending order
     (smaller attribute values first);
   * SPH_SORT_TIME_SEGMENTS mode, that sorts by time segments (last
     hour/day/week/month) in descending order, and then by relevance in
     descending order;
   * SPH_SORT_EXTENDED mode, that sorts by SQL-like combination of columns
     in ASC/DESC order;
   * SPH_SORT_EXPR mode, that sorts by an arithmetic expression.

SPH_SORT_RELEVANCE ignores any additional parameters and always sorts
matches by relevance rank. All other modes require an additional sorting
clause, with the syntax depending on specific mode. SPH_SORT_ATTR_ASC,
SPH_SORT_ATTR_DESC and SPH_SORT_TIME_SEGMENTS modes require simply an
attribute name. SPH_SORT_RELEVANCE is equivalent to sorting by "@weight
DESC, @id ASC" in extended mode, SPH_SORT_ATTR_ASC is equivalent to
"attribute ASC, @weight DESC, @id ASC", and SPH_SORT_ATTR_DESC to
"attribute DESC, @weight DESC, @id ASC" respectively.

SPH_SORT_TIME_SEGMENTS mode
---------------------------

In SPH_SORT_TIME_SEGMENTS mode, attribute values are split into so-called
time segments, and then sorted by time segment first, and by relevance
second.

The segments are calculated according to the current timestamp at the time
when the search is performed, so the results would change over time. The
segments are as follows:

   * last hour,
   * last day,
   * last week,
   * last month,
   * last 3 months,
   * everything else.

These segments are hardcoded, but it is trivial to change them if
necessary.

This mode was added to support searching through blogs, news headlines,
etc. When using time segments, recent records would be ranked higher
because of segment, but withing the same segment, more relevant records
would be ranked higher - unlike sorting by just the timestamp attribute,
which would not take relevance into account at all.

SPH_SORT_EXTENDED mode
----------------------

In SPH_SORT_EXTENDED mode, you can specify an SQL-like sort expression with
up to 5 attributes (including internal attributes), eg:

   | @relevance DESC, price ASC, @id DESC

Both internal attributes (that are computed by the engine on the fly) and
user attributes that were configured for this index are allowed. Internal
attribute names must start with magic @-symbol; user attribute names can be
used as is. In the example above, @relevance and @id are internal
attributes and price is user-specified.

Known internal attributes are:

   * @id (match ID)
   * @weight (match weight)
   * @rank (match weight)
   * @relevance (match weight)

@rank and @relevance are just additional aliases to @weight.

SPH_SORT_EXPR mode
------------------

Expression sorting mode lets you sort the matches by an arbitrary
arithmetic expression, involving attribute values, internal attributes (@id
and @weight), arithmetic operations, and a number of built-in functions.
Here's an example:

   | $cl->SetSortMode ( SPH_SORT_EXPR,
   | 	"@weight + ( user_karma + ln(pageviews) )*0.1" );

The following operators and functions are supported. They are mimiced after
MySQL. The functions take a number of arguments depending on the specific
function.

   * Operators: +, -, *, /, <, > <=, >=, =, <>.
   * Unary (1-argument) functions: abs(), ceil(), floor(), sin(), cos(),
     ln(), log2(), log10(), exp(), sqrt().
   * Binary (2-argument) functions: min(), max(), pow().
   * Ternary (3-argument) functions: if().

All calculations are performed in single-precision, 32-bit IEEE 754
floating point format. Comparison operators (eg. = or <=) return 1.0 when
the condition is true and 0.0 otherwise. For instance, (a=b)+3 will
evaluate to 4 when attribute 'a' is equal to attribute 'b', and to 3 when
'a' is not. Unlike MySQL, the equality comparisons (ie. = and <> operators)
introduce a small equality threshold (1e-6 by default). If the difference
between compared values is within the threshold, they will be considered
equal.

All unary and binary functions are straightforward, they behave just like
their mathematical counterparts. But IF() behavior needs to be explained in
more detail. It takes 3 arguments, check whether the 1st argument is equal
to 0.0, returns the 2nd argument if it is not zero, or the 3rd one when it
is. Note that unlike comparison operators, IF() does not use a threshold!
Therefore, it's safe to use comparison results as its 1st argument, but
arithmetic operators might produce unexpected results. For instance, the
following two calls will produce different results even though they are
logically equivalent:

   | IF ( sqrt(3)*sqrt(3)-3<>0, a, b )
   | IF ( sqrt(3)*sqrt(3)-3, a, b )

In the first case, the comparison operator <> will return 0.0 (false)
because of a threshold, and IF() will always return 'b' as a result. In the
second one, the same sqrt(3)*sqrt(3)-3 expression will be compared with
zero without threshold by the IF() function itself. But its value will be
slightly different from zero because of limited floating point calculations
precision. Because of that, the comparison with 0.0 done by IF() will not
pass, and the second variant will return 'a' as a result.

4.6. Grouping (clustering) search results
-----------------------------------------

Sometimes it could be useful to group (or in other terms, cluster) search
results and/or count per-group match counts - for instance, to draw a nice
graph of how much maching blog posts were there per each month; or to group
Web search results by site; or to group matching forum posts by author;
etc.

In theory, this could be performed by doing only the full-text search in
Sphinx and then using found IDs to group on SQL server side. However, in
practice doing this with a big result set (10K-10M matches) would typically
kill performance.

To avoid that, Sphinx offers so-called grouping mode. It is enabled with
SetGroupBy() API call. When grouping, all matches are assigned to different
groups based on group-by value. This value is computed from specified
attribute using one of the following built-in functions:

   * SPH_GROUPBY_DAY, extracts year, month and day in YYYYMMDD format from
     timestamp;
   * SPH_GROUPBY_WEEK, extracts year and first day of the week number
     (counting from year start) in YYYYNNN format from timestamp;
   * SPH_GROUPBY_MONTH, extracts month in YYYYMM format from timestamp;
   * SPH_GROUPBY_YEAR, extracts year in YYYY format from timestamp;
   * SPH_GROUPBY_ATTR, uses attribute value itself for grouping.

The final search result set then contains one best match per group.
Grouping function value and per-group match count are returned along as
"virtual" attributes named @group and @count respectively.

The result set is sorted by group-by sorting clause, with the syntax
similar to SPH_SORT_EXTENDED sorting clause syntax. In addition to @id and
@weight, group-by sorting clause may also include:

   * @group (groupby function value),
   * @count (amount of matches in group).

The default mode is to sort by groupby value in descending order, ie. by
"@group desc".

On completion, total_found result parameter would contain total amount of
matching groups over he whole index.

WARNING: grouping is done in fixed memory and thus its results are only
approximate; so there might be more groups reported in total_found than
actually present. @count might also be underestimated. To reduce
inaccuracy, one should raise max_matches. If max_matches allows to store
all found groups, results will be 100% correct.

For example, if sorting by relevance and grouping by "published" attribute
with SPH_GROUPBY_DAY function, then the result set will contain

   * one most relevant match per each day when there were any matches
     published,
   * with day number and per-day match count attached,
   * sorted by day number in descending order (ie. recent days first).

4.7. Distributed searching
--------------------------

To scale well, Sphinx has distributed searching capabilities. Distributed
searching is useful to improve query latency (ie. search time) and
throughput (ie. max queries/sec) in multi-server, multi-CPU or multi-core
environments. This is essential for applications which need to search
through huge amounts data (ie. billions of records and terabytes of text).

The key idea is to horizontally partition (HP) searched data accross search
nodes and then process it in parallel.

Partitioning is done manually. You should

   * setup several instances of Sphinx programs (indexer and searchd) on
     different servers;
   * make the instances index (and search) different parts of data;
   * configure a special distributed index on some of the searchd
     instances;
   * and query this index.

This index only contains references to other local and remote indexes - so
it could not be directly reindexed, and you should reindex those indexes
which it references instead.

When searchd receives a query against distributed index, it does the
following:

   1. connects to configured remote agents;
   2. issues the query;
   3. sequentially searches configured local indexes (while the remote
      agents are searching);
   4. retrieves remote agents' search results;
   5. merges all the results together, removing the duplicates;
   6. sends the merged resuls to client.

From the application's point of view, there are no differences between
usual and distributed index at all.

Any searchd instance could serve both as a master (which aggregates the
results) and a slave (which only does local searching) at the same time.
This has a number of uses:

   1. every machine in a cluster could serve as a master which searches the
      whole cluster, and search requests could be balanced between masters
      to achieve a kind of HA (high availability) in case any of the nodes
      fails;
   2. if running within a single multi-CPU or multi-core machine, there
      would be only 1 searchd instance quering itself as an agent and thus
      utilizing all CPUs/core.

It is scheduled to implement better HA support which would allow to specify
which agents mirror each other, do health checks, keep track of alive
agents, load-balance requests, etc.

4.8. searchd query log format
-----------------------------

searchd logs all succesfully executed search queries into query log file.
Here's an example:

   | [Fri Jun 29 21:17:58 2007] 0.004 sec [all/0/rel 35254 (0,20)] [lj] test
   | [Fri Jun 29 21:20:34 2007] 0.024 sec [all/0/rel 19886 (0,20) @channel_id] [lj] test

This log format is as follows:

   | [query-date] query-time [match-mode/filters-count/sort-mode
   |     total-matches (offset,limit) @groupby-attr] [index-name] query

Match mode can take one of the following values:

   * "all" for SPH_MATCH_ALL mode;
   * "any" for SPH_MATCH_ANY mode;
   * "phr" for SPH_MATCH_PHRASE mode;
   * "bool" for SPH_MATCH_BOOLEAN mode;
   * "ext" for SPH_MATCH_EXTENDED mode.

Sort mode can take one of the following values:

   * "rel" for SPH_SORT_RELEVANCE mode;
   * "attr-" for SPH_SORT_ATTR_DESC mode;
   * "attr+" for SPH_SORT_ATTR_ASC mode;
   * "tsegs" for SPH_SORT_TIME_SEGMENTS mode;
   * "ext" for SPH_SORT_EXTENDED mode.

5. API reference
================

There is a number of native searchd client API implementations for Sphinx.
As of time of this writing, we officially support our own PHP, Python, and
Java implementations. There also are third party free, open-source API
implementations for Perl, Ruby, and C++.

The reference API implementation is in PHP, because (we believe) Sphinx is
most widely used with PHP than any other language. This reference
documentation is in turn based on reference PHP API, and all code samples
in this section will be given in PHP.

However, all other APIs provide the same methods and implement the very
same network protocol. Therefore the documentation does apply to them as
well. There might be minor differences as to the method naming conventions
or specific data structures used. But the provided functionality must not
differ across languages.

5.1. General API functions
--------------------------

5.1.1. GetLastError
-------------------

Prototype: function GetLastError()

Returns last error message, as a string, in human readable format. If there
were no errors during the previous API call, empty string is returned.

You should call it when any other function (such as Query()) fails
(typically, the failing function returns false). The returned string will
contain the error description.

The error message is not reset by this call; so you can safely call it
several times if needed.

5.1.2. GetLastWarning
---------------------

Prototype: function GetLastWarning ()

Returns last warning message, as a string, in human readable format. If
there were no warnings during the previous API call, empty string is
returned.

You should call it to verify whether your request (such as Query()) was
completed but with warnings. For instance, search query against
a distributed index might complete succesfully even if several remote
agents timed out. In that case, a warning message would be produced.

The warning message is not reset by this call; so you can safely call it
several times if needed.

5.1.3. SetServer
----------------

Prototype: function SetServer ( $host, $port )

Sets searchd host name and TCP port. All subsequent requests will use the
new host and port settings. Default host and port are 'localhost' and 3312,
respectively.

5.1.4. SetRetries
-----------------

Prototype: function SetRetries ( $count, $delay=0 )

Sets distributed retry count and delay.

On temporary failures searchd will attempt up to $count retries per agent.
$delay is the delay between the retries, in milliseconds. Retries are
disabled by default. Note that this call will not make the API itself retry
on temporary failure; it only tells searchd to do so. Currently, the list
of temporary failures includes all kinds of connect() failures and maxed
out (too busy) remote agents.

5.1.5. SetArrayResult
---------------------

Prototype: function SetArrayResult ( $arrayresult )

PHP specific. Controls matches format in the search results set (whether
matches should be returned as an array or a hash).

$arrayresult argument must be boolean. If $arrayresult is false (the
default mode), matches will returned in PHP hash format with document IDs
as keys, and other information (weight, attributes) as values. If
$arrayresult is true, matches will be returned as a plain array with
complete per-match information including document ID.

Introduced along with GROUP BY support on MVA attributes. Group-by-MVA
result sets may contain duplicate document IDs. Thus they need to be
returned as plain arrays, because hashes will only keep one entry per
document ID.

5.2. General query settings
---------------------------

5.2.1. SetLimits
----------------

Prototype: function SetLimits ( $offset, $limit, $max_matches=0, $cutoff=0
)

Sets offset into server-side result set ($offset) and amount of matches to
return to client starting from that offset ($limit). Can additionally
control maximum server-side result set size for current query
($max_matches) and the threshold amount of matches to stop searching at
($cutoff). All parameters must be non-negative integers.

First two parameters to SetLimits() are identical in behavior to MySQL
LIMIT clause. They instruct searchd to return at most $limit matches
starting from match number $offset. The default offset and limit settings
are 0 and 20, that is, to return first 20 matches.

max_matches setting controls how much matches searchd will keep in RAM
while searching. All matching documents will be normally processed, ranked,
filtered, and sorted even if max_matches is set to 1. But only best
N documents are stored in memory at any given moment for performance and
RAM usage reasons, and this setting controls that N. Note that there are
two places where max_matches limit is enforced. Per-query limit is
controlled by this API call, but there also is per-server limit controlled
by max_matches setting in the config file. To prevent RAM usage abuse,
server will not allow to set per-query limit higher than the per-server
limit.

You can't retrieve more than max_matches matches to the client application.
The default limit is set to 1000. Normally, you must not have to go over
this limit. One thousand records is enough to present to the end user. And
if you're thinking about pulling the results to application for further
sorting or filtering, that would be much more efficient if performed on
Sphinx side.

$cutoff setting is intended for advanced performance control. It tells
searchd to forcibly stop search query once $cutoff matches had been found
and processed.

5.2.2. SetMaxQueryTime
----------------------

Prototype: function SetMaxQueryTime ( $max_query_time )

Sets maximum search query time, in milliseconds. Parameter must be
a non-negative integer. Default valus is 0 which means "do not limit".

Similar to $cutoff setting from SetLimits(), but limits elapsed query time
instead of processed matches count. Local search queries will be stopped
once that much time has elapsed. Note that if you're performing a search
which queries several local indexes, this limit applies to each index
separately.

5.3. Full-text search query settings
------------------------------------

5.3.1. SetMatchMode
-------------------

Prototype: function SetMatchMode ( $mode )

Sets full-text query matching mode, as described in Section 4.1, <<Matching
modes>>. Parameter must be a constant specifying one of the known modes.

WARNING: (PHP specific) you must not take the matching mode constant name
in quotes, that syntax specifies a string and is incorrect:

   | $cl->SetMatchMode ( "SPH_MATCH_ANY" ); // INCORRECT! will not work as expected
   | $cl->SetMatchMode ( SPH_MATCH_ANY ); // correct, works OK

5.3.2. SetRankingMode
---------------------

Prototype: function SetRankingMode ( $ranker )

Sets ranking mode. Only available in SPH_MATCH_EXTENDED2 matching mode at
the time of this writing. Parameter must be a constant specifying one of
the known modes.

By default, Sphinx computes two factors which contribute to the final match
weight. The major part is query phrase proximity to document text. The
minor part is so-called BM25 statistical function, which varies from 0 to
1 depending on the keyword frequency within document (more occurrences
yield higher weight) and within the whole index (more rare keywords yield
higher weight).

However, in some cases you'd want to compute weight differently - or maybe
avoid computing it at all for performance reasons because you're sorting
the result set by something else anyway. This can be accomplished by
setting the appropriate ranking mode.

Currently implemented modes are:

   * SPH_RANK_PROXIMITY_BM25, default ranking mode which uses and combines
     both phrase proximity and BM25 ranking.
   * SPH_RANK_BM25, statistical ranking mode which uses BM25 ranking only
     (similar to most other full-text engines). This mode is faster but may
     result in worse quality on queries which contain more than 1 keyword.
   * SPH_RANK_NONE, disabled ranking mode. This mode is the fastest. It is
     essentially equivalent to boolean searching. A weight of 1 is assigned
     to all matches.

5.3.3. SetSortMode
------------------

Prototype: function SetSortMode ( $mode, $sortby="" )

Set matches sorting mode, as described in Section 4.5, <<Sorting modes>>.
Parameter must be a constant specifying one of the known modes.

WARNING: (PHP specific) you must not take the matching mode constant name
in quotes, that syntax specifies a string and is incorrect:

   | $cl->SetSortMode ( "SPH_SORT_ATTR_DESC" ); // INCORRECT! will not work as expected
   | $cl->SetSortMode ( SPH_SORT_ATTR_ASC ); // correct, works OK

5.3.4. SetWeights
-----------------

Prototype: function SetWeights ( $weights )

Binds per-field weights in the order of appearance in the index.
DEPRECATED, use SetFieldWeights() instead.

5.3.5. SetFieldWeights
----------------------

Prototype: function SetFieldWeights ( $weights )

Binds per-field weights by name. Parameter must be a hash (associative
array) mapping string field names to integer weights.

Match ranking can be affected by per-field weights. For instance, see
Section 4.4, <<Weighting>> for an explanation how phrase proximity ranking
is affected. This call lets you specify what non-default weights to assign
to different full-text fields.

The weights must be positive 32-bit integers. The final weight will be
a 32-bit integer too. Default weight value is 1. Unknown field names will
be silently ignored.

There is no enforced limit on the maximum weight value at the moment.
However, beware that if you set it too high you can start hitting 32-bit
wraparound issues. For instance, if you set a weight of 10,000,000 and
search in extended mode, then maximum possible weight will be equal to 10
million (your weight) by 1 thousand (internal BM25 scaling factor, see
Section 4.4, <<Weighting>>) by 1 or more (phrase proximity rank). The
result is at least 10 billion that does not fit in 32 bits and will be
wrapped around, producing unexpected results.

5.3.6. SetIndexWeights
----------------------

Prototype: function SetIndexWeights ( $weights )

Sets per-index weights, and enables weighted summing of match weights
across different indexes. Parameter must be a hash (associative array)
mapping string index names to integer weights. Default is empty array that
means to disable weighting summing.

When a match with the same document ID is found in several different local
indexes, by default Sphinx simply chooses the match from the index
specified last in the query. This is to support searching through partially
overlapping index partitions.

However in some cases the indexes are not just partitions, and you might
want to sum the weights across the indexes instead of picking one.
SetIndexWeights() lets you do that. With summing enabled, final match
weight in result set will be computed as a sum of match weight coming from
the given index multiplied by respective per-index weight specified in this
call. Ie. if the document 123 is found in index A with the weight of 2, and
also in index B with the weight of 3, and you called SetIndexWeights (
array ( "A"=>100, "B"=>10 ) ), the final weight return to the client will
be 2*100+3*10 = 230.

5.4. Result set filtering settings
----------------------------------

5.4.1. SetIDRange
-----------------

Prototype: function SetIDRange ( $min, $max )

Sets an accepted range of document IDs. Parameters must be integers.
Defaults are 0 and 0; that combination means to not limit by range.

After this call, only those records that have document ID between $min and
$max (including IDs exactly equal to $min or $max) will be matched.

5.4.2. SetFilter
----------------

Prototype: function SetFilter ( $attribute, $values, $exclude=false )

Adds new integer values set filter.

On this call, additional new filter is added to the existing list of
filters. $attribute must be a string with attribute name. $values must be
a plain array containing integer values. $exclude must be a boolean value;
it controls whether to accept the matching documents (default mode, when
$exclude is false) or reject them.

Only those documents where $attribute column value stored in the index
matches any of the values from $values array will be matched (or rejected,
if $exclude is true).

5.4.3. SetFilterRange
---------------------

Prototype: function SetFilterRange ( $attribute, $min, $max, $exclude=false
)

Adds new integer range filter.

On this call, additional new filter is added to the existing list of
filters. $attribute must be a string with attribute name. $min and $max
must be integers that define the acceptable attribute values range
(including the boundaries). $exclude must be a boolean value; it controls
whether to accept the matching documents (default mode, when $exclude is
false) or reject them.

Only those documents where $attribute column value stored in the index is
between $min and $max (including values that are exactly equal to $min or
$max) will be matched (or rejected, if $exclude is true).

5.4.4. SetFilterFloatRange
--------------------------

Prototype: function SetFilterFloatRange ( $attribute, $min, $max,
$exclude=false )

Adds new float range filter.

On this call, additional new filter is added to the existing list of
filters. $attribute must be a string with attribute name. $min and $max
must be floats that define the acceptable attribute values range (including
the boundaries). $exclude must be a boolean value; it controls whether to
accept the matching documents (default mode, when $exclude is false) or
reject them.

Only those documents where $attribute column value stored in the index is
between $min and $max (including values that are exactly equal to $min or
$max) will be matched (or rejected, if $exclude is true).

5.4.5. SetGeoAnchor
-------------------

Prototype: function SetGeoAnchor ( $attrlat, $attrlong, $lat, $long )

Sets anchor point for and geosphere distance (geodistance) calculations,
and enable them.

$attrlat and $attrlong must be strings that contain the names of latitude
and longitude attributes, respectively. $lat and $long are floats that
specify anchor point latitude and longitude, in radians.

Once an anchor point is set, you can use magic "@geodist" attribute name in
your filters and/or sorting expressions. Sphinx will compute geosphere
distance between the given anchor point and a point specified by latitude
and lognitude attributes from each full-text match, and attach this value
to the resulting match. The latitude and longitude values both in
SetGeoAnchor and the index attribute data are expected to be in radians.
The result will be returned in meters, so geodistance value of 1000.0 means
1 km. 1 mile is approximately 1609.344 meters.

5.5. GROUP BY settings
----------------------

5.5.1. SetGroupBy
-----------------

Prototype: function SetGroupBy ( $attribute, $func, $groupsort="@group
desc" )

Sets grouping attribute, function, and groups sorting mode; and enables
grouping (as described in Section 4.6, <<Grouping (clustering) search
results >>).

$attribute is a string that contains group-by attribute name. $func is
a constant that chooses a function applied to the attribute value in order
to compute group-by key. $groupsort is a clause that controls how the
groups will be sorted. Its syntax is similar to that described in
Section 4.5, <<SPH_SORT_EXTENDED mode>>.

Grouping feature is very similar in nature to GROUP BY clause from SQL.
Results produces by this function call are going to be the same as produced
by the following pseudo code:

   | SELECT ... GROUP BY $func($attribute) ORDER BY $groupsort

Note that it's $groupsort that affects the order of matches in the final
result set. Sorting mode (see Section 5.3.3, <<SetSortMode>>) affect the
ordering of matches within group, ie. what match will be selected as the
best one from the group. So you can for instance order the groups by
matches count and select the most relevant match within each group at the
same time.

5.5.2. SetGroupDistinct
-----------------------

Prototype: function SetGroupDistinct ( $attribute )

Sets attribute name for per-group distinct values count calculations. Only
available for grouping queries.

$attribute is a string that contains the attribute name. For each group,
all values of this attribute will be stored (as RAM limits permit), then
the amount of distinct values will be calculated and returned to the
client. This feature is similar to COUNT(DISTINCT) clause in standard SQL;
so these Sphinx calls:

   | $cl->SetGroupBy ( "category", SPH_GROUPBY_ATTR, "@count desc" );
   | $cl->SetGroupDistinct ( "vendor" );

can be expressed using the following SQL clauses:

   | SELECT id, weight, all-attributes,
   | 	COUNT(DISTINCT vendor) AS @distinct,
   | 	COUNT(*) AS @count
   | FROM products
   | GROUP BY category
   | ORDER BY @count DESC

In the sample pseudo code shown just above, SetGroupDistinct() call
corresponds to COUNT(DISINCT vendor) clause only. GROUP BY, ORDER BY, and
COUNT(*) clauses are all an equivalent of SetGroupBy() settings. Both
queries will return one matching row for each category. In addition to
indexed attributes, matches will also contain total per-category matches
count, and the count of distinct vendor IDs within each category.

5.6. Querying
-------------

5.6.1. Query
------------

Prototype: function Query ( $query, $index="*" )

Connects to searchd server, runs given search query with current settings,
obtains and returns the result set.

$query is a query string. $index is an index name (or names) string.
Returns false and sets GetLastError() message on general error. Returns
search result set on success.

Default value for $index is "*" that means to query all local indexes.
Characters allowed in index names include Latin letters (a-z), numbers
(0-9), minus sign (-), and underscore (_); everything else is considered
a separator. Therefore, all of the following samples calls are valid and
will search the same two indexes:

   | $cl->Query ( "test query", "main delta" );
   | $cl->Query ( "test query", "main;delta" );
   | $cl->Query ( "test query", "main, delta" );

Index specification order matters. If document with identical IDs are found
in two or more indexes, weight and attribute values from the very last
matching index will be used for sorting and returning to client (unless
explicitly overridden with SetIndexWeights()). Therefore, in the example
above, matches from "delta" index will always win over matches from "main".

On success, Query() returns a result set that contains some of the found
matches (as requested by SetLimits()) and additional general per-query
statistics. The result set is a hash (PHP specific; other languages might
utilize other structures instead of hash) with the following keys and
values:

"matches":
   Hash which maps found document IDs to another small hash containing
   document weight and attribute values (or an array of the similar small
   hashes if SetArrayResult() was enabled).

"total":
   Total amount of matches retrieved on server (ie. to the server side
   result set) by this query. You can retrieve up to this amount of matches
   from server for this query text with current query settings.

"total_found":
   Total amount of matching documents in index (that were found and
   procesed on server).

"words":
   Hash which maps query keywords (case-folded, stemmed, and otherwise
   processed) to a small hash with per-keyword statitics ("docs", "hits").

"error":
   Query error message reported by searchd (string, human readable). Empty
   if there were no errors.

"warning":
   Query warning message reported by searchd (string, human readable).
   Empty if there were no warnings.

5.6.2. AddQuery
---------------

Prototype: function AddQuery ( $query, $index="*" )

Adds additional query with current settings to multi-query batch. $query is
a query string. $index is an index name (or names) string. Returns index to
results array returned from RunQueries().

Batch queries (or multi-queries) enable searchd to perform internal
optimizations if possible. They also reduce network connection overheads
and search process creation overheads in all cases. They do not result in
any additional overheads compared to simple queries. Thus, if you run
several different queries from your web page, you should always consider
using multi-queries.

For instance, running the same full-text query but with different sorting
or group-by settings will enable searchd to perform expensive full-text
search and ranking operation only once, but compute multiple group-by
results from its output.

This can be a big saver when you need to display not just plain search
results but also some per-category counts, such as the amount of products
grouped by vendor. Without multi-query, you would have to run several
queries which perform essentially the same search and retrieve the same
matches, but create result sets differently. With multi-query, you simply
pass all these querys in a single batch and Sphinx optimizes the redundant
full-text search internally.

AddQuery() internally saves full current settings state along with the
query, and you can safely change them afterwards for subsequent AddQuery()
calls. Already added queries will not be affected; there's actually no way
to change them at all. Here's an example:

   | $cl->SetSortMode ( SPH_SORT_RELEVANCE );
   | $cl->AddQuery ( "hello world", "documents" );
   | 
   | $cl->SetSortMode ( SPH_SORT_ATTR_DESC, "price" );
   | $cl->AddQuery ( "ipod", "products" );
   | 
   | $cl->AddQuery ( "harry potter", "books" );
   | 
   | $results = $cl->RunQueries ();

With the code above, 1st query will search for "hello world" in "documents"
index and sort results by relevance, 2nd query will search for "ipod" in
"products" index and sort results by price, and 3rd query will search for
"harry potter" in "books" index while still sorting by price. Note that 2nd
SetSortMode() call does not affect the first query (because it's already
added) but affects both other subsequent queries.

AddQuery() does not modify the current state. That is, all current sorting,
filtering, and grouping settings will not be affected by this call; so
subsequent queries can easily reuse current query settings.

AddQuery() returns an index into an array of results that will be returned
from RunQueries() call. It is simply a sequentially increasing 0-based
integer, ie. first call will return 0, second will return 1, and so on.
Just a small helper so you won't have to track the indexes manualy if you
need then.

5.6.3. RunQueries
-----------------

Prototype: function RunQueries ()

Connect to searchd, runs a batch of all queries added using AddQuery(),
obtains and returns the result sets. Returns false and sets GetLastError()
message on general error (such as network I/O failure). Returns a plain
array of result sets on success.

Each result set in the returned array is exactly the same as the result set
returned from Query().

Note that the batch query request itself almost always succeds - unless
there's a network error, blocking index rotation in progress, or another
general failure which prevents the whole request from being processed.

However individual queries within the batch might very well fail. In this
case their respective result sets will contain non-empty "error" message,
but no matches or query statistics. In the extreme case all queries within
the batch could fail. There still will be no general error reported,
because API was able to succesfully connect to searchd, submit the batch,
and receive the results - but every result set will have a specific error
message.

5.6.4. ResetFilters
-------------------

Prototype: function ResetFilters ()

Clears all currently set filters.

This call is only normally required when using multi-queries. You might
want to set different filters for different queries in the batch. To do
that, you should call ResetFilters() and add new filters using the
respective calls.

5.6.5. ResetGroupBy
-------------------

Prototype: function ResetGroupBy ()

Clears all currently group-by settings, and disables group-by.

This call is only normally required when using multi-queries. You can
change individual group-by settings using SetGroupBy() and
SetGroupDistinct() calls, but you can not disable group-by using those
calls. ResetGroupBy() fully resets previous group-by settings and disables
group-by mode in the current state, so that subsequent AddQuery() calls can
perform non-grouping searches.

5.7. Additional functionality
-----------------------------

5.7.1. BuildExcerpts
--------------------

Prototype: function BuildExcerpts ( $docs, $index, $words, $opts=array() )

Excerpts (snippets) builder function. Connects to searchd, asks it to
generate excerpts (snippets) from given documents, and returns the results.

$docs is a plain array of strings that carry the documents' contents.
$index is an index name string. Different settings (such as charset,
morphology, wordforms) from given index will be used. $words is a string
that contains the keywords to highlight. They will be processed with
respect to index settings. For instance, if English stemming is enabled in
the index, "shoes" will be highlighted even if keyword is "shoe". $opts is
a hash which contains additional optional highlighting parameters:

"before_match":
   A string to insert before a keyword match. Default is "<b>".

"after_match":
   A string to insert after a keyword match. Default is "<b>".

"chunk_separator":
   A string to insert between snippet chunks (passages). Default is
   " ... ".

"limit":
   Maximum snippet size, in symbols (codepoints). Integer, default is 256.

"around":
   How much words to pick around each matching keywords block. Integer,
   default is 5.

"exact_phrase":
   Whether to highlight exact query phrase matches only instead of
   individual keywords. Boolean, default is false.

"single_passage":
   Whether to extract single best passage only. Boolean, default is false.

"weight_order":
   Whether to sort the extracted passages in order of relevance (decreasing
   weight), or in order of appearance in the document (increasing
   position). Boolean, default is false.

Returns false on failure. Returns a plain array of strings with excerpts
(snippets) on success.

5.7.2. UpdateAttributes
-----------------------

Prototype: function UpdateAttributes ( $index, $attrs, $values )

Instantly updates given attribute values in given documents. Returns number
of actually updated documents (0 or more) on success, or -1 on failure.

$index is a name of the index (or indexes) to be updated. $attrs is a plain
array with string attribute names, listing attributes that are updated.
$values is a hash where key is document ID, and value is a plain array of
new attribute values.

$index can be either a single index name or a list, like in Query(). Unlike
Query(), wildcard is not allowed and all the indexes to update must be
specified explicitly. The list of indexes can include distributed index
names. Updates on distributed indexes will be pushed to all agents.

The updates only work with docinfo=extern storage strategy. They are very
fast because they're working fully in RAM, but they can also be made
persistent: updates are saved on disk on clean searchd shutdown initiated
by SIGTERM signal.

Usage example:

   | $cl->UpdateAttributes ( "test1", array("group_id"), array(1=>array(456)) );
   | $cl->UpdateAttributes ( "products", array ( "price", "amount_in_stock" ),
   | 	array ( 1001=>array(123,5), 1002=>array(37,11), 1003=>(25,129) ) );

The first sample statement will update document 1 in index "test1", setting
"group_id" to 456. The second one will update documents 1001, 1002 and 1003
in index "products". For document 1001, the new price will be set to 123
and the new amount in stock to 5; for document 1002, the new price will be
37 and the new amount will be 11; etc.

5.7.3. BuildKeywords
--------------------

Prototype: function BuildKeywords ( $query, $index, $hits )

Extracts keywords from query using tokenizer settings for given index,
optionally with per-keyword occurrence statistics. Returns an array of
hashes with per-keyword information.

$query is a query to extract keywords from. $index is a name of the index
to get tokenizing settings and keyword occurrence statistics from. $hits is
a boolean flag that indicates whether keyword occurrence statistics are
required.

Usage example:

   | $keywords = $cl->BuildKeywords ( "this.is.my query", "test1", false );

5.7.4. EscapeString
-------------------

Prototype: function EscapeString ( $string )

Escapes characters that are treated as special operators by the query
language parser. Returns an escaped string.

$string is a string to escape.

This function might seem redundant because it's trivial to implement in any
calling application. However, as the set of special characters might change
over time, it makes sense to have an API call that is guaranteed to escape
all such characters at all times.

Usage example:

   | $escaped = $cl->EscapeString ( "escaping-sample@query/string" );

6. MySQL storage engine (SphinxSE)
==================================

6.1. SphinxSE overview
----------------------

SphinxSE is MySQL storage engine which can be compiled into MySQL server
5.x using its pluggable architecure. It is not available for MySQL 4.x
series. It also requires MySQL 5.0.22 or higher in 5.0.x series, or MySQL
5.1.12 or higher in 5.1.x series.

Despite the name, SphinxSE does not actually store any data itself. It is
actually a built-in client which allows MySQL server to talk to searchd,
run search queries, and obtain search results. All indexing and searching
happen outside MySQL.

Obvious SphinxSE applications include:

   * easier porting of MySQL FTS applications to Sphinx;
   * allowing Sphinx use with progamming languages for which native APIs
     are not available yet;
   * optimizations when additional Sphinx result set processing on MySQL
     side is required (eg. JOINs with original document tables, additional
     MySQL-side filtering, etc).

6.2. Installing SphinxSE
------------------------

You will need to obtain a copy of MySQL sources, prepare those, and then
recompile MySQL binary. MySQL sources (mysql-5.x.yy.tar.gz) could be
obtained from dev.mysql.com Web site.

For some MySQL versions, there are delta tarballs with already prepared
source versions available from Sphinx Web site. After unzipping those over
original sources MySQL would be ready to be configured and built with
Sphinx support.

If such tarball is not available, or does not work for you for any reason,
you would have to prepare sources manually. You will need to GNU Autotools
framework (autoconf, automake and libtool) installed to do that.

6.2.1. Compiling MySQL 5.0.x with SphinxSE
------------------------------------------

Skips steps 1-3 if using already prepared delta tarball.

   1. copy sphinx.5.0.yy.diff patch file into MySQL sources directory and
      run

      | patch -p1 < sphinx.5.0.yy.diff

      If there's no .diff file exactly for the specific version you need to
      build, try applying .diff with closest version numbers. It is
      important that the patch should apply with no rejects.

   2. in MySQL sources directory, run

      | sh BUILD/autorun.sh

   3. in MySQL sources directory, create sql/sphinx directory in and copy
      all files in mysqlse directory from Sphinx sources there. Example:

      | cp -R /root/builds/sphinx-0.9.7/mysqlse /root/builds/mysql-5.0.24/sql/sphinx

   4. configure MySQL and enable Sphinx engine:

      | ./configure --with-sphinx-storage-engine

   5. build and install MySQL:

      | make
      | make install

6.2.2. Compiling MySQL 5.1.x with SphinxSE
------------------------------------------

Skip steps 1-2 if using already prepared delta tarball.

   1. in MySQL sources directory, create storage/sphinx directory in and
      copy all files in mysqlse directory from Sphinx sources there.
      Example:

      | cp -R /root/builds/sphinx-0.9.7/mysqlse /root/builds/mysql-5.1.14/storage/sphinx

   2. in MySQL sources directory, run

      | sh BUILD/autorun.sh

   3. configure MySQL and enable Sphinx engine:

      | ./configure --with-plugins=sphinx

   4. build and install MySQL:

      | make
      | make install

6.2.3. Checking SphinxSE installation
-------------------------------------

To check whether SphinxSE has been succesfully compiled into MySQL, launch
newly built servers, run mysql client and issue SHOW ENGINES query. You
should see a list of all available engines. Sphinx should be present and
"Support" column should contain "YES":

   |      
   | mysql> show engines;
   | +------------+----------+----------------------------------------------------------------+
   | | Engine     | Support  | Comment                                                        |
   | +------------+----------+----------------------------------------------------------------+
   | | MyISAM     | DEFAULT  | Default engine as of MySQL 3.23 with great performance         |
   |   ...
   | | SPHINX     | YES      | Sphinx storage engine                                          |
   |   ...
   | +------------+----------+----------------------------------------------------------------+
   | 13 rows in set (0.00 sec)    

6.3. Using SphinxSE
-------------------

To search via SphinxSE, you would need to create special ENGINE=SPHINX
"search table", and then SELECT from it with full text query put into WHERE
clause for query column.

Let's begin with an example create statement and search query:

   | CREATE TABLE t1
   | (
   |     id          INTEGER NOT NULL,
   |     weight      INTEGER NOT NULL,
   |     query       VARCHAR(3072) NOT NULL,
   |     group_id    INTEGER,
   |     INDEX(query)
   | ) ENGINE=SPHINX CONNECTION="sphinx://localhost:3312/test";
   | 
   | SELECT * FROM t1 WHERE query='test it;mode=any';

First 3 columns of search table must be INTEGER, INTEGER and VARCHAR which
will be mapped to document ID, match weight and search query accordingly.
Query column must be indexed; all the others must be kept unindexed.
Columns' names are ignored so you can use arbitrary ones.

Additional columns must be either INTEGER or TIMESTAMP. They will be bound
to attributes provided in Sphinx result set by name, so their names must
match attribute names specified in sphinx.conf. If there's no such
attribute name in Sphinx search results, column will have NULL values.

Special "virtual" attributes names can also be bound to SphinxSE columns.
_sph_ needs to be used instead of @ for that. For instance, to obtain
@group and @count virtual attributes, use _sph_group and _sph_count column
names.

CONNECTION string parameter can be used to specify default searchd host,
port and indexes for queries issued using this table. If no connection
string is specified in CREATE TABLE, index name "*" (ie. search all
indexes) and localhost:3312 are assumed. Connection string syntax is as
follows:

   | CONNECTION="sphinx://HOST:PORT/INDEXNAME"

You can change the default connection string later:

   | ALTER TABLE t1 CONNECTION="sphinx://NEWHOST:NEWPORT/NEWINDEXNAME";

You can also override all these parameters per-query.

As seen in example, both query text and search options should be put into
WHERE clause on search query column (ie. 3rd column); the options are
separated by semicolons; and their names from values by equality sign. Any
number of options can be specified. Available options are:

   * query - query text;
   * mode - matching mode. Must be one of "all", "any", "phrase",
     "boolean", or "extended". Default is "all";
   * sort - match sorting mode. Must be one of "relevance", "attr_desc",
     "attr_asc", "time_segments", or "extended". In all modes besides
     "relevance" attribute name (or sorting clause for "extended") is also
     required after a colon:

      | ... WHERE query='test;sort=attr_asc:group_id';
      | ... WHERE query='test;sort=extended:@weight desc, group_id asc';

   * offset - offset into result set, default is 0;
   * limit - amount of matches to retrieve from result set, default is 20;
   * index - names of the indexes to search:

      | ... WHERE query='test;index=test1;';
      | ... WHERE query='test;index=test1,test2,test3;';

   * minid, maxid - min and max document ID to match;
   * weights - comma-separated list of weights to be assigned to Sphinx
     full-text fields:

      | ... WHERE query='test;weights=1,2,3;';

   * filter, !filter - comma-separated attribute name and a set of values
     to match:

      | # only include groups 1, 5 and 19
      | ... WHERE query='test;filter=group_id,1,5,19;';
      | 
      | # exclude groups 3 and 11
      | ... WHERE query='test;!filter=group_id,3,11;';

   * range, !range - comma-separated attribute name, min and max value to
     match:

      | # include groups from 3 to 7, inclusive
      | ... WHERE query='test;range=group_id,3,7;';
      | 
      | # exclude groups from 5 to 25
      | ... WHERE query='test;!range=group_id,5,25;';

   * maxmatches - per-query max matches value:

      | ... WHERE query='test;maxmatches=2000;';

   * groupby - group-by function and attribute:

      | ... WHERE query='test;groupby=day:published_ts;';
      | ... WHERE query='test;groupby=attr:group_id;';

   * groupsort - group-by sorting clause:

      | ... WHERE query='test;groupsort=@count desc;';

   * indexweights - comma-separated list of index names and weights to use
     when searching through several indexes:

      | ... WHERE query='test;indexweights=idx_exact,2,idx_stemmed,1;';

One very important note that it is much more efficient to allow Sphinx to
perform sorting, filtering and slicing the result set than to raise max
matches count and use WHERE, ORDER BY and LIMIT clauses on MySQL side. This
is for two reasons. First, Sphinx does a number of optimizations and
performs better than MySQL on these tasks. Second, less data would need to
be packed by searchd, transferred and unpacked by SphinxSE.

Additional query info besides result set could be retrieved with SHOW
ENGINE SPHINX STATUS statement:

   | mysql> SHOW ENGINE SPHINX STATUS;
   | +--------+-------+-------------------------------------------------+
   | | Type   | Name  | Status                                          |
   | +--------+-------+-------------------------------------------------+
   | | SPHINX | stats | total: 25, total found: 25, time: 126, words: 2 | 
   | | SPHINX | words | sphinx:591:1256 soft:11076:15945                | 
   | +--------+-------+-------------------------------------------------+
   | 2 rows in set (0.00 sec)

You could perform JOINs on SphinxSE search table and tables using other
engines. Here's an example with "documents" from example.sql:

   | mysql> SELECT content, date_added FROM test.documents docs
   | -> JOIN t1 ON (docs.id=t1.id) 
   | -> WHERE query="one document;mode=any";
   | +-------------------------------------+---------------------+
   | | content                             | docdate             |
   | +-------------------------------------+---------------------+
   | | this is my test document number two | 2006-06-17 14:04:28 | 
   | | this is my test document number one | 2006-06-17 14:04:28 | 
   | +-------------------------------------+---------------------+
   | 2 rows in set (0.00 sec)
   | 
   | mysql> SHOW ENGINE SPHINX STATUS;
   | +--------+-------+---------------------------------------------+
   | | Type   | Name  | Status                                      |
   | +--------+-------+---------------------------------------------+
   | | SPHINX | stats | total: 2, total found: 2, time: 0, words: 2 | 
   | | SPHINX | words | one:1:2 document:2:2                        | 
   | +--------+-------+---------------------------------------------+
   | 2 rows in set (0.00 sec)

7. Reporting bugs
=================

Unfortunately, Sphinx is not yet 100% bug free (even though I'm working
hard towards that), so you might occasionally run into some issues.

Reporting as much as possible about each bug is very important - because to
fix it, I need to be able either to reproduce and debug the bug, or to
deduce what's causing it from the information that you provide. So here are
some instructions on how to do that.

Build-time issues
-----------------

If Sphinx fails to build for some reason, please do the following:

   1. check that headers and libraries for your DBMS are properly installed
      (for instance, check that mysql-devel package is present);
   2. report Sphinx version and config file (be sure to remove the
      passwords!), MySQL (or PostgreSQL) configuration info, gcc version,
      OS version and CPU type (ie. x86, x86-64, PowerPC, etc):

      | mysql_config
      | gcc --version
      | uname -a

   3. report the error message which is produced by configure or gcc (it
      should be to include error message itself only, not the whole build
      log).

Run-time issues
---------------

If Sphinx builds and runs, but there are any problems running it, please do
the following:

   1. describe the bug (ie. both the expected behavior and actual behavior)
      and all the steps necessary to reproduce it;
   2. include Sphinx version and config file (be sure to remove the
      passwords!), MySQL (or PostgreSQL) version, gcc version, OS version
      and CPU type (ie. x86, x86-64, PowerPC, etc):

      | mysql --version
      | gcc --version
      | uname -a

   3. build, install and run debug versions of all Sphinx programs (this is
      to enable a lot of additional internal checks, so-called assertions):

      | make distclean
      | ./configure --with-debug
      | make install
      | killall -TERM searchd

   4. reindex to check if any assertions are triggered (in this case, it's
      likely that the index is corrupted and causing problems);
   5. if the bug does not reproduce with debug versions, revert to
      non-debug and mention it in your report;
   6. if the bug could be easily reproduced with a small (1-100 record)
      part of your database, please provide a gzipped dump of that part;
   7. if the problem is related to searchd, include relevant entries from
      searchd.log and query.log in your bug report;
   8. if the problem is related to searchd, try running it in console mode
      and check if it dies with an assertion:

      | ./searchd --console

   9. if any program dies with an assertion, provide the assertion message.

Debugging assertions, crashes and hangups
-----------------------------------------

If any program dies with an assertion, crashes without an assertion or
hangs up, you would additionally need to generate a core dump and examine
it.

   1. enable core dumps. On most Linux systems, this is done using ulimit:

      | ulimit -c 32768

   2. run the program and try to reproduce the bug;
   3. if the program crashes (either with or without an assertion), find
      the core file in current directory (it should typically print out
      "Segmentation fault (core dumped)" message);
   4. if the program hangs, use kill -SEGV from another console to force it
      to exit and dump core:

      | kill -SEGV HANGED-PROCESS-ID

   5. use gdb to examine the core file and obtain a backtrace:

      | gdb ./CRASHED-PROGRAM-FILE-NAME CORE-DUMP-FILE-NAME
      | (gdb) bt
      | (gdb) quit

Note that HANGED-PROCESS-ID, CRASHED-PROGRAM-FILE-NAME and
CORE-DUMP-FILE-NAME must all be replaced with specific numbers and file
names. For example, hanged searchd debugging session would look like:

   | # kill -SEGV 12345
   | # ls *core*
   | core.12345
   | # gdb ./searchd core.12345
   | (gdb) bt
   | ...
   | (gdb) quit

Note that ulimit is not server-wide and only affects current shell session.
This means that you will not have to restore any server-wide limits - but
if you relogin, you will have to set ulimit again.

Core dumps should be placed in current working directory (and Sphinx
programs do not change it), so this is where you would look for them.

Please do not immediately remove the core file because there could be
additional helpful information which could be retrieved from it. You do not
need to send me this file (as the debug info there is closely tied to your
system) but I might need to ask you a few additional questions about it.

8. sphinx.conf options reference
================================

8.1. Data source configuration options
--------------------------------------

8.1.1. type
-----------

Data source type. Mandatory, no default value. Known types are mysql,
pgsql, xmlpipe and xmlpipe2.

All other per-source options depend on source type selected by this option.
Names of the options used for SQL sources (ie. MySQL and PostgreSQL) start
with "sql_"; names of the ones used for xmlpipe and xmlpipe2 start with
"xmlpipe_".

Example:

   | type = mysql

8.1.2. sql_host
---------------

SQL server host to connect to. Mandatory, no default value. Applies to SQL
source types (mysql and pgsql) only.

In the simplest case when Sphinx resides on the same host with your MySQL
or PostgreSQL installation, you would simply specify "localhost". Note that
MySQL client library chooses whether to connect over TCP/IP or over UNIX
socket based on the host name. Generally speaking, "localhost" will force
it to use UNIX socket (this is the default and generally recommended mode)
and "127.0.0.1" will force TCP/IP usage. Refer to MySQL manual for more
details.

Example:

   | sql_host = localhost

8.1.3. sql_port
---------------

SQL server IP port to connect to. Optional, default is 3306 for mysql
source type and 5432 for pgsql type. Applies to SQL source types (mysql and
pgsql) only. Note that it depends on sql_host setting whether this value
will actually be used.

Example:

   | sql_port = 3306

8.1.4. sql_user
---------------

SQL user to use when connecting to sql_host. Mandatory, no default value.
Applies to SQL source types (mysql and pgsql) only.

Example:

   | sql_user = test

8.1.5. sql_pass
---------------

SQL user password to use when connecting to sql_host. Mandatory, no default
value. Applies to SQL source types (mysql and pgsql) only.

Example:

   | sql_pass = mysecretpassword

8.1.6. sql_db
-------------

SQL database (in MySQL terms) to use after the connection and perform
further queries within. Mandatory, no default value. Applies to SQL source
types (mysql and pgsql) only.

Example:

   | sql_db = test

8.1.7. sql_sock
---------------

UNIX socket name to connect to for local SQL servers. Optional, default
value is empty (use client library default settings). Applies to SQL source
types (mysql and pgsql) only.

On Linux, it would typically be /var/lib/mysql/mysql.sock. On FreeBSD, it
would typically be /tmp/mysql.sock. Note that it depends on sql_host
setting whether this value will actually be used.

Example:

   | sql_sock = /tmp/mysql.sock

8.1.8. mysql_connect_flags
--------------------------

MySQL client connection flags. Optional, default value is 0 (do not set any
flags). Applies to mysql source type only.

This option must contain an integer value with the sum of the flags. The
value will be passed to mysql_real_connect() verbatim. The flags are
enumerated in mysql_com.h include file. Flags that are especially
interesting in regard to indexing, with their respective values, are as
follows:

   * CLIENT_COMPRESS = 32; can use compression protocol
   * CLIENT_SSL = 2048; switch to SSL after handshake
   * CLIENT_SECURE_CONNECTION = 32768; new 4.1 authentication

For instance, you can specify 2080 (2048+32) to use both compression and
SSL, or 32768 to use new authentication only. Initially, this option was
introduced to be able to use compression when the indexer and mysqld are on
different hosts. Compression on 1 Gbps links is most likely to hurt
indexing time though it reduces network traffic, both in theory and in
practice. However, enabling compression on 100 Mbps links may improve
indexing time significantly (upto 20-30% of the total indexing time
improvement was reported). Your mileage may vary.

Example:

   | mysql_connect_flags = 32 # enable compression

8.1.9. sql_query_pre
--------------------

Pre-fetch query, or pre-query. Multi-value, optional, default is empty list
of queries. Applies to SQL source types (mysql and pgsql) only.

Multi-value means that you can specify several pre-queries. They are
executed before the main fetch query, and they will be exectued exactly in
order of appeareance in the configuration file. Pre-query results are
ignored.

Pre-queries are useful in a lot of ways. They are used to setup encoding,
mark records that are going to be indexed, update internal counters, set
various per-connection SQL server options and variables, and so on.

Perhaps the most frequent pre-query usage is to specify the encoding that
the server will use for the rows it returnes. It must match the encoding
that Sphinx expects (as specified by charset_type and charset_table
options). Two MySQL specific examples of setting the encoding are:

   | sql_query_pre = SET CHARACTER_SET_RESULTS=cp1251
   | sql_query_pre = SET NAMES utf8

Also specific to MySQL sources, it is useful to disable query cache (for
indexer connection only) in pre-query, because indexing queries are not
going to be re-run frequently anyway, and there's no sense in caching their
results. That could be achieved with:

   | sql_query_pre = SET SESSION query_cache_type=OFF

Example:

   | sql_query_pre = SET NAMES utf8
   | sql_query_pre = SET SESSION query_cache_type=OFF

8.1.10. sql_query
-----------------

Main document fetch query. Mandatory, no default value. Applies to SQL
source types (mysql and pgsql) only.

There can be only one main query. This is the query which is used to
retrieve documents from SQL server. You can specify up to 32 full-text
fields (formally, upto SPH_MAX_FIELDS from sphinx.h), and an arbitrary
amount of attributes. All of the columns that are neither document ID (the
first one) nor attributes will be full-text indexed.

Document ID MUST be the very first field, and it MUST BE UNIQUE UNSIGNED
POSITIVE (NON-ZERO, NON-NEGATIVE) INTEGER NUMBER. It can be either 32-bit
or 64-bit, depending on how you built Sphinx; by default it builds with
32-bit IDs support but --enable-id64 option to configure allows to build
with 64-bit document and word IDs support.

Example:

   | sql_query = \
   | 	SELECT id, group_id, UNIX_TIMESTAMP(date_added) AS date_added, \
   | 		title, content \
   | 	FROM documents

8.1.11. sql_query_range
-----------------------

Range query setup. Optional, default is empty. Applies to SQL source types
(mysql and pgsql) only.

Setting this option enables ranged document fetch queries (see Section 3.7,
<<Ranged queries>>). Ranged queries are useful to avoid notorious MyISAM
table locks when indexing lots of data. (They also help with other less
notorious issues, such as reduced performance caused by big result sets, or
additional resources consumed by InnoDB to serialize big read
transactions.)

The query specified in this option must fetch min and max document IDs that
will be used as range boundaries. It must return exactly two integer
fields, min ID first and max ID second; the field names are ignored.

When ranged queries are enabled, sql_query will be required to contain
$start and $end macros (because it obviously would be a mistake to index
the whole table many times over). Note that the intervals specified by
$start..$end will not overlap, so you should not remove document IDs that
are exactly equal to $start or $end from your query. The example in
Section 3.7, <<Ranged queries>>) illustrates that; note how it uses
greater-or-equal and less-or-equal comparisons.

Example:

   | sql_query_range = SELECT MIN(id),MAX(id) FROM documents

8.1.12. sql_range_step
----------------------

Range query step. Optional, default is 1024. Applies to SQL source types
(mysql and pgsql) only.

Only used when ranged queries are enabled. The full document IDs interval
fetched by sql_query_range will be walked in this big steps. For example,
if min and max IDs fetched are 12 and 3456 respectively, and the step is
1000, indexer will call sql_query several times with the following
substitutions:

   * $start=12, $end=1011
   * $start=1012, $end=2011
   * $start=2012, $end=3011
   * $start=3012, $end=3456

Example:

   | sql_range_step = 1000

8.1.13. sql_attr_uint
---------------------

Unsigned integer attribute declaration. Multi-value (there might be
multiple attributes declared), optional. Applies to SQL source types (mysql
and pgsql) only.

The column value should fit into 32-bit unsigned integer range. Values
outside this range will be accepted but wrapped around. For instance, -1
will be wrapped around to 2^32-1 or 4,294,967,295.

You can specify bit count for integer attributes by appending ':BITCOUNT'
to attribute name (see example below). Attributes with less than default
32-bit size, or bitfields, perform slower. But they require less RAM when
using extern storage: such bitfields are packed together in 32-bit chunks
in .spa attribute data file. Bit size settings are ignored if using inline
storage.

Example:

   | sql_attr_uint = group_id
   | sql_attr_uint = forum_id:9 # 9 bits for forum_id

8.1.14. sql_attr_bool
---------------------

Boolean attribute declaration. Multi-value (there might be multiple
attributes declared), optional. Applies to SQL source types (mysql and
pgsql) only. Equivalent to sql_attr_uint declaration with a bit count of 1.

Example:

   | sql_attr_bool = is_deleted # will be packed to 1 bit

8.1.15. sql_attr_timestamp
--------------------------

UNIX timestamp attribute declaration. Multi-value (there might be multiple
attributes declared), optional. Applies to SQL source types (mysql and
pgsql) only.

The column value should be a timestamp in UNIX format, ie. 32-bit unsigned
integer number of seconds elapsed since midnight, January 01, 1970, GMT.
Timestamps are internally stored and handled as integers everywhere. But in
addition to working with timestamps as integers, it's also legal to use
them along with different date-based functions - such as time segments
sorting mode, or day/week/month/year extraction for GROUP BY. Note that
DATE or DATETIME column types in MySQL can not be directly used as
timestamps; you need to explicitly convert such columns using
UNIX_TIMESTAMP function.

Example:

   | sql_attr_timestamp = UNIX_TIMESTAMP(added_datetime) AS added_ts

8.1.16. sql_attr_str2ordinal
----------------------------

Ordinal string number attribute declaration. Multi-value (there might be
multiple attributes declared), optional. Applies to SQL source types (mysql
and pgsql) only.

This attribute type (so-called ordinal, for brevity) is intended to allow
sorting by string values, but without storing the strings themselves. When
indexing ordinals, string values are fetched from database, temporarily
stored, sorted, and then replaced by their respective ordinal numbers in
the array of sorted strings. So, the ordinal number is an integer such that
sorting by it produces the same result as if lexicographically sorting by
original strings. by string values lexicographically.

Earlier versions could consume a lot of RAM for indexing ordinals. Starting
with revision r1112, ordinals accumulation and sorting also runs in fixed
memory (at the cost of using additional temporary disk space), and honors
mem_limit settings.

Ideally the strings should be sorted differently, depending on the encoding
and locale. For instance, if the strings are known to be Russian text in
KOI8R encoding, sorting the bytes 0xE0, 0xE1, and 0xE2 should produce 0xE1,
0xE2 and 0xE0, because in KOI8R value 0xE0 encodes a character that is
(noticeably) after characters encoded by 0xE1 and 0xE2. Unfortunately,
Sphinx does not support that at the moment and will simply sort the strings
bytewise.

Note that the ordinals are by construction local to each index, and it's
therefore impossible to merge ordinals while retaining the proper order.
The processed strings are replaced by their sequential number in the index
they occurred in, but different indexes have different sets of strings. For
instance, if 'main' index contains strings "aaa", "bbb", "ccc", and so on
up to "zzz", they'll be assigned numbers 1, 2, 3, and so on up to 26,
respectively. But then if 'delta' only contains "zzz" the assigned number
will be 1. And after the merge, the order will be broken. Unfortunately,
this is impossible to workaround without storing the original strings (and
once Sphinx supports storing the original strings, ordinals will not be
necessary any more).

Example:

   | sql_attr_str2ordinal = author_name

8.1.17. sql_attr_float
----------------------

Floating point attribute declaration. Multi-value (there might be multiple
attributes declared), optional. Applies to SQL source types (mysql and
pgsql) only.

The values will be stored in single precision, 32-bit IEEE 754 format.
Represented range is approximately from 1e-38 to 1e+38. The amount of
decimal digits that can be stored precisely is approximately 7. One
important usage of the float attributes is storing latitude and longitude
values (in radians), for further usage in query-time geosphere distance
calculations.

Example:

   | sql_attr_float = lat_radians
   | sql_attr_float = long_radians

8.1.18. sql_attr_multi
----------------------

Multi-valued attribute (MVA) declaration. Multi-value (ie. there may be
more than one such attribute declared), optional. Applies to SQL source
types (mysql and pgsql) only.

Plain attributes only allow to attach 1 value per each document. However,
there are cases (such as tags or categories) when it is desired to attach
multiple values of the same attribute and be able to apply filtering or
grouping to value lists.

The declaration format is as follows (backslashes are for clarity only;
everything can be declared in a single line as well):

   | sql_attr_multi = ATTR-TYPE ATTR-NAME 'from' SOURCE-TYPE \
   | 	[;QUERY] \
   | 	[;RANGE-QUERY]

where

   * ATTR-TYPE is 'uint' or 'timestamp'
   * SOURCE-TYPE is 'field', 'query', or 'ranged-query'
   * QUERY is SQL query used to fetch all ( docid, attrvalue ) pairs
   * RANGE-QUERY is SQL query used to fetch min and max ID values, similar
     to 'sql_query_range'

Example:

   | sql_attr_multi = uint tag from query; SELECT id, tag FROM tags
   | sql_attr_multi = uint tag from ranged-query; \
   | 	SELECT id, tag FROM tags WHERE id>=$start AND id<=$end; \
   | 	SELECT MIN(id), MAX(id) FROM tags

8.1.19. sql_query_post
----------------------

Post-fetch query. Optional, default value is empty. Applies to SQL source
types (mysql and pgsql) only.

This query is executed immediately after sql_query completes successfully.
When post-fetch query produces errors, they are reported as warnings, but
indexing is not terminated. It's result set is ignored. Note that indexing
is not yet completed at the point when this query gets executed, and
further indexing still may fail. Therefore, any permanent updates should
not be done from here. For instance, updates on helper table that
permanently change the last successfully indexed ID should not be run from
post-fetch query; they should be run from post-index query instead.

Example:

   | sql_query_post = DROP TABLE my_tmp_table

8.1.20. sql_query_post_index
----------------------------

Post-index query. Optional, default value is empty. Applies to SQL source
types (mysql and pgsql) only.

This query is executed when indexing is fully and succesfully completed. If
this query produces errors, they are reported as warnings, but indexing is
not terminated. It's result set is ignored. $maxid macro can be used in its
text; it will be expanded to maximum document ID which was actually fetched
from the database during indexing.

Example:

   | sql_query_post_index = REPLACE INTO counters ( id, val ) \
   |     VALUES ( 'max_indexed_id', $maxid )

8.1.21. sql_ranged_throttle
---------------------------

Ranged query throttling period, in milliseconds. Optional, default is 0 (no
throttling). Applies to SQL source types (mysql and pgsql) only.

Throttling can be useful when indexer imposes too much load on the database
server. It causes the indexer to sleep for given amount of milliseconds
once per each ranged query step. This sleep is unconditional, and is
performed before the fetch query.

Example:

   | sql_ranged_throttle = 1000 # sleep for 1 sec before each query step

8.1.22. sql_query_info
----------------------

Document info query. Optional, default is empty. Applies to mysql source
type only.

Only used by CLI search to fetch and display document information, only
works with MySQL at the moment, and only intended for debugging purposes.
This query fetches the row that will be displayed by CLI search utility for
each document ID. It is required to contain $id macro that expands to the
queried document ID.

Example:

   | sql_query_info = SELECT * FROM documents WHERE id=$id

8.1.23. xmlpipe_command
-----------------------

Shell command that invokes xmlpipe stream producer. Mandatory. Applies to
xmlpipe and xmlpipe2 source types only.

Specifies a command that will be executed and which output will be parsed
for documents. Refer to Section 3.8, <<xmlpipe data source>> or
Section 3.9, <<xmlpipe2 data source>> for specific format description.

Example:

   | xmlpipe_command = cat /home/sphinx/test.xml

8.1.24. xmlpipe_field
---------------------

xmlpipe field declaration. Multi-value, optional. Applies to xmlpipe2
source type only. Refer to Section 3.9, <<xmlpipe2 data source>>.

Example:

   | xmlpipe_field = subject
   | xmlpipe_field = content

8.1.25. xmlpipe_attr_uint
-------------------------

xmlpipe integer attribute declaration. Multi-value, optional. Applies to
xmlpipe2 source type only. Syntax fully matches that of sql_attr_uint.

Example:

   | xmlpipe_attr_uint = author

8.1.26. xmlpipe_attr_bool
-------------------------

xmlpipe boolean attribute declaration. Multi-value, optional. Applies to
xmlpipe2 source type only. Syntax fully matches that of sql_attr_bool.

Example:

   | xmlpipe_attr_bool = is_deleted # will be packed to 1 bit

8.1.27. xmlpipe_attr_timestamp
------------------------------

xmlpipe UNIX timestamp attribute declaration. Multi-value, optional.
Applies to xmlpipe2 source type only. Syntax fully matches that of
sql_attr_timestamp.

Example:

   | xmlpipe_attr_timestamp = published

8.1.28. xmlpipe_attr_str2ordinal
--------------------------------

xmlpipe string ordinal attribute declaration. Multi-value, optional.
Applies to xmlpipe2 source type only. Syntax fully matches that of
sql_attr_str2ordinal.

Example:

   | xmlpipe_attr_str2ordinal = author_sort

8.1.29. xmlpipe_attr_float
--------------------------

xmlpipe floating point attribute declaration. Multi-value, optional.
Applies to xmlpipe2 source type only. Syntax fully matches that of
sql_attr_float.

Example:

   | xmlpipe_attr_float = lat_radians
   | xmlpipe_attr_float = long_radians

8.1.30. xmlpipe_attr_multi
--------------------------

xmlpipe MVA attribute declaration. Multi-value, optional. Applies to
xmlpipe2 source type only.

This setting declares an MVA attribute tag in xmlpipe2 stream. The contents
of the specified tag will be parsed and a list of integers that will
constitute the MVA will be extracted, similar to how sql_attr_multi parses
SQL column contents when 'field' MVA source type is specified.

Example:

   | xmlpipe_attr_multi = taglist

8.2. Index configuration options
--------------------------------

8.2.1. type
-----------

Index type. Optional, default is empty (index is plain local index). Known
values are empty string or 'distributed'.

Sphinx supports two different types of indexes: local, that are stored and
processed on the local machine; and distributed, that involve not only
local searching but querying remote searchd instances over the network as
well. Index type settings lets you choose this type. By default, indexes
are local. Specifying 'distributed' for type enables distributed searching,
see Section 4.7, <<Distributed searching>>.

Example:

   | type = distributed

8.2.2. source
-------------

Adds document source to local index. Multi-value, mandatory.

Specifies document source to get documents from when the current index is
indexed. There must be at least one source. There may be multiple sources,
without any restrictions on the source types: ie. you can pull part of the
data from MySQL server, part from PostgreSQL, part from the filesystem
using xmlpipe2 wrapper.

However, there are some restrictions on the source data. First, document
IDs must be globally unique across all sources. If that condition is not
met, you might get unexpected search results. Second, source schemas must
be the same in order to be stored within the same index.

No source ID is stored automatically. Therefore, in order to be able to
tell what source the matched document came from, you will need to store
some additional information yourself. Two typical approaches include:

   1. mangling document ID and encoding source ID in it:

      | source src1
      | {
      | 	sql_query = SELECT id*10+1, ... FROM table1
      | 	...
      | }
      | 
      | source src2
      | {
      | 	sql_query = SELECT id*10+2, ... FROM table2
      | 	...
      | }

   2. storing source ID simply as an attribute:

      | source src1
      | {
      | 	sql_query = SELECT id, 1 AS source_id FROM table1
      | 	sql_attr_uint = source_id
      | 	...
      | }
      | 
      | source src2
      | {
      | 	sql_query = SELECT id, 2 AS source_id FROM table2
      | 	sql_attr_uint = source_id
      | 	...
      | }

Example:

   | source = srcpart1
   | source = srcpart2
   | source = srcpart3

8.2.3. path
-----------

Index files path and file name (without extension). Mandatory.

Path specifies both directory and file name, but without extension. indexer
will append different extensions to this path when generating final names
for both permanent and temporary index files. Permanent data files have
several different extensions starting with '.sp'; temporary files'
extensions start with '.tmp'. It's safe to remove .tmp* files is if indexer
fails to remove them automatically.

For reference, different index files store the following data:

   * .spa stores document attributes (used in extern docinfo storage mode
     only);
   * .spd stores matching document ID lists for each word ID;
   * .sph stores index header information;
   * .spi stores word lists (word IDs and pointers to .spd file);
   * .spm stores MVA data;
   * .spp stores hit (aka posting, aka word occurence) lists for each word
     ID.

Example:

   | path = /var/data/test1

8.2.4. docinfo
--------------

Document attribute values (docinfo) storage mode. Optional, default is
'extern'. Known values are 'none', 'extern' and 'inline'.

Docinfo storage mode defines how exactly docinfo will be physically stored
on disk and RAM. "none" means that there will be no docinfo at all (ie. no
attributes). Normally you need not to set "none" explicitly because Sphinx
will automatically select "none" when there are no attributes configured.
"inline" means that the docinfo will be stored in the .spd file, along with
the document ID lists. "extern" means that the docinfo will be stored
separately (externally) from document ID lists, in a special .spa file.

Basically, externally stored docinfo must be kept in RAM when querying. for
performance reasons. So in some cases "inline" might be the only option.
However, such cases are infrequent, and docinfo defaults to "extern". Refer
to Section 3.2, <<Attributes>> for in-depth discussion and RAM usage
estimates.

Example:

   | docinfo = inline

8.2.5. mlock
------------

Memory locking for cached data. Optional, default is 0 (do not call
mlock()).

For search performance, searchd preloads a copy of .spa and .spi files in
RAM, and keeps that copy in RAM at all times. But if there are no searches
on the index for some time, there are no accesses to that cached copy, and
OS might decide to swap it out to disk. First queries to such "cooled down"
index will cause swap-in and their latency will suffer.

Setting mlock option to 1 makes Sphinx lock physical RAM used for that
cached data using mlock(2) system call, and that prevents swapping (see man
2 mlock for details). mlock(2) is a privileged call, so it will require
searchd to be either run from root account, or be granted enough privileges
otherwise. If mlock() fails, a warning is emitted, but index continues
working.

Example:

   | mlock = 1

8.2.6. morphology
-----------------

A list of morphology preprocessors to apply. Optional, default is empty (do
not apply any preprocessor).

Morphology preprocessors can be applied to the words being indexed to
replace different forms of the same word with the base, normalized form.
For instance, English stemmer will normalize both "dogs" and "dog" to
"dog", making search results for both searches the same.

Built-in preprocessors include English stemmer, Russian stemmer (that
supports UTF-8 and Windows-1251 encodings), Soundex, and Metaphone. The
latter two replace the words with special phonetic codes that are equal is
words are phonetically close. Additional stemmers provided by Snowball
project libstemmer library can be enabled at compile time using
--with-libstemmer configure option. Built-in English and Russian stemmers
should be faster than their libstemmer counterparts, but can produce
slightly different results, because they are based on an older version.
Metaphone implementation is based on Double Metaphone algorithm and indexes
the primary code.

Built-in values that be used in morphology option are: 'none', 'stem_en',
'stem_ru', 'stem_enru', 'soundex', and 'metaphone'. Additional values
provided by libstemmer are in 'libstemmer_XXX' format, where XXX is
libstemmer algorithm codename (refer to libstemmer_c/libstemmer/modules.txt
for a complete list).

Several stemmers can be specified (comma-separated). They will be applied
to incoming words in the order they are listed, and the processing will
stop once one of the stemmers actually modifies the word. Also when
wordforms feature is enabled the word will be looked up in word forms
dictionary first, and if there is a matching entry in the dictionary,
stemmers will not be applied at all. Or in other words, wordforms can be
used to implement stemming exceptions.

Example:

   | morphology = stem_en, libstemmer_sv

8.2.7. stopwords
----------------

Stopword files list (space separated). Optional, default is empty.

Stopwords are the words that will not be indexed. Typically you'd put most
frequent words in the stopwords list because they do not add much value to
search results but consume a lot of resources to process.

You can specify several file names, separated by spaces. All the files will
be loaded. Stopwords file format is simple plain text. The encoding must
match index encoding specified in charset_type. File data will be tokenized
with respect to charset_table settings, so you can use the same separators
as in the indexed data. The stemmers will also be applied when parsing
stopwords file.

While stopwords are not indexed, they still do affect the keyword
positions. For instance, assume that "the" is a stopword, that document
1 contains the line "in office", and that document 2 contains "in the
office". Searching for "in office" as for exact phrase will only return the
first document, as expected, even though "the" in the second one is
stopped.

Example:

   | stopwords = /usr/local/sphinx/data/stopwords.txt
   | stopwords = stopwords-ru.txt stopwords-en.txt

8.2.8. wordforms
----------------

Word forms dictionary. Optional, default is empty.

Word forms are applied after tokenizing the incoming text by charset_table
rules. They essentialy let you replace one word with another. Normally,
that would be used to bring different word forms to a single normal form
(eg. to normalize all the variants such as "walks", "walked", "walking" to
the normal form "walk"). It can also be used to implement stemming
exceptions, because stemming is not applied to words found in the forms
list.

Dictionaries are used to normalize incoming words both during indexing and
searching. Therefore, to pick up changes in wordforms file it's required to
reindex and restart searchd.

Word forms support in Sphinx is designed to support big dictionaries well.
They moderately affect indexing speed: for instance, a dictionary with
1 million entries slows down indexing about 1.5 times. Searching speed is
not affected at all. Additional RAM impact is roughly equal to the
dictionary file size, and dictionaries are shared across indexes: ie. if
the very same 50 MB wordforms file is specified for 10 different indexes,
additional searchd RAM usage will be about 50 MB.

Dictionary file should be in a simple plain text format. Each line should
contain source and destination word forms, in exactly the same encoding as
specified in charset_type, separated by "greater" sign. Rules from the
charset_table will be applied when the file is loaded. So basically it's as
case sensitive as your other full-text indexed data, ie. typically case
insensitive. Here's the file contents sample:

   | walks > walk
   | walked > walk
   | walking > walk

There is bundled spelldump utility that helps you create a dictionary file
in the format Sphinx can read from source .dict and .aff dictionary files
in ispell format.

Example:

   | wordforms = /usr/local/sphinx/data/wordforms.txt

8.2.9. exceptions
-----------------

Tokenizing exceptions file. Optional, default is empty.

Exceptions allow to map one or more tokens (including tokens with
characters that would normally be excluded) to a single keyword. They are
similar to wordforms in that they also perform mapping, but have a number
of important differences.

Short summary of the differences is as follows:

   * exceptions are case sensitive, wordforms are not;
   * exceptions allow to detect sequences of tokens, wordforms work with
     single words only;
   * exceptions can use special characters that are not in charset_table,
     wordforms fully obey charset_table;
   * exceptions can underperform on huge dictionaries, wordforms handle
     millions of entries well.

The expected file format is also plain text, with one line per exception,
and the line format is as follows:

   | map-from-tokens => map-to-token

Example file:

   | AT & T => AT&T
   | AT&T => AT&T
   | Standarten   Fuehrer => standartenfuhrer
   | Standarten Fuhrer => standartenfuhrer
   | MS Windows => ms windows
   | Microsoft Windows => ms windows
   | C++ => cplusplus
   | c++ => cplusplus
   | C plus plus => cplusplus

All tokens here are case sensitive: they will not be processed by
charset_table rules. Thus, with the example exceptions file above, "At&t"
text will be tokenized as two keywords "at" and "t", because of lowercase
letters. On the other hand, "AT&T" will match exactly and produce single
"AT&T" keyword.

Note that this map-to keyword is a) always interpereted as a single word,
and b) is both case and space sensitive! In our sample, "ms windows" query
will not match the document with "MS Windows" text. The query will be
interpreted as a query for two keywords, "ms" and "windows". And what "MS
Windows" gets mapped to is a single keyword "ms windows", with a space in
the middle. On the other hand, "standartenfuhrer" will retrieve documents
with "Standarten Fuhrer" or "Standarten Fuehrer" contents (capitalized
exactly like this), or any capitalization variant of the keyword itself,
eg. "staNdarTenfUhreR". (It won't catch "standarten fuhrer", however: this
text does not match any of the listed exceptions because of case
sensitivity, and gets indexed as two separate keywords.)

Whitespace in the map-from tokens list matters, but its amount does not.
Any amount of the whitespace in the map-form list will match any other
amount of whitespace in the indexed document or query. For instance,
"AT & T" map-from token will match "AT    &  T" text, whatever the amount
of space in both map-from part and the indexed text. Such text will
therefore be indexed as a special "AT&T" keyword, thanks to the very first
entry from the sample.

Exceptions also allow to capture special characters (that are exceptions
from general charset_table rules; hence the name). Assume that you
generally do not want to treat '+' as a valid character, but still want to
be able search for some exceptions from this rule such as 'C++'. The sample
above will do just that, totally independent of what characters are in the
table and what are not.

Exceptions are applied to raw incoming document and query data during
indexing and searching respectively. Therefore, to pick up changes in the
file it's required to reindex and restart searchd.

Example:

   | exceptions = /usr/local/sphinx/data/exceptions.txt

8.2.10. min_word_len
--------------------

Minimum indexed word length. Optional, default is 1 (index everything).

Only those words that are not shorter than this minimum will be indexed.
For instance, if min_word_len is 4, then 'the' won't be indexed, but 'they'
will be.

Example:

   | min_word_len = 4

8.2.11. charset_type
--------------------

Character set encoding type. Optional, default is 'sbcs'. Known values are
'sbcs' and 'utf-8'.

Different encodings have different methods for mapping their internal
characters codes into specific byte sequences. Two most common methods in
use today are single-byte encoding and UTF-8. Their corresponding
charset_type values are 'sbcs' (stands for Single Byte Character Set) and
'utf-8'. The selected encoding type will be used everywhere where the index
is used: when indexing the data, when parsing the query against this index,
when generating snippets, etc.

Note that while 'utf-8' implies that the decoded values must be treated as
Unicode codepoint numbers, there's a family of 'sbcs' encodings that may in
turn treat different byte values differently, and that should be properly
reflected in your charset_table settings. For example, the same byte value
of 224 (0xE0 hex) maps to different Russian letters depending on whether
koi-8r or windows-1251 encoding is used.

Example:

   | charset_type = utf-8

8.2.12. charset_table
---------------------

Accepted characters table, with case folding rules. Optional, default value
depends on charset_type value.

charset_table is the main workhorse of Sphinx tokenizing process, ie. the
process of extracting keywords from document text or query txet. It
controls what characters are accepted as valid and what are not, and how
the accepted characters should be transformed (eg. should the case be
removed or not).

You can think of charset_table as of a big table that has a mapping for
each and every of 100K+ characters in Unicode (or as of a small
256-character table if you're using SBCS). By default, every character maps
to 0, which means that it does not occur within keywords and should be
treated as a separator. Once mentioned in the table, character is mapped to
some other character (most frequently, either to itself or to a lowercase
letter), and is treated as a valid keyword part.

The expected value format is a commas-separated list of mappings. Two
simplest mappings simply declare a character as valid, and map a single
character to another single character, respectively. But specifying the
whole table in such form would result in bloated and barely manageable
specifications. So there are several syntax shortcuts that let you map
ranges of characters at once. The complete list is as follows:

A->a
   Single char mapping, declares source char 'A' as allowed to occur within
   keywords and maps it to destination char 'a' (but does not declare 'a'
   as allowed).

A..Z->a..z
   Range mapping, declares all chars in source range as allowed and maps
   them to the destination range. Does not declare destination range as
   allowed. Also checks ranges' lengths (the lengths must be equal).

a
   Stray char mapping, declares a character as allowed and maps it to
   itself. Equivalent to a->a single char mapping.

a..z
   Stray range mapping, declares all characters in range as allowed and
   maps them to themselves. Equivalent to a..z->a..z range mapping.

A..Z/2
   Checkerboard range map. Maps every pair of chars to the second char.
   More formally, declares odd characters in range as allowed and maps them
   to the even ones; also declares even characters as allowed and maps them
   to themselves. For instance, A..Z/2 is equivalent to A->B, B->B, C->D,
   D->D, ..., Y->Z, Z->Z. This mapping shortcut is helpful for a number of
   Unicode blocks where uppercase and lowercase letters go in such
   interleaved order instead of contiguous chunks.

Control characters with codes from 0 to 31 are always treated as
separators. Characters with codes 32 to 127, ie. 7-bit ASCII characters,
can be used in the mappings as is. To avoid configuration file encoding
issues, 8-bit ASCII characters and Unicode characters must be specified in
U+xxx form, where 'xxx' is hexadecimal codepoint number. This form can also
be used for 7-bit ASCII characters to encode special ones: eg. use U+20 to
encode space, U+2E to encode dot, U+2C to encode comma.

Example:

   | # 'sbcs' defaults for English and Russian
   | charset_table = 0..9, A..Z->a..z, _, a..z, \
   | 	U+A8->U+B8, U+B8, U+C0..U+DF->U+E0..U+FF, U+E0..U+FF
   | 
   | # 'utf-8' defaults for English and Russian
   | charset_table = 0..9, A..Z->a..z, _, a..z, \
   | 	U+410..U+42F->U+430..U+44F, U+430..U+44F

8.2.13. ignore_chars
--------------------

Ignored characters list. Optional, default is empty.

Useful in the cases when some characters, such as soft hyphenation mark
(U+00AD), should be not just treated as separators but rather fully
ignored. For example, if '-' is simply not in the charset_table, "abc-def"
text will be indexed as "abc" and "def" keywords. On the contrary, if '-'
is added to ignore_chars list, the same text will be indexed as a single
"abcdef" keyword.

The syntax is the same as for charset_table, but it's only allowed to
declare characters, and not allowed to map them. Also, the ignored
characters must not be present in charset_table.

Example:

   | ignore_chars = U+AD

8.2.14. min_prefix_len
----------------------

Minimum word prefix length to index. Optional, default is 0 (do not index
prefixes).

Prefix indexing allows to implement wildcard searching by 'wordstart*'
wildcards (refer to enable_star option for details on wildcard syntax).
When mininum prefix length is set to a positive number, indexer will index
all the possible keyword prefixes (ie. word beginnings) in addition to the
keywords themselves. Too short prefixes (below the minimum allowed length)
will not be indexed.

For instance, indexing a keyword "example" with min_prefix_len=3 will
result in indexing "exa", "exam", "examp", "exampl" prefixes along with the
word itself. Searches against such index for "exam" will match documents
that contain "example" word, even if they do not contain "exam" on itself.
However, indexing prefixes will make the index grow significantly (because
of many more indexed keywords), and will degrade both indexing and
searching times.

There's no automatic way to rank perfect word matches higher in a prefix
index, but there's a number of tricks to achieve that. First, you can setup
two indexes, one with prefix indexing and one without it, search through
both, and use SetIndexWeights() call to combine weights. Second, you can
enable star-syntax and rewrite your extended-mode queries:

   | # in sphinx.conf
   | enable_star = 1
   | 
   | // in query
   | $cl->Query ( "( keyword | keyword* ) other keywords" );

Example:

   | min_prefix_len = 3

8.2.15. min_infix_len
---------------------

Minimum infix prefix length to index. Optional, default is 0 (do not index
infixes).

Infix indexing allows to implement wildcard searching by 'start*', '*end',
and '*middle*' wildcards (refer to enable_star option for details on
wildcard syntax). When mininum infix length is set to a positive number,
indexer will index all the possible keyword infixes (ie. substrings) in
addition to the keywords themselves. Too short infixes (below the minimum
allowed length) will not be indexed. For instance, indexing a keyword
"test" with min_infix_len=2 will result in indexing "te", "es", "st",
"tes", "est" infixes along with the word itself. Searches against such
index for "es" will match documents that contain "test" word, even if they
do not contain "es" on itself. However, indexing infixes will make the
index grow significantly (because of many more indexed keywords), and will
degrade both indexing and searching times.

There's no automatic way to rank perfect word matches higher in an infix
index, but the same tricks as with prefix indexes can be applied.

Example:

   | min_infix_len = 3

8.2.16. prefix_fields
---------------------

The list of full-text fields to limit prefix indexing to. Optional, default
is empty (index all fields in prefix mode).

Because prefix indexing impacts both indexing and searching performance, it
might be desired to limit it to specific full-text fields only: for
instance, to provide prefix searching through URLs, but not through page
contents. prefix_fields specifies what fields will be prefix-indexed; all
other fields will be indexed in normal mode. The value format is
a comma-separated list of field names.

Example:

   | prefix_fields = url, domain

8.2.17. infix_fields
--------------------

The list of full-text fields to limit infix indexing to. Optional, default
is empty (index all fields in infix mode).

Similar to prefix_fields, but lets you limit infix-indexing to given
fields.

Example:

   | infix_fields = url, domain

8.2.18. enable_star
-------------------

Enables star-syntax (or wildcard syntax) when searching through
prefix/infix indexes. Optional, default is is 0 (do not use wildcard
syntax), for compatibility with 0.9.7. Known values are 0 and 1.

This feature enables "star-syntax", or wildcard syntax, when searching
through indexes which were created with prefix or infix indexing enabled.
It only affects searching; so it can be changed without reindexing by
simply restarting searchd.

The default value is 0, that means to disable star-syntax and treat all
keywords as prefixes or infixes respectively, depending on indexing-time
min_prefix_len and min_infix_len settings. The value of 1 means that star
('*') can be used at the start and/or the end of the keyword. The star will
match zero or more characters.

For example, assume that the index was built with infixes and that
enable_star is 1. Searching should work as follows:

   1. "abcdef" query will match only those documents that contain the exact
      "abcdef" word in them.
   2. "abc*" query will match those documents that contain any words
      starting with "abc" (including the documents which contain the exact
      "abc" word only);
   3. "*cde*" query will match those documents that contain any words which
      have "cde" characters in any part of the word (including the
      documents which contain the exact "cde" word only).
   4. "*def" query will match those documents that contain any words ending
      with "def" (including the documents that contain the exact "def" word
      only).

Example:

   | enable_star = 1

8.2.19. ngram_len
-----------------

N-gram lengths for N-gram indexing. Optional, default is 0 (disable n-gram
indexing). Known values are 0 and 1 (other lengths to be implemented).

N-grams provide basic CJK (Chinese, Japanse, Koreasn) support for
unsegmented texts. The issue with CJK searching is that there could be no
clear separators between the words. Ideally, the texts would be filtered
through a special program called segmenter that would insert separators in
proper locations. However, segmenters are slow and error prone, and it's
common to index contiguous groups of N characters, or n-grams, instead.

When this feature is enabled, streams of CJK characters are indexed as
N-grams. For example, if incoming text is "ABCDEF" (where A to F represent
some CJK characters) and length is 1, in will be indexed as if it was "A
B C D E F". (With length equal to 2, it would produce "AB BC CD DE EF"; but
only 1 is supported at the moment.) Only those characters that are listed
in ngram_chars table will be split this way; other ones will not be
affected.

Note that if search query is segmented, ie. there are separators between
individual words, then wrapping the words in quotes and using extended mode
will resut in proper matches being found even if the text was not
segmented. For instance, assume that the original query is BC DEF. After
wrapping in quotes on the application side, it should look like "BC" "DEF"
(with quotes). This query will be passed to Sphinx and internally split
into 1-grams too, resulting in "B C" "D E F" query, still with quotes that
are the phrase matching operator. And it will match the text even though
there were no separators in the text.

Even if the search query is not segmented, Sphinx should still produce good
results, thanks to phrase based ranking: it will pull closer phrase matches
(which in case of N-gram CJK words can mean closer multi-character word
matches) to the top.

Example:

   | ngram_len = 1

8.2.20. ngram_chars
-------------------

N-gram characters list. Optional, default is empty.

To be used in conjunction with in ngram_len, this list defines characters,
sequences of which are subject to N-gram extraction. Words comprised of
other characters will not be affected by N-gram indexing feature. The value
format is identical to charset_table.

Example:

   | ngram_chars = U+3000..U+2FA1F

8.2.21. phrase_boundary
-----------------------

Phrase boundary characters list. Optional, default is empty.

This list controls what characters will be treated as phrase boundaries, in
order to adjust word positions and enable phrase-level search emulation
through proximity search. The syntax is similar to charset_table. Mappings
are not allowed and the boundary characters must not overlap with anything
else.

On phrase boundary, additional word position increment (specified by
phrase_boundary_step) will be added to current word position. This enables
phrase-level searching through proximity queries: words in different
phrases will be guaranteed to be more than phrase_boundary_step distance
away from each other; so proximity search within that distance will be
equivalent to phrase-level search.

Phrase boundary condition will be raised if and only if such character is
followed by a separator; this is to avoid abbreviations such as
S.T.A.L.K.E.R or URLs being treated as several phrases.

Example:

   | phrase_boundary = ., ?, !, U+2026 # horizontal ellipsis

8.2.22. phrase_boundary_step
----------------------------

Phrase boundary word position increment. Optional, default is 0.

On phrase boundary, current word position will be additionally incremented
by this number. See phrase_boundary for details.

Example:

   | phrase_boundary_step = 100

8.2.23. html_strip
------------------

Whether to strip HTML markup from incoming full-text data. Optional,
default is 0. Known values are 0 (disable stripping) and 1 (enable
stripping).

Stripping does not work with xmlpipe source type (it's suggested to upgrade
to xmlpipe2 anyway). It should work with properly formed HTML and XHTML,
but, just as most browsers, may produce unexpected results on malformed
input (such as HTML with stray <'s or unclosed >'s).

Only the tags themselves, and also HTML comments, are stripped. To strip
the contents of the tags too (eg. to strip embedded scripts), see
html_remove_elements option. There are no restrictions on tag names; ie.
everything that looks like a valid tag start, or end, or a comment will be
stripped.

Example:

   | html_strip = 1

8.2.24. html_index_attrs
------------------------

A list of markup attributes to index when stripping HTML. Optional, default
is emptu (do not index markup attributes).

Specifies HTML markup attributes whose contents should be retained and
indexed even though other HTML markup is stripped. The format is per-tag
enumeration of indexable attributes, as shown in the example below.

Example:

   | html_index_attrs = img=alt,title; a=title;

8.2.25. html_remove_elements
----------------------------

A list of HTML elements for which to strip contents along with the elements
themselves. Optional, default is empty string (do not strip contents of any
elements).

This feature allows to strip element contents, ie. everything that is
between the opening and the closing tags. It is useful to remove embedded
scripts, CSS, etc. Short tag form for empty elements (ie. <br />) is
properly supported; ie. the text that follows such tag will not be removed.

The value is a comma-separated list of element (tag) names whose contents
should be removed. Tag names are case insensitive.

Example:

   | html_remove_elements = style, script

8.2.26. local
-------------

Local index declaration in the distributed index. Multi-value, optional,
default is empty.

This setting is used to declare local indexes that will be searched when
given distributed index is searched. All local indexes will be searched
sequentially, utilizing only 1 CPU or core; to parallelize processing, you
can configure searchd to query itself (refer to Section 8.2.27, <<agent>>
for the details). There might be several local indexes declared per each
distributed index. Any local index can be mentioned several times in other
distributed indexes.

Example:

   | local = chunk1
   | local = chunk2

8.2.27. agent
-------------

Remote agents and indexes declaration in the distributed index.
Multi-value, optional, default is empty.

This setting is used to declare remote agents that will be searched when
given distributed index is searched. The agents can be thought of as
network pointers that specify host, port, and index names. In the basic
case agents would correspond to remote physical machines. More formally,
that is not always correct: you can point several agents to the same remote
machine; or you can even point agents to the very same single instance of
searchd (in order to utilize many CPUs or cores).

The value format is as follows:

   | agent = hostname:port:remote-indexes-list

where 'hostname' is remote host name; 'port' is remote TCP port; and
'remote-indexes-list' is a comma-separated list of remote index names.

All agents will be searched in parallel. However, all indexes specified for
a given agent will be searched sequentially in this agent. This lets you
fine-tune the configuration to the hardware. For instance, if two remote
indexes are stored on the same physical HDD, it's better to configure one
agent with several sequentially searched indexes to avoid HDD steping. If
they are stored on different HDDs, having two agents will be advantageous,
because the work will be fully parallelized. The same applies to CPUs;
though CPU performance impact caused by two processes stepping on each
other is somewhat smaller and frequently can be ignored at all.

On machines with many CPUs and/or HDDs, agents can be pointed to the same
machine to utilize all of the hardware in parallel and reduce query
latency. There is no need to setup several searchd instances for that; it's
legal to configure the instance to contact itself. Here's an example setup,
intended for a 4-CPU machine, that will use up to 4 CPUs in parallel to
process each query:

   | index dist
   | {
   | 	type = distributed
   | 	local = chunk1
   | 	agent = localhost:3312:chunk2
   | 	agent = localhost:3312:chunk3
   | 	agent = localhost:3312:chunk4
   | }

Note how one of the chunks is searched locally and the same instance of
searchd queries itself to launch searches through three other ones in
parallel.

Example:

   | agent = localhost:3312:chunk2 # contact itself
   | agent = searchbox2:3312:chunk3,chunk4 # search remote indexes

8.2.28. agent_connect_timeout
-----------------------------

Remote agent connection timeout, in milliseconds. Optional, default is 1000
(ie. 1 second).

When connecting to remote agents, searchd will wait at most this much time
for connect() call to complete succesfully. If the timeout is reached but
connect() does not complete, and retries are enabled, retry will be
initiated.

Example:

   | agent_connect_timeout = 300

8.2.29. agent_query_timeout
---------------------------

Remote agent query timeout, in milliseconds. Optional, default is 3000 (ie.
3 seconds).

After connection, searchd will wait at most this much time for remote
queries to complete. This timeout is fully separate from connection
timeout; so the maximum possible delay caused by a remote agent equals to
the sum of agent_connection_timeout and agent_query_timeout. Queries will
not be retried if this timeout is reached; a warning will be produced
instead.

Example:

   | agent_query_timeout = 10000 # our query can be long, allow up to 10 sec

8.2.30. preopen
---------------

Whether to pre-open all index files, or open them per each query. Optional,
default is 0 (do not preopen).

This option tells searchd that it should pre-open all index files on
startup (or rotation) and keep them open while it runs. Currently, the
default mode is not to pre-open the files (this may change in the future).
Preopened indexes take a few (currently 2) file descriptors per index.
However, they save on per-query open() calls; and also they are
invulnerable to subtle race conditions that may happen during index
rotation under high load. On the other hand, when serving many indexes
(100s to 1000s), it still might be desired to open the on per-query basis
in order to save file descriptors.

Example:

   | preopen = 1

8.3. indexer program configuration options
------------------------------------------

8.3.1. mem_limit
----------------

Indexing RAM usage limit. Optional, default is 32M.

Enforced memory usage limit that the indexer will not go above. Can be
specified in bytes, or kilobytes (using K postfix), or megabytes (using
M postfix); see the example. This limit will be automatically raised if set
to extremely low value causing I/O buffers to be less than 8 KB; the exact
lower bound for that depends on the indexed data size. If the buffers are
less than 256 KB, a warning will be produced.

Maximum possible limit is 2047M. Too low values can hurt indexing speed,
but 256M to 1024M should be enough for most if not all datasets. Setting
this value too high can cause SQL server timeouts. During the document
collection phase, there will be periods when the memory buffer is partially
sorted and no communication with the database is performed; and the
database server can timeout. You can resolve that either by raising
timeouts on SQL server side or by lowering mem_limit.

Example:

   | mem_limit = 256M
   | # mem_limit = 262144K # same, but in KB
   | # mem_limit = 268435456 # same, but in bytes

8.3.2. max_iops
---------------

Maximum I/O operations per second, for I/O throttling. Optional, default is
0 (unlimited).

I/O throttling related option. It limits maximum count of I/O operations
(reads or writes) per any given second. A value of 0 means that no limit is
imposed.

indexer can cause bursts of intensive disk I/O during indexing, and it
might desired to limit its disk activity (and keep something for other
programs running on the same machine, such as searchd). I/O throttling
helps to do that. It works by enforcing a minimum guaranteed delay between
subsequent disk I/O operations performed by indexer. Modern SATA HDDs are
able to perform up to 70-100+ I/O operations per second (that's mostly
limited by disk heads seek time). Limiting indexing I/O to a fraction of
that can help reduce search performance dedgradation caused by indexing.

Example:

   | max_iops = 40

8.3.3. max_iosize
-----------------

Maximum allowed I/O operation size, in bytes, for I/O throttling. Optional,
default is 0 (unlimited).

I/O throttling related option. It limits maximum file I/O operation (read
or write) size for all operations performed by indexer. A value of 0 means
that no limit is imposed. Reads or writes that are bigger than the limit
will be split in several smaller operations, and counted as several
operation by max_iops setting. At the time of this writing, all I/O calls
should be under 256 KB (default internal buffer size) anyway, so max_iosize
values higher than 256 KB must not affect anything.

Example:

   | max_iosize = 1048576

8.4. searchd program configuration options
------------------------------------------

8.4.1. address
--------------

Interface IP address to bind on. Optional, default is 0.0.0.0 (ie. listen
on all interfaces).

address setting lets you specify which network interface searchd will bind
to, listen on, and accept incoming network connections on. The default
value is 0.0.0.0 which means to listen on all interfaces. At the time, you
can not specify multiple interfaces.

Example:

   | address = 192.168.0.1

8.4.2. port
-----------

searchd TCP port number. Mandatory, default is 3312.

Example:

   | port = 3312

8.4.3. log
----------

Log file name. Optional, default is 'searchd.log'. All searchd run time
events will be logged in this file.

Example:

   | log = /var/log/searchd.log

8.4.4. query_log
----------------

Query log file name. Optional, default is empty (do not log queries). All
search queries will be logged in this file. The format is described in
Section 4.8, <<searchd query log format>>.

Example:

   | query_log = /var/log/query.log

8.4.5. read_timeout
-------------------

Network client request read timeout, in seconds. Optional, default is
5 seconds. searchd will forcibly close the client connections which fail to
send a query within this timeout.

Example:

   | read_timeout = 1

8.4.6. max_children
-------------------

Maximum amount of children to fork (or in other words, concurrent searches
to run in parallel). Optional, default is 0 (unlimited).

Useful to control server load. There will be no more than this much
concurrent searches running, at all times. When the limit is reached,
additional incoming clients are dismissed with temporarily failure
(SEARCHD_RETRY) status code and a message stating that the server is maxed
out.

Example:

   | max_children = 10

8.4.7. pid_file
---------------

searchd process ID file name. Mandatory.

PID file will be re-created (and locked) on startup. It will contain head
daemon process ID while the daemon is running, and it will be unlinked on
daemon shutdown. It's mandatory because Sphinx uses it internally for
a number of things: to check whether there already is a running instance of
searchd; to stop searchd; to notify it that it should rotate the indexes.
Can also be used for different external automation scripts.

Example:

   | pid_file = /var/run/searchd.pid

8.4.8. max_matches
------------------

Maximum amount of matches that the daemon keeps in RAM for each index and
can return to the client. Optional, default is 1000.

Introduced in order to control and limit RAM usage, max_matches setting
defines how much matches will be kept in RAM while searching each index.
Every match found will still be processed; but only best N of them will be
kept in memory and return to the client in the end. Assume that the index
contains 2,000,000 matches for the query. You rarely (if ever) need to
retrieve all of them. Rather, you need to scan all of them, but only choose
"best" at most, say, 500 by some criteria (ie. sorted by relevance, or
price, or anything else), and display those 500 matches to the end user in
pages of 20 to 100 matches. And tracking only the best 500 matches is much
more RAM and CPU efficient than keeping all 2,000,000 matches, sorting
them, and then discarding everything but the first 20 needed to display the
search results page. max_matches controls N in that "best N" amount.

This parameter noticeably affects per-query RAM and CPU usage. Values of
1,000 to 10,000 are generally fine, but higher limits must be used with
care. Recklessly raising max_matches to 1,000,000 means that searchd will
have to allocate and initialize 1-million-entry matches buffer for every
query. That will obviously increase per-query RAM usage, and in some cases
can also noticeably impact performance.

CAVEAT EMPTOR! Note that there also is another place where this limit is
enforced. max_matches can be decreased on the fly through the corresponding
API call, and the default value in the API is also set to 1,000. So in
order to retrieve more than 1,000 matches to your application, you will
have to change the configuration file, restart searchd, and set proper
limit in SetLimits() call. Also note that you can not set the value in the
API higher than the value in the .conf file. This is prohibited in order to
have some protection against malicious and/or malformed requests.

Example:

   | max_matches = 10000

8.4.9. seamless_rotate
----------------------

Prevents searchd stalls while rotating indexes with huge amounts of data to
precache. Optional, default is 1 (enable seamless rotation).

Indexes may contain some data that needs to be precached in RAM. At the
moment, .spa, .spi and .spm files are fully precached (they contain
attribute data, MVA data, and keyword index, respectively.) Without
seamless rotate, rotating an index tries to use as little RAM as possible
and works as follows:

   1. new queries are temporarly rejected (with "retry" error code);
   2. searchd waits for all currently running queries to finish;
   3. old index is deallocated and its files are renamed;
   4. new index files are renamed and required RAM is allocated;
   5. new index attribute and dictionary data is preloaded to RAM;
   6. searchd resumes serving queries from new index.

However, if there's a lot of attribute or dictionary data, then preloading
step could take noticeble time - up to several minutes in case of
preloading 1-5+ GB files.

With seamless rotate enabled, rotation works as follows:

   1. new index RAM storage is allocated;
   2. new index attribute and dictionary data is asynchronously preloaded
      to RAM;
   3. on success, old index is deallocated and both indexes' files are
      renamed;
   4. on failure, new index is deallocated;
   5. at any given moment, queries are served either from old or new index
      copy.

Seamless rotate comes at the cost of higher peak memory usage during the
rotation (because both old and new copies of .spa/.spi/.spm data need to be
in RAM while preloading new copy). Average usage stays the same.

Example:

   | seamless_rotate = 1

8.4.10. preopen_indexes
-----------------------

Whether to forcibly preopen all indexes on startup. Optional, default is
0 (do not preopen). Enforces enabled preopen on all served indexes, to
avoid manually specifying it in every index.

Example:

   | preopen_indexes = 1

8.4.11. unlink_old
------------------

Whether to unlink .old index copies on succesful rotation. Optional,
default is 1 (do unlink).

Example:

   | unlink_old = 0

A. Sphinx revision history
==========================

A.1. Version 0.9.8.1, 30 oct 2008
---------------------------------

   * added configure script to libsphinxclient
   * changed proximity/quorum operator syntax to require whitespace after
     length
   * fixed potential head process crash on SIGPIPE during "maxed out"
     message
   * fixed handling of incomplete remote replies (caused over-degraded
     distributed results, in rare cases)
   * fixed sending of big remote requests (caused distributed requests to
     fail, in rare cases)
   * fixed FD_SET() overflow (caused searchd to crash on startup, in rare
     cases)
   * fixed MVA vs distributed indexes (caused loss of 1st MVA value in
     result set)
   * fixed tokenizing of exceptions terminated by specials (eg. "GPS AT&T"
     in extended mode)
   * fixed buffer overrun in stemmer on overlong tokens occasionally
     emitted by proximity/quorum operator parser (caused crashes on certain
     proximity/quorum queries)
   * fixed wordcount ranker (could be dropping hits)
   * fixed --merge feature (numerous different fixes, caused broken
     indexes)
   * fixed --merge-dst-range performance
   * fixed prefix/infix generation for stopwords
   * fixed ignore_chars vs specials
   * fixed misplaced F_SETLKW check (caused certain build types, eg. RPM
     build on FC8, to fail)
   * fixed dictionary-defined charsets support in spelldump, added \x-style
     wordchars support
   * fixed Java API to properly send long strings (over 64K; eg. long
     document bodies for excerpts)
   * fixed Python API to accept offset/limit of 'long' type
   * fixed default ID range (that filtered out all 64-bit values) in Java
     and Python APIs

A.2. Version 0.9.8, 14 jul 2008
-------------------------------

Indexing
--------

   * added support for 64-bit document and keyword IDs, --enable-id64
     switch to configure
   * added support for floating point attributes
   * added support for bitfields in attributes, sql_attr_bool directive and
     bit-widths part in sql_attr_uint directive
   * added support for multi-valued attributes (MVA)
   * added metaphone preprocessor
   * added libstemmer library support, provides stemmers for a number of
     additional languages
   * added xmlpipe2 source type, that supports arbitrary fields and
     attributes
   * added word form dictionaries, wordforms directive (and spelldump
     utility)
   * added tokenizing exceptions, exceptions directive
   * added an option to fully remove element contents to HTML stripper,
     html_remove_elements directive
   * added HTML entities decoder (with full XHTML1 set support) to HTML
     stripper
   * added per-index HTML stripping settings, html_strip, html_index_attrs,
     and html_remove_elements directives
   * added IO load throttling, max_iops and max_iosize directives
   * added SQL load throttling, sql_ranged_throttle directive
   * added an option to index prefixes/infixes for given fields only,
     prefix_fields and infix_fields directives
   * added an option to ignore certain characters (instead of just treating
     them as whitespace), ignore_chars directive
   * added an option to increment word position on phrase boundary
     characters, phrase_boundary and phrase_boundary_step directives
   * added --merge-dst-range switch (and filters) to index merging feature
     (--merge switch)
   * added mysql_connect_flags directive (eg. to reduce indexing time MySQL
     network traffic and/or time)
   * improved ordinals sorting; now runs in fixed RAM
   * improved handling of documents with zero/NULL ids, now skipping them
     instead of aborting

Search daemon
-------------

   * added an option to unlink old index on succesful rotation, unlink_old
     directive
   * added an option to keep index files open at all times (fixes subtle
     races on rotation), preopen and preopen_indexes directives
   * added an option to profile searchd disk I/O, --iostats command-line
     option
   * added an option to rotate index seamlessly (fully avoids query
     stalls), seamless_rotate directive
   * added HTML stripping support to excerpts (uses per-index settings)
   * added 'exact_phrase', 'single_passage', 'use_boundaries',
     'weight_order 'options to BuildExcerpts() API call
   * added distributed attribute updates propagation
   * added distributed retries on master node side
   * added log reopen on SIGUSR1
   * added --stop switch (sends SIGTERM to running instance)
   * added Windows service mode, and --servicename switch
   * added Windows --rotate support
   * improved log timestamping, now with millisecond precision

Querying
--------

   * added extended engine V2 (faster, cleaner, better; SPH_MATCH_EXTENDED2
     mode)
   * added ranking modes support (V2 engine only; SetRankingMode() API
     call)
   * added quorum searching support to query language (V2 engine only;
     example: "any three of all these words"/3)
   * added query escaping support to query language, and EscapeString() API
     call
   * added multi-field syntax support to query language (example:
     "@(field1,field2) something"), and @@relaxed field checks option
   * added optional star-syntax ('word*') support in keywords, enable_star
     directive (for prefix/infix indexes only)
   * added full-scan support (query must be fully empty; can perform
     block-reject optimization)
   * added COUNT(DISTINCT(attr)) calculation support, SetGroupDistinct()
     API call
   * added group-by on MVA support, SetArrayResult() PHP API call
   * added per-index weights feature, SetIndexWeights() API call
   * added geodistance support, SetGeoAnchor() API call
   * added result set sorting by arbitrary expressions in run time (eg.
     "@weight+log(price)*2.5"), SPH_SORT_EXPR mode
   * added result set sorting by @custom compile-time sorting function (see
     src/sphinxcustomsort.inl)
   * added result set sorting by @random value
   * added result set merging for indexes with different schemas
   * added query comments support (3rd arg to Query()/AddQuery() API calls,
     copied verbatim to query log)
   * added keyword extraction support, BuildKeywords() API call
   * added binding field weights by name, SetFieldWeights() API call
   * added optional limit on query time, SetMaxQueryTime() API call
   * added optional limit on found matches count (4rd arg to SetLimits()
     API call, so-called 'cutoff')

APIs and SphinxSE
-----------------

   * added pure C API (libsphinxclient)
   * added Ruby API (thanks to Dmytro Shteflyuk)
   * added Java API
   * added SphinxSE support for MVAs (use varchar), floats (use float),
     64bit docids (use bigint)
   * added SphinxSE options "floatrange", "geoanchor", "fieldweights",
     "indexweights", "maxquerytime", "comment", "host" and "port"; and
     support for "expr:CLAUSE"
   * improved SphinxSE max query size (using MySQL condition pushdown),
     upto 256K now

General
-------

   * added scripting (shebang syntax) support to config files (example:
     #!/usr/bin/php in the first line)
   * added unified config handling and validation to all programs
   * added unified documentation
   * added .spec file for RPM builds
   * added automated testing suite
   * improved index locking, now fcntl()-based instead of buggy
     file-existence-based
   * fixed unaligned RAM accesses, now works on SPARC and ARM

Changes and fixes since 0.9.8-RC2
---------------------------------

   * added pure C API (libsphinxclient)
   * added Ruby API
   * added SetConnectTimeout() PHP API call
   * added allowed type check to UpdateAttributes() handler (issue #174)
   * added defensive MVA checks on index preload (protection against broken
     indexes, issue #168)
   * added sphinx-min.conf sample file
   * added --without-iconv switch to configure
   * removed redundant -lz dependency in searchd
   * removed erroneous "xmlpipe2 deprecated" warning
   * fixed EINTR handling in piped read (issue #166)
   * fixup query time before logging and sending to client (issue #153)
   * fixed attribute updates vs full-scan early-reject index (issue #149)
   * fixed gcc warnings (issue #160)
   * fixed mysql connection attempt vs pgsql source type (issue #165)
   * fixed 32-bit wraparound when preloading over 2 GB files
   * fixed "out of memory" message vs over 2 GB allocs (issue #116)
   * fixed unaligned RAM access detection on ARM (where unaligned reads do
     not crash but produce wrong results)
   * fixed missing full scan results in some cases
   * fixed several bugs in --merge, --merge-dst-range
   * fixed @geodist vs MultiQuery and filters, @expr vs MultiQuery
   * fixed GetTokenEnd() vs 1-grams (was causing crash in excerpts)
   * fixed sql_query_range to handle empty strings in addition to NULL
     strings (Postgres specific)
   * fixed morphology=none vs infixes
   * fixed case sensitive attributes names in UpdateAttributes()
   * fixed ext2 ranking vs. stopwords (now using atompos from query parser)
   * fixed EscapeString() call
   * fixed escaped specials (now handled as whitespace if not in charset)
   * fixed schema minimizer (now handles type/size mismatches)
   * fixed word stats in extended2; stemmed form is now returned
   * fixed spelldump case folding vs dictionary-defined character sets
   * fixed Postgres BOOLEAN handling
   * fixed enforced "inline" docinfo on empty indexes (normally ok, but
     index merge was really confused)
   * fixed rare count(distinct) out-of-bounds issue (it occasionaly caused
     too high @distinct values)
   * fixed hangups on documents with id=DOCID_MAX in some cases
   * fixed rare crash in tokenizer (prefixed synonym vs. input stream eof)
   * fixed query parser vs "aaa (bbb ccc)|ddd" queries
   * fixed BuildExcerpts() request in Java API
   * fixed Postgres specific memory leak
   * fixed handling of overshort keywords (less than min_word_len)
   * fixed HTML stripper (now emits space after indexed attributes)
   * fixed 32-field case in query parser
   * fixed rare count(distinct) vs. querying multiple local indexes vs.
     reusable sorter issue
   * fixed sorting of negative floats in SPH_SORT_EXTENDED mode

A.3. Version 0.9.7, 02 apr 2007
-------------------------------

   * added support for sql_str2ordinal_column
   * added support for upto 5 sort-by attrs (in extended sorting mode)
   * added support for separate groups sorting clause (in group-by mode)
   * added support for on-the-fly attribute updates (PRE-ALPHA; will change
     heavily; use for preliminary testing ONLY)
   * added support for zero/NULL attributes
   * added support for 0.9.7 features to SphinxSE
   * added support for n-grams (alpha, 1-grams only for now)
   * added support for warnings reported to client
   * added support for exclude-filters
   * added support for prefix and infix indexing (see max_prefix_len,
     max_infix_len)
   * added @* syntax to reset current field to query language
   * added removal of duplicate entries in query index order
   * added PHP API workarounds for PHP signed/unsigned braindamage
   * added locks to avoid two concurrent indexers working on same index
   * added check for existing attributes vs. docinfo=none case
   * improved groupby code a lot (better precision, and upto 25x times
     faster in extreme cases)
   * improved error handling and reporting
   * improved handling of broken indexes (reports error instead of
     hanging/crashing)
   * improved mmap() limits for attributes and wordlists (now able to map
     over 4 GB on x64 and over 2 GB on x32 where possible)
   * improved malloc() pressure in head daemon (search time should not
     degrade with time any more)
   * improved test.php command line options
   * improved error reporting (distributed query, broken index etc issues
     now reported to client)
   * changed default network packet size to be 8M, added extra checks
   * fixed division by zero in BM25 on 1-document collections (in extended
     matching mode)
   * fixed .spl files getting unlinked
   * fixed crash in schema compatibility test
   * fixed UTF-8 Russian stemmer
   * fixed requested matches count when querying distributed agents
   * fixed signed vs. unsigned issues everywhere (ranged queries, CLI
     search output, and obtaining docid)
   * fixed potential crashes vs. negative query offsets
   * fixed 0-match docs vs. extended mode vs. stats
   * fixed group/timestamp filters being ignored if querying from older
     clients
   * fixed docs to mention pgsql source type
   * fixed issues with explicit '&' in extended matching mode
   * fixed wrong assertion in SBCS encoder
   * fixed crashes with no-attribute indexes after rotate

A.4. Version 0.9.7-RC2, 15 dec 2006
-----------------------------------

   * added support for extended matching mode (query language)
   * added support for extended sorting mode (sorting clauses)
   * added support for SBCS excerpts
   * added mmap()ing for attributes and wordlist (improves search time,
     speeds up fork() greatly)
   * fixed attribute name handling to be case insensitive
   * fixed default compiler options to simplify post-mortem debugging
     (added -g, removed -fomit-frame-pointer)
   * fixed rare memory leak
   * fixed "hello hello" queries in "match phrase" mode
   * fixed issue with excerpts, texts and overlong queries
   * fixed logging multiple index name (no longer tokenized)
   * fixed trailing stopword not flushed from tokenizer
   * fixed boolean evaluation
   * fixed pidfile being wrongly unlink()ed on bind() failure
   * fixed --with-mysql-includes/libs (they conflicted with well-known
     paths)
   * fixes for 64-bit platforms

A.5. Version 0.9.7-RC1, 26 oct 2006
-----------------------------------

   * added alpha index merging code
   * added an option to decrease max_matches per-query
   * added an option to specify IP address for searchd to listen on
   * added support for unlimited amount of configured sources and indexes
   * added support for group-by queries
   * added support for /2 range modifier in charset_table
   * added support for arbitrary amount of document attributes
   * added logging filter count and index name
   * added --with-debug option to configure to compile in debug mode
   * added -DNDEBUG when compiling in default mode
   * improved search time (added doclist size hints, in-memory wordlist
     cache, and used VLB coding everywhere)
   * improved (refactored) SQL driver code (adding new drivers should be
     very easy now)
   * improved exceprts generation
   * fixed issue with empty sources and ranged queries
   * fixed querying purely remote distributed indexes
   * fixed suffix length check in English stemmer in some cases
   * fixed UTF-8 decoder for codes over U+20000 (for CJK)
   * fixed UTF-8 encoder for 3-byte sequences (for CJK)
   * fixed overshort (less than min_word_len) words prepended to next field
   * fixed source connection order (indexer does not connect to all sources
     at once now)
   * fixed line numbering in config parser
   * fixed some issues with index rotation

A.6. Version 0.9.6, 24 jul 2006
-------------------------------

   * added support for empty indexes
   * added support for multiple sql_query_pre/post/post_index
   * fixed timestamp ranges filter in "match any" mode
   * fixed configure issues with --without-mysql and --with-pgsql options
   * fixed building on Solaris 9

A.7. Version 0.9.6-RC1, 26 jun 2006
-----------------------------------

   * added boolean queries support (experimental, beta version)
   * added simple file-based query cache (experimental, beta version)
   * added storage engine for MySQL 5.0 and 5.1 (experimental, beta
     version)
   * added GNU style configure script
   * added new searchd protocol (all binary, and should be backwards
     compatible)
   * added distributed searching support to searchd
   * added PostgreSQL driver
   * added excerpts generation
   * added min_word_len option to index
   * added max_matches option to searchd, removed hardcoded MAX_MATCHES
     limit
   * added initial documentation, and a working example.sql
   * added support for multiple sources per index
   * added soundex support
   * added group ID ranges support
   * added --stdin command-line option to search utility
   * added --noprogress option to indexer
   * added --index option to search
   * fixed UTF-8 decoder (3-byte codepoints did not work)
   * fixed PHP API to handle big result sets faster
   * fixed config parser to handle empty values properly
   * fixed redundant time(NULL) calls in time-segments mode

--eof--
