DlfQuery(3pm)

📦 version 2.1.1, in arch rolling

💖 Lire::DlfQuery — SQL wrapper bestie energy 💖

okay bestie, welcome to the DlfQuery(3pm) page from LogReport's Lire Documentation. This class is the interface to the specialized SQL wrappers that the Lire API uses internally. iykyk 💅

🎀 NAME 🎀

Lire::DlfQuery — the interface to the specialized SQL wrappers used internally by the Lire API. That's the whole vibe: it's a behind-the-scenes SQL helper, not a main-character public API. 🫶

✨ SYNOPSIS ✨

Drop this in and you're in:

use Lire::DlfQuery;

💅 DESCRIPTION 💅

Okay, here's the method tea ☕ — each one is a little building block for queries.

`new( $stream_name )`

Constructor vibes 🎀. The signature says new( $stream_name ), and the actual tea is that it takes a dlf stream name and a Lire::DlfStore object as parameters. That Lire::DlfStore is expected to contain the specified stream. Both parameters are mandatory — no skipping, bestie. It returns an instance of Lire::DlfQuery.

`stream_name()`

Returns the DLF stream's name that this DlfQuery is defined on. Literally what it says on the label. ✨

`join_stream( $stream_name )`

Use this to add an ExtendedSchema stream that will be joined in the query. Teamwork makes the query work 🌈.

`joined_streams()`

Returns a reference to an array of all the streams that are part of the query. All the joined besties in one list 💖.

`release()`

Nested DlfQuery objects create a circular reference between the children and the parent. Important: call release() on the top-level DlfQuery to remove the circular reference when the DlfQuery object isn't needed anymore, so Perl can garbage collect the objects. Don't let them ghost each other forever 👻.

`create_nested_query()`

Creates and returns an instance of Lire::DlfQuery nested inside the current query. The returned query gets modified later with regular methods. It's giving query inception 🌀.

`nested_queries()`

Returns a reference to an array containing all the nested queries of the current query. All the baby queries in one place 👑.

`has_field( $field_name )`

Returns true if a field named $field_name is defined in the query. A little vibe check for fields ✅.

`field_def( $field_name )`

Returns the SQL expression associated with the field $field_name in the query. If there's no field $field_name defined in the query, this method throws an exception — so bestie, check before you ask 😭.

`fields()`

Returns the names of the fields defined as simple fields, as an array reference. These are the fields added through the add_field() method. Simple-field squad 🎀.

`group_fields()`

Returns the names of the fields defined as group fields, as an array reference. These are the fields added through the add_group_field() method. Group-field gang 💅.

`aggr_fields()`

Returns the names of the fields defined as aggregate fields, as an array reference. These are the fields added through the add_aggr_field() method. Aggregate-field agenda ✨.

`add_field( $field_name, $expr )`

Adds a simple field to the current query. First parameter is the field name. Second parameter is an expression that gets aliased with that field name. Only the field name is mandatory.

Certain restrictions apply: simple fields cannot be added to queries containing either subqueries or group fields. So no mixing simple fields into subquery/group-field situations — that's the rule 🚫.

`add_aggr_field( $field_name, $aggregate )`

Adds a group field to the current query. First parameter is the field name. Second parameter is the aggregate expression that gets aliased with the specified field name. Both parameters are mandatory — no half-sending this one.

Aggregate fields can only be added to queries that contain group fields. Periodt. 👑

`add_group_field( $field_name, $expr )`

Adds a group field to the current query. First parameter is the field name. Second parameter is an expression that gets 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. No cap 🧢.

`set_order_by_clause( $clause )`

Sets the order clause of the query — meaning the thing that will appear in the "ORDER BY" clause of the SQL statement. Put it in order, bestie 📋.

`order_by_clause()`

Returns the current ORDER BY clause, or undef when none was set. If it's not set, it's not set 🫠.

`set_sort_spec( $spec )` and `sort_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. Sorting lore unlocked 🔓.

`set_limit()`

Sets the limit clause of the query — what will appear in the "LIMIT" clause of the SQL statement. This method also has an impact on the internal handling of the query. Limit it, but make it cute ✨.

`limit()`

Returns the maximum number of records that should be returned by the query. When no limit was set, it returns 0. Zero means no limit was set here, bestie 🫶.

`set_filter_clause( $clause, @params )`

Sets the filter clause of the query. The filter clause is the SQL restrictions on the results that will be returned by the query — i.e. what will appear in the "WHERE" clause of the SQL statement.

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

Only the $clause parameter is mandatory; the number of elements in @params depends on the amount of placeholders specified in the clause. Filtering, but make it database-safe 💅.

`filter_clause()`

Returns the current WHERE clause, or undef when none was set. WHERE my filter at? 🤔

`execute()`

Executes the query through the database interface and returns an instance of Lire::DlfResult so you can obtain the data. Go off, query 🔥.

`execute_summary()`

Same as execute(), except the query is executed as a summary query. Summary mode activated 📊.

🌈 SEE ALSO 🌈

Check these out too, bestie:

👑 AUTHORS 👑

Shoutout to the authors 👑:

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

💜 VERSION 💜

The version line is literally this string:

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

🍓 COPYRIGHT 🍓

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.

that's the whole page, bestie! This manual is Lire 2.1.1, dated 2025-09-28, and it's the DlfQuery(3pm) page. Bye 🫶💖

📦 where this page comes from

arch rolling: lire 2.1.1-8 · GPL-2.0-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

DlfQuery(3pm)

💖 Lire::DlfQuery — SQL wrapper bestie energy 💖

🎀 NAME 🎀

✨ SYNOPSIS ✨

💅 DESCRIPTION 💅

new( $stream_name )

stream_name()

join_stream( $stream_name )

joined_streams()

release()

create_nested_query()

nested_queries()

has_field( $field_name )

field_def( $field_name )

fields()

group_fields()

aggr_fields()

add_field( $field_name, $expr )

add_aggr_field( $field_name, $aggregate )

add_group_field( $field_name, $expr )

set_order_by_clause( $clause )

order_by_clause()

set_sort_spec( $spec ) and sort_spec()

set_limit()

limit()

set_filter_clause( $clause, @params )

filter_clause()

execute()

execute_summary()