view release on metacpan or  search on metacpan

lib/DBICx/MaterializedPath.pm  view on Meta::CPAN

 my @ancestors = $result_source
                      ->search({ parent => { -in => \@ancestor_ids },
                               { order_by => \"LENGTH(path)" });

We can thank the great and powerful Ovid's co-worker Mark MorganE<mdash>L<http://use.perl.org/~Ovid/journal/39460>E<mdash>for the sorting solution for ensuring the proper order of ancestors is returned.

See also I<Trees in SQL: Nested Sets and Materialized Path>, Vadim Tropashko, L<http://www.dbazine.com/oracle/or-articles/tropashko4>.

=head2 CAVEAT

This package requires your table has a single primary key and a method to look up a parent record by its single primary key.

=head1 METHODS

=over 4

=item [path method]

Whatever column you set for your materialized path. In the L</SYNOPSIS> code it is set to C<path> to match the sample table definition. The default if you don't set one is C<materialized_path>. This will, of course, cause errors if there is no such c...

=item ancestors

Searches on the materialized path ids excepting the object's own. This is generally cheap because it uses the path instead of recursion.

=item get_root

Returns the root object for a given record.

=item grandchildren

Return all children and grandchildren.

=item node_depth

Returns 1 for a record with no parent.

=item root_node

=item siblings

=item max_depth

Set this to assert a maximum tree depth. Default is 500.

=item set_materialized_path

Probably shouldn't mess with this. It's used by L</insert> and L</delete>.

=back

=head2 OVERRIDDEN METHODS

=over 4

=item insert

Sets the materialized path.

=item update

Updates which change the parent of a record necessarily cascade through all their children and grandchildren to recompute and set their new materialized paths. E.g., given this treeE<ndash>

                  1
                  |
                  3
                 / \
               12   8
              /\    /\
             5 13  7  4

You get paths including B<1/3/12/13> and B<1/3/4>. Let's say we change record 3's parent from 1 to 2E<ndash>

                  2
                  |
                  3
                 / \
               12   8
              /\    /\
             5 13  7  4

The change is simple and it's obvious you have to update record 3 but you just broke the materialized path for records 4, 5, 7, 8, 12, and 13. In a big tree you may have broken hundreds or even thousands of paths with a single parent change. So we ha...

=back

=head1 CAVEATS

If your materialized path column is insufficiently large you're going to have problems. A C<VARCHAR(255)> is only wide enough to support a tree which is 35 nodes deep if the average PK values are integers in the millions. This might be fine for your ...

=head1 TO DO

=over 4

=item Better documents; obviously.

=item More tests; what else is new?

One set with nothing changed: use default column names.

One set with everything changed.

=back

=head1 CODE REPOSITORY

L<http://github.com/pangyre/p5-dbicx-materializedpath>.

=head1 SEE ALSO

L<DBIx::Class::Ordered>, L<DBIx::Class>.

=head2 WHY NOT DBIx::Class::Ordered?

There are data sets which have implicit, or even tacit, orderingE<mdash>E<rdquo>positionE<ldquo> in L<DBIx::Class::Ordered> parlanceE<ndash> in the data already. Published articles, for example, will be naturally ordered chronologically. Additional p...

=head1 AUTHOR

Ashley Pond V E<middot> ashley.pond.v@gmail.com E<middot> L<http://pangyresoft.com>.

=head1 LICENSE

You may redistribute and modify this software under the same terms as Perl itself.