/ 
Pg-Explain-2.7
River stage zero No dependents
/ Pg::Explain

NAME

Pg::Explain - Object approach at reading explain analyze output

VERSION

Version 2.7

SYNOPSIS

Quick summary of what the module does.

Perhaps a little code snippet.

use Pg::Explain;

my $explain = Pg::Explain->new('source_file' => 'some_file.out');
...

my $explain = Pg::Explain->new(
    'source' => 'Seq Scan on tenk1  (cost=0.00..333.00 rows=10000 width=148)'
);
...

FUNCTIONS

source_format

What is the detected format of source plan. One of: TEXT, JSON, YAML, OR XML.

planning_time

How much time PostgreSQL spent planning the query. In milliseconds.

total_buffers

All buffers used by query - for planning and execution. Mathematically: sum of planning_buffers and top_level->buffers.

planning_buffers

How much buffers PostgreSQL used for planning. Either undef or object of Pg::Explain::Buffers class.

execution_time

How much time PostgreSQL spent executing the query. In milliseconds.

total_runtime

How much time PostgreSQL spent working on this query. This was part of EXPLAIN OUTPUT only for PostgreSQL 9.3 or older.

trigger_times

Information about triggers that were called during execution of this query. Array of hashes, where each hash can contains:

  • name - name of the trigger

  • calls - how many times it was called

  • time - total time spent in all executions of this trigger

jit

Contains information about JIT timings, as object of Pg::Explain::JIT class.

If there was no JIT info, it will return undef.

query

What query this explain is for. This is available only for auto-explain plans. If not available, it will be undef.

settings

If explain contains information about specific settings that were changed in Pg, this hashref will contain it.

If there are none - if will be undef.

add_trigger_time

Adds new information about trigger time.

It will be available at $node->trigger_times (returns arrayref)

runtime

How long did the query run. Tries to get the value from various sources (total_runtime, execution_time, or top_node->actual_time_last).

node

Returns node with given id from current explain.

If there is second argument present, and it's Pg::Explain::Node object, it sets internal cache for this id and this node.

source

Returns original source (text version) of explain.

source_filtered

Returns filtered source explain.

Currently there are only two filters:

  • remove quotes added by pgAdmin3

  • remove + character at the end of line, added by default psql config.

new

Object constructor.

Takes one of (only one!) (source, source_file) parameters, and either parses it from given source, or first reads given file.

top_node

This method returns the top node of parsed plan.

For example - in this plan:

                          QUERY PLAN
--------------------------------------------------------------
 Limit  (cost=0.00..0.01 rows=1 width=4)
   ->  Seq Scan on test  (cost=0.00..14.00 rows=1000 width=4)

top_node is Pg::Explain::Node element with type set to 'Limit'.

Generally every output of plans should start with ->top_node(), and descend recursively in it, using subplans(), initplans() and sub_nodes() methods.

parse_source

Internally (from ->BUILD()) called function which checks which parser to use (text, json, xml, yaml), runs appropriate function, and stores top level node in $self->top_node.

check_for_exclusive_time_fixes

Certain types of nodes (CTE Scans, and InitPlans) can cause issues with "naive" calculations of node exclusive time.

To fix that whole tree will be scanned, and, if neccessary, node->exclusive_fix will be modified.

check_for_exclusive_time_fixes_cte

Modifies node->exclusive_fix according to times that were used by CTEs.

check_for_exclusive_time_fixes_init

Modifies node->exclusive_fix according to times that were used by InitScans.

check_for_parallelism

Handles parallelism by setting "force_loops" if plan is analyzed and there are gather nodes.

Generally, for each

_read_source_from_file

Helper function to read source from file.

as_text

Returns parsed plan back as plain text format (regenerated from in-memory structure).

This is mostly useful for (future at the moment) anonymizations.

get_struct

Function which returns simple, not blessed, hashref with all information about the explain.

This can be used for debug purposes, or as a base to print information to user.

Output looks like this:

{
    'top_node'               => {...}
    'planning_time'          => '12.44',
    'planning_buffers'       => {...},
    'execution_time'         => '12.44',
    'total_runtime'          => '12.44',
    'trigger_times'          => [
       { 'name' => ..., 'time' => ..., 'calls' => ... },
       ...
    ],
}

anonymize

Used to remove all individual values from the explain, while still retaining all values that are needed to see what's wrong.

If there are any arguments, these are treated as strings, anonymized using anonymizer used for plan, and are returned in the same order.

This is mainly useful to anonymize queries.

AUTHOR

hubert depesz lubaczewski, <depesz at depesz.com>

BUGS

Please report any bugs or feature requests to depesz at depesz.com.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Pg::Explain

COPYRIGHT & LICENSE

Copyright 2008-2023 hubert depesz lubaczewski, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.