/[pgestraier]/trunk/README.pod

This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!

Diff of /trunk/README.pod

Parent Directory | Revision Log | View Patch Patch

-revision 60 by dpavlin,
Tue Jul 11 14:11:42 2006 UTC
+revision 64 by dpavlin,
Mon Aug  7 14:32:21 2006 UTC
 Line 1
- =head1 pgestraier - search Hyper Estraier indexes from PostgreSQL
+ =head1 pgestraier - PostgreSQL full-text search using Hyper Estraier
- This package is essentially PostgreSQL C function which calls Hyper Estraier
+ This package is essentially composed of two different parts:
- API and returns results in user defined format.
+ =over 4
+ =item search function
+ PostgreSQL function to search Hyper Estraier full-text index, using
+ full-text queries and attribute filtering to return user-specified
+ table of results.
+ This function can mimic SQL C<LIMIT>, C<OFFSET> and C<ORDER BY>
+ functionality much faster than using those SQL constructs on search
+ results.
+ =item trigger function
+ PostgreSQL trigger function to keep Hyper Estraier in sync with PostgreSQL.
+ It triggers after insert, update or delete and update full-text index
+ accordingly.
+ =back
+ Both functions are written in C, while test framework and supporting
+ utilities are written in perl.
+ You can use just one of those functions. If you want just to search existing
+ Hyper Estraier index or generate it off-line (after nightly batch jobs, for
+ example), just use search function.
+ On the other hand, if you want just to keep your Hyper Estraier index in
+ sync with PostgreSQL data, you can use just trigger function to achieve that.
  =head1 Why is it written?
- Aside from providing single API to query your RDBMS and full text index
+ Aside from providing single query language (SQL) to RDBMS and full text index
  (using any language that has PostgreSQL client libraries), real power is
  hidden in ability to join results from full text index and structured data
  in RDBMS.
  For simple real-life example which address problem
- I<where like '%foo%' is slow>
+ C<< WHERE name LIKE '%foo%' OR surname LIKE '%foo%' >>
- see L<Tutorial>.
+ is slow see L<Tutorial>.
  =head1 How to install
  Installation should be simple. However, you will have to have following
- software already installed before you try this function:
+ software already installed before you try this functions:
  =over
  =item *
- PostgreSQL (tested with versions 7.4 and 8.0) with development libraries
+ PostgreSQL (tested with versions 7.4, 8.0 and 8.1) with development libraries
  =item *
- Hyper Estraier (tested with various versions, recommended 1.2.4 of newer)
+ Hyper Estraier (tested with various versions, recommended 1.2.4 or newer)
+ with development headers
+ =item *
+ working C compiler (tested with gcc)
  =back
- To run tests you will also need:
+ If you want to use helper script to create consistency triggers to keep
+ Hyper Estraier in sync with PostgreSQL database, you will also need:
  =over
-Line 41 
 working perl installation
+Line 76 
 working perl installation
  =item *
- perl modules C<DBI>, C<DBD::Pg>, C<Test::More> and optionally C<Search::Estraier>
+ perl modules C<Search::Estraier>, C<DBI> and C<DBD::Pg>
+ =back
+ To run tests you will also need:
+ =over
+ =item *
+ perl module C<Test::More>
  =item *
-Line 85 
 To run tests (which require that you hav
+Line 130 
 To run tests (which require that you hav
  See also included file C<test.sql> for more examples of usage.
- =head1 Usage of pgest from SQL
+ =head1 Usage of search function pgest from SQL
  C<pgest> PostgreSQL function tries to mimic usage of normal database tables (with support for attribute filtering, limit and offset) in following way:
-Line 144 
 This will work a bit faster on really sm
+Line 189 
 This will work a bit faster on really sm
  index grows bigger, you might consider using node API to remove overhead of
  database opening on each query.
+ =head1 Usage of trigger function pgest_trigger from SQL
+ Let's first say that I really suggest that you use C<dbi-index.pl> helper script to
+ create triggers because it already supports following steps automatically:
+ =over
+ =item begin transaction
+ Transaction is needed to catch updates which might happen while creation
+ of full-text index is in progress (and on huge collections this can take a while,
+ just like normal index creation in PostgreSQL).
+ =item insert all existing data in full-text index
+ This will be done directly from PostgreSQL database to Hyper Estraier index.
+ This is somewhat faster than waiting for trigger to fire for each existing
+ row.
+ =item create insert, update and delete triggers
+ Which will keep data in sync later
+ =item commit transaction
+ =back
+ If you still want to do that manually, you will need to know format of
+ C<pgest_trigger> function:
+         CREATE TRIGGER pgest_trigger_insert AFTER INSERT
+                 ON table FOR EACH ROW
+                 EXECUTE PROCEDURE pgest_trigger(
+                         -- node URI, login and password
+                         'http://localhost:1978/node/trivia', 'admin', 'admin',
+                         -- name of primary key column
+                         'id',
+                         -- names of all other columns to index (one or more)
+                         'column', 'another_one', 'and_another'
+                 )
+ You have to create triggers for C<UPDATE> and C<DELETE> in similar way.
  =head1 Who wrote this?
  Hyper Estraier is written by Mikio Hirabayashi.

 Legend:



Removed from v.60
 


changed lines


 
Added in v.64
 Legend:



Removed from v.60
 


changed lines


 
Added in v.64
-Removed from v.60
+Added in v.64

	ViewVC Help
Powered by ViewVC 1.1.26