DlfQuery(3pm)

NAME
Lire::DlfQuery - Interface to specialized SQL wrappers used internally by the Lire API.

SYNOPSIS
  use Lire::DlfQuery;

DESCRIPTION

  new( $stream_name )
This is the constructor method for the Lire::DlfQuery class. It takes a dlf stream name and a Lire::DlfStore object as parameters. Lire::DlfStore is expected to contain the specified stream. Both parameters are mandatory. This method returns an instance of Lire::DlfQuery.

  stream_name()
Returns the DLF stream's name upon which this DlfQuery is defined.

  join_stream( $stream_name )
This method can be used to add an ExtendedSchema stream which will be joined in the query.

  joined_streams()
Returns as an array reference all the streams that are part of the query.

  release()
Nested DlfQuery introduce a circular reference between the children and the parent. Call release() on the top-level DlfQuery to remove the circular when the DlfQuery object isn't needed anymore, so that perl can garbage collect the objects.

  create_nested_query()
This method will create and return an instance of Lire::DlfQuery nested within the current query. The returned query will be modified later with regular methods.

  nested_queries()
This method returns a reference to an array containing all the nested queries of the current query.

  has_field( $field_name )
Returns true if there is a field $field_name defined in the query.

  field_def( $field_name )
Returns the SQL expression that is associated with the field $field_name in the query. This method will throw an exception if there is no field $field_name defined in the query.

  fields()
Returns the name of the fields defined as simple fields in an array reference. These are fields added through the add_field() method.

  group_fields()
Returns the name of the fields defined as group fields in an array reference. These are fields added through the add_group_field() method.

  aggr_fields()
Returns the name of the fields defined as aggregate fields in an array reference. These are fields added through the add_aggr_field() method.

  add_field( $field_name, $expr )
Add a simple field to the current query. The first parameter will be the field name. The second represents an expression that will then be aliased with the specified field name. Only the field name is mandatory.

Certain restrictions apply: simple fields cannot be added to queries containing either subqueries or group fields.

  add_aggr_field( $field_name, $aggregate )
Add a group field to the current query. The first parameter will be the field name. The second represents the aggregate expression that will then be aliased with the specified field name. Both parameters are mandatory.

Aggregate field can only be added to queries which contain group fields.

  add_group_field( $field_name, $expr )
Add a group field to the current query. The first parameter will be the field name. The second represents an expression that will then be aliased with the specified field name. Only the field name is mandatory.

Certain restrictions apply: group fields cannot be added to queries containing simple fields.

  set_order_by_clause( $clause )
Sets the order clause of the query, that is, what will appear in the "ORDER BY" clause of the SQL statement.

  order_by_clause()
Returns the current ORDER BY clause or undef when none was set.

  set_sort_spec( $spec )

  sort_spec()
Returns the sort specification that was set using set_sort_spec(). If no sort specification was set (or it was set using the set_order_by_clause() method), this will be undef.

  set_limit()
Sets the limit clause of the query, that is, what will appear in the "LIMIT" clause of the SQL statement. This method will also have an impact on the internal handling of the query.

  limit()
Returns the maximum number of records that should be returned by the query. When no limit was set, it returns 0.

  set_filter_clause( $clause, @params )
Sets the filter clause of the query, the filter clause being the SQL restrictions on the results that will be return by the query, i.e. what will appear in the "WHERE" clause of the SQL statement.

It is compatible with the DBI handling of placeholders ('?'). Of course, the amount of placeholders has to be the same of the amount of values and variables that are passed in @params.

Only the clause parameter is mandatory, the number of elements in @params being dependent on the amount of placeholders specified therein.

  filter_clause()
Returns the current WHERE clause or undef when none was set.

  execute()
This method executes the query through the database interface and returns an instance of Lire::DlfResult to obtain the data.

  execute_summary()
Same as the execute() except that the query is executed as a summary query.

SEE ALSO
Lire::DlfQuery(3pm) Lire::DlfStream(3pm) Lire::DlfStore(3pm)

AUTHORS
  Francis J. Lacoste <flacoste@logreport.org>
  Wolfgang Sourdeau <Wolfgang.Sourdeau@Contre.COM>

VERSION
$Id: DlfQuery.pm,v 1.44 2006/07/23 13:16:28 vanbaal Exp $

COPYRIGHT
Copyright (C) 2003 Stichting LogReport Foundation LogReport@LogReport.org

This file is part of Lire.

Lire is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program 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 General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (see COPYING); if not, check with http://www.gnu.org/copyleft/gpl.html.