| Taxi::Mysql::Query::Base - extendable full-text index using mysql: queries: base class |
Taxi::Mysql::Query::Base - extendable full-text index using mysql: queries: base class
##======================================================================== ## PRELIMINARIES
use Taxi::Mysql::Query::Base;
##======================================================================== ## Constructors etc.
$q = $CLASS_OR_OBJ->new(%args); $q = $q->initialize();
$q2 = $q1->clone(); $qdst = $qdst->assign($qsrc); $qdst = $qdst->merge($qsrc); $qdst = $qdst->unify($qsrc);
\%tabName2vars = $query->tab2vars();
$q->clear(); $q = $q->clearCache();
##======================================================================== ## Properties
$bool = $q->ok();
##======================================================================== ## Query Construction: Utilities
$var = $q->newVariable(%args); $var = $q->newTokenVariable(); $varName = $q->setToken($varName);
$canonical_ref = $q->canonicalVariable($var); \%alias_table = $q->canonicalHash();
undef = $q->aliasVariables($varFrom=>$varTo, ...);
$conds = flatConditions($cond_string_or_ref); $conds = nestedConditions($cond_string_or_ref_or_refref); $q = $q->pushConditions(\@conditions);
##======================================================================== ## SQL: Generation
\%sql_alias = $q->_sql_alias(); $q = $q->sql_prepare();
$options_string = $q->sql_select_options(); $column_string = $q->sql_select_columns(); $table_string = $q->sql_from_tables(); $join_string = $q->sql_join_conditions(); $where_strings = $q->sql_where_conditions(); $conditions_string = $q->sql_conditions(); $sql_fragment = $q->sql_limit(%args);
$sql_query_string = $q->sql();
##======================================================================== ## SQL: execution
$q = $q->open(); $q = $q->close();
$hit = $q->fetchHit(); $hitList = $q->fetchHitList();
$q = $q->openPage($pagenum); undef = $q->closePage(); $hitList = $q->fetchPage($pagenum);
##======================================================================== ## DEBUG
$hash = $q->_debug();
Taxi::Mysql::Query::Base inherits from Taxi::Mysql::Connection.
Taxi::Mysql::Query::Base exports the utility functions
flatConditions() and nestedConditions under the tag ':child'.
Useful for derived subclasses.
$q = $CLASS_OR_OBJ->new(%args);
Low-level query constructor. Variable references in conditions, joins, etc. are strings of the form '${'.$VARNAME.'}'. See the Taxi::Mysql::MacroUtils manpage for details. Object structure / keyword %args:
{
##-- Defaults
index => $ix, ##-- underlying Taxi::MySQL object
default_table => $table, ##-- default table-suffix for token variables: default='token'
default_hit => $default_hit_col, ##-- column name for default value of $q->{hit}: default='doc'
##-- Tables and Variables
var2tab => { "$var1"=>$table1, ... }, ##-- maps *all* variable labels to Table objects
vareq => { "$var1"=>$alias1, ... }, ##-- variable alias table (canonical variable name)
toks => { "$var1"=>undef, ..., }, ##-- pseudo-set: holds all independent (token) vars
##-- Tokens and Hits: [BAD IDEAS?]
hit => $current_hit_column, ##-- identifies current hit column [may be undef]
match_table=> $match_table, ##-- matched-token table (default=$q->{default_table})
##-- Query conditions
joins => [ $join_1, ..., $join_NJ ], ##-- join conditions (AND'ed together)
conds => [
$and_1=[$or_1_1, ..., $or_1_N1], ##-- query conditions in conjunctive normal form
..., ## interp:
$and_M=[$or_M_1, ..., $or_M_NM], ## (($or_1_1,...,$or_1_N1) AND...AND ($or_M_1,...,$or_M_NM))
],
##-- Query execution
sql => $cached_sql_string, ##-- cached on $query->open(), cleared on $query->close()
pagesize => $nHitsPerPage, ##-- max number of rows to return per 'page', undef --> all rows (default)
pagenum => $pageNumber ##-- page number requested (counting from 0; default=0)
##-- inherited from Taxi::Mysql::Base
verbose=>$level, ##-- verbosity level
##-- inherited from Taxi::Mysql::Connection
handleArgs=>\%handleArgs, ##-- arguments for Taxi::Mysql::Handle->new()
## + default: inherited from $r->{index}
handle=>$handle, ##-- a Taxi::Mysql::Handle object
}
$q = $q->initialize();
Initializes a query object. Default implementation currently does nothing.
$q2 = $q1->clone();
Creates and returns a deep clone of a query object.
$qdst = $qdst->assign($qsrc);
Assigns $qdst structure to $qsrc. Structure in this sense includes variable names, join and query conditions, as well as selected hit.
$qdst = $qdst->mergeVars($qsrc)
Adopts token list, variables, and var-equivalances, from $qsrc into $qdst. Does NOT check for variable-name conflicts.
$qdst = $qdst->merge($qsrc);
``Heavy'' merge operation.
Merges variables from $qsrc into $qdst [calls $qdst->mergeVariables($qsrc))].
Merges joins from $qsrc into $qdst.
Does NOT integrate $qsrc->{conds} at all.
Used by boolean query constructors.
$qdst = $qdst->unify($qsrc);
Calls $qdst->merge($qsrc).
Attempts to alias variables from $qsrc->{toks} to corresponding variables in $qdst->{toks}.
Aliasing heuristic is sort order, which should be equivalent to macroGensym() order.
\%tabName2vars = $query->tab2vars();
Low-level method. Returns a hash keyed by table name with values sorted array-refs of (independent) variable names.
$q->clear();
Clears all query structure and cached values.
$q = $q->clearCache();
Clears query cached data.
Destructor.
$bool = $q->ok();
Checks whether query is valid. Validity tests are currently not very sophisticated, but should return quickly.
TODO: be more paranoid here.
$var = $q->newVariable(%args);
Allocate a new query-local variable string symbol.
Known %args:
table => $varTable, ##-- default: $q->{default_table}: may be name or ref
label => $varLabel, ##-- default: independent (new variable)
## + may contain 1 or more references to independent vars
tok => $bool, ##-- if true $varLabel is added to $q->{toks}
The allocated variable will have the label $varLabel (default: generated) and be bound to the index table $varTable. If the 'tok' keyword argument is given as a true value, then the new variable will be added to the pseudo-set of 'independent' variables $q->{toks}. Otherwise, if the 'tok' argument was not specified or undefined, the new variable will only be considered 'independent' if no 'label' argument was specified. In all other cases, the new variable is considered 'dependent', and therefore not added to $q->{toks}. Returns the identifier for the newly allocated variable.
$var = $q->newTokenVariable(); $var = $q->newTokenVariable($table);
Wrapper for $q->newVariable() which allocates a new independent variable
for $table.
$varName = $q->setToken($varName);
Low-level method. Sets the name of the currently 'active' independent variable $q->{tok} to $varName, and adds $varName to $q->{toks}.
$canonical_ref = $q->canonicalVariable($var);
Returns the canonical name of the variable $var.
\%alias_table = $q->canonicalHash();
Returns a HASH-ref mapping all known variable identifiers to their canonical forms. Sets $q->{_canonical}.
$undef = $q->aliasVariables($varFrom=>$varTo, ...);
Aliases $varFrom variable(s) to $varTo variable(s),
causing $varFrom and $varTo to refer to the same underlying
canonical variable.
Both $varFrom and $varTo must be independent (read: ``token'') variables for this to
work correctly.
$conds = flatConditions($cond_string_or_ref);
Utility function to ensure that an array is returned.
$conds = nestedConditions($cond_string_or_ref_or_refref);
Utility function to ensure that an array-of-arrays is returned.
$q = $q->pushConditions(\@conditions);
Pushes \@conditions onto query conditions for $q. Used for normal-form type logical connective.
$q = $q->distributeConditions(\@conditions)
Distributes \@conditions over query conditions for $q Used for non-normal-form type logical connective.
\%sql_alias = $q->_sql_alias(); \%sql_alias = $q->_sql_alias($prefix)
Generates and returns an sql-safe alias table, storing it in $q->{_sql_alias}. The generated table %sql_alias maps variable identifiers to SQL-safe table alias names. $prefix is an sql-safe alias prefix; defaults to 'tab_'.
$q = $q->sql_prepare();
Prepare query for SQL generation. Current implementation imposes the default hit restrictor, caches canonical variable forms and SQL variable aliases, as well as an SQL alias macro expansion table.
$options_string = $q->sql_select_options();
Additional options between SELECT and column list in the generated query.
@column_strings = $q->sql_select_columns(); ##-- list context $columns_string = $q->sql_select_columns(); ##-- scalar context
Returns SQL backend query column list.
@table_strings = $q->sql_from_tables(); ##-- list context; $tables_string = $q->sql_from_tables(); ##-- scalar context
Returns SQL backend query FROM tables list, with 'AS' aliases.
@join_strings = $q->sql_join_conditions(); ##-- list context; $joins_string = $q->sql_join_conditions(); ##-- scalar context
Returns SQL backend query join conditions.
NOTE join computation using the 'JOIN' keyword in the FROM tables list is slightly faster in MySQL v5.x than joining using explicit conditions in the 'WHERE' clause. MySQL v4.x seems incapable of correctly optimizing queries containing the 'JOIN' keyword however, so these strings live in the 'WHERE' clause for now.
@where_strings = $q->sql_where_conditions(); ##-- list context; $wheres_string = $q->sql_where_conditions(); ##-- scalar context
Returns query-specific restrictions for the backend WHERE clause (except for join conditions).
$conditions_string = $q->sql_conditions(); ##-- scalar context only;
Wrapper to return all conditions for the backend 'WHERE' clause.
Returns backend SQL 'GROUP BY' column list. For the current implementation, the 'GROUP BY' column list must contain exactly one column, and that column must be the primary key of some indexed table. Thus, the selected 'GROUP BY' table is also known as the 'hit container'.
Default implementation returns $q->{hit}.
$sql_query_string = $q->sql();
Generates and returns basic backend SQL query: everything except for LIMIT clause.
$sql_fragment = $q->sql_limit(%args);
Generates and returns LIMIT clause for paging options (pagesize, pagenum) in $q, which may overridden by %args.
$q = $q->open(%args);
Open a backend SQL statement handle $q->{sth} for the query, caching $q->{sth}{NAME} as $q->{sth_NAME}.
Known %args: sql, pagenum, pagesize, ...
$q = $q->close();
Closes the backend statement handle for the query (if any).
Resets $q->{pagenum} to 0 (zero).
Flushes cached values: $q->{sql}, $q->{sth_NAME}.
Drops underlying statement handle.
$hit = $q->fetchHit(%hitArgs)
Fetches and returns the next hit as a $q->{index}{hitClass} object.
Passes %hitArgs to $q->{index}{hitClass}->new().
Returns undef if no hit is available.
Returned Hit object is neither implicitly opened nor populated.
$hitList = $q->fetchHitList(); $hitList = $q->fetchHitList($hitList,%hitArgs)
Fetches and populates all available hits, returns the result as a Taxi::Mysql::HitList object.
$q = $q->openPage($pagenum);
Convenience wrapper for setting $q->{pagenum} and calling $q->open().
undef = $q->closePage();
Closes the current page by closing $q->{sth}, but does not clear any cached data.
$hitList = $q->fetchPage($pagenum); $hitList = $q->fetchPage($pagenum, $hitlist) $hitList = $q->fetchPage($pagenum, $hitlist, %hitArgs)
Convenience wrapper for openPage() and fetchHitList().
$hash = $q->_debug();
Returns a more or less human-readble string representation of the query for debugging purposes.
Perl by Larry Wall.
Bryan Jurish <moocow@ling.uni-potsdam.de>
Copyright (C) 2006 by Bryan Jurish
This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.
perl(1), Taxi::Mysql(3perl), Taxi::Mysql::Query(3perl), Taxi::Mysql::Query::Boolean(3perl), Taxi::Mysql::Query::Parser(3perl), Taxi::Mysql::Hit(3perl), Taxi::Mysql::HitList(3perl).
| Taxi::Mysql::Query::Base - extendable full-text index using mysql: queries: base class |