saint/discourse-legacysite-perl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
9797a6824a
discourse-legacysite-perl/site/glist/templates/help/GT/SQL/Search.html
dsainty b6fc94ff0f Second pass at adding key files
2024-06-17 22:24:05 +10:00

792 lines
25 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>GT::SQL::Search - internal driver for searching</title>
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
<style type="text/css">
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
/* $MVD$:fontset("Arial","Arial") */
/* $MVD$:fontset("Arial Black","Arial Black") */
/* $MVD$:fontset("Algerian","Algerian") */
body {
background-color: white;
font-family: Verdana, Arial, sans-serif;
font-size: small;
color: black;
}
p {
background-color : white;
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
h1 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : medium;
background-color : white;
color : maroon;
}
h2 {
font-family : Verdana, Arial, sans-serif;
font-size : medium;
font-weight : bold;
color : blue;
background-color : white;
}
h3 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : medium;
color : black;
background-color : white;
}
h4 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : small;
color : maroon;
background-color : white;
}
h5 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : small;
color : blue;
background-color : white;
}
h6 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : small;
color : black;
background-color : white;
}
ul {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
ol {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dl {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
li {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
th {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
td {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dl {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dd {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dt {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
code {
font-family : Courier;
font-size : small;
color : black;
}
pre {
font-family : Courier;
font-size : small;
color : black;
}
.mvd-H1 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : 14.0pt;
background-color : transparent;
background-image : none;
color : maroon;
}
.mvd-H2 {
font-family : Verdana, Arial, sans-serif;
font-size : 12.0pt;
color : blue;
}
p.indent {
font-family : "Verdana, Arial, sans-serif";
list-style-type : circle;
list-style-position : inside;
color : black;
margin-left : 16.0pt;
}
.mvd-P-indent {
font-family : Verdana, Arial, sans-serif;
list-style-type : circle;
list-style-position : inside;
color : black;
margin-left : 16.0pt;
}
pre.programlisting {
font-size : 9.0pt;
list-style-type : disc;
margin-left : 16.0pt;
margin-top : -14.0pt;
}
.mvd-PRE-programlisting {
font-size : 9.0pt;
list-style-type : disc;
margin-left : 16.0pt;
margin-top : -14.0pt;
}
.mvd-PRE {
font-size : 9.0pt;
}
p.note {
margin-left : 28.0pt;
}
.mvd-P-note {
margin-left : 28.0pt;
}
.mvd-H4 {
font-family : Verdana, Arial, sans-serif;
font-weight : normal;
font-size : 9.0pt;
color : black;
margin-left : 6.0pt;
margin-top : -14.0pt;
}
.mvd-P {
font-family : Verdana, Arial, sans-serif;
font-size : 10.0pt;
color : black;
}
.mvd-BODY {
font-family : Verdana, Arial, sans-serif;
background-color : white;
}
p.indentnobullet {
font-family : Verdana, Arial, sans-serif;
list-style-type : none;
}
.mvd-P-indentnobullet {
font-family : Verdana, Arial, sans-serif;
list-style-type : none;
}
</style>
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>
<li><a href="#drivers">Drivers</a></li>
<li><a href="#structure_of_an_indexing_driver">Structure of an Indexing Driver</a></li>
<li><a href="#structure_of_indexing_driver">Structure of Indexing Driver</a></li>
<li><a href="#structure_of_a_search_driver">Structure of a Search Driver</a></li>
</ul>
<li><a href="#copyright">COPYRIGHT</a></li>
<li><a href="#version">VERSION</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>GT::SQL::Search - internal driver for searching</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>This implements the query string based searching scheme for GT::SQL. Driver
based, it is designed to take advantage of the different indexing schemes
available on different database engines.</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>Instead of describing how Search.pm is interfaced* this will describe how a
driver should be structured and how a new driver can be implemented.</p>
<p>* as it is never accessed directly by the programmer as it was designed to be
called through the functions GT::SQL::Table::query and GT::SQL::Table::query_sth</p>
<p>
</p>
<h2><a name="drivers">Drivers</a></h2>
<p>A driver has two parts. The Indexer and the Search packages are the most
important. Howserver, for any driver in the search, there must exist a directory
with the name of the driver in ALL CAPS. For exampel, MYSQL for MySQL, POSTGRES
for Postgres. Within each driver directory, The Indexer and Search portions of
the driver contains all the information required for initializing the database
table and searching the database.</p>
<p>The Indexing package of the driver handles all the data that is manipulated in
the database and also the initializes and the database for indexing.</p>
<p>The Search package handles the queries and retrieves results for the eventual
consumption by the calling program.</p>
<p>Drivers are simply subclasses of the base driver module, GT::SQL::Search::Base
and operate by overriding certain key functions.</p>
<p>The next few sections will cover how to create a search driver, and assumes a
fair bit of familiarity with GT::SQL.</p>
<p>
</p>
<h2><a name="structure_of_an_indexing_driver">Structure of an Indexing Driver</a></h2>
<p>The following is an absolutely simple skeleton driver that does nothing and but
called ``CUSTOM''. Found in the CUSTOM directory, this is the search package, and
would be call Search.pm in the GT/SQL/Search/CUSTOM library directory.</p>
<pre>
package GT::SQL::Search::CUSTOM::Search;
#------------------------------------------
use strict;
use vars qw/ @ISA /;
use GT::SQL::Search::Base::Search;
@ISA = qw( GT::SQL::Search::Base::Search );
sub load { my $package_name = shift; return GT::SQL::Search::CUSTOM::Search-&gt;new(@_) };
# overrides would go here
1;</pre>
<p>For the indexer, another file, Indexer.pm would be found in the
GT/SQL/Search/CUSTOM directory.</p>
<pre>
package GT::SQL::Search::CUSTOM::Indexer;
#------------------------------------------
use strict;
use vars qw/ @ISA /;
use GT::SQL::Search::Base;
@ISA = qw/ GT::SQL::Search::Base::Indexer /;
sub load { my $package_name = shift; return GT::SQL::Search::CUSTOM::Indexer-&gt;new(@_) };
# overrides would go here
1;</pre>
<p>The almost empty subs that immediately return with a value are functions that
can be overridden to do special tasks. More will be detailed later.</p>
<p>The Driver has been split into two packages. The original package name,
GT::SQL::Search::Nothing, houses the Search package.
GT::SQL::Search::Nothing::Indexer is the Indexing portion of the seach system.
``::Indexer'' must be appended to the orginial search name for the indexer.</p>
<p>Each of the override functions are triggered at points just before and after a
major event occurs in GT::SQL. Depending on the type of actions you require, you
pick and chose which events you'd like your driver to attach to.</p>
<p>
</p>
<h2><a name="structure_of_indexing_driver">Structure of Indexing Driver</a></h2>
<p>The Indexer is responsible for creating all the indexes, maintaining them and
when the table is dropped, removing all the associated indexes.</p>
<p>The following header must be defined for the Indexer.
GT::SQL::Search::Base::Indexer is the superclass that our driver inherits from.</p>
<pre>
package GT::SQL::Search::CUSTOM::Indexer;
#------------------------------------------
use strict;
use vars qw/ @ISA /;
use GT::Base;
use GT::SQL::Search::Base::Indexer;
@ISA = qw/ GT::SQL::Search::Base::Indexer /;</pre>
<p>In addition to the header, the following function must be defined.
GT::SQL::Search::Driver::Indexer::load creates the new object and allows for
special preinitialization that must occur. You can also create another driver
silently (such as defaulting to INTERNAL after a version check fails).</p>
<pre>
sub load { my $package_name = shift; return GT::SQL::Search::CUSTOM::Indexer-&gt;new(@_) };</pre>
<p>Finally, there are the overrides. None of the override functions need be defined
in your driver. Any calls made to undefined methods will silently fallback to
the superclass driver's methods. When a method has been overridden, the function
must return a true value when it is successful, otherwise the action will fail
and an error generated.</p>
<p>Whenever a object is created it will receive one property $self-&gt;{table} which
is the table that is being worked upon. This property is available in all the
method calls and is required for methods such as _create_table and
_drop_search_driver methods.</p>
<p>When a table is first created or when a table is destroyed the following two
functions are called. They are not passed any special values, however, these are
all class methods and $self-&gt;{table} will be a reference to the current table in
use.</p>
<p>This set of overrides are used by GT::SQL::Creator when the ::create method is
called. They are called just prior and then after the create table sql query has
been executed.</p>
<dl>
<dt><strong><a name="item_pre_create_table">pre_create_table</a></strong><br />
</dt>
<dt><strong><a name="item_post_create_table">post_create_table</a></strong><br />
</dt>
<dd>
These functions receive no special parameters. They will receive the data to the
table in the $self-&gt;{table} property.
</dd>
<p></p></dl>
<p>This next set of functions take place in GT::SQL::Editor.</p>
<dl>
<dt><strong><a name="item_drop_search_driver">drop_search_driver</a></strong><br />
</dt>
<dd>
This method receives no special parameters but is responsible for removing all
indexes and ``things'' associated with the indexing schema.
</dd>
<p></p>
<dt><strong><a name="item_add_search_driver">add_search_driver</a></strong><br />
</dt>
<dd>
Receives no extra parameters. Creates all indexes and does all actions required
to initialize indexing scheme.
</dd>
<p></p>
<dt><strong><a name="item_pre_add_column">pre_add_column</a></strong><br />
</dt>
<dt><strong><a name="item_post_add_column">post_add_column</a></strong><br />
</dt>
<dd>
The previous two functions are called just before and after a new column is
added.
</dd>
<dd>
<p>pre_add_column accepts $name (of column), $col (hashref of column attributes).
The method will only be called if the column has a weight associated with it.
The function must return a non-zero value if successful. Note that the returned
value will be passed into the post_add_column so temporary values can be passed
through if required.</p>
</dd>
<dd>
<p>post_add_column accepts $name (of column), $col (hashref of column attributes),
$results (of pre_add_column). This method is called just after the column has
been inserted into the database.</p>
</dd>
<p></p>
<dt><strong><a name="item_pre_delete_column">pre_delete_column</a></strong><br />
</dt>
<dt><strong><a name="item_post_delete_column">post_delete_column</a></strong><br />
</dt>
<dd>
These previous functions are called just before and after the sql for a old
column is deleted. They must remove all objects and ``things'' associated with a
particular column's index.
</dd>
<dd>
<p>pre_delete_column accepts $name (of column), $col (hashref of column
attributes). The method will only be called if the column has a weight
associated with it. The function must return a non-zero value if successful.
Note that the returned value will be passed into the post_delete_column so
temporary values can be passed through if required.</p>
</dd>
<dd>
<p>post_delete_column accepts $name (of column), $col (hashref of column
attributes), $results (of pre_add_column). This method is called just after the
column has been dropped from the database.</p>
</dd>
<p></p>
<dt><strong><a name="item_pre_drop_table">pre_drop_table</a></strong><br />
</dt>
<dt><strong><a name="item_post_drop_table">post_drop_table</a></strong><br />
</dt>
<dd>
The two previous methods are used before and after the table is dropped. The
methods must remove any tables or ``things'' related to indexing from the table.
</dd>
<dd>
<p>pre_drop_table receives no arguments. It can find a copy of the current table
and columns associated in $self-&gt;{table}.</p>
</dd>
<dd>
<p>post_drop_table receives one argument, which is the result of the
pre_drop_table.</p>
</dd>
<p></p></dl>
<p>The following set of functions take place in GT::SQL::Table</p>
<dl>
<dt><strong><a name="item_pre_add_record">pre_add_record</a></strong><br />
</dt>
<dt><strong><a name="item_post_add_record">post_add_record</a></strong><br />
</dt>
<dd>
Called just before and after an insert occurs. These functions take the record
and indexes them as required.
</dd>
<dd>
<p>pre_add_record will receive one argument, $rec, hashref, which is the record
that will be inserted into the database. Table information can be found by
accessing $self-&gt;{table} Much like the other functions, on success the result
will be cached and fed into the post_add_record function.</p>
</dd>
<dd>
<p>post_add_record receives $rec, a hashref to describing the new result, the $sth
of the insert query, and the result of the pre_add_record method. The result
from $sth-&gt;insert_id if there is a ai field will be the new unique primary key.</p>
</dd>
<p></p>
<dt><strong><a name="item_pre_update_record">pre_update_record</a></strong><br />
</dt>
<dt><strong><a name="item_post_update_record">post_update_record</a></strong><br />
</dt>
<dd>
Intercepts the update request before and just after the sql query is executed.
This override has the potential of being rather messy. More than one record can
be modified in this action and the indexer must work a lot to ensure the
database is up to snuff.
</dd>
<dd>
<p>pre_update_record receives two parameters, $set_cond, $where_cond. $set_cond is
a hashref containing the new values that must be set, and $where_cond is a
GT::SQL::Condition object selecting records to update. The result once again, is
cached and if undef is considered an error.</p>
</dd>
<dd>
<p>post_update_record takes the same parameters as pre_update_record, except one
extra paremeter, the result of pre_update_record.</p>
</dd>
<p></p>
<dt><strong><a name="item_pre_delete_record">pre_delete_record</a></strong><br />
</dt>
<dt><strong><a name="item_post_delete_record">post_delete_record</a></strong><br />
</dt>
<dd>
Called just before and after the deletion request for records are called.
</dd>
<dd>
<p>pre_delete_record, has only one parameter, $where, a GT::SQL::Condition object
telling which records to delete. The results of this method are passed to
post_delete_record.</p>
</dd>
<dd>
<p>post_delete_record, has one addition parameter to pre_delete_record and like
most post_ methods, is the result of the pre_delete_record method.</p>
</dd>
<p></p>
<dt><strong><a name="item_pre_delete_all_records">pre_delete_all_records</a></strong><br />
</dt>
<dt><strong><a name="item_post_delete_all_records">post_delete_all_records</a></strong><br />
</dt>
<dd>
These two functions are quite simple, but they are different from drop search
driver in that though the records are all dropped, the framework for all the
indexing is not dropped as well.
</dd>
<dd>
<p>Neither function is passed any special data, except for post_delete_all_records
which receives the rsults of the pre_delete_all_records method.</p>
</dd>
<p></p>
<dt><strong><a name="item_reindex_all">reindex_all</a></strong><br />
</dt>
<dd>
This function is sometimes called by the user to refresh the index. The
motivation for this, in the case of the INTERNAL driver, is sometimes due to
outside manipulation of the database tables, the index can become
non-representative of the data in the tables. This method is to force the
indexing system to fix errors that have passed.
</dd>
<p></p>
<dt><strong><a name="item_ok">ok</a></strong><br />
</dt>
<dd>
This function is called by GT::SQL::Search as a package method,
GT::SQL::Search::EXAMPLE::Indexer-&gt;ok( $table ); and is passed a table object
reference. What this function must do is to return a true or false value that
tells the search system if this driver can be used. The MYSQL driver has a good
example for this, it tests to ensure that the mysql database system version is
at least 3.23.23.
</dd>
<p></p></dl>
<p>
</p>
<h2><a name="structure_of_a_search_driver">Structure of a Search Driver</a></h2>
<p>The Searcher is responsible for only one thing, to return results from a query
search. You can override the parser, however, subclassing the following methods
will have full parsing for all things such as +/-, string parsing and substring
matching.</p>
<p>The structures passed into the methods get a little complicated so beware!</p>
<p>ALL the following functions receive two parameters, the first is a search
parameters detailing the words/phrases to search for, the second parameter is
the current result set of IDs =&gt; scores.</p>
<p>There are two types of search parameters, one for words and the other for
phrases. The structure is a little messy so I'll detail them here.</p>
<p>For words, the structure is like the following:</p>
<pre>
$word_search = {
'word' =&gt; {
substring =&gt; '1', # set to 1 if this is substring match
phrase =&gt; 0, # not a phrase
keyword =&gt; 1, # is a keyword
mode =&gt; '', # can also be must, cannot to mean +/-
},
'word2' =&gt; ...
}</pre>
<p>For phrases the structure will become:</p>
<pre>
$phrase_search =&gt; {
'phrase' =&gt; {
substring =&gt; undef # never required
phrase =&gt; [
'word1',
'word2',
'word3',
...
], # for searching by indiv word if required
keyword =&gt; 0, # not a keyword
mode =&gt; '' # can also be must, cannot
},
'phrase2' =&gt; ...
}</pre>
<p>Based on these structures, hopefully it will be easy enough to build whatever is
required to grab the appropriate records.</p>
<p>Finally, the second item passed in will be a hash filled with ID =&gt; score values
of search results. They look something like this:</p>
<pre>
$results = {
1 =&gt; 56,
2 =&gt; 31,
4 =&gt; 6
}</pre>
<p>It is important for all the methods to take the results and return the results,
as the result set will be daisychained down like a set to be operated on by
various searching schemes.</p>
<p>At the end of the query, the results in this set will be sorted and returned to
the user as an sth.</p>
<p>Operations on this set are preformed by the following five methods.</p>
<dl>
<dt><strong><a name="item__query">_query</a></strong><br />
</dt>
<dd>
This method is called just after all the query string has been parsed and put
into their proper buckets. This method is overridden by the INTERNAL driver to
decide it wants to switch to the NONINDEX driver for better performance.
</dd>
<dd>
<p>Two parameters are passed in, ( $input, $buckets ). $input is a hash that
contains all the form/cgi parameters passed to the $tbl-&gt;query function and
$buckets is s the structure that is created after the query string is parsed.
You may also call $self-&gt;SUPER::_query( $input, $buckets ) to pass the request
along normally.</p>
</dd>
<dd>
<p>You must return undef or an STH from this function.</p>
</dd>
<p></p>
<dt><strong><a name="item__union_query">_union_query</a></strong><br />
</dt>
<dd>
This method takes a $word_search and does a simple match query. If it finds
records with any of the words included, it will append the results to the list.
Passed in is the $results and it must return the altered results set.
</dd>
<dd>
<p>This method must also implement substring searching.</p>
</dd>
<p></p>
<dt><strong><a name="item__phrase_query">_phrase_query</a></strong><br />
</dt>
<dd>
Just like the union_query, however it searches based on phrases.
</dd>
<p></p>
<dt><strong><a name="item__phrase_intersect_query">_phrase_intersect_query</a></strong><br />
</dt>
<dd>
This takes a $phrase_search and a $result as parameters. This method must look
to find results that are found within the current result set that have the
passed phrases as well. However, if there are no results found, this method can
look for more results.
</dd>
<p></p>
<dt><strong><a name="item__intersect_query">_intersect_query</a></strong><br />
</dt>
<dd>
Takes two parameters, a $word_search, and $results. Just like the
_phrase_intersect query, if there are results already, tries to whittle away the
result set. If there are no results, tries to look for results that have all the
keywords in a record.
</dd>
<dd>
<p>This method must also implement substring searching.</p>
</dd>
<p></p>
<dt><strong><a name="item__disjoin_query">_disjoin_query</a></strong><br />
</dt>
<dd>
Takes two parameters, a $word_search, and $results. This will look through the
result set and remove all matches to any of the keywords.
</dd>
<dd>
<p>This method must also implement substring searching.</p>
</dd>
<p></p>
<dt><strong><a name="item__phrase_disjoin_query">_phrase_disjoin_query</a></strong><br />
</dt>
<dd>
Two parameters, $phrase_search and $results are passed to this method. This does
the exact same thing as _disjoin_query but it looks for phrases.
</dd>
<p></p>
<dt><strong><a name="item_query">query</a></strong><br />
</dt>
<dd>
If you choose to override this method, you will have full control of the query.
</dd>
<dd>
<p>This method accepts a $CGI or a $HASH object and performs the following</p>
</dd>
<dd>
<pre>
Options:
- paging
mh : max hits
nh : number hit (or page of hits)
sb : column to sort by (default is by score)</pre>
</dd>
<dd>
<pre>
- searching
ww : whole word
ma : 1 =&gt; OR match, 0 =&gt; AND match, undefined =&gt; QUERY
substring : search for substrings of words
bool : 'and' =&gt; and search, 'or' =&gt; or search, '' =&gt; regular query
query : the string of things to ask for</pre>
</dd>
<dd>
<pre>
- filtering
field_name : value # Find all rows with field_name = value
field_name : &quot;&gt;value&quot; # Find all rows with field_name &gt; value.
field_name : &quot;&lt;value&quot; # Find all rows with field_name &lt; value.
field_name-gt : value # Find all rows with field_name &gt; value.
field_name-lt : value # Find all rows with field_name &lt; value.</pre>
</dd>
<dd>
<p>The function must return a STH object. However, you may find useful the
GT::SQL::Search::STH object, which will automatically handle mh, nh, and
alternative sorting requests. All you will have to do is</p>
</dd>
<dd>
<pre>
sub query { ... your code ... return $self-&gt;sth( $results ); }</pre>
</dd>
<dd>
<p>Where results is a hashref containing primarykeyvalue =&gt; scorevalues.</p>
</dd>
<p></p>
<dt><strong><a name="item_alternate_driver_query">alternate_driver_query</a></strong><br />
</dt>
<dd>
There is no reason to override this method, however, if you would like to use
another driver's search instead of the current, this method will let you do so.
</dd>
<dd>
<p>Accepting 2 parameters, ( $drivername, $input ), where $drivername is the name
of the driver you'd like to use and $input is the parameters passed to the
method. Returned is an $sth value (undef if an error has occured). This method
was used in the INTERNAL driver to shunt to NONINDEXED if it found the search
would take too long.</p>
</dd>
<p></p></dl>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
<p>
</p>
<hr />
<h1><a name="version">VERSION</a></h1>
<p>Revision: $Id: Search.pm,v 1.60 2004/08/28 03:53:43 jagerman Exp $</p>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink