Mailing List Archive

Author: creamyg
Date: 2008-08-28 15:15:30 -0700 (Thu, 28 Aug 2008)
New Revision: 3780

Modified:
trunk/perl/lib/KinoSearch/Docs/DocNums.pod
Log:
Update Docs::DocNums, adding info about all valid nums being positive and 0
being a sentinel.


Modified: trunk/perl/lib/KinoSearch/Docs/DocNums.pod
===================================================================
--- trunk/perl/lib/KinoSearch/Docs/DocNums.pod 2008-08-28 20:12:21 UTC (rev 3779)
+++ trunk/perl/lib/KinoSearch/Docs/DocNums.pod 2008-08-28 22:15:30 UTC (rev 3780)
@@ -1,23 +1,33 @@
=head1 NAME

-KinoSearch::Docs::DocNums - Document numbers in KinoSearch are ephemeral.
+KinoSearch::Docs::DocNums - Characteristics of KinoSearch document numbers.

=head1 DESCRIPTION

+=head2 Document numbers are positive 32-bit integers
+
+Document numbers in KinoSearch start at 1. Because all valid values are
+positive, we can use 0 as a sentinel value:
+
+ while ( my $doc_num = $posting_list->next ) {
+ ...
+ }
+
+=head2 Document numbers are ephemeral
+
The document numbers used by KinoSearch are associated with a single invindex
snapshot. The moment an invindex is updated, the mapping of document numbers
-to documents is likely to change.
+to documents may change.

Since IndexReader objects represent a point-in-time view of an invindex,
document numbers are guaranteed to remain static for the life of the reader.
However, because they are not permanent, KinoSearch document numbers cannot be
-used as foreign keys, used to retrieve data from external databases.
+used as foreign keys, used to retrieve data from external databases. If you
+truly need a primary key field, you must define it and populate it yourself.
+
Furthermore, the order of document numbers does not tell you anything about
-the order in which documents were added to the index.
+the sequence in which documents were added to the index.

-If you truly need a primary key field, you must define it and populate it
-yourself.
-
=head1 COPYRIGHT

Copyright 2008 Marvin Humphrey


_______________________________________________
kinosearch-commits mailing list
kinosearch-commits@rectangular.com
http://www.rectangular.com/mailman/listinfo/kinosearch-commits