view release on metacpan or  search on metacpan

DiaColloDB/Relation/DDC.pod  view on Meta::CPAN

=item profile

 $mprf = $rel->profile($coldb, %opts);

get a relation profile for selected items as a DiaColloDB::Profile::Multi object.
%opts: as for DiaColloDB::Relation::profile(), also:

 ##-- sampling options
 limit => $limit,       ##-- maximum number of items to return from ddc; sets $qconfig{limit} (default: query "#limit[N]" or $rel->{ddcLimit})
 sample => $sample,     ##-- ddc sample size; sets $qconfig{qcount} Sample property (default: query "#sample[N]" or $rel->{ddcSample})
 cfmin => $cfmin,       ##-- minimum subcorpus frequency for returned items (default: query "#fmin[N]" or $rel->{cfmin})
 dmax  => $dmax,        ##-- maxmimum distance for implicit near() queries (default: query "#dmax[N]" or $rel->{dmax})

=item extend

 $mprf = $rel->extend($coldb, %opts);

Get independent f2 frequencies for C<$opts{slice2keys}> as a L<DiaColloDB::Profile::Multi|DiaColloDB::Profile::Multi>
object. May generate multiple DDC requests for large extension sets to avoid exceeding the underlying DDC server's
request length limit (CHost.m_maxReceiveBytes = DDC_STATC_BUFLEN ?= 4096).

=item compare

 $mprf = $rel->compare($coldb, %opts);

Get a comparison profile for selected items as a DiaColloDB::Profile::MultiDiff object.

%opts: as for DiaColloDB::Relation::compare(), also:

 ##-- sampling options
 (a|b)?limit => $limit,       ##-- maximum number of items to return from ddc; sets $qconfig{limit} (default: query "#limit[N]" or $rel->{ddcLimit})
 (a|b)?sample => $sample,     ##-- ddc sample size; sets $qconfig{qcount} Sample property (default: query "#sample[N]" or $rel->{ddcSample})
 (a|b)?cfmin => $cfmin,       ##-- minimum subcorpus frequency for returned items (default: query "#fmin[N]" or $rel->{cfmin})
 (a|b)?dmax  => $dmax,        ##-- maxmimum distance for implicit near() queries (default: query "#dmax[N]" or $rel->{dmax})

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::DDC: Utils: profiling
=pod

=head2 Utils: profiling

=over 4

=item ddcClient

 $dclient = $rel->ddcClient(%opts);

returns cached $rel-E<gt>{dclient} if defined, otherwise creates and caches a new client.
chokes if ddcServer is not defined

%opts: clobber %{$rel-E<gt>{dclient}}

=item ddcQuery

 $results = $rel->ddcQuery($coldb, $query_or_str, %opts);

Returns decoded JSON results for DDC client query $query_or_str,
optionally logging the query and tracking errors.

%opts:

 logas => $prefix,   ##-- log prefix (default: 'ddcQuery()')
 loglevel => $level, ##-- log level (default=$coldb-E<gt>{logProfile})
 limit => $limit,    ##-- set result client limit (default: current client limit, or -1 for limit=E<gt>undef)

=item fcoef

 $fcoef = $rel->fcoef($cquery);

Get expected frequency coefficient for the L<DDC::XS::CQuery|DDC::XS::CQuery> object $cquery.
Used to estimate total independent marginal frequencies (f1,f2,N) for profile construction.
The default implementation should provide reasonable guesses for common query types.

=item countQuery

 $qcount = $rel->countQuery($coldb,\%opts);

creates a L<DDC::XS::CQCount|DDC::XS::CQCount> object for profile() options %opts.
sets following keys in %opts:

 gbexprs => $gbexprs,      ##-- groupby expressions (DDC::Any::CQCountKeyExprList)
 gbrestr => $gbrestr,      ##-- groupby item2 restrictions (DDC::Any::CQWith conjunction of token expressions)
 gbfilters => \@gbfilters, ##-- groupby filter restrictions (ARRAY-ref of DDC::Any::CQFilter)
 gbtitles => \@gbtitles,   ##-- groupby column titles (ARRAY-ref of strings)
 limit  => $limit,         ##-- hit return limit for ddc query
 dslo   => $dslo,          ##-- minimum date-slice, from @opts{qw(date slice fill)}
 dshi   => $dshi,          ##-- maximum date-slice, from @opts{qw(date slice fill)}
 dlo    => $dlo,           ##-- minimum date request (ddc)
 dhi    => $dhi,           ##-- maximum date request (ddc)
 fcoef  => $fcoef,         ##-- frequency coefficient, parsed from "#coef[N]", auto-generated for near() queries
 qtemplate => $qtemplate,  ##-- query template for ddc hit link-up
 qcount1 => $qcount1,      ##-- count-query for f1 acquisition
 fcoef1 => $fcoef1,        ##-- f1 coefficient for qcount1


=item collocantCountQuery

 $qcount1 = $rel->collocantCountQuery($qcount,$matchId)

maps count-queries returned by L<countQuery()|/countQuery> to ${matchId}-item queries (default $matchid=1).

=item itemCountNode

 $nod2_or_undef = $rel->itemCountNode($nod,$matchId)

Guts for L<collocantCountQuery()|/collocantCountQuery>:
maps countQuery() nodes to ${matchId}-query nodes only;
simplifies by removing extraneous CQBinOp, CQNear, and CQSeq nodes.

=item collocateCountQueries

 \@qcounts2 = $rel->collocateCountQueries($qcount,\%slice2prf,\%opts)

Gets a list of DDC::Any::CQCount object(s) for f2-acquisition given profile() options %opts,
which are as for L<countQuery()|/countQuery>,
L<DiaColloDB::Relation::DDC::profile()|DDC::Relation/profile>, etc.
Sets following keys in %opts: