.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "DBIx::SearchBuilder 3pm" .TH DBIx::SearchBuilder 3pm "2021-01-24" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" DBIx::SearchBuilder \- Encapsulate SQL queries and rows in simple perl objects .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use DBIx::SearchBuilder; \& \& package My::Things; \& use base qw/DBIx::SearchBuilder/; \& \& sub _Init { \& my $self = shift; \& $self\->Table(\*(AqThings\*(Aq); \& return $self\->SUPER::_Init(@_); \& } \& \& sub NewItem { \& my $self = shift; \& # MyThing is a subclass of DBIx::SearchBuilder::Record \& return(MyThing\->new); \& } \& \& package main; \& \& use DBIx::SearchBuilder::Handle; \& my $handle = DBIx::SearchBuilder::Handle\->new(); \& $handle\->Connect( Driver => \*(AqSQLite\*(Aq, Database => "my_test_db" ); \& \& my $sb = My::Things\->new( Handle => $handle ); \& \& $sb\->Limit( FIELD => "column_1", VALUE => "matchstring" ); \& \& while ( my $record = $sb\->Next ) { \& print $record\->my_column_name(); \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides an object-oriented mechanism for retrieving and updating data in a DBI-accesible database. .PP In order to use this module, you should create a subclass of \f(CW\*(C`DBIx::SearchBuilder\*(C'\fR and a subclass of \f(CW\*(C`DBIx::SearchBuilder::Record\*(C'\fR for each table that you wish to access. (See the documentation of \f(CW\*(C`DBIx::SearchBuilder::Record\*(C'\fR for more information on subclassing it.) .PP Your \f(CW\*(C`DBIx::SearchBuilder\*(C'\fR subclass must override \f(CW\*(C`NewItem\*(C'\fR, and probably should override at least \f(CW\*(C`_Init\*(C'\fR also; at the very least, \f(CW\*(C`_Init\*(C'\fR should probably call \f(CW\*(C`_Handle\*(C'\fR and \f(CW\*(C`_Table\*(C'\fR to set the database handle (a \f(CW\*(C`DBIx::SearchBuilder::Handle\*(C'\fR object) and table name for the class. You can try to override just about every other method here, as long as you think you know what you are doing. .SH "METHOD NAMING" .IX Header "METHOD NAMING" Each method has a lower case alias; '_' is used to separate words. For example, the method \f(CW\*(C`RedoSearch\*(C'\fR has the alias \f(CW\*(C`redo_search\*(C'\fR. .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" Creates a new SearchBuilder object and immediately calls \f(CW\*(C`_Init\*(C'\fR with the same parameters that were passed to \f(CW\*(C`new\*(C'\fR. If you haven't overridden \f(CW\*(C`_Init\*(C'\fR in your subclass, this means that you should pass in a \f(CW\*(C`DBIx::SearchBuilder::Handle\*(C'\fR (or one of its subclasses) like this: .PP .Vb 1 \& my $sb = My::DBIx::SearchBuilder::Subclass\->new( Handle => $handle ); .Ve .PP However, if your subclass overrides _Init you do not need to take a Handle argument, as long as your subclass returns an appropriate handle object from the \f(CW\*(C`_Handle\*(C'\fR method. This is useful if you want all of your SearchBuilder objects to use a shared global handle and don't want to have to explicitly pass it in each time, for example. .SS "_Init" .IX Subsection "_Init" This method is called by \f(CW\*(C`new\*(C'\fR with whatever arguments were passed to \f(CW\*(C`new\*(C'\fR. By default, it takes a \f(CW\*(C`DBIx::SearchBuilder::Handle\*(C'\fR object as a \f(CW\*(C`Handle\*(C'\fR argument, although this is not necessary if your subclass overrides \f(CW\*(C`_Handle\*(C'\fR. .SS "CleanSlate" .IX Subsection "CleanSlate" This completely erases all the data in the SearchBuilder object. It's useful if a subclass is doing funky stuff to keep track of a search and wants to reset the SearchBuilder data without losing its own data; it's probably cleaner to accomplish that in a different way, though. .SS "Clone" .IX Subsection "Clone" Returns copy of the current object with all search restrictions. .SS "_ClonedAttributes" .IX Subsection "_ClonedAttributes" Returns list of the object's fields that should be copied. .PP If your subclass store references in the object that should be copied while clonning then you probably want override this method and add own values to the list. .SS "_Handle [\s-1DBH\s0]" .IX Subsection "_Handle [DBH]" Get or set this object's DBIx::SearchBuilder::Handle object. .SS "_DoSearch" .IX Subsection "_DoSearch" This internal private method actually executes the search on the database; it is called automatically the first time that you actually need results (such as a call to \f(CW\*(C`Next\*(C'\fR). .SS "AddRecord \s-1RECORD\s0" .IX Subsection "AddRecord RECORD" Adds a record object to this collection. .SS "_RecordCount" .IX Subsection "_RecordCount" This private internal method returns the number of Record objects saved as a result of the last query. .SS "_DoCount" .IX Subsection "_DoCount" This internal private method actually executes a counting operation on the database; it is used by \f(CW\*(C`Count\*(C'\fR and \f(CW\*(C`CountAll\*(C'\fR. .SS "_ApplyLimits \s-1STATEMENTREF\s0" .IX Subsection "_ApplyLimits STATEMENTREF" This routine takes a reference to a scalar containing an \s-1SQL\s0 statement. It massages the statement to limit the returned rows to only \f(CW\*(C`$self\->RowsPerPage\*(C'\fR rows, skipping \f(CW\*(C`$self\->FirstRow\*(C'\fR rows. (That is, if rows are numbered starting from 0, row number \f(CW\*(C`$self\->FirstRow\*(C'\fR will be the first row returned.) Note that it probably makes no sense to set these variables unless you are also enforcing an ordering on the rows (with \f(CW\*(C`OrderByCols\*(C'\fR, say). .SS "_DistinctQuery \s-1STATEMENTREF\s0" .IX Subsection "_DistinctQuery STATEMENTREF" This routine takes a reference to a scalar containing an \s-1SQL\s0 statement. It massages the statement to ensure a distinct result set is returned. .SS "_BuildJoins" .IX Subsection "_BuildJoins" Build up all of the joins we need to perform this query. .SS "_isJoined" .IX Subsection "_isJoined" Returns true if this SearchBuilder will be joining multiple tables together. .SS "_isLimited" .IX Subsection "_isLimited" If we've limited down this search, return true. Otherwise, return false. .SS "BuildSelectQuery" .IX Subsection "BuildSelectQuery" Builds a query string for a \*(L"\s-1SELECT\s0 rows from Tables\*(R" statement for this SearchBuilder object .SS "BuildSelectCountQuery" .IX Subsection "BuildSelectCountQuery" Builds a \s-1SELECT\s0 statement to find the number of rows this SearchBuilder object would find. .SS "Next" .IX Subsection "Next" Returns the next row from the set as an object of the type defined by sub NewItem. When the complete set has been iterated through, returns undef and resets the search such that the following call to Next will start over with the first item retrieved from the database. .SS "GotoFirstItem" .IX Subsection "GotoFirstItem" Starts the recordset counter over from the first item. The next time you call Next, you'll get the first item returned by the database, as if you'd just started iterating through the result set. .SS "GotoItem" .IX Subsection "GotoItem" Takes an integer N and sets the record iterator to N. The first time \*(L"Next\*(R" is called afterwards, it will return the Nth item found by the search. .PP You should only call GotoItem after you've already fetched at least one result or otherwise forced the search query to run (such as via \*(L"ItemsArrayRef\*(R"). If GotoItem is called before the search query is ever run, it will reset the item iterator and \*(L"Next\*(R" will return the \*(L"First\*(R" item. .SS "First" .IX Subsection "First" Returns the first item .SS "Last" .IX Subsection "Last" Returns the last item .SS "DistinctFieldValues" .IX Subsection "DistinctFieldValues" Returns list with distinct values of field. Limits on collection are accounted, so collection should be \*(L"UnLimit\*(R"ed to get values from the whole table. .PP Takes paramhash with the following keys: .IP "Field" 4 .IX Item "Field" Field name. Can be first argument without key. .IP "Order" 4 .IX Item "Order" \&'\s-1ASC\s0', '\s-1DESC\s0' or undef. Defines whether results should be sorted or not. By default results are not sorted. .IP "Max" 4 .IX Item "Max" Maximum number of elements to fetch. .SS "ItemsArrayRef" .IX Subsection "ItemsArrayRef" Return a refernece to an array containing all objects found by this search. .SS "NewItem" .IX Subsection "NewItem" NewItem must be subclassed. It is used by DBIx::SearchBuilder to create record objects for each row returned from the database. .SS "RedoSearch" .IX Subsection "RedoSearch" Takes no arguments. Tells DBIx::SearchBuilder that the next time it's asked for a record, it should requery the database .SS "UnLimit" .IX Subsection "UnLimit" UnLimit clears all restrictions and causes this object to return all rows in the primary table. .SS "Limit" .IX Subsection "Limit" Limit takes a hash of parameters with the following keys: .IP "\s-1TABLE\s0" 4 .IX Item "TABLE" Can be set to something different than this table if a join is wanted (that means we can't do recursive joins as for now). .IP "\s-1ALIAS\s0" 4 .IX Item "ALIAS" Unless \s-1ALIAS\s0 is set, the join criterias will be taken from \s-1EXT_LINKFIELD\s0 and \s-1INT_LINKFIELD\s0 and added to the criterias. If \s-1ALIAS\s0 is set, new criterias about the foreign table will be added. .IP "\s-1LEFTJOIN\s0" 4 .IX Item "LEFTJOIN" To apply the Limit inside the \s-1ON\s0 clause of a previously created left join, pass this option along with the alias returned from creating the left join. ( This is similar to using the \s-1EXPRESSION\s0 option when creating a left join but this allows you to refer to the join alias in the expression. ) .IP "\s-1FIELD\s0" 4 .IX Item "FIELD" Column to be checked against. .IP "\s-1FUNCTION\s0" 4 .IX Item "FUNCTION" Function that should be checked against or applied to the \s-1FIELD\s0 before check. See \*(L"CombineFunctionWithField\*(R" for rules. .IP "\s-1VALUE\s0" 4 .IX Item "VALUE" Should always be set and will always be quoted. .IP "\s-1OPERATOR\s0" 4 .IX Item "OPERATOR" \&\s-1OPERATOR\s0 is the \s-1SQL\s0 operator to use for this phrase. Possible choices include: .RS 4 .ie n .IP """=""" 4 .el .IP "``=''" 4 .IX Item "=" .PD 0 .ie n .IP """!=""" 4 .el .IP "``!=''" 4 .IX Item "!=" .ie n .IP """\s-1LIKE""\s0" 4 .el .IP "``\s-1LIKE''\s0" 4 .IX Item "LIKE" .PD In the case of \s-1LIKE,\s0 the string is surrounded in % signs. Yes. this is a bug. .ie n .IP """\s-1NOT LIKE""\s0" 4 .el .IP "``\s-1NOT LIKE''\s0" 4 .IX Item "NOT LIKE" .PD 0 .ie n .IP """\s-1STARTSWITH""\s0" 4 .el .IP "``\s-1STARTSWITH''\s0" 4 .IX Item "STARTSWITH" .PD \&\s-1STARTSWITH\s0 is like \s-1LIKE,\s0 except it only appends a % at the end of the string .ie n .IP """\s-1ENDSWITH""\s0" 4 .el .IP "``\s-1ENDSWITH''\s0" 4 .IX Item "ENDSWITH" \&\s-1ENDSWITH\s0 is like \s-1LIKE,\s0 except it prepends a % to the beginning of the string .ie n .IP """\s-1MATCHES""\s0" 4 .el .IP "``\s-1MATCHES''\s0" 4 .IX Item "MATCHES" \&\s-1MATCHES\s0 is equivalent to the database's \s-1LIKE\s0 \*(-- that is, it's actually \s-1LIKE,\s0 but doesn't surround the string in % signs as \s-1LIKE\s0 does. .ie n .IP """\s-1IN""\s0 and ""\s-1NOT IN""\s0" 4 .el .IP "``\s-1IN''\s0 and ``\s-1NOT IN''\s0" 4 .IX Item "IN and NOT IN" \&\s-1VALUE\s0 can be an array reference or an object inherited from this class. If it's not then it's treated as any other operator and in most cases \s-1SQL\s0 would be wrong. Values in array are considered as constants and quoted according to \s-1QUOTEVALUE.\s0 .Sp If object is passed as \s-1VALUE\s0 then its select statement is used. If no \*(L"Column\*(R" is selected then \f(CW\*(C`id\*(C'\fR is used, if more than one selected then warning is issued and first column is used. .RE .RS 4 .RE .IP "\s-1ENTRYAGGREGATOR\s0" 4 .IX Item "ENTRYAGGREGATOR" Can be \f(CW\*(C`AND\*(C'\fR or \f(CW\*(C`OR\*(C'\fR (or anything else valid to aggregate two clauses in \s-1SQL\s0). Special value is \f(CW\*(C`none\*(C'\fR which means that no entry aggregator should be used. The default value is \f(CW\*(C`OR\*(C'\fR. .IP "\s-1CASESENSITIVE\s0" 4 .IX Item "CASESENSITIVE" on some databases, such as postgres, setting \s-1CASESENSITIVE\s0 to 1 will make this search case sensitive .IP "\s-1SUBCLAUSE\s0" 4 .IX Item "SUBCLAUSE" Subclause allows you to assign tags to Limit statements. Statements with matching \s-1SUBCLAUSE\s0 tags will be grouped together in the final \s-1SQL\s0 statement. .Sp Example: .Sp Suppose you want to create Limit statements which would produce results the same as the following \s-1SQL:\s0 .Sp .Vb 1 \& SELECT * FROM Users WHERE EmailAddress OR Name OR RealName OR Email LIKE $query; .Ve .Sp You would use the following Limit statements: .Sp .Vb 3 \& $folks\->Limit( FIELD => \*(AqEmailAddress\*(Aq, OPERATOR => \*(AqLIKE\*(Aq, VALUE => "$query", SUBCLAUSE => \*(Aqgroupsearch\*(Aq); \& $folks\->Limit( FIELD => \*(AqName\*(Aq, OPERATOR => \*(AqLIKE\*(Aq, VALUE => "$query", SUBCLAUSE => \*(Aqgroupsearch\*(Aq); \& $folks\->Limit( FIELD => \*(AqRealName\*(Aq, OPERATOR => \*(AqLIKE\*(Aq, VALUE => "$query", SUBCLAUSE => \*(Aqgroupsearch\*(Aq); .Ve .SS "OrderBy \s-1PARAMHASH\s0" .IX Subsection "OrderBy PARAMHASH" Orders the returned results by \s-1ALIAS.FIELD ORDER.\s0 .PP Takes a paramhash of \s-1ALIAS, FIELD\s0 and \s-1ORDER.\s0 \&\s-1ALIAS\s0 defaults to \f(CW\*(C`main\*(C'\fR. \&\s-1FIELD\s0 has no default value. \&\s-1ORDER\s0 defaults to \s-1ASC\s0(ending). \s-1DESC\s0(ending) is also a valid value for OrderBy. .PP \&\s-1FIELD\s0 also accepts \f(CW\*(C`FUNCTION(FIELD)\*(C'\fR format. .SS "OrderByCols \s-1ARRAY\s0" .IX Subsection "OrderByCols ARRAY" OrderByCols takes an array of paramhashes of the form passed to OrderBy. The result set is ordered by the items in the array. .SS "_OrderClause" .IX Subsection "_OrderClause" returns the \s-1ORDER BY\s0 clause for the search. .SS "GroupByCols \s-1ARRAY_OF_HASHES\s0" .IX Subsection "GroupByCols ARRAY_OF_HASHES" Each hash contains the keys \s-1FIELD, FUNCTION\s0 and \s-1ALIAS.\s0 Hash combined into \s-1SQL\s0 with \*(L"CombineFunctionWithField\*(R". .SS "_GroupClause" .IX Subsection "_GroupClause" Private function to return the \*(L"\s-1GROUP BY\*(R"\s0 clause for this query. .SS "NewAlias" .IX Subsection "NewAlias" Takes the name of a table and paramhash with \s-1TYPE\s0 and \s-1DISTINCT.\s0 .PP Use \s-1TYPE\s0 equal to \f(CW\*(C`LEFT\*(C'\fR to indicate that it's \s-1LEFT JOIN.\s0 Old style way to call (see below) is also supported, but should be \&\fBavoided\fR: .PP .Vb 1 \& $records\->NewAlias(\*(AqaTable\*(Aq, \*(Aqleft\*(Aq); .Ve .PP True \s-1DISTINCT\s0 value indicates that this join keeps result set distinct and \s-1DB\s0 side distinct is not required. See also \*(L"Join\*(R". .PP Returns the string of a new Alias for that table, which can be used to Join tables or to Limit what gets found by a search. .SS "Join" .IX Subsection "Join" Join instructs DBIx::SearchBuilder to join two tables. .PP The standard form takes a param hash with keys \s-1ALIAS1, FIELD1, ALIAS2\s0 and \&\s-1FIELD2. ALIAS1\s0 and \s-1ALIAS2\s0 are column aliases obtained from \f(CW$self\fR\->NewAlias or a \f(CW$self\fR\->Limit. \s-1FIELD1\s0 and \s-1FIELD2\s0 are the fields in \s-1ALIAS1\s0 and \s-1ALIAS2\s0 that should be linked, respectively. For this type of join, this method has no return value. .PP Supplying the parameter \s-1TYPE\s0 => 'left' causes Join to preform a left join. in this case, it takes \s-1ALIAS1, FIELD1, TABLE2\s0 and \s-1FIELD2.\s0 Because of the way that left joins work, this method needs a \s-1TABLE\s0 for the second field rather than merely an alias. For this type of join, it will return the alias generated by the join. .PP Instead of \s-1ALIAS1/FIELD1,\s0 it's possible to specify \s-1EXPRESSION,\s0 to join \&\s-1ALIAS2/TABLE2\s0 on an arbitrary expression. .PP It is also possible to join to a pre-existing, already-limited DBIx::SearchBuilder object, by passing it as \s-1COLLECTION2,\s0 instead of providing an \s-1ALIAS2\s0 or \s-1TABLE2.\s0 .PP By passing true value as \s-1DISTINCT\s0 argument join can be marked distinct. If all joins are distinct then whole query is distinct and SearchBuilder can avoid \*(L"_DistinctQuery\*(R" call that can hurt performance of the query. See also \*(L"NewAlias\*(R". .SS "Pages: size and changing" .IX Subsection "Pages: size and changing" Use \*(L"RowsPerPage\*(R" to set size of pages. \*(L"NextPage\*(R", \&\*(L"PrevPage\*(R", \*(L"FirstPage\*(R" or \*(L"GotoPage\*(R" to change pages. \*(L"FirstRow\*(R" to do tricky stuff. .PP \fIRowsPerPage\fR .IX Subsection "RowsPerPage" .PP Get or set the number of rows returned by the database. .PP Takes an optional integer which restricts the # of rows returned in a result. Zero or undef argument flush back to \*(L"return all records matching current conditions\*(R". .PP Returns the current page size. .PP \fINextPage\fR .IX Subsection "NextPage" .PP Turns one page forward. .PP \fIPrevPage\fR .IX Subsection "PrevPage" .PP Turns one page backwards. .PP \fIFirstPage\fR .IX Subsection "FirstPage" .PP Jumps to the first page. .PP \fIGotoPage\fR .IX Subsection "GotoPage" .PP Takes an integer number and jumps to that page or first page if number omitted. Numbering starts from zero. .PP \fIFirstRow\fR .IX Subsection "FirstRow" .PP Get or set the first row of the result set the database should return. Takes an optional single integer argrument. Returns the currently set integer minus one (this is historical issue). .PP Usually you don't need this method. Use \*(L"RowsPerPage\*(R", \*(L"NextPage\*(R" and other methods to walk pages. It only may be helpful to get 10 records starting from 5th. .SS "_ItemsCounter" .IX Subsection "_ItemsCounter" Returns the current position in the record set. .SS "Count" .IX Subsection "Count" Returns the number of records in the set. .SS "CountAll" .IX Subsection "CountAll" Returns the total number of potential records in the set, ignoring any \&\*(L"RowsPerPage\*(R" settings. .SS "IsLast" .IX Subsection "IsLast" Returns true if the current row is the last record in the set. .SS "Column" .IX Subsection "Column" Call to specify which columns should be loaded from the table. Each calls adds one column to the set. Takes a hash with the following named arguments: .IP "\s-1FIELD\s0" 4 .IX Item "FIELD" Column name to fetch or apply function to. .IP "\s-1ALIAS\s0" 4 .IX Item "ALIAS" Alias of a table the field is in; defaults to \f(CW\*(C`main\*(C'\fR .IP "\s-1FUNCTION\s0" 4 .IX Item "FUNCTION" A \s-1SQL\s0 function that should be selected instead of \s-1FIELD\s0 or applied to it. .IP "\s-1AS\s0" 4 .IX Item "AS" The \fBcolumn\fR alias to use instead of the default. The default column alias is either the column's name (i.e. what is passed to \s-1FIELD\s0) if it is in this table (\s-1ALIAS\s0 is 'main') or an autogenerated alias. Pass \f(CW\*(C`undef\*(C'\fR to skip column aliasing entirely. .PP \&\f(CW\*(C`FIELD\*(C'\fR, \f(CW\*(C`ALIAS\*(C'\fR and \f(CW\*(C`FUNCTION\*(C'\fR are combined according to \&\*(L"CombineFunctionWithField\*(R". .PP If a \s-1FIELD\s0 is provided and it is in this table (\s-1ALIAS\s0 is 'main'), then the column named \s-1FIELD\s0 and can be accessed as usual by accessors: .PP .Vb 5 \& $articles\->Column(FIELD => \*(Aqid\*(Aq); \& $articles\->Column(FIELD => \*(AqSubject\*(Aq, FUNCTION => \*(AqSUBSTR(?, 1, 20)\*(Aq); \& my $article = $articles\->First; \& my $aid = $article\->id; \& my $subject_prefix = $article\->Subject; .Ve .PP Returns the alias used for the column. If \s-1FIELD\s0 was not provided, or was from another table, then the returned column alias should be passed to the \*(L"_Value\*(R" in DBIx::SearchBuilder::Record method to retrieve the column's result: .PP .Vb 3 \& my $time_alias = $articles\->Column(FUNCTION => \*(AqNOW()\*(Aq); \& my $article = $articles\->First; \& my $now = $article\->_Value( $time_alias ); .Ve .PP To choose the column's alias yourself, pass a value for the \s-1AS\s0 parameter (see above). Be careful not to conflict with existing column aliases. .SS "CombineFunctionWithField" .IX Subsection "CombineFunctionWithField" Takes a hash with three optional arguments: \s-1FUNCTION, FIELD\s0 and \s-1ALIAS.\s0 .PP Returns \s-1SQL\s0 with all three arguments combined according to the following rules. .IP "\(bu" 4 \&\s-1FUNCTION\s0 or undef returned when \s-1FIELD\s0 is not provided .IP "\(bu" 4 \&'main' \s-1ALIAS\s0 is used if not provided .IP "\(bu" 4 \&\s-1ALIAS.FIELD\s0 returned when \s-1FUNCTION\s0 is not provided .IP "\(bu" 4 \&\s-1NULL\s0 returned if \s-1FUNCTION\s0 is '\s-1NULL\s0' .IP "\(bu" 4 If \s-1FUNCTION\s0 contains '?' (question marks) then they are replaced with \&\s-1ALIAS.FIELD\s0 and result returned. .IP "\(bu" 4 If \s-1FUNCTION\s0 has no '(' (opening parenthesis) then \s-1ALIAS.FIELD\s0 is appended in parentheses and returned. .PP Examples: .PP .Vb 2 \& $obj\->CombineFunctionWithField() \& => undef \& \& $obj\->CombineFunctionWithField(FUNCTION => \*(AqFOO\*(Aq) \& => \*(AqFOO\*(Aq \& \& $obj\->CombineFunctionWithField(FIELD => \*(Aqfoo\*(Aq) \& => \*(Aqmain.foo\*(Aq \& \& $obj\->CombineFunctionWithField(ALIAS => \*(Aqbar\*(Aq, FIELD => \*(Aqfoo\*(Aq) \& => \*(Aqbar.foo\*(Aq \& \& $obj\->CombineFunctionWithField(FUNCTION => \*(AqFOO(?, ?)\*(Aq, FIELD => \*(Aqbar\*(Aq) \& => \*(AqFOO(main.bar, main.bar)\*(Aq \& \& $obj\->CombineFunctionWithField(FUNCTION => \*(AqFOO\*(Aq, ALIAS => \*(Aqbar\*(Aq, FIELD => \*(Aqbaz\*(Aq) \& => \*(AqFOO(bar.baz)\*(Aq \& \& $obj\->CombineFunctionWithField(FUNCTION => \*(AqNULL\*(Aq, FIELD => \*(Aqbar\*(Aq) \& => \*(AqNULL\*(Aq .Ve .SS "Columns \s-1LIST\s0" .IX Subsection "Columns LIST" Specify that we want to load only the columns in \s-1LIST\s0 .SS "AdditionalColumn" .IX Subsection "AdditionalColumn" Calls \*(L"Column\*(R", but first ensures that this table's standard columns are selected as well. Thus, each call to this method results in an additional column selected instead of replacing the default columns. .PP Takes a hash of parameters which is the same as \*(L"Column\*(R". Returns the result of calling \*(L"Column\*(R". .SS "Fields \s-1TABLE\s0" .IX Subsection "Fields TABLE" Return a list of fields in \s-1TABLE.\s0 These fields are in the case presented by the database, which may be case-sensitive. .SS "HasField { \s-1TABLE\s0 => undef, \s-1FIELD\s0 => undef }" .IX Subsection "HasField { TABLE => undef, FIELD => undef }" Returns true if \s-1TABLE\s0 has field \s-1FIELD.\s0 Return false otherwise .PP Note: Both \s-1TABLE\s0 and \s-1FIELD\s0 are case-sensitive (See: \*(L"Fields\*(R") .SS "Table [\s-1TABLE\s0]" .IX Subsection "Table [TABLE]" If called with an argument, sets this collection's table. .PP Always returns this collection's table. .SS "QueryHint [Hint]" .IX Subsection "QueryHint [Hint]" If called with an argument, sets a query hint for this collection. .PP Always returns the query hint. .PP When the query hint is included in the \s-1SQL\s0 query, the \f(CW\*(C`/* ... */\*(C'\fR will be included for you. Here's an example query hint for Oracle: .PP .Vb 1 \& $sb\->QueryHint("+CURSOR_SHARING_EXACT"); .Ve .SS "QueryHintFormatted" .IX Subsection "QueryHintFormatted" Returns the query hint formatted appropriately for inclusion in \s-1SQL\s0 queries. .SH "DEPRECATED METHODS" .IX Header "DEPRECATED METHODS" .SS "GroupBy" .IX Subsection "GroupBy" \&\s-1DEPRECATED.\s0 Alias for the \*(L"GroupByCols\*(R" method. .SS "SetTable" .IX Subsection "SetTable" \&\s-1DEPRECATED.\s0 Alias for the \*(L"Table\*(R" method. .SS "ShowRestrictions" .IX Subsection "ShowRestrictions" \&\s-1DEPRECATED AND DOES NOTHING.\s0 .SS "ImportRestrictions" .IX Subsection "ImportRestrictions" \&\s-1DEPRECATED AND DOES NOTHING.\s0 .SH "TESTING" .IX Header "TESTING" In order to test most of the features of \f(CW\*(C`DBIx::SearchBuilder\*(C'\fR, you need to provide \f(CW\*(C`make test\*(C'\fR with a test database. For each \s-1DBI\s0 driver that you would like to test, set the environment variables \f(CW\*(C`SB_TEST_FOO\*(C'\fR, \f(CW\*(C`SB_TEST_FOO_USER\*(C'\fR, and \f(CW\*(C`SB_TEST_FOO_PASS\*(C'\fR to a database name, database username, and database password, where \*(L"\s-1FOO\*(R"\s0 is the driver name in all uppercase. You can test as many drivers as you like. (The appropriate \f(CW\*(C`DBD::\*(C'\fR module needs to be installed in order for the test to work.) Note that the \f(CW\*(C`SQLite\*(C'\fR driver will automatically be tested if \f(CW\*(C`DBD::Sqlite\*(C'\fR is installed, using a temporary file as the database. For example: .PP .Vb 2 \& SB_TEST_MYSQL=test SB_TEST_MYSQL_USER=root SB_TEST_MYSQL_PASS=foo \e \& SB_TEST_PG=test SB_TEST_PG_USER=postgres make test .Ve .SH "AUTHOR" .IX Header "AUTHOR" Best Practical Solutions, \s-1LLC\s0 .SH "BUGS" .IX Header "BUGS" All bugs should be reported via email to .PP .Vb 1 \& L .Ve .PP or via the web at .PP .Vb 1 \& L. .Ve .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (C) 2001\-2014, Best Practical Solutions \s-1LLC.\s0 .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" DBIx::SearchBuilder::Handle, DBIx::SearchBuilder::Record.