DragonFly On-Line Manual Pages
SEARCH(1) Sphinxsearch SEARCH(1)
NAME
search - Sphinxsearch command-line index query
SYNOPSIS
search [OPTIONS] word1 [word2 [word3 [...]] ]
DESCRIPTION
Sphinx is a collection of programs that aim to provide high quality
fulltext search.
search is one of the helper tools within the Sphinx package. Whereas
searchd is responsible for searches in a server-type environment,
search is aimed at testing the index from the command line, and testing
the index quickly without building a framework to make the connection
to the server and process its response.
Note: search is not intended to be deployed as part of a client
application; it is strongly recommended you do not write an interface
to search instead of searchd, and none of the bundled client APIs
support this method. (In any event, search will reload files each time,
whereas searchd will cache them in memory for performance.)
That said, many types of query that you could build in the APIs could
also be made with search, however for very complex searches it may be
easier to construct them using a small script and the corresponding
API. Additionally, some newer features may be available in the searchd
system that have not yet been brought into search.
When calling search, it is not necessary to have searchd running;
simply make sure that the account running the search program has read
access to the configuration file and the index files.
The default behaviour is to apply a search for word1 (AND word2 AND
word3... as specified) to all fields in all indexes as given in the
configuration file. If constructing the equivalent in the API, this
would be the equivalent to passing SPH_MATCH_ALL to SetMatchMode, and
specifying * as the indexes to query as part of Query.
OPTIONS
There are many options available to search.
Firstly, the general options:
--config CONFIGFILE, -c CONFIGFILE
Use the given file as its configuration, just as with indexer.
--index INDEX, -i INDEX
Limit searching to the specified index only; normally search would
attempt to search all of the physical indexes listed in
sphinx.conf, not any distributed ones.
--stdin
Accept the query from the standard input, rather than the command
line. This can be useful for testing purposes whereby you could
feed input via pipes and from scripts
Options for setting matches:
--any, -a
Changes the matching mode to match any of the words as part of the
query (word1 OR word2 OR word3). In the API this would be
equivalent to passing SPH_MATCH_ANY to SetMatchMode.
--phrase, -p
Changes the matching mode to match all of the words as part of the
query, and do so in the phrase given (not including punctuation).
In the API this would be equivalent to passing SPH_MATCH_PHRASE to
SetMatchMode.
--boolean, -b
Changes the matching mode to Boolean matching. Note if using
Boolean syntax matching on the command line, you may need to escape
the symbols (with a backslash) to avoid the shell/command line
processor applying them, such as ampersands being escaped on a
Unix/Linux system to avoid it forking to the search process,
although this can be resolved by using --stdin, as below. In the
API this would be equivalent to passing SPH_MATCH_BOOLEAN to
SetMatchMode.
--ext, -e
Changes the matching mode to Extended matching. In the API this
would be equivalent to passing SPH_MATCH_EXTENDED to SetMatchMode,
and it should be noted that use of this mode is being discouraged
in favour of Extended2, below.
--ext2, -e2
Changes the matching mode to Extended matching, version 2. In the
API this would be equivalent to passing SPH_MATCH_EXTENDED2 to
SetMatchMode, and it should be noted that use of this mode is being
recommended in favour of Extended, due to being more efficient and
providing other features.
--filter <attr><v>, -f <attr><v>
Filters the results such that only documents where the attribute
given (attr) matches the value given (v). For example, --filter
deleted 0 only matches documents with an attribute called 'deleted'
where its value is 0. You can also add multiple filters on the
command line, by specifying multiple --filter multiple times,
however if you apply a second filter to an attribute it will
override the first defined filter.
Options for handling the results:
--limit <count>, -l <count>
limits the total number of matches back to the number given. If a
'group' is specified, this will be the number of grouped results.
This defaults to 20 results if not specified (as do the APIs)
--offset <count>, -o <count>
offsets the result list by the number of places set by the count;
this would be used for pagination through results, where if you
have 20 results per 'page', the second page would begin at offset
20, the third page at offset 40, etc.
--group <attr>, -g <attr>
specifies that results should be grouped together based on the
attribute specified. Like the GROUP BY clause in SQL, it will
combine all results where the attribute given matches, and returns
a set of results where each returned result is the best from each
group. Unless otherwise specified, this will be the best match on
relevance.
--groupsort <expr>, -gs <expr>
instructs that when results are grouped with --group, the
expression given in <expr> shall determine the order of the groups.
Note, this does not specify which is the best item within the
group, only the order in which the groups themselves shall be
returned.
--sortby <clause>, -s <clause>
specifies that results should be sorted in the order listed in
<clause>. This allows you to specify the order you wish results to
be presented in, ordering by different columns. For example, you
could say --sortby "@weight DESC entrytime DESC" to sort entries
first by weight (or relevance) and where two or more entries have
the same weight, to then sort by the time with the highest time
(newest) first. You will usually need to put the items in quotes
(--sortby "@weight DESC") or use commas (--sortby @weight,DESC) to
avoid the items being treated separately. Additionally, like the
regular sorting modes, if --group (grouping) is being used, this
will state how to establish the best match within each group.
--sortexpr <expr>, -S <expr>
specifies that the search results should be presented in an order
determined by an arithmetic expression, stated in expr. For
example: --sortexpr "@weight + ( user_karma + ln(pageviews) )*0.1"
(again noting that this will have to be quoted to avoid the shell
dealing with the asterisk). Extended sort mode is discussed in more
detail under the SPH_SORT_EXTENDED entry under the Sorting modes
section of the manual.
--sort=date
specifies that the results should be sorted by descending (i.e.
most recent first) date. This requires that there is an attribute
in the index that is set as a timestamp.
--rsort=date
specifies that the results should be sorted by ascending (i.e.
oldest first) date. This requires that there is an attribute in the
index that is set as a timestamp.
--sort=ts
specifies that the results should be sorted by timestamp in groups;
it will return all of the documents whose timestamp is within the
last hour, then sorted within that bracket for relevance. After, it
would return the documents from the last day, sorted by relevance,
then the last week and then the last month. It is discussed in more
detail under the SPH_SORT_TIME_SEGMENTS entry under the Sorting
modes section of the manual.
Other options:
--noinfo, -q
instructs search not to look-up data in your SQL database.
Specifically, for debugging with MySQL and search, you can provide
it with a query to look up the full article based on the returned
document ID. It is explained in more detail under the
sql_query_info directive.
AUTHOR
Andrey Aksenoff (shodan@sphinxsearch.com). This manual page is written
by Alexey Vinogradov (klirichek@sphinxsearch.com). Permission is
granted to copy, distribute and/or modify this document under the terms
of the GNU General Public License, Version 2 any later version
published by the Free Software Foundation.
On Debian systems, the complete text of the GNU General Public License
can be found in /usr/share/common-licenses/GPL.
SEE ALSO
indexer(1), searchd(1), indextool(1)
Sphinx and it's programs are documented fully by the Sphinx reference
manual available in /usr/share/doc/sphinxsearch.
2.2.1-beta 11/13/2013 SEARCH(1)