.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Sphinx::Search 3pm" .TH Sphinx::Search 3pm "2012-09-28" "perl v5.20.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Sphinx::Search \- Sphinx search engine API Perl client .SH "VERSION" .IX Header "VERSION" Please note that you *MUST* install a version which is compatible with your version of Sphinx. .PP Use version 0.28 for Sphinx\-2.0.3\-release (svn\-r3043) .PP Use version 0.26.1 for Sphinx\-2.0.1\-beta (svn\-r2792) .PP Use version 0.25_03 for Sphinx svn\-r2575 .PP Use version 0.24.1 for Sphinx\-1.10\-beta (svn\-r2420) .PP Use version 0.23_02 for Sphinx svn\-r2269 (experimental) .PP Use version 0.22 for Sphinx 0.9.9\-rc2 and later (Please read the Compatibility Note under SetEncoders regarding encoding changes) .PP Use version 0.15 for Sphinx 0.9.9\-svn\-r1674 .PP Use version 0.12 for Sphinx 0.9.8 .PP Use version 0.11 for Sphinx 0.9.8\-rc1 .PP Use version 0.10 for Sphinx 0.9.8\-svn\-r1112 .PP Use version 0.09 for Sphinx 0.9.8\-svn\-r985 .PP Use version 0.08 for Sphinx 0.9.8\-svn\-r871 .PP Use version 0.06 for Sphinx 0.9.8\-svn\-r820 .PP Use version 0.05 for Sphinx 0.9.8\-cvs\-20070907 .PP Use version 0.02 for Sphinx 0.9.8\-cvs\-20070818 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Sphinx::Search; \& \& $sph = Sphinx::Search\->new(); \& \& $results = $sph\->SetMatchMode(SPH_MATCH_ALL) \& \->SetSortMode(SPH_SORT_RELEVANCE) \& \->Query("search terms"); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is the Perl \s-1API\s0 client for the Sphinx open-source \s-1SQL\s0 full-text indexing search engine, . .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .SS "new" .IX Subsection "new" .Vb 2 \& $sph = Sphinx::Search\->new; \& $sph = Sphinx::Search\->new(\e%options); .Ve .PP Create a new Sphinx::Search instance. .PP \&\s-1OPTIONS\s0 .IP "log" 4 .IX Item "log" Specify an optional logger instance. This can be any class that provides error, warn, info, and debug methods (e.g. see Log::Log4perl). Logging is disabled if no logger instance is provided. .IP "debug" 4 .IX Item "debug" Debug flag. If set (and a logger instance is specified), debugging messages will be generated. .SH "METHODS" .IX Header "METHODS" .SS "GetLastError" .IX Subsection "GetLastError" .Vb 1 \& $error = $sph\->GetLastError; .Ve .PP Get last error message (string) .SS "GetLastWarning" .IX Subsection "GetLastWarning" .Vb 1 \& $warning = $sph\->GetLastWarning; .Ve .PP Get last warning message (string) .SS "IsConnectError" .IX Subsection "IsConnectError" Check connection error flag (to differentiate between network connection errors and bad responses). Returns true value on connection error. .SS "SetEncoders" .IX Subsection "SetEncoders" .Vb 1 \& $sph\->SetEncoders(\e&encode_function, \e&decode_function) .Ve .PP \&\s-1COMPATIBILITY NOTE:\s0 \fISetEncoders()\fR was introduced in version 0.17. Prior to that, all strings were considered to be sequences of bytes which may have led to issues with multi-byte characters. If you were previously encoding/decoding strings external to Sphinx::Search, you will need to disable encoding/decoding by setting Sphinx::Search to use raw values as explained below (or modify your code and let Sphinx::Search do the recoding). .PP Set the string encoder/decoder functions for transferring strings between perl and Sphinx. The encoder should take the perl internal representation and convert to the bytestream that searchd expects, and the decoder should take the bytestream returned by searchd and convert to perl format. .PP The searchd format will depend on the 'charset_type' index setting in the Sphinx configuration file. .PP The coders default to encode_utf8 and decode_utf8 respectively, which are compatible with the 'utf8' charset_type. .PP If either the encoder or decoder functions are left undefined in the call to SetEncoders, they return to their default values. .PP If you wish to send raw values (no encoding/decoding), supply a function that simply returns its argument, e.g. .PP .Vb 1 \& $sph\->SetEncoders( sub { shift }, sub { shift }); .Ve .PP Returns \f(CW$sph\fR. .SS "SetServer" .IX Subsection "SetServer" .Vb 2 \& $sph\->SetServer($host, $port); \& $sph\->SetServer($path, $port); .Ve .PP In the first form, sets the host (string) and port (integer) details for the searchd server using a network (\s-1INET\s0) socket (default is localhost:9312). .PP In the second form, where \f(CW$path\fR is a local filesystem path (optionally prefixed by 'unix://'), sets the client to access the searchd server via a local (\s-1UNIX\s0 domain) socket at the specified path. .PP Returns \f(CW$sph\fR. .SS "SetConnectTimeout" .IX Subsection "SetConnectTimeout" .Vb 1 \& $sph\->SetConnectTimeout($timeout) .Ve .PP Set server connection timeout (in seconds). .PP Returns \f(CW$sph\fR. .SS "SetConnectRetries" .IX Subsection "SetConnectRetries" .Vb 1 \& $sph\->SetConnectRetries($retries) .Ve .PP Set server connection retries (in case of connection fail). .PP Returns \f(CW$sph\fR. .SS "SetLimits" .IX Subsection "SetLimits" .Vb 2 \& $sph\->SetLimits($offset, $limit); \& $sph\->SetLimits($offset, $limit, $max); .Ve .PP Set match offset/limits, and optionally the max number of matches to return. .PP Returns \f(CW$sph\fR. .SS "SetMaxQueryTime" .IX Subsection "SetMaxQueryTime" .Vb 1 \& $sph\->SetMaxQueryTime($millisec); .Ve .PP Set maximum query time, in milliseconds, per index. .PP The value may not be negative; 0 means \*(L"do not limit\*(R". .PP Returns \f(CW$sph\fR. .SS "SetMatchMode" .IX Subsection "SetMatchMode" .Vb 1 \& $sph\->SetMatchMode($mode); .Ve .PP Set match mode, which may be one of: .IP "\(bu" 4 \&\s-1SPH_MATCH_ALL\s0 .Sp Match all words .IP "\(bu" 4 \&\s-1SPH_MATCH_ANY \s0 .Sp Match any words .IP "\(bu" 4 \&\s-1SPH_MATCH_PHRASE \s0 .Sp Exact phrase match .IP "\(bu" 4 \&\s-1SPH_MATCH_BOOLEAN \s0 .Sp Boolean match, using \s-1AND \s0(&), \s-1OR \s0(|), \s-1NOT \s0(!,\-) and parenthetic grouping. .IP "\(bu" 4 \&\s-1SPH_MATCH_EXTENDED \s0 .Sp Extended match, which includes the Boolean syntax plus field, phrase and proximity operators. .PP Returns \f(CW$sph\fR. .SS "SetRankingMode" .IX Subsection "SetRankingMode" .Vb 1 \& $sph\->SetRankingMode(SPH_RANK_BM25, $rank_exp); .Ve .PP Set ranking mode, which may be one of: .IP "\(bu" 4 \&\s-1SPH_RANK_PROXIMITY_BM25 \s0 .Sp Default mode, phrase proximity major factor and \s-1BM25\s0 minor one .IP "\(bu" 4 \&\s-1SPH_RANK_BM25 \s0 .Sp Statistical mode, \s-1BM25\s0 ranking only (faster but worse quality) .IP "\(bu" 4 \&\s-1SPH_RANK_NONE \s0 .Sp No ranking, all matches get a weight of 1 .IP "\(bu" 4 \&\s-1SPH_RANK_WORDCOUNT \s0 .Sp Simple word-count weighting, rank is a weighted sum of per-field keyword occurence counts .IP "\(bu" 4 \&\s-1SPH_RANK_MATCHANY\s0 .Sp Returns rank as it was computed in \s-1SPH_MATCH_ANY\s0 mode earlier, and is internally used to emulate \s-1SPH_MATCH_ANY\s0 queries. .IP "\(bu" 4 \&\s-1SPH_RANK_FIELDMASK\s0 .Sp Returns a 32\-bit mask with N\-th bit corresponding to N\-th fulltext field, numbering from 0. The bit will only be set when the respective field has any keyword occurences satisfiying the query. .IP "\(bu" 4 \&\s-1SPH_RANK_SPH04\s0 .Sp \&\s-1SPH_RANK_SPH04\s0 is generally based on the default \s-1SPH_RANK_PROXIMITY_BM25\s0 ranker, but additionally boosts the matches when they occur in the very beginning or the very end of a text field. .IP "\(bu" 4 \&\s-1SPH_RANK_EXPR\s0 .Sp Allows the ranking formula to be specified at run time. It exposes a number of internal text factors and lets you define how the final weight should be computed from those factors. \f(CW$rank_exp\fR should be set to the ranking expression string, e.g. to emulate \s-1SPH_RANK_PROXIMITY_BM25,\s0 use \*(L"sum(lcs*user_weight)*1000+bm25\*(R". .PP Returns \f(CW$sph\fR. .SS "SetSortMode" .IX Subsection "SetSortMode" .Vb 2 \& $sph\->SetSortMode(SPH_SORT_RELEVANCE); \& $sph\->SetSortMode($mode, $sortby); .Ve .PP Set sort mode, which may be any of: .IP "\s-1SPH_SORT_RELEVANCE \-\s0 sort by relevance" 4 .IX Item "SPH_SORT_RELEVANCE - sort by relevance" .PD 0 .IP "\s-1SPH_SORT_ATTR_DESC, SPH_SORT_ATTR_ASC\s0" 4 .IX Item "SPH_SORT_ATTR_DESC, SPH_SORT_ATTR_ASC" .PD Sort by attribute descending/ascending. \f(CW$sortby\fR specifies the sorting attribute. .IP "\s-1SPH_SORT_TIME_SEGMENTS\s0" 4 .IX Item "SPH_SORT_TIME_SEGMENTS" Sort by time segments (last hour/day/week/month) in descending order, and then by relevance in descending order. \f(CW$sortby\fR specifies the time attribute. .IP "\s-1SPH_SORT_EXTENDED\s0" 4 .IX Item "SPH_SORT_EXTENDED" Sort by SQL-like syntax. \f(CW$sortby\fR is the sorting specification. .IP "\s-1SPH_SORT_EXPR\s0" 4 .IX Item "SPH_SORT_EXPR" .PP Returns \f(CW$sph\fR. .SS "SetWeights" .IX Subsection "SetWeights" .Vb 1 \& $sph\->SetWeights([ 1, 2, 3, 4]); .Ve .PP This method is deprecated. Use SetFieldWeights instead. .PP Set per-field (integer) weights. The ordering of the weights correspond to the ordering of fields as indexed. .PP Returns \f(CW$sph\fR. .SS "SetFieldWeights" .IX Subsection "SetFieldWeights" .Vb 1 \& $sph\->SetFieldWeights(\e%weights); .Ve .PP Set per-field (integer) weights by field name. The weights hash provides field name to weight mappings. .PP Takes precedence over SetWeights. .PP Unknown names will be silently ignored. Missing fields will be given a weight of 1. .PP Returns \f(CW$sph\fR. .SS "SetIndexWeights" .IX Subsection "SetIndexWeights" .Vb 1 \& $sph\->SetIndexWeights(\e%weights); .Ve .PP Set per-index (integer) weights. The weights hash is a mapping of index name to integer weight. .PP Returns \f(CW$sph\fR. .SS "SetIDRange" .IX Subsection "SetIDRange" .Vb 1 \& $sph\->SetIDRange($min, $max); .Ve .PP Set IDs range only match those records where document \s-1ID\s0 is between \f(CW$min\fR and \f(CW$max\fR (including \f(CW$min\fR and \f(CW$max\fR) .PP Returns \f(CW$sph\fR. .SS "SetFilter" .IX Subsection "SetFilter" .Vb 2 \& $sph\->SetFilter($attr, \e@values); \& $sph\->SetFilter($attr, \e@values, $exclude); .Ve .PP Sets the results to be filtered on the given attribute. Only results which have attributes matching the given values will be returned. .PP This may be called multiple times with different attributes to select on multiple attributes. .PP If 'exclude' is set, excludes results that match the filter. .PP Returns \f(CW$sph\fR. .SS "SetFilterRange" .IX Subsection "SetFilterRange" .Vb 2 \& $sph\->SetFilterRange($attr, $min, $max); \& $sph\->SetFilterRange($attr, $min, $max, $exclude); .Ve .PP Sets the results to be filtered on a range of values for the given attribute. Only those records where \f(CW$attr\fR column value is between \f(CW$min\fR and \f(CW$max\fR (including \f(CW$min\fR and \f(CW$max\fR) will be returned. .PP If 'exclude' is set, excludes results that fall within the given range. .PP Returns \f(CW$sph\fR. .SS "SetFilterFloatRange" .IX Subsection "SetFilterFloatRange" .Vb 1 \& $sph\->SetFilterFloatRange($attr, $min, $max, $exclude); .Ve .PP Same as SetFilterRange, but allows floating point values. .PP Returns \f(CW$sph\fR. .SS "SetGeoAnchor" .IX Subsection "SetGeoAnchor" .Vb 1 \& $sph\->SetGeoAnchor($attrlat, $attrlong, $lat, $long); .Ve .PP Setup anchor point for using geosphere distance calculations in filters and sorting. Distance will be computed with respect to this point .ie n .IP "$attrlat is the name of latitude attribute" 4 .el .IP "\f(CW$attrlat\fR is the name of latitude attribute" 4 .IX Item "$attrlat is the name of latitude attribute" .PD 0 .ie n .IP "$attrlong is the name of longitude attribute" 4 .el .IP "\f(CW$attrlong\fR is the name of longitude attribute" 4 .IX Item "$attrlong is the name of longitude attribute" .ie n .IP "$lat is anchor point latitude, in radians" 4 .el .IP "\f(CW$lat\fR is anchor point latitude, in radians" 4 .IX Item "$lat is anchor point latitude, in radians" .ie n .IP "$long is anchor point longitude, in radians" 4 .el .IP "\f(CW$long\fR is anchor point longitude, in radians" 4 .IX Item "$long is anchor point longitude, in radians" .PD .PP Returns \f(CW$sph\fR. .SS "SetGroupBy" .IX Subsection "SetGroupBy" .Vb 2 \& $sph\->SetGroupBy($attr, $func); \& $sph\->SetGroupBy($attr, $func, $groupsort); .Ve .PP Sets attribute and function of results grouping. .PP In grouping mode, all matches are assigned to different groups based on grouping function value. Each group keeps track of the total match count, and the best match (in this group) according to current sorting function. The final result set contains one best match per group, with grouping function value and matches count attached. .PP \&\f(CW$attr\fR is any valid attribute. Use ResetGroupBy to disable grouping. .PP \&\f(CW$func\fR is one of: .IP "\(bu" 4 \&\s-1SPH_GROUPBY_DAY\s0 .Sp Group by day (assumes timestamp type attribute of form \s-1YYYYMMDD\s0) .IP "\(bu" 4 \&\s-1SPH_GROUPBY_WEEK\s0 .Sp Group by week (assumes timestamp type attribute of form \s-1YYYYNNN\s0) .IP "\(bu" 4 \&\s-1SPH_GROUPBY_MONTH\s0 .Sp Group by month (assumes timestamp type attribute of form \s-1YYYYMM\s0) .IP "\(bu" 4 \&\s-1SPH_GROUPBY_YEAR\s0 .Sp Group by year (assumes timestamp type attribute of form \s-1YYYY\s0) .IP "\(bu" 4 \&\s-1SPH_GROUPBY_ATTR\s0 .Sp Group by attribute value .IP "\(bu" 4 \&\s-1SPH_GROUPBY_ATTRPAIR\s0 .Sp Group by two attributes, being the given attribute and the attribute that immediately follows it in the sequence of indexed attributes. The specified attribute may therefore not be the last of the indexed attributes. .PP Groups in the set of results can be sorted by any SQL-like sorting clause, including both document attributes and the following special internal Sphinx attributes: .ie n .IP "@id \- document \s-1ID\s0;" 4 .el .IP "\f(CW@id\fR \- document \s-1ID\s0;" 4 .IX Item "@id - document ID;" .PD 0 .ie n .IP "@weight, @rank, @relevance \- match weight;" 4 .el .IP "\f(CW@weight\fR, \f(CW@rank\fR, \f(CW@relevance\fR \- match weight;" 4 .IX Item "@weight, @rank, @relevance - match weight;" .ie n .IP "@group \- group by function value;" 4 .el .IP "\f(CW@group\fR \- group by function value;" 4 .IX Item "@group - group by function value;" .ie n .IP "@count \- number of matches in group." 4 .el .IP "\f(CW@count\fR \- number of matches in group." 4 .IX Item "@count - number of matches in group." .PD .PP The default mode is to sort by groupby value in descending order, ie. by \*(L"@group desc\*(R". .PP In the results set, \*(L"total_found\*(R" contains the total amount of matching groups over the whole index. .PP \&\s-1WARNING:\s0 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. \f(CW@count\fR might also be underestimated. .PP For example, if sorting by relevance and grouping by a \*(L"published\*(R" attribute with \s-1SPH_GROUPBY_DAY\s0 function, then the result set will contain only the most relevant match for each day when there were any matches published, with day number and per-day match count attached, and sorted by day number in descending order (ie. recent days first). .SS "SetGroupDistinct" .IX Subsection "SetGroupDistinct" .Vb 1 \& $sph\->SetGroupDistinct($attr); .Ve .PP Set count-distinct attribute for group-by queries .SS "SetRetries" .IX Subsection "SetRetries" .Vb 1 \& $sph\->SetRetries($count, $delay); .Ve .PP Set distributed retries count and delay .SS "SetOverride" .IX Subsection "SetOverride" .Vb 1 \& $sph\->SetOverride($attrname, $attrtype, $values); \& \& Set attribute values override. There can be only one override per attribute. \& $values must be a hash that maps document IDs to attribute values .Ve .SS "SetSelect" .IX Subsection "SetSelect" .Vb 1 \& $sph\->SetSelect($select) .Ve .PP Set select list (attributes or expressions). SQL-like syntax. .SS "ResetFilters" .IX Subsection "ResetFilters" .Vb 1 \& $sph\->ResetFilters; .Ve .PP Clear all filters. .SS "ResetGroupBy" .IX Subsection "ResetGroupBy" .Vb 1 \& $sph\->ResetGroupBy; .Ve .PP Clear all group-by settings (for multi-queries) .SS "ResetOverrides" .IX Subsection "ResetOverrides" Clear all attribute value overrides (for multi-queries) .SS "Query" .IX Subsection "Query" .Vb 1 \& $results = $sph\->Query($query, $index); .Ve .PP Connect to searchd server and run given search query. .IP "query is query string" 4 .IX Item "query is query string" .PD 0 .ie n .IP "index is index name to query, default is ""*"" which means to query all indexes. Use a space or comma separated list to search multiple indexes." 4 .el .IP "index is index name to query, default is ``*'' which means to query all indexes. Use a space or comma separated list to search multiple indexes." 4 .IX Item "index is index name to query, default is * which means to query all indexes. Use a space or comma separated list to search multiple indexes." .PD .PP Returns undef on failure .PP Returns hash which has the following keys on success: .IP "matches" 4 .IX Item "matches" Array containing hashes with found documents ( \*(L"doc\*(R", \*(L"weight\*(R", \*(L"group\*(R", \*(L"stamp\*(R" ) .IP "total" 4 .IX Item "total" Total amount of matches retrieved (upto \s-1SPH_MAX_MATCHES,\s0 see sphinx.h) .IP "total_found" 4 .IX Item "total_found" Total amount of matching documents in index .IP "time" 4 .IX Item "time" Search time .IP "words" 4 .IX Item "words" Hash which maps query terms (stemmed!) to ( \*(L"docs\*(R", \*(L"hits\*(R" ) hash .PP Returns the results array on success, undef on error. .SS "AddQuery" .IX Subsection "AddQuery" .Vb 1 \& $sph\->AddQuery($query, $index); .Ve .PP Add a query to a batch request. .PP Batch queries enable searchd to perform internal optimizations, if possible; and reduce network connection overheads in all cases. .PP For instance, running exactly the same query with different groupby settings will enable searched to perform expensive full-text search and ranking operation only once, but compute multiple groupby results from its output. .PP Parameters are exactly the same as in \fIQuery()\fR call. .PP Returns corresponding index to the results array returned by \fIRunQueries()\fR call. .SS "RunQueries" .IX Subsection "RunQueries" .Vb 1 \& $sph\->RunQueries .Ve .PP Run batch of queries, as added by AddQuery. .PP Returns undef on network \s-1IO\s0 failure. .PP Returns an array of result sets on success. .PP Each result set in the returned array is a hash which contains the same keys as the hash returned by Query, plus: .IP "\(bu" 4 error .Sp Errors, if any, for this query. .IP "\(bu" 4 warning .Sp Any warnings associated with the query. .SS "BuildExcerpts" .IX Subsection "BuildExcerpts" .Vb 1 \& $excerpts = $sph\->BuildExcerpts($docs, $index, $words, $opts) .Ve .PP Generate document excerpts for the specified documents. .IP "docs" 4 .IX Item "docs" An array reference of strings which represent the document contents .IP "index" 4 .IX Item "index" A string specifiying the index whose settings will be used for stemming, lexing and case folding .IP "words" 4 .IX Item "words" A string which contains the words to highlight .IP "opts" 4 .IX Item "opts" A hash which contains additional optional highlighting parameters: .RS 4 .ie n .IP "before_match \- a string to insert before a set of matching words, default is """"" 4 .el .IP "before_match \- a string to insert before a set of matching words, default is ``''" 4 .IX Item "before_match - a string to insert before a set of matching words, default is " .PD 0 .ie n .IP "after_match \- a string to insert after a set of matching words, default is """"" 4 .el .IP "after_match \- a string to insert after a set of matching words, default is ``''" 4 .IX Item "after_match - a string to insert after a set of matching words, default is " .ie n .IP "chunk_separator \- a string to insert between excerpts chunks, default is "" ... """ 4 .el .IP "chunk_separator \- a string to insert between excerpts chunks, default is `` ... ''" 4 .IX Item "chunk_separator - a string to insert between excerpts chunks, default is ... " .IP "limit \- max excerpt size in symbols (codepoints), default is 256" 4 .IX Item "limit - max excerpt size in symbols (codepoints), default is 256" .IP "limit_passages \- Limits the maximum number of passages that can be included into the snippet. Integer, default is 0 (no limit)." 4 .IX Item "limit_passages - Limits the maximum number of passages that can be included into the snippet. Integer, default is 0 (no limit)." .IP "limit_words \- Limits the maximum number of keywords that can be included into the snippet. Integer, default is 0 (no limit)." 4 .IX Item "limit_words - Limits the maximum number of keywords that can be included into the snippet. Integer, default is 0 (no limit)." .IP "around \- how many words to highlight around each match, default is 5" 4 .IX Item "around - how many words to highlight around each match, default is 5" .IP "exact_phrase \- whether to highlight exact phrase matches only, default is false" 4 .IX Item "exact_phrase - whether to highlight exact phrase matches only, default is false" .IP "single_passage \- whether to extract single best passage only, default is false" 4 .IX Item "single_passage - whether to extract single best passage only, default is false" .IP "use_boundaries" 4 .IX Item "use_boundaries" .IP "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." 4 .IX Item "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." .ie n .IP "query_mode \- Whether to handle $words as a query in extended syntax, or as a bag of words (default behavior). For instance, in query mode (""one two"" | ""three four"") will only highlight and include those occurrences ""one two"" or ""three four"" when the two words from each pair are adjacent to each other. In default mode, any single occurrence of ""one"", ""two"", ""three"", or ""four"" would be highlighted. Boolean, default is false." 4 .el .IP "query_mode \- Whether to handle \f(CW$words\fR as a query in extended syntax, or as a bag of words (default behavior). For instance, in query mode (``one two'' | ``three four'') will only highlight and include those occurrences ``one two'' or ``three four'' when the two words from each pair are adjacent to each other. In default mode, any single occurrence of ``one'', ``two'', ``three'', or ``four'' would be highlighted. Boolean, default is false." 4 .IX Item "query_mode - Whether to handle $words as a query in extended syntax, or as a bag of words (default behavior). For instance, in query mode (one two | three four) will only highlight and include those occurrences one two or three four when the two words from each pair are adjacent to each other. In default mode, any single occurrence of one, two, three, or four would be highlighted. Boolean, default is false." .IP "force_all_words \- Ignores the snippet length limit until it includes all the keywords. Boolean, default is false." 4 .IX Item "force_all_words - Ignores the snippet length limit until it includes all the keywords. Boolean, default is false." .ie n .IP "start_passage_id \- Specifies the starting value of %PASSAGE_ID% macro (that gets detected and expanded in before_match, after_match strings). Integer, default is 1." 4 .el .IP "start_passage_id \- Specifies the starting value of \f(CW%PASSAGE_ID\fR% macro (that gets detected and expanded in before_match, after_match strings). Integer, default is 1." 4 .IX Item "start_passage_id - Specifies the starting value of %PASSAGE_ID% macro (that gets detected and expanded in before_match, after_match strings). Integer, default is 1." .ie n .IP "load_files \- Whether to handle $docs as data to extract snippets from (default behavior), or to treat it as file names, and load data from specified files on the server side. Boolean, default is false." 4 .el .IP "load_files \- Whether to handle \f(CW$docs\fR as data to extract snippets from (default behavior), or to treat it as file names, and load data from specified files on the server side. Boolean, default is false." 4 .IX Item "load_files - Whether to handle $docs as data to extract snippets from (default behavior), or to treat it as file names, and load data from specified files on the server side. Boolean, default is false." .ie n .IP "html_strip_mode \- \s-1HTML\s0 stripping mode setting. Defaults to ""index"", which means that index settings will be used. The other values are ""none"" and ""strip"", that forcibly skip or apply stripping irregardless of index settings; and ""retain"", that retains \s-1HTML\s0 markup and protects it from highlighting. The ""retain"" mode can only be used when highlighting full documents and thus requires that no snippet size limits are set. String, allowed values are ""none"", ""strip"", ""index"", and ""retain""." 4 .el .IP "html_strip_mode \- \s-1HTML\s0 stripping mode setting. Defaults to ``index'', which means that index settings will be used. The other values are ``none'' and ``strip'', that forcibly skip or apply stripping irregardless of index settings; and ``retain'', that retains \s-1HTML\s0 markup and protects it from highlighting. The ``retain'' mode can only be used when highlighting full documents and thus requires that no snippet size limits are set. String, allowed values are ``none'', ``strip'', ``index'', and ``retain''." 4 .IX Item "html_strip_mode - HTML stripping mode setting. Defaults to index, which means that index settings will be used. The other values are none and strip, that forcibly skip or apply stripping irregardless of index settings; and retain, that retains HTML markup and protects it from highlighting. The retain mode can only be used when highlighting full documents and thus requires that no snippet size limits are set. String, allowed values are none, strip, index, and retain." .IP "allow_empty \- Allows empty string to be returned as highlighting result when a snippet could not be generated (no keywords match, or no passages fit the limit). By default, the beginning of original text would be returned instead of an empty string. Boolean, default is false." 4 .IX Item "allow_empty - Allows empty string to be returned as highlighting result when a snippet could not be generated (no keywords match, or no passages fit the limit). By default, the beginning of original text would be returned instead of an empty string. Boolean, default is false." .IP "passage_boundary" 4 .IX Item "passage_boundary" .IP "emit_zones" 4 .IX Item "emit_zones" .IP "load_files_scattered" 4 .IX Item "load_files_scattered" .RE .RS 4 .RE .PD .PP Returns undef on failure. .PP Returns an array ref of string excerpts on success. .SS "BuildKeywords" .IX Subsection "BuildKeywords" .Vb 1 \& $results = $sph\->BuildKeywords($query, $index, $hits) .Ve .PP Generate keyword list for a given query Returns undef on failure, Returns an array of hashes, where each hash describes a word in the query with the following keys: .IP "\(bu" 4 tokenized .Sp Tokenised term from query .IP "\(bu" 4 normalized .Sp Normalised term from query .IP "\(bu" 4 docs .Sp Number of docs in which word was found (if \f(CW$hits\fR is true) .IP "\(bu" 4 hits .Sp Number of occurrences of word (if \f(CW$hits\fR is true) .SS "EscapeString" .IX Subsection "EscapeString" .Vb 1 \& $escaped = $sph\->EscapeString(\*(Aqabcde!@#$%\*(Aq) .Ve .PP Inserts backslash before all non-word characters in the given string. .SS "UpdateAttributes" .IX Subsection "UpdateAttributes" .Vb 2 \& $sph\->UpdateAttributes($index, \e@attrs, \e%values); \& $sph\->UpdateAttributes($index, \e@attrs, \e%values, $mva); .Ve .PP Update specified attributes on specified documents .IP "index" 4 .IX Item "index" Name of the index to be updated .IP "attrs" 4 .IX Item "attrs" Array of attribute name strings .IP "values" 4 .IX Item "values" A hash with key as document id, value as an array of new attribute values .PP Returns number of actually updated documents (0 or more) on success .PP Returns undef on failure .PP Usage example: .PP .Vb 1 \& $sph\->UpdateAttributes("test1", [ qw/group_id/ ], { 1 => [ 456] }) ); .Ve .SS "Open" .IX Subsection "Open" .Vb 1 \& $sph\->Open() .Ve .PP Opens a persistent connection for subsequent queries. .PP To reduce the network connection overhead of making Sphinx queries, you can call \&\f(CW$sph\fR\->\fIOpen()\fR, then run any number of queries, and call \f(CW$sph\fR\->\fIClose()\fR when finished. .PP Returns 1 on success, 0 on failure. .SS "Close" .IX Subsection "Close" .Vb 1 \& $sph\->Close() .Ve .PP Closes a persistent connection. .PP Returns 1 on success, 0 on failure. .SS "Status" .IX Subsection "Status" .Vb 1 \& $status = $sph\->Status() .Ve .PP Queries searchd status, and returns a hash of status variable name and value pairs. .PP Returns undef on failure. .SS "FlushAttributes" .IX Subsection "FlushAttributes" .SH "SEE ALSO" .IX Header "SEE ALSO" .SH "NOTES" .IX Header "NOTES" There is (or was) a bundled Sphinx.pm in the contrib area of the Sphinx source distribution, which was used as the starting point of Sphinx::Search. Maintenance of that version appears to have lapsed at sphinx\-0.9.7, so many of the newer \s-1API\s0 calls are not available there. Sphinx::Search is mostly compatible with the old Sphinx.pm except: .IP "On failure, Sphinx::Search returns undef rather than 0 or \-1." 4 .IX Item "On failure, Sphinx::Search returns undef rather than 0 or -1." .PD 0 .ie n .IP "Sphinx::Search 'Set' functions are cascadable, e.g. you can do Sphinx::Search\->new \->SetMatchMode(\s-1SPH_MATCH_ALL\s0) \->SetSortMode(\s-1SPH_SORT_RELEVANCE\s0) \->Query(""search terms"")" 4 .el .IP "Sphinx::Search 'Set' functions are cascadable, e.g. you can do Sphinx::Search\->new \->SetMatchMode(\s-1SPH_MATCH_ALL\s0) \->SetSortMode(\s-1SPH_SORT_RELEVANCE\s0) \->Query(``search terms'')" 4 .IX Item "Sphinx::Search 'Set' functions are cascadable, e.g. you can do Sphinx::Search->new ->SetMatchMode(SPH_MATCH_ALL) ->SetSortMode(SPH_SORT_RELEVANCE) ->Query(search terms)" .PD .PP Sphinx::Search also provides documentation and unit tests, which were the main motivations for branching from the earlier work. .SH "AUTHOR" .IX Header "AUTHOR" Jon Schutz .PP .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-sphinx\-search at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Sphinx::Search .Ve .PP You can also look for information at: .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" This module is based on Sphinx.pm (not deployed to \s-1CPAN\s0) for Sphinx version 0.9.7\-rc1, by Len Kranendonk, which was in turn based on the Sphinx \s-1PHP API.\s0 .PP Thanks to Alexey Kholodkov for contributing a significant patch for handling persistent connections. .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2012 Jon Schutz, all rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License.