ESTRAIER(3)
π estraier.h β the core API of Hyper Estraier π
okay bestie, this is ESTRAIER(3) from Hyper Estraier β¨ and we're about to make the whole core API make sense, fr fr.
β¨ NAME β¨
estraier.h β the core API of Hyper Estraier π
π SYNOPSIS π
#include <estraier.h>
#include <cabin.h>
#include <stdlib.h>
π API FOR DOCUMENT π
This API is giving βletβs handle documents that were registered into the indexβ π
The structure type ESTDOC is the abstraction of a document. A document is made of some attributes and some text sentences. You never touch an entity of ESTDOC directly β itβs accessed by the pointer, periodt. The term βdocument objectβ means that pointer and its referent. A document object gets created by est_doc_new and destroyed by est_doc_delete. Every created document object should be destroyed, bestie, donβt leave it hanging π
Target documents of search need to be registered in the database beforehand. The ID is assigned to each registered document. When you search, they can be retrieved from the database by their ID. The encoding of attributes and text sentences should be UTF-8. No exceptions. πΈ
π est_doc_new
est_doc_new is the one you call to create a document object, bestie.
ESTDOC *est_doc_new(void);
The return value is an object of a document. π
πΈ est_doc_new_from_draft
est_doc_new_from_draft creates a document object made from draft data. Itβs giving βnew doc, but make it draftβ β¨
ESTDOC *est_doc_new_from_draft(const char *draft);
draft specifies a string of draft data. The return value is an object of a document.
π
est_doc_delete
est_doc_delete destroys a document object. Clean up your mess, queen.
void est_doc_delete(ESTDOC *doc);
doc specifies a document object.
π¦ est_doc_add_attr
est_doc_add_attr adds an attribute to a document object.
void est_doc_add_attr(ESTDOC *doc, const char *name, const char *value);
doc specifies a document object. name specifies the name of an attribute. value specifies the value of the attribute. If it is NULL, the attribute is removed. π«Ά
π est_doc_add_text
est_doc_add_text adds a sentence of text to a document object.
void est_doc_add_text(ESTDOC *doc, const char *text);
doc specifies a document object. text specifies a sentence of text.
π est_doc_add_hidden_text
est_doc_add_hidden_text adds a hidden sentence to a document object. Secret text vibes.
void est_doc_add_hidden_text(ESTDOC *doc, const char *text);
doc specifies a document object. text specifies a hidden sentence.
π est_doc_set_keywords
est_doc_set_keywords attaches keywords to a document object.
void est_doc_set_keywords(ESTDOC *doc, CBMAP *kwords);
doc specifies a document object. kwords specifies a map object of keywords. Keys of the map should be keywords of the document and values should be their scores in decimal string. The map object is copied internally. π
β est_doc_set_score
est_doc_set_score sets the substitute score of a document object.
void est_doc_set_score(ESTDOC *doc, int score);
doc specifies a document object. score specifies the substitute score. If it is negative, the substitute score setting is nullified. π
π est_doc_id
est_doc_id gets the ID number of a document object.
int est_doc_id(ESTDOC *doc);
doc specifies a document object. The return value is the ID number of the document object. If the object has not been registered, -1 is returned. No cap. π«
π est_doc_attr_names
est_doc_attr_names gets a list of attribute names of a document object.
CBLIST *est_doc_attr_names(ESTDOC *doc);
doc specifies a document object. The return value is a new list object of attribute names of the document object. Because the object of the return value is opened with the function cblistopen, it should be closed with the function cblistclose if it is no longer in use. So close it, bestie. π
π est_doc_attr
est_doc_attr gets the value of an attribute of a document object.
const char *est_doc_attr(ESTDOC *doc, const char *name);
doc specifies a document object. name specifies the name of an attribute. The return value is the value of the attribute or NULL if it does not exist. The life duration of the returned string is synchronous with the one of the document object. β³
π est_doc_texts
est_doc_texts gets a list of sentences of the text of a document object.
const CBLIST *est_doc_texts(ESTDOC *doc);
doc specifies a document object. The return value is a list object of sentences of the text of the document object. The life duration of the returned object is synchronous with the one of the document object. β¨
π§΅ est_doc_cat_texts
est_doc_cat_texts concatenates sentences of the text of a document object.
char *est_doc_cat_texts(ESTDOC *doc);
doc specifies a document object. The return value is concatenated sentences of the document object. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. π
bestie, if it saysmalloc, you know what to do:freeit when youβre done. π
ποΈ est_doc_keywords
est_doc_keywords gets attached keywords of a document object.
CBMAP *est_doc_keywords(ESTDOC *doc);
doc specifies a document object. The return value is a map object of keywords and their scores in decimal string. If no keyword is attached, NULL is returned. The life duration of the returned object is synchronous with the one of the document object. π
π¦ est_doc_dump_draft
est_doc_dump_draft dumps draft data of a document object.
char *est_doc_dump_draft(ESTDOC *doc);
doc specifies a document object. The return value is draft data of the document object. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. π«Ά
βοΈ est_doc_make_snippet
est_doc_make_snippet makes a snippet of the body text of a document object. Snippet queen.
char *est_doc_make_snippet(ESTDOC *doc, const CBLIST *words, int wwidth, int hwidth, int awidth);
doc specifies a document object. words specifies a list object of words to be highlight. wwidth specifies whole width of the result. hwidth specifies width of strings picked up from the beginning of the text. awidth specifies width of strings picked up around each highlighted word. The return value is a snippet string of the body text of the document object. There are tab separated values. Each line is a string to be shown. Though most lines have only one field, some lines have two fields. If the second field exists, the first field is to be shown with highlighted, and the second field means its normalized form. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. π
π API FOR SEARCH CONDITIONS π
okay bestie, this whole section is about how you tell the index what you want. The API for search conditions exists to specify search conditions given to the index. Periodt.
The type of the structure ESTCOND is for abstraction of search conditions. A unit of search conditions is composed of one search phrase, some attribute expressions, and one order expression. No entity of ESTCOND is accessed directly β it's accessed by the pointer, always. So when we say "condition object," we mean the pointer and its referent, together. A condition object is created by est_cond_new and destroyed by est_cond_delete. And fr fr: every created condition object should be destroyed. Every. Single. One. π
Condition objects get used as a parameter to search for documents registered in the database, so that a list of IDs of corresponding documents is returned. (For the formats of expressions, go read the manual, iykyk.) The encoding of conditional expressions should be UTF-8. β¨
π¦ est_cond_new
The function est_cond_new is used in order to create a condition object.
ESTCOND *est_cond_new(void);
- the return value is an object of search conditions π
π est_cond_delete
The function est_cond_delete is used in order to destroy a condition object.
void est_cond_delete(ESTCOND *cond);
condspecifies a condition object.
πΈ est_cond_set_phrase
The function est_cond_set_phrase is used in order to set the search phrase to a condition object.
void est_cond_set_phrase(ESTCOND *cond, const char *phrase);
condspecifies a condition object.phrasespecifies a search phrase.
π§ est_cond_add_attr
The function est_cond_add_attr is used in order to add an expression for an attribute to a condition object.
void est_cond_add_attr(ESTCOND *cond, const char *expr);
condspecifies a condition object.exprspecifies an expression for an attribute.
π
est_cond_set_order
The function est_cond_set_order is used in order to set the order of a condition object.
void est_cond_set_order(ESTCOND *cond, const char *expr);
condspecifies a condition object.exprspecifies an expression for the order.- by default, the order is by score descending.
β est_cond_set_max
The function est_cond_set_max is used in order to set the maximum number of retrieval of a condition object.
void est_cond_set_max(ESTCOND *cond, int max);
condspecifies a condition object.maxspecifies the maximum number of retrieval.- by default, the number of retrieval is not limited.
π est_cond_set_skip
The function est_cond_set_skip is used in order to set the number of skipped documents of a condition object.
void est_cond_set_skip(ESTCOND *cond, int skip);
condspecifies a condition object.skipspecifies the number of documents to be skipped in the search result.
π₯ est_cond_set_options
The function est_cond_set_options is used in order to set options of retrieval of a condition object.
void est_cond_set_options(ESTCOND *cond, int options);
condspecifies a condition object.optionsspecifies options:ESTCONDSUREβ checks every N-gram key.ESTCONDUSUALβ the default, checks N-gram keys with skipping one key.ESTCONDFASTβ skips two keys.ESTCONDAGITOβ skips three keys.ESTCONDNOIDFβ specifies not to perform TF-IDF tuning.ESTCONDSIMPLEβ specifies to use simplified phrase.ESTCONDROUGHβ specifies to use rustic phrase.ESTCONDUNIONβ specifies to use union phrase.ESTCONDISECTβ specifies to use intersection phrase.ESTCONDSCFBβ specifies to feed back scores (only for debugging).
Each option can be specified at the same time by bitwise or. And heads up: if keys are skipped, though search speed is improved, the relevance ratio grows less. trade-offs, bestie, it's giving balance π
π est_cond_set_auxiliary
The function est_cond_set_auxiliary is used in order to set permission to adopt result of the auxiliary index.
void est_cond_set_auxiliary(ESTCOND *cond, int min);
condspecifies a condition object.minspecifies the minimum hits to adopt result of the auxiliary index.- if it is not more than
0, the auxiliary index is not used. - by default, it is
32.
π est_cond_set_eclipse
The function est_cond_set_eclipse is used in order to set the lower limit of similarity eclipse.
void est_cond_set_eclipse(ESTCOND *cond, double limit);
condspecifies a condition object.limitspecifies the lower limit of similarity for documents to be eclipsed. Similarity is between0.0and1.0.- if the limit is added by
ESTECLSIMURL, similarity is weighted by URL. - if the limit is
ESTECLSERV, similarity is ignored and documents in the same server are eclipsed. - if the limit is
ESTECLDIR, similarity is ignored and documents in the same directory are eclipsed. - if the limit is
ESTECLFILE, similarity is ignored and documents of the same file are eclipsed.
- if the limit is added by
π est_cond_set_distinct
The function est_cond_set_distinct is used in order to set the attribute distinction filter.
void est_cond_set_distinct(ESTCOND *cond, const char *name);
condspecifies a condition object.namespecifies the name of an attribute to be distinct.- if this filter is set, candidates which have same value of the attribute is omitted. (yes, dedupe by attribute, iconic π )
π est_cond_set_mask
The function est_set_cond_mask is used in order to set the mask of targets of meta search.
void est_cond_set_mask(ESTCOND *cond, int mask);
condspecifies a condition object.maskspecifies a masking number.1means the first target,2means the second target,4means the third target, and power values of 2 and their summation compose the mask.
ποΈ API FOR DATABASE ποΈ
now we're talking about the whole database of the index, bestie. The API for database aims to handle the database of the index.
The type of the structure ESTDB is for abstraction of access methods to database. A database has inverted index, document data, and meta data. One of writer or reader is selected when the connection is established. No entity of ESTDB is accessed directly β it's accessed by the pointer, same deal as before. The term "database object" means the pointer and its referent. A database object is created by est_db_open and destroyed by est_db_close. And you already know: every created database object should be destroyed. no skipping this step π
Errors with some operations are informed to by the function est_db_error. The meaning of each error code can be gotten as a string by the function est_err_msg.
The following constant are defined for error codes.
π est_err_msg
The function est_err_msg is used in order to get the string of an error code.
const char *est_err_msg(int ecode);
ecodespecifies an error code.- the return value is the string of the error code.
π¦ est_db_open
The function est_db_open is used in order to open a database.
ESTDB *est_db_open(const char *name, int omode, int *ecp);
namespecifies the name of a database directory.omodespecifies open modes:ESTDBWRITERas a writer,ESTDBREADERas a reader.- if the mode is
ESTDBWRITER, the following may be added by bitwise or:ESTDBCREATβ it creates a new database if not exist.ESTDBTRUNCβ it creates a new database regardless if one exists.
- both of
ESTDBREADERandESTDBWRITERcan be added to by bitwise or:ESTDBNOLCKβ it opens a database file without file locking.ESTDBLCKNBβ locking is performed without blocking.
- if
ESTDBNOLCKis used, the application is responsible for exclusion control. ESTDBCREATcan be added to by bitwise or:ESTDBPERFNGβ N-gram analysis is performed against European text also.ESTDBCHRCATβ character category analysis is performed instead of N-gram analysis.ESTDBSMALLβ the index is tuned to register less than50000documents.ESTDBLARGEβ the index is tuned to register more than300000documents.ESTDBHUGEβ the index is tuned to register more than1000000documents.ESTDBHUGE2β the index is tuned to register more than5000000documents.ESTDBHUGE3β the index is tuned to register more than10000000documents.ESTDBSCVOIDβ scores are stored as void.ESTDBSCINTβ scores are stored as 32-bit integer.ESTDBSCASISβ scores are stored as-is and marked not to be tuned when search.
- if the mode is
ecpspecifies the pointer to a variable to which the error code is assigned.- the return value is a database object of the database, or
NULLif failure.
π«Ά est_db_close
The function est_db_close is used in order to close a database.
int est_db_close(ESTDB *db, int *ecp);
dbspecifies a database object.ecpspecifies the pointer to a variable to which the error code is assigned.- the return value is true if success, else it is false.
πΈ est_db_error
The function est_db_error is used in order to get the last happened error code of a database.
int est_db_error(ESTDB *db);
dbspecifies a database object.- the return value is the last happened error code of the database.
π§ est_db_fatal
The function est_db_fatal is used in order to check whether a database has a fatal error.
int est_db_fatal(ESTDB *db);
dbspecifies a database object.- the return value is true if the database has fatal error, else it is false.
β est_db_add_attr_index
The function est_db_add_attr_index is used in order to add an index for narrowing or sorting with document attributes.
int est_db_add_attr_index(ESTDB *db, const char *name, int type);
dbspecifies a database object connected as a writer.namespecifies the name of an attribute.typespecifies the data type of attribute index:ESTIDXATTRSEQβ for multipurpose sequencial access method.ESTIDXATTRSTRβ for narrowing with attributes as strings.ESTIDXATTRNUMβ for narrowing with attributes as numbers.
- the return value is true if success, else it is false.
note that this function should be called before the first document is registered. like, before. don't come crying to me later π
π est_db_flush
The function est_db_flush is used in order to flush index words in the cache of a database.
int est_db_flush(ESTDB *db, int max);
dbspecifies a database object connected as a writer.maxspecifies the maximum number of words to be flushed. If it not more than zero, all words are flushed.- the return value is true if success, else it is false.
π est_db_sync
The function est_db_sync is used in order to synchronize updating contents of a database.
int est_db_sync(ESTDB *db);
dbspecifies a database object connected as a writer.- the return value is true if success, else it is false.
π₯ est_db_optimize
The function est_db_optimize is used in order to optimize a database.
β¦and hold that thought bestie, because there's more coming π
est_db_optimize π
int est_db_optimize(ESTDB *db, int options);
Okay so db is a database object thatβs connected as a writer. options is your flag zone: ESTOPTNOPURGE if you wanna skip purging the dispensable region of deleted documents, and ESTOPTNODBOPT if you wanna skip optimizing the database files. The three can be specified at the same time by bitwise or. (Yes, the original says βthreeβ but lists two. We donβt make the rules. π) The return value is true if success, else it is false.
The function est_db_merge is used in order to merge another database.
est_db_merge π¦
int est_db_merge(ESTDB *db, const char *name, int options);
db is a database object connected as a writer. name is the name of another database directory. options can be ESTMGCLEAN to clean up dispensable regions of the deleted document. The return value is true if success, else it is false. Creation options of the two databases should be same entirely. ID numbers of imported documents are changed within the sequence of the destination database. If URIs of imported documents conflict ones of existing documents, existing documents are removed.
The function est_db_put_doc is used in order to add a document to a database.
est_db_put_doc πΈ
int est_db_put_doc(ESTDB *db, ESTDOC *doc, int options);
db is a database object connected as a writer. doc is a document object. The document object should have the URI attribute. options can be ESTPDCLEAN to clean up dispensable regions of the overwritten document, or ESTPDWEIGHT to weight scores statically with score weighting attribute. The return value is true if success, else it is false. If the URI attribute is same with an existing document in the database, the existing one is deleted.
The function est_db_out_doc is used in order to remove a document from a database.
est_db_out_doc π
int est_db_out_doc(ESTDB *db, int id, int options);
db is a database object connected as a writer. id is the ID number of a registered document. options can be ESTODCLEAN to clean up dispensable regions of the deleted document. The return value is true if success, else it is false.
The function est_db_edit_doc is used in order to edit attributes of a document in a database.
est_db_edit_doc β¨
int est_db_edit_doc(ESTDB *db, ESTDOC *doc);
db is a database object connected as a writer. doc is a document object. The return value is true if success, else it is false. The ID can not be changed. If the URI is changed and it overlaps the URI of another registered document, this function fails.
The function est_db_get_doc is used in order to retrieve a document in a database.
est_db_get_doc π
ESTDOC *est_db_get_doc(ESTDB *db, int id, int options);
db is a database object. id is the ID number of a registered document. options can be ESTGDNOATTR to ignore attributes, ESTGDNOTEXT to ignore the body text, ESTGDNOKWD to ignore keywords. The two can be specified at the same time by bitwise or. (Again, βtwoβ but there are three. Weβre just vibing. π) The return value is a document object. It should be deleted with est_doc_delete if it is no longer in use. On error, NULL is returned.
The function est_db_get_doc_attr is used in order to retrieve the value of an attribute of a document in a database.
est_db_get_doc_attr π
char *est_db_get_doc_attr(ESTDB *db, int id, const char *name);
db is a database object. id is the ID number of a registered document. name is the name of an attribute. The return value is the value of the attribute or NULL if it does not exist. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use.
The function est_db_uri_to_id is used in order to get the ID of a document specified by URI.
est_db_uri_to_id π₯
int est_db_uri_to_id(ESTDB *db, const char *uri);
db is a database object. uri is the URI of a registered document. The return value is the ID of the document. On error, -1 is returned.
The function est_db_name is used in order to get the name of a database.
est_db_name π
const char *est_db_name(ESTDB *db);
db is a database object. The return value is the name of the database. The life duration of the returned string is synchronous with the one of the database object.
The function est_db_doc_num is used in order to get the number of documents in a database.
est_db_doc_num π
int est_db_doc_num(ESTDB *db);
db is a database object. The return value is the number of documents in the database.
The function est_db_word_num is used in order to get the number of unique words in a database.
est_db_word_num β
int est_db_word_num(ESTDB *db);
db is a database object. The return value is the number of unique words in the database.
The function est_db_size is used in order to get the size of a database.
est_db_size π«
double est_db_size(ESTDB *db);
db is a database object. The return value is the size of the database.
The function est_db_search is used in order to search a database for documents corresponding a condition.
est_db_search π
int *est_db_search(ESTDB *db, ESTCOND *cond, int *nump, CBMAP *hints);
db is a database object. cond is a condition object. nump is the pointer to a variable to which the number of elements in the result is assigned. hints is a map object into which the number of documents corresponding to each word is stored. If a word is in a negative condition, the number is negative. The element whose key is an empty string specifies the number of whole result. If it is NULL, it is not used. The return value is an array whose elements are ID numbers of corresponding documents. This function does never fail. Even if no document corresponds or an error occurs, an empty array is returned. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use.
Search plural databases for documents corresponding a condition.
est_db_search_meta π«Ά
int *est_db_search_meta(ESTDB **dbs, int dbnum, ESTCOND *cond, int *nump, CBMAP *hints);
dbs is an array whose elements are database objects. dbnum is the number of elements of the array. cond is a condition object. nump is the pointer to a variable to which the number of elements in the result is assigned. hints is a map object into which the number of documents corresponding to each word is stored. If a word is in a negative condition, the number is negative. The element whose key is an empty string specifies the number of whole result. If it is NULL, it is not used. The return value is an array whose elements are indexes of container databases and ID numbers of in each database alternately. This function does never fail. Even if no document corresponds or an error occurs, an empty array is returned. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use.
The function est_db_scan_doc is used in order to check whether a document object matches the phrase of a search condition object definitely.
est_db_scan_doc π§
int est_db_scan_doc(ESTDB *db, ESTDOC *doc, ESTCOND *cond);
db is a database object. doc is a document object. cond is a search condition object. The return value is true if the document matches the phrase of the condition object definitely, else it is false.
The function est_db_set_cache_size is used in order to set the maximum size of the cache memory of a database.
est_db_set_cache_size πΎ
void est_db_set_cache_size(ESTDB *db, size_t size, int anum, int tnum, int rnum);
db is a database object. size is the maximum size of the index cache. By default, it is 64MB. If it is negative, the current size is not changed. anum is the maximum number of cached records for document attributes. By default, it is 8192. If it is negative, the current size is not changed. tnum is the maximum number of cached records for document texts. By default, it is 1024. If it is negative, the current size is not changed. rnum is the maximum number of cached records for occurrence results. By default, it is 256. If it is negative, the current size is not changed.
β¨ PARALLELING β¨
Databases of Hyper Estraier are protected by file locking. While a writer is connected to a database, neither readers nor writers can be connected. While a reader is connected to a database, other readers can be connect, but writers can not.
If you use multi thread, it is suggested to use the MT-safe API of Hyper Estraier. It is a wrapper to make the core API thread-safe. As the MT-safe API provides the same functions as with the core API, the following is different.
πΈ AUTHOR πΈ
Hyper Estraier is written by Mikio Hirabayashi. You can contact the author by e-mail to <mikio@users.sourceforge.net>. Any suggestion or bug report is welcome to the author.
π«Ά ACKNOWLEDGEMENTS π«Ά
Hyper Estraier was developed under management by Fumitoshi Ukai and with support by the Exploratory Software Project of Information-technology Promotion Agency, Japan (IPA).
π COPYRIGHT π
Copyright (C) 2004-2007 Mikio Hirabayashi
Hyper Estraier is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version.
Hyper Estraier is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with Hyper Estraier; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
π₯ SEE ALSO π₯
estconfig(1), estcmd(1), estmaster(1), estcall(1), estwaver(1), cabin(3), estnode(3)
Please see http://hyperestraier.sourceforge.net/pguide-en.html for detail.
Thatβs the whole thing, bestie. This was the ESTRAIER(3) man page, dated 2007-03-06, from the Man Page collection. Mwah πβ¨
π¦ where this page comes from
- fedora 43: hyperestraier-devel 1.4.13-69.fc43 Β· LGPL-2.1-or-later AND BSD-3-Clause
- fedora 43: hyperestraier-devel 1.4.13-69.fc43 Β· LGPL-2.1-or-later AND BSD-3-Clause
- fedora 44: hyperestraier-devel 1.4.13-73.fc44 Β· LGPL-2.1-or-later AND BSD-3-Clause
- fedora 44: hyperestraier-devel 1.4.13-73.fc44 Β· LGPL-2.1-or-later AND BSD-3-Clause
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms