Yioop_V9.5_Source_Code_Documentation

__construct()

Sets up the database manager that will be used and name of the search engine database

Parameters

$db_name : string = CDB_NAME

the name of the database for the search engine

$connect : bool = true

whether to connect to the database by default after making the datasource class

Return values

beginMatch()

Matches terms (non white-char strings) in the language $lang_tag in $phrase that begin with $start_with and don't contain $not_contain, replaces $start_with with $new_prefix and adds $suffix to the end

Parameters

$phrase : string

string to look for terms in

$start_with : string

what we're looking to see if term begins with

$new_prefix : string

what to change $start_with to

$suffix : string = ""

what to tack on to the end of the term if there is a match

$not_contains : string = []

string match is not allowed to contain

$lang_tag : string = "en-US"

what language the phrase must be in for the rule to apply

Return values

boldKeywords()

Given a string, wraps in bold html tags a set of key words it contains.

Parameters

$text : string

haystack string to look for the key words

$words : array<string|int, mixed>

an array of words to bold face

Return values

clearQuerySavePoint()

A save point is used to store to disk a sequence generation-doc-offset pairs of a particular mix query when doing an archive crawl of a crawl mix. This is used so that the mix can remember where it was the next time it is invoked by the web app on the machine in question.

Parameters

$save_timestamp : int

timestamp of save point to delete

$machine_urls : array<string|int, mixed> = null

machines on which to try to delete savepoint

Return values

createIfNecessaryDirectory()

Creates a directory and sets it to world permission if it doesn't already exist

Parameters

$directory : string

name of directory to create

Return values

endMatch()

Matches terms (non white-char strings) in the language $lang_tag in $phrase that end with $end_with and don't contain $not_contain, replaces $end_with with $new_suffix (if not empty) and adds $prefix to the beginning

Parameters

$phrase : string

string to look for terms in

$end_with : string

what we're looking to see if term ends with

$prefix : string

what to tack on to the start if there is a match

$new_suffix : string = ""

what to change $end_with to

$not_contains : string = []

string match is not allowed to contain

$lang_tag : string = "en-US"

what language the phrase must be in for the rule to apply

Return values

execMachines()

This method is invoked by other ParallelModel (@see CrawlModel for examples) methods when they want to have their method performed on an array of other Yioop instances. The results returned can then be aggregated. The invocation sequence is crawlModelMethodA invokes execMachine with a list of urls of other Yioop instances. execMachine makes REST requests of those instances of the given command and optional arguments This request would be handled by a CrawlController which in turn calls crawlModelMethodA on the given Yioop instance, serializes the result and gives it back to execMachine and then back to the originally calling function.

Parameters

$command : string

the ParallelModel method to invoke on the remote Yioop instances

$machine_urls : array<string|int, mixed>

machines to invoke this command on

$arg : string = null

additional arguments to be passed to the remote machine

$num_machines : int

the integer to be used in calculating partition

$send_specs : bool = false

whether to send the queue_server, num fetcher info for given machine

$fetcher_queue_server_ratio : int = 1

maximum of the number 1 and the number of active fetchers running across all yioop instances currently divided by the number of queue servers

Return values

extractMetaWordInfo()

Given a query string, this method extracts meta words, which of these are "materialized" (i.e., should be encoded as part of word ids), disallowed phrases, the query string after meta words removed and ampersand substitution applied, the query string with meta words but apersand substitution applied, the index and the weights found as part of the query string. Finally, it extracts the locale_tag for the query

Parameters

$phrase : string

the query string

Return values

fileGetContents()

Either a wrapper for file_get_contents, or if a WebSite object is being used to serve pages, it reads it in using blocking I/O file_get_contents() and caches it before return its string contents.

Parameters

$filename : string

name of file to get contents of

$force_read : bool = false

whether to force the file to be read from persistent storage rather than the cache

Return values

filePutContents()

Either a wrapper for file_put_contents, or if a WebSite object is being used to serve pages, writes $data to the persistent file with name $filename. Saves a copy in the RAM cache if there is a copy already there.

Parameters

$filename : string

name of file to write to persistent storages

$data : string

string of data to store in file

Return values

formatSinglePageResult()

Given a page summary, extracts snippets which are related to a set of search words. For each snippet, bold faces the search terms, and then creates a new summary array.

Parameters

$page : array<string|int, mixed>

a single search result summary

$words : array<string|int, mixed> = null

keywords (typically what was searched on)

$description_length : int = self::DEFAULT_DESCRIPTION_LENGTH

length of the description

Return values

fromCallback()

Controls which tables and the names of tables underlie the given model and should be used in a getRows call This defaults to the single table whose name is whatever is before Model in the name of the model. For example, by default on FooModel this method would return "FOO". If a different behavior, this can be overridden in subclasses of Model

Parameters

$args : mixed = null

any additional arguments which should be used to determine these tables

Return values

getCrawlItem()

Get a summary of a document based on its url, the active machines and the idnex we want to look up in.

Parameters

$url : string

of summary we are trying to look-up

$machine_urls : array<string|int, mixed> = null

an array of urls of yioop queue servers

$index_name : string = ""

timestamp of the index to do the lookup in

Return values

getCrawlItems()

Gets summaries for a set of document by their url, or by group of 5-tuples of the form (machine, key, index, generation, offset).

Parameters

$lookups : string

things whose summaries we are trying to look up

$machine_urls : array<string|int, mixed> = null

an array of urls of yioop queue servers

$exclude_fields : array<string|int, mixed> = []

an array of fields which might be int the crawlItem but which should be excluded from the result. This will make the result smaller and so hopefully faster to transmit

$format_words : array<string|int, mixed> = null

words which should be highlighted in search snippets returned

$description_length : int = self::DEFAULT_DESCRIPTION_LENGTH

length of snippets to be returned for each search result

Return values

getDbmsList()

Gets a list of all DBMS that work with the search engine

Return values

getPhrasePageResults()

Given a query phrase, returns formatted document summaries of the documents that match the phrase.

Parameters

$input_phrase : string

the phrase to try to match

$low : int

return results beginning with the $low document

$results_per_page : int = CNUM_RESULTS_PER_PAGE

how many results to return

$format : bool = true

whether to highlight in the returned summaries the matched text

$filter : SearchfiltersModel = null

Model responsible for keeping track of edited and deleted search results

$use_cache_if_allowed : bool = true

if true and USE_CACHE is true then an attempt will be made to look up the results in the file cache. Otherwise, items will be recomputed and then potentially restored in cache

$raw : int

($raw == 0) normal grouping, ($raw == 1) no grouping done on data also no summaries returned (only lookup info), $raw > 1 return summaries but no grouping

$queue_servers : array<string|int, mixed> = []

a list of urls of yioop machines which might be used during lookup

$guess_semantics : bool = true

whether to do query rewriting before lookup

$save_timestamp : int

if this timestamp is nonzero, then save iterate position, so can resume on future queries that make use of the timestamp

$ranking_factors : array<string|int, mixed> = []

field say how url, keywords, and title words should influence relevance and doc rank calculations

Return values

getQueryIterator()

Using the supplied $word_structs, constructs an iterator for getting results to a query

Parameters

$word_structs : array<string|int, mixed>

an array of word_structs. Here a word_struct is an associative array with at least the following fields KEYS -- an array of word keys QUOTE_POSITIONS -- an array of positions of words that appreared in quotes (so need to be matched exactly) DISALLOW_PHRASES -- an array of words the document must not contain WEIGHT -- a weight to multiple scores returned from this iterator by INDEX_NAME -- an index timestamp to get results from

$filter : SearchfiltersModel

Model responsible for keeping track of edited and deleted search results

$raw : int

($raw == 0) normal grouping, ($raw == 1) no grouping done on data also no summaries returned (only lookup info), $raw > 1 return summaries but no grouping

$to_retrieve : int

number of items to retrieve from location in iterator

$queue_servers : array<string|int, mixed> = []

a list of urls of yioop machines which might be used during lookup

$original_query : string = ""

if set, the original query that corresponds to $word_structs

$save_timestamp_name : string = ""

if this timestamp is non empty, then when making iterator get sub-iterators to advance to gen doc_offset stored with respect to save_timestamp if exists.

$ranking_factors : array<string|int, mixed> = []

field say how url, keywords, and title words should influence relevance and doc rank calculations

Return values

getRows()

Gets a range of rows which match the provided search criteria from $th provided table

Parameters

$limit : int

starting row from the potential results to return

$num : int

number of rows after start row to return

$total : int

gets set with the total number of rows that can be returned by the given database query

$search_array : array<string|int, mixed> = []

each element of this is a quadruple name of a field, what comparison to perform, a value to check, and an order (ascending/descending) to sort by

$args : array<string|int, mixed> = null

additional values which may be used to get rows (what these are will typically depend on the subclass implementation)

Return values

getSnippets()

Given a string, extracts a snippets of text related to a given set of key words. For a given word a snippet is a window of characters to its left and right that is less than a maximum total number of characters.

Parameters

$text : string

haystack to extract snippet from

$words : array<string|int, mixed>

keywords used to make look in haystack

$description_length : string

length of the description desired

Return values

getSummariesByHash()

Gets doc summaries of documents containing given words and meeting the additional provided criteria

Parameters

$word_structs : array<string|int, mixed>

an array of word_structs. Here a word_struct is an associative array with at least the following fields KEYS -- an array of word keys QUOTE_POSITIONS -- an array of positions of words that appeared in quotes (so need to be matched exactly) DISALLOW_PHRASES -- an array of words the document must not contain WEIGHT -- a weight to multiple scores returned from this iterator by INDEX_NAME -- an index timestamp to get results from

$limit : int

number of first document in order to return

$num : int

number of documents to return summaries of

$filter : SearchfiltersModel

Model responsible for keeping track of edited and deleted search results

$use_cache_if_allowed : bool = true

if true and USE_CACHE is true then an attempt will be made to look up the results in the file cache. Otherwise, items will be recomputed and then potentially restored in cache

$raw : int

($raw == 0) normal grouping, ($raw > 0) no grouping done on data. if ($raw == 1) no lookups of summaries done

$queue_servers : array<string|int, mixed> = []

a list of urls of yioop machines which might be used during lookup

$original_query : string = ""

if set, the original query that corresponds to $word_structs

$save_timestamp_name : string = ""

if this timestamp is not empty, then save iterate position, so can resume on future queries that make use of the timestamp. If used then $limit ignored and get next $num docs after $save_timestamp 's previous iterate position.

$format_words : array<string|int, mixed> = null

words which should be highlighted in search snippets returned

$ranking_factors : array<string|int, mixed> = []

field say how url, keywords, and title words should influence relevance and doc rank calculations

Return values

getSummariesFromOffsets()

Used to lookup summary info for the pages provided (using their) self::SUMMARY_OFFSET field. If any of the lookup-ed summaries are HTTP Location redirect page's then looks these up in turn.

Parameters

$pages : array<string|int, mixed>

of page data without text summaries

$queue_servers : array<string|int, mixed>

array of queue server to find data on

$raw : int

only lookup locations if 0

$groups_with_docs : bool

whether to return only groups that contain at least one doc as opposed to a groups with only links

$with_question_answer_info : bool

whether question answer info in summaries needs to be returned

$format_words : array<string|int, mixed> = null

words which should be highlighted in search snippets returned

$description_length : int = self::DEFAULT_DESCRIPTION_LENGTH

length of snippets to be returned for each search result

Return values

getUserId()

Get the user_id associated with a given username (In base class as used as an internal method in both signin and user models)

Parameters

$username : string

the username to look up

Return values

guessSemantics()

Ideally, this function tries to guess from the query what the user is looking for. For now, we are just doing simple things like when a query term is a url and rewriting it to the appropriate meta meta word.

Parameters

$phrase : string

input query to guess semantics of

Return values

indexExists()

Returns whether there is a index with the provide timestamp

Parameters

$index_time_stamp : int

timestamp of the index to check if in cache

Return values

isSingleLocalhost()

Used to determine if an action involves just one yioop instance on the current local machine or not

Parameters

$machine_urls : array<string|int, mixed>

urls of yioop instances to which the action applies

$index_timestamp : string = -1

if timestamp exists checks if the index has declared itself to be a no network index.

Return values

loginDbms()

Returns whether the provided dbms needs a login and password or not (sqlite or sqlite3)

Parameters

$dbms : string

the name of a database management system

Return values

lookupSummaryOffsetGeneration()

Determines the offset into the summaries WebArchiveBundle and generation of the provided url (or hash_url) so that the info:url (info:base64_hash_url) summary can be retrieved. This assumes of course that the info:url meta word has been stored.

Parameters

$url_or_key : string

either info:base64_hash_url or just a url to lookup

$index_name : string = ""

index into which to do the lookup

$is_key : bool = false

whether the string is info:base64_hash_url or just a url

Return values

networkGetCrawlItems()

In a multiple queue server setting, gets summaries for a set of document by their url, or by group of 5-tuples of the form (machine, key, index, generation, offset). This makes an execMachines call to make a network request to the CrawlController's on each machine which in turn calls getCrawlItems (and thence nonNetworkGetCrawlItems) on each machine. The results are then sent back to networkGetCrawlItems and aggregated.

Parameters

$lookups : string

things whose summaries we are trying to look up

$machine_urls : array<string|int, mixed>

an array of urls of yioop queue servers

$exclude_fields : array<string|int, mixed> = []

an array of fields which might be int the crawlItem but which should be excluded from the result. This will make the result smaller and so hopefully faster to transmit

$format_words : array<string|int, mixed> = null

words which should be highlighted in search snippets returned

$description_length : int = self::DEFAULT_DESCRIPTION_LENGTH

length of snippets to be returned for each search result

Return values

nonNetworkGetCrawlItems()

Gets summaries on a particular machine for a set of document by their url, or by group of 5-tuples of the form (machine, key, index, generation, offset) This may be used in either the single queue_server setting or it may be called indirectly by a particular machine's CrawlController as part of fufilling a network-based getCrawlItems request. $lookups contains items which are to be grouped (as came from same url or site with the same cache). So this function aggregates their descriptions.

Parameters

$lookups : string

things whose summaries we are trying to look up

$exclude_fields : array<string|int, mixed> = []

an array of fields which might be in the crawlItem but which should be excluded from the result. This will make the result smaller and so hopefully faster to transmit

$format_words : array<string|int, mixed> = null

words which should be highlighted in search snippets returned

$description_length : int = self::DEFAULT_DESCRIPTION_LENGTH

length of snippets to be returned for each search result

Return values

parseIfConditions()

Evaluates any if: conditional meta-words in the query string to calculate a new query string.

Parameters

$phrase : string

original query string

Return values

parseWordStructConjunctiveQuery()

Parses from a string phrase representing a conjunctive query, a struct consisting of the words keys searched for, the allowed and disallowed phrases, the weight that should be put on these query results, and which archive to use.

Parameters

$phrase : string

string to extract struct from, if the phrase semantics is guessed or an if condition is processed the value of phrase will be altered. (Helps for feeding to network queries)

Return values

postQueryCallback()

Called after getRows has retrieved all the rows that it would retrieve but before they are returned to give one last place where they could be further manipulated. For example, in MachineModel this callback is used to make parallel network calls to get the status of each machine returned by getRows. The default for this method is to leave the rows that would be returned unchanged

Parameters

$rows : array<string|int, mixed>

that have been calculated so far by getRows

Return values

rewriteMixQuery()

Rewrites a mix query so that it maps directly to a query about crawls

Parameters

$query : string

the original before a rewrite

$mix : object

a mix object saying how the mix is built out of crawls

Return values

rowCallback()

Called after as row is retrieved by getRows from the database to perform some manipulation that would be useful for this model.

Parameters

$row : array<string|int, mixed>

row as retrieved from database query

$args : mixed

additional arguments that might be used by this callback

Return values

searchArrayToWhereOrderClauses()

Creates the WHERE and ORDER BY clauses for a query of a Yioop table such as USERS, ROLE, GROUP, which have associated search web forms. Searches are case insensitive

Parameters

$search_array : array<string|int, mixed>

each element of this is a quadruple name of a field, what comparison to perform, a value to check, and an order (ascending/descending) to sort by

$any_fields : array<string|int, mixed> = ['status']

these fields if present in search array but with value "-1" will be skipped as part of the where clause but will be used for order by clause

Return values

selectCallback()

Controls which columns and the names of those columns from the tables underlying the given model should be return from a getRows call.

Parameters

$args : mixed = null

any additional arguments which should be used to determine the columns

Return values

translateDb()

Used to get the translation of a string_id stored in the database to the given locale.

Parameters

$string_id : string

id to translate

$locale_tag : string

to translate to

Return values

whereCallback()

Controls the WHERE clause of the SQL query that underlies the given model and should be used in a getRows call.

Parameters

$args : mixed = null

additional arguments that might be used to construct the WHERE clause.

Return values