Difference between revisions of "API:EPrints/Search"

From EPrints Documentation
Jump to: navigation, search
(add_field)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Search.pm|package_name=EPrints::Search}}[[Category:API|SEARCH]][[Category:API:EPrints/Search|SEARCH]]<div><!-- Edit below this comment -->
__NOTOC__
 
{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/Search.pm|package_name=EPrints::Search}}[[Category:API|Search]]<div><!-- Edit below this comment -->
 
  
  
<!-- Pod2Wiki=head_name --></div>
+
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
==NAME==
 
==NAME==
'''EPrints::Search''' - Represents a single search
+
EPrints::Search - retrieve objects based on search criteria
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_description --></div>
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_description -->
 
==DESCRIPTION==
 
==DESCRIPTION==
The Search object represents the conditions of a single search.
+
The Search object represents the conditions of a single search.
  
It used to also store the results of the search, but now it returns an [[API:EPrints/List|EPrints::List]] object.  
+
Executing a search returns an [[API:EPrints/List|EPrints::List]] object.
  
 
A search expression can also render itself as a web-form, populate itself with values from that web-form and render the results as a web page.
 
A search expression can also render itself as a web-form, populate itself with values from that web-form and render the results as a web page.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
[[API:EPrints/Plugin/Search|EPrints::Plugin::Search]] provides a pluggable architecture for searching EPrints.
<h4><span style='display:none'>User Comments</span></h4>
+
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_examples --></div>
+
<!-- Pod2Wiki= -->
==EXAMPLES==
+
<!-- Pod2Wiki=head_synopsis -->
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
==SYNOPSIS==
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_searching_for_eprints --></div>
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_searching_for_eprints -->
 
===Searching for Eprints===
 
===Searching for Eprints===
  $ds = $session-&gt;get_repository-&gt;get_dataset( "archive" );
+
<pre>  $ds = $repo-&gt;dataset( "archive" );
 
    
 
    
   $searchexp = EPrints::Search-&gt;new(
+
  # NB 'archive' is an implicit filter on eprint.status
    satisfy_all =&gt; 1,
+
   $list = $ds->search(filters => [{
     session =&gt; $session,
+
     meta_fields => [qw( eprintid )], value => 23,
    dataset =&gt; $ds,
+
   }]);
   );
 
 
    
 
    
  # Search for an eprint with eprintid 23
+
   $list = $ds->search(search_fields => [{
  # (ought to use EPrints::DataObj::EPrint-&gt;new( SESSION, ID ))
+
    meta_fields => [qw( creators_name )], value => "John Smith",
   $searchexp-&gt;add_field( $ds-&gt;get_field( "eprintid" ), 23 );
+
  }]);
 
    
 
    
   $searchexp-&gt;add_field( $ds-&gt;get_field( "creators" ), "John Smith" );
+
   $searchexp = $ds->prepare_search();
    
+
  $searchexp->add_field(
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
    fields => [
<h4><span style='display:none'>User Comments</span></h4>
+
      $ds->field('creators_name')
 +
    ],
 +
    value => "John Smith",
 +
    match => "EQ", # EQuals
 +
  );
 +
   $searchexp->add_field(
 +
    fields => [
 +
      $ds->field('title')
 +
    ],
 +
    value => "eagle buzzard",
 +
    match => "IN", # INdex
 +
  );</pre>
 +
 
 +
See [[API:EPrints/DataSet|EPrints::DataSet]] for more API methods for constructing search objects.
 +
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_getting_results --></div>
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_getting_results -->
 
===Getting Results===
 
===Getting Results===
  $results = $searchexp-&gt;perform_search;
+
<pre>  $list = $searchexp-&gt;perform_search;
 
    
 
    
   my $count = $results-&gt;count;
+
   my $count = $list->count;
 
    
 
    
   my $ids = $results-&gt;ids( 0, 10 );
+
   my $ids = $results->ids( 0, 10 );
   my $ids = $results-&gt;ids; # Get all matching ids
+
   my $ids = $results->ids; # Get all matching ids
 
    
 
    
   my $info = { matches =&gt; 0 };
+
   my $info = { matches => 0 };
 
   sub fn {
 
   sub fn {
 
     my( $session, $dataset, $eprint, $info ) = @_;
 
     my( $session, $dataset, $eprint, $info ) = @_;
     $info-&gt;{matches}++;
+
     $info->{matches}++;
 
   };
 
   };
   $results-&gt;map( \&amp;fn, $info );
+
   $list->map( \&fn, $info );</pre>
 
+
 
  $results-&gt;dispose;
 
 
 
 
See [[API:EPrints/List|EPrints::List]] for more.
 
See [[API:EPrints/List|EPrints::List]] for more.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_methods --></div>
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_methods -->
 
==METHODS==
 
==METHODS==
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<!-- Pod2Wiki=head_new -->
<h4><span style='display:none'>User Comments</span></h4>
+
===new===
<!-- Edit below this comment -->
 
 
 
  
<!-- Pod2Wiki=item_new --></div>
+
<source lang="perl">$searchexp = EPrints::Search->new( %params )
===$searchexp = EPrints::Search-&gt;new( %params )===
 
  
 +
</source>
 
Create a new search expression.
 
Create a new search expression.
  
Line 97: Line 103:
 
GENERAL PARAMETERS
 
GENERAL PARAMETERS
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* session (required)
<h4><span style='display:none'>User Comments</span></h4>
+
: The current [[API:EPrints/Session|EPrints::Session]]
<!-- Edit below this comment -->
 
  
 +
* dataset OR dataset_id (required)
 +
: Either the [[API:EPrints/DataSet|EPrints::DataSet]] to search, or the ID of it.
  
<!-- Pod2Wiki=item_session --></div>
+
* allow_blank (default 0)
===session (required)===
+
: Unless this is set, a search with no conditions will return zero records  rather than all records.
  
The current [[API:EPrints/Session|EPrints::Session]]
+
* satisfy_all (default 1)
 +
: If this is true than all search-fields much be satisfied, if false then  results matching any search-field will be returned.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* search_fields
<h4><span style='display:none'>User Comments</span></h4>
+
: A reference to an array of search field configuration structures. Each takes the form { id=&gt;"...", default=&gt;"..", meta_fields=&gt;"..." } where the meaning is the same as for search configuration in ArchiveConfig.
<!-- Edit below this comment -->
 
  
 +
: Search fields can also be added to the search expression after it has been constructed.
  
<!-- Pod2Wiki=item_dataset_id --></div>
+
* order
===dataset OR dataset_id (required)===
+
: The order the results should be returned. This is a key to the list of orders available to this dataset, defined in ArchiveConfig.pm
  
Either the [[API:EPrints/DataSet|EPrints::DataSet]] to search, or the ID of it.
+
* custom_order
 +
: "order" limits you to the orders specified in ArchiveConfig, and is usually used by the web page based searching. custom_order allows you to specify any order you like. The format is  foo/-bar. This means that the results will be sorted by foo and then any with equal foo values will be reverse sorted by bar. More than 2 fields can be specified.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* keep_cache
<h4><span style='display:none'>User Comments</span></h4>
+
: If true then the search results produced will be stored in the database even after the current script ends. This is useful for speeding up page 2 onwards of a search.
<!-- Edit below this comment -->
 
  
 +
: keep_cache may get set to true anyway for various reasons, but setting the parameter makes certain of it.
  
<!-- Pod2Wiki=item_allow_blank --></div>
+
* cache_id
===allow_blank (default 0)===
+
: The ID of a cached search. The cache contains both the results of the search, and the parameters used for the search.
  
Unless this is set, a search with no conditions will return zero records rather than all records.
+
: If the cache still exists, it will set the default values of the  search fields, and when the search is performed it will skip the search and build a search results object directly from the cache.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* limit
<h4><span style='display:none'>User Comments</span></h4>
+
: Limit the number of matching records to limit.
<!-- Edit below this comment -->
 
  
 +
WEB PAGE RELATED PARAMETERS
  
<!-- Pod2Wiki=item_satisfy_all --></div>
+
* prefix (default "")
===satisfy_all (default 1)===
+
: When generating the web form and reading back from the web form, the prefix is inserted before the form names of all fields. This is useful if you need to put two search expressions in a single form for some reason.
  
If this is true than all search-fields much be satisfied, if false then  results matching any search-field will be returned.
+
* staff (default 0)
 +
: If true then this is a "staff" search, which prevents searching unless the user is staff, and the results link to the staff URL of an item rather than the public URL.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* filters
<h4><span style='display:none'>User Comments</span></h4>
+
: A reference to an array of filter definitions.
<!-- Edit below this comment -->
 
  
 +
: Filter definitions take the form of: { value=&gt;"..", match=&gt;"..", merge=&gt;"..", id=&gt;".." } and work much like normal search fields except that they do not appear in the web form so force certain search parameters on the user.
  
<!-- Pod2Wiki=item_search_fields --></div>
+
: An optional parameter of describe=&gt;0 can be set to supress the filter being mentioned in the description of the search.
===search_fields===
 
  
A reference to an array of search field configuration structures. Each  takes the form { id=&gt;"...", default=&gt;"..", meta_fields=&gt;"..." } where the meaning is the same as for search configuration in ArchiveConfig.
+
<!-- Edit below this comment -->
  
Search fields can also be added to the search expression after it has been constructed.
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<!-- Pod2Wiki= -->
<h4><span style='display:none'>User Comments</span></h4>
+
<!-- Pod2Wiki=head_from_cache -->
<!-- Edit below this comment -->
+
===from_cache===
  
 +
<source lang="perl">$ok = $thing->from_cache( $id )
  
<!-- Pod2Wiki=item_order --></div>
+
</source>
===order===
+
Populate this search expression with values from the given cache.
  
The order the results should be returned. This is a key to the list of orders available to this dataset, defined in ArchiveConfig.pm
+
Return false if the cache does not exist.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_custom_order --></div>
+
<!-- Pod2Wiki= -->
===custom_order===
+
<!-- Pod2Wiki=head_add_field -->
 
+
===add_field===
"order" limits you to the orders specified in ArchiveConfig, and is usually used by the web page based searching. custom_order allows you to specify any order you like. The format is  foo/-bar. This means that the results will be sorted by foo and then any with equal foo values will be reverse sorted by bar. More than 2 fields can be specified.
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
  
 +
<source lang="perl">$searchfield = $searchexp->add_field( %opts )
  
<!-- Pod2Wiki=item_keep_cache --></div>
+
</source>
===keep_cache===
+
<pre>  fields - one or more fields to search over
 +
  match - match type
 +
  merge - merge type
 +
  value - value to match against (for EX matches, NULL = is_null!)
 +
  id - search field id, if not the name of the first field
 +
  filter - is filter-type
 +
  show_help - show help in search input</pre>
  
If true then the search results produced will be stored in the database even after the current script ends. This is useful for speeding up  page 2 onwards of a search.
+
Adds a new search in $fields which is either a single [[API:EPrints/MetaField|EPrints::MetaField]] or a list of fields in an array ref with default $value. If a search field already exists, the value of that field is replaced with $value.
  
keep_cache may get set to true anyway for various reasons, but setting the parameter makes certain of it.
+
See [[API:EPrints/Search/Field|EPrints::Search::Field]] for details on match/merge etc.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
 +
Note relating to the <code>for EX matches, NULL = is_null</code> documentation above.
  
<!-- Pod2Wiki=item_cache_id --></div>
+
To search for items with no value, use something similar to this - explicitly setting the value to undef.:
===cache_id===
+
<source lang="perl">
 +
### Example: search for items in the review area with no date set.
 +
my $ds = $session->dataset( "buffer" );
 +
my $searchexp = $ds->prepare_search();
 +
$searchexp->add_field(
 +
    fields => [
 +
      $ds->field( 'date' ),
 +
    ],
 +
    value => undef,
 +
    match => "EX",
 +
);
 +
</source>
  
The ID of a cached search. The cache contains both the results of the search, and the parameters used for the search.
 
  
If the cache still exists, it will set the default values of the  search fields, and when the search is performed it will skip the  search and build a search results object directly from the cache.
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_clear -->
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
===clear===
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
  
 +
<source lang="perl">$searchexp->clear
  
<!-- Pod2Wiki=item_limit --></div>
+
</source>
===limit===
+
Clear the search values of all search fields in the expression.
  
Limit the number of matching records to limit.
+
Resets satisfy_all to true.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_prefix --></div>
+
<!-- Pod2Wiki= -->
===prefix (default "")===
+
<!-- Pod2Wiki=head_get_satisfy_all -->
 +
===get_satisfy_all===
  
When generating the web form and reading back from the web form, the prefix is inserted before the form names of all fields. This is useful if you need to put two search expressions in a single form for some reason.
+
<source lang="perl">$bool = $searchexp->get_satisfy_all
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
</source>
<h4><span style='display:none'>User Comments</span></h4>
+
Return true if this search requires that all the search fields with values are satisfied.
<!-- Edit below this comment -->
 
  
 
<!-- Pod2Wiki=item_staff --></div>
 
===staff (default 0)===
 
 
If true then this is a "staff" search, which prevents searching unless the user is staff, and the results link to the staff URL of an item rather than the public URL.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_filters --></div>
+
<!-- Pod2Wiki= -->
===filters===
+
<!-- Pod2Wiki=head_is_blank -->
 +
===is_blank===
  
A reference to an array of filter definitions.
+
<source lang="perl">$boolean = $searchexp->is_blank
  
Filter definitions take the form of: { value=&gt;"..", match=&gt;"..", merge=&gt;"..", id=&gt;".." } and work much like normal search fields except that they do not appear in the web form so force certain search parameters on the user.
+
</source>
 +
Return true is this searchexpression has no conditions set, otherwise true.
  
An optional parameter of describe=&gt;0 can be set to supress the filter being mentioned in the description of the search.
+
If any field is set to "exact" then it can never count as unset.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_from_cache --></div>
+
<!-- Pod2Wiki= -->
===$ok = $thing-&gt;from_cache( $id )===
+
<!-- Pod2Wiki=head_serialise -->
 +
===serialise===
  
Populate this search expression with values from the given cache.
+
<source lang="perl">$string = $searchexp->serialise
  
Return false if the cache does not exist.
+
</source>
 +
Return a text representation of the search expression, for persistent storage. Doesn't store table or the order by fields, just the field names, values, default order and satisfy_all.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_add_field --></div>
+
<!-- Pod2Wiki= -->
===$searchfield = $searchexp-&gt;add_field( $metafields, $value, $match, $merge, $id, $filter, $show_help )===
+
<!-- Pod2Wiki=head_from_string -->
 +
===from_string===
  
Adds a new search in $metafields which is either a single [[API:EPrints/MetaField|EPrints::MetaField]] or a list of fields in an array ref with default $value. If a search field already exists, the value of that field is replaced with $value.
+
<source lang="perl">$searchexp->from_string( $string )
  
 +
</source>
 +
Unserialises the contents of $string but only into the fields alrdeady existing in $searchexp. Set the order and satisfy_all mode but do not  affect the dataset or allow blank.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_searchfield --></div>
+
<!-- Pod2Wiki= -->
===$searchfield = $searchexp-&gt;get_searchfield( $sf_id )===
+
<!-- Pod2Wiki=head_clone -->
 +
===clone===
  
Return a [[API:EPrints/Search/Field|EPrints::Search::Field]] belonging to this Search with the given id.
+
<source lang="perl">$newsearchexp = $searchexp->clone
  
Return undef if not searchfield of that ID belongs to this search.  
+
</source>
 +
Return a new search expression which is a duplicate of this one.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_clear --></div>
+
<!-- Pod2Wiki= -->
===$searchexp-&gt;clear===
+
<!-- Pod2Wiki=head_get_conditons -->
 +
===get_conditons===
  
Clear the search values of all search fields in the expression.
+
<source lang="perl">$conditions = $searchexp->get_conditons
  
Resets satisfy_all to true.
+
</source>
 +
Return a tree of [[API:EPrints/Search/Condition|EPrints::Search::Condition]] objects describing the simple steps required to perform this search.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_satisfy_all --></div>
+
<!-- Pod2Wiki= -->
===$bool = $searchexp-&gt;get_satisfy_all===
+
<!-- Pod2Wiki=head_get_dataset -->
 +
===get_dataset===
 +
 
 +
<source lang="perl">$dataset = $searchexp->get_dataset
  
Return true if this search requires that all the search fields with values are satisfied.  
+
</source>
 +
Return the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_is_blank --></div>
+
<!-- Pod2Wiki= -->
===$boolean = $searchexp-&gt;is_blank===
+
<!-- Pod2Wiki=head_set_dataset -->
 +
===set_dataset===
  
Return true is this searchexpression has no conditions set, otherwise true.
+
<source lang="perl">$searchexp->set_dataset( $dataset )
  
If any field is set to "exact" then it can never count as unset.
+
</source>
 +
Set the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_serialise --></div>
+
<!-- Pod2Wiki= -->
===$string = $searchexp-&gt;serialise===
+
<!-- Pod2Wiki=head_render_description -->
 +
===render_description===
 +
 
 +
<source lang="perl">$xhtml = $searchexp->render_description
  
Return a text representation of the search expression, for persistent storage. Doesn't store table or the order by fields, just the field names, values, default order and satisfy_all.
+
</source>
 +
Return an XHTML DOM description of this search expressions current parameters.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_from_string --></div>
+
<!-- Pod2Wiki= -->
===$searchexp-&gt;from_string( $string )===
+
<!-- Pod2Wiki=head_render_conditions_description -->
 +
===render_conditions_description===
 +
 
 +
<source lang="perl">$xhtml = $searchexp->render_conditions_description
  
Unserialises the contents of $string but only into the fields alrdeady existing in $searchexp. Set the order and satisfy_all mode but do not  affect the dataset or allow blank.
+
</source>
 +
Return an XHTML DOM description of this search expressions conditions. ie title is "foo"
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_clone --></div>
+
<!-- Pod2Wiki= -->
===$newsearchexp = $searchexp-&gt;clone===
+
<!-- Pod2Wiki=head_render_order_description -->
 +
===render_order_description===
  
Return a new search expression which is a duplicate of this one.
+
<source lang="perl">$xhtml = $searchexp->render_order_description
 +
 
 +
</source>
 +
Return an XHTML DOM description of how this search is ordered.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_conditons --></div>
+
<!-- Pod2Wiki= -->
===$conditions = $searchexp-&gt;get_conditons===
+
<!-- Pod2Wiki=head_set_property -->
 +
===set_property===
  
Return a tree of [[API:EPrints/Search/Condition|EPrints::Search::Condition]] objects describing the simple steps required to perform this search.
+
<source lang="perl">$searchexp->set_property( $property, $value );
 +
 
 +
</source>
 +
Set any single property of this search, such as the order.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_dataset --></div>
+
<!-- Pod2Wiki= -->
===$dataset = $searchexp-&gt;get_dataset===
+
<!-- Pod2Wiki=head_get_searchfields -->
 +
===get_searchfields===
 +
 
 +
<source lang="perl">@search_fields = $searchexp->get_searchfields()
  
Return the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.
+
</source>
 +
Return the [[API:EPrints/Search/Field|EPrints::Search::Field]] objects relating to this search.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_set_dataset --></div>
+
<!-- Pod2Wiki= -->
===$searchexp-&gt;set_dataset( $dataset )===
+
<!-- Pod2Wiki=head_get_non_filter_searchfields -->
 +
===get_non_filter_searchfields===
  
Set the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.
+
<source lang="perl">@search_fields = $searchexp->get_non_filter_searchfields();
 +
 
 +
</source>
 +
Return the [[API:EPrints/Search/Field|EPrints::Search::Field]] objects relating to this search, which are normal search fields, and not "filters".
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_render_description --></div>
+
<!-- Pod2Wiki= -->
===$xhtml = $searchexp-&gt;render_description===
+
<!-- Pod2Wiki=head_get_set_searchfields -->
 +
===get_set_searchfields===
 +
 
 +
<source lang="perl">@search_fields = $searchexp->get_set_searchfields
  
Return an XHTML DOM description of this search expressions current parameters.
+
</source>
 +
Return the searchfields belonging to this search expression which have a value set.  
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_render_conditions_description --></div>
+
<!-- Pod2Wiki= -->
===$xhtml = $searchexp-&gt;render_conditions_description===
+
<!-- Pod2Wiki=head_get_cache_id -->
 +
===get_cache_id===
 +
 
 +
<source lang="perl">$cache_id = $searchexp->get_cache_id
  
Return an XHTML DOM description of this search expressions conditions. ie title is "foo"
+
</source>
 +
Return the ID of the cache containing the results of this search, if known.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_render_order_description --></div>
+
<!-- Pod2Wiki= -->
===$xhtml = $searchexp-&gt;render_order_description===
+
<!-- Pod2Wiki=head_perform_search -->
 +
===perform_search===
 +
 
 +
<source lang="perl">$results = $searchexp->perform_search
  
Return an XHTML DOM description of how this search is ordered.
+
</source>
 +
Execute this search and return a [[API:EPrints/List|EPrints::List]] object representing the results.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_set_property --></div>
+
<!-- Pod2Wiki= -->
===$searchexp-&gt;set_property( $property, $value );===
+
<!-- Pod2Wiki=head_perform_distinctby -->
 +
===perform_distinctby===
 +
 
 +
<source lang="perl">$ids_map = $searchexp->perform_distinctby( $fields )
  
Set any single property of this search, such as the order.
+
</source>
 +
Perform a DISTINCT on $fields to find all unique ids by value.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_searchfields --></div>
+
<!-- Pod2Wiki= -->
===@search_fields = $searchexp-&gt;get_searchfields()===
+
<!-- Pod2Wiki=head_perform_groupby -->
 +
===perform_groupby===
  
Return the [[API:EPrints/Search/Field|EPrints::Search::Field]] objects relating to this search.
+
<source lang="perl">($values, $counts) = $searchexp->perform_groupby( $field )
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
</source>
<h4><span style='display:none'>User Comments</span></h4>
+
Perform a SQL GROUP BY on $field based on the current search parameters.
<!-- Edit below this comment -->
 
  
 +
Returns two array references, one containing a list of unique values and one a list of counts for each value.
  
<!-- Pod2Wiki=item_get_non_filter_searchfields --></div>
+
<!-- Edit below this comment -->
===@search_fields = $searchexp-&gt;get_non_filter_searchfields();===
 
  
Return the [[API:EPrints/Search/Field|EPrints::Search::Field]] objects relating to this search, which are normal search fields, and not "filters".
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<!-- Pod2Wiki= -->
<h4><span style='display:none'>User Comments</span></h4>
+
<!-- Pod2Wiki=head_get_ids_by_field_values -->
<!-- Edit below this comment -->
+
===get_ids_by_field_values===
  
 +
<source lang="perl">$hash = $searchexp->get_ids_by_field_values( $field )
  
<!-- Pod2Wiki=item_get_set_searchfields --></div>
+
</source>
===@search_fields = $searchexp-&gt;get_set_searchfields===
+
Find the ids for each unique value in $field.
 
 
Return the searchfields belonging to this search expression which have a value set.  
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_cache_id --></div>
+
<!-- Pod2Wiki= -->
===$cache_id = $searchexp-&gt;get_cache_id===
 
 
 
Return the ID of the cache containing the results of this search, if known.
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_perform_search --></div>
+
<!-- Pod2Wiki= -->
===$results = $searchexp-&gt;perform_search===
+
<!-- Pod2Wiki=head_copyright -->
 
+
==COPYRIGHT==
Execute this search and return a [[API:EPrints/List|EPrints::List]] object representing the results.
+
Copyright 2000-2011 University of Southampton.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
  
 +
This file is part of EPrints http://www.eprints.org/.
  
<!-- Pod2Wiki=item_perform_groupby --></div>
+
EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
===($values, $counts) = $searchexp-&gt;perform_groupby( $field )===
 
  
Perform a SQL GROUP BY on $field based on the current search parameters.
+
EPrints 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 Lesser General Public License for more details.
  
Returns two array references, one containing a list of unique values and one a list of counts for each value.
+
You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_ids_by_field_values --></div>
+
<!-- Pod2Wiki= -->
===$hash = $searchexp-&gt;get_ids_by_field_values( $field )===
+
<!-- Pod2Wiki=_postamble_ -->
 
 
Find the ids for each unique value in $field.
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
 
 
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
 

Latest revision as of 08:18, 6 July 2018

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


API: Core API

Latest Source Code (3.3, 3.2) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::Search - retrieve objects based on search criteria


DESCRIPTION

The Search object represents the conditions of a single search.

Executing a search returns an EPrints::List object.

A search expression can also render itself as a web-form, populate itself with values from that web-form and render the results as a web page.

EPrints::Plugin::Search provides a pluggable architecture for searching EPrints.


SYNOPSIS

Searching for Eprints

  $ds = $repo->dataset( "archive" );
  
  # NB 'archive' is an implicit filter on eprint.status
  $list = $ds->search(filters => [{
    meta_fields => [qw( eprintid )], value => 23,
  }]);
  
  $list = $ds->search(search_fields => [{
    meta_fields => [qw( creators_name )], value => "John Smith",
  }]);
  
  $searchexp = $ds->prepare_search();
  $searchexp->add_field(
    fields => [
      $ds->field('creators_name')
    ],
    value => "John Smith",
    match => "EQ", # EQuals
  );
  $searchexp->add_field(
    fields => [
      $ds->field('title')
    ],
    value => "eagle buzzard",
    match => "IN", # INdex
  );

See EPrints::DataSet for more API methods for constructing search objects.


Getting Results

  $list = $searchexp->perform_search;
  
  my $count = $list->count;
  
  my $ids = $results->ids( 0, 10 );
  my $ids = $results->ids; # Get all matching ids
  
  my $info = { matches => 0 };
  sub fn {
    my( $session, $dataset, $eprint, $info ) = @_;
    $info->{matches}++;
  };
  $list->map( \&fn, $info );

See EPrints::List for more.


METHODS

new

$searchexp = EPrints::Search->new( %params )

Create a new search expression.

The parameters are split into two parts. The general parameters and those which influence how the HTML form is rendered, and the results displayed.

GENERAL PARAMETERS

  • session (required)
The current EPrints::Session
  • dataset OR dataset_id (required)
Either the EPrints::DataSet to search, or the ID of it.
  • allow_blank (default 0)
Unless this is set, a search with no conditions will return zero records rather than all records.
  • satisfy_all (default 1)
If this is true than all search-fields much be satisfied, if false then results matching any search-field will be returned.
  • search_fields
A reference to an array of search field configuration structures. Each takes the form { id=>"...", default=>"..", meta_fields=>"..." } where the meaning is the same as for search configuration in ArchiveConfig.
Search fields can also be added to the search expression after it has been constructed.
  • order
The order the results should be returned. This is a key to the list of orders available to this dataset, defined in ArchiveConfig.pm
  • custom_order
"order" limits you to the orders specified in ArchiveConfig, and is usually used by the web page based searching. custom_order allows you to specify any order you like. The format is foo/-bar. This means that the results will be sorted by foo and then any with equal foo values will be reverse sorted by bar. More than 2 fields can be specified.
  • keep_cache
If true then the search results produced will be stored in the database even after the current script ends. This is useful for speeding up page 2 onwards of a search.
keep_cache may get set to true anyway for various reasons, but setting the parameter makes certain of it.
  • cache_id
The ID of a cached search. The cache contains both the results of the search, and the parameters used for the search.
If the cache still exists, it will set the default values of the search fields, and when the search is performed it will skip the search and build a search results object directly from the cache.
  • limit
Limit the number of matching records to limit.

WEB PAGE RELATED PARAMETERS

  • prefix (default "")
When generating the web form and reading back from the web form, the prefix is inserted before the form names of all fields. This is useful if you need to put two search expressions in a single form for some reason.
  • staff (default 0)
If true then this is a "staff" search, which prevents searching unless the user is staff, and the results link to the staff URL of an item rather than the public URL.
  • filters
A reference to an array of filter definitions.
Filter definitions take the form of: { value=>"..", match=>"..", merge=>"..", id=>".." } and work much like normal search fields except that they do not appear in the web form so force certain search parameters on the user.
An optional parameter of describe=>0 can be set to supress the filter being mentioned in the description of the search.


from_cache

$ok = $thing->from_cache( $id )

Populate this search expression with values from the given cache.

Return false if the cache does not exist.


add_field

$searchfield = $searchexp->add_field( %opts )
  fields - one or more fields to search over
  match - match type
  merge - merge type
  value - value to match against (for EX matches, NULL = is_null!)
  id - search field id, if not the name of the first field
  filter - is filter-type
  show_help - show help in search input

Adds a new search in $fields which is either a single EPrints::MetaField or a list of fields in an array ref with default $value. If a search field already exists, the value of that field is replaced with $value.

See EPrints::Search::Field for details on match/merge etc.


Note relating to the for EX matches, NULL = is_null documentation above.

To search for items with no value, use something similar to this - explicitly setting the value to undef.:

### Example: search for items in the review area with no date set.
my $ds = $session->dataset( "buffer" );
my $searchexp = $ds->prepare_search();
$searchexp->add_field(
    fields => [
      $ds->field( 'date' ),
    ],
    value => undef,
    match => "EX",
);


clear

$searchexp->clear

Clear the search values of all search fields in the expression.

Resets satisfy_all to true.


get_satisfy_all

$bool = $searchexp->get_satisfy_all

Return true if this search requires that all the search fields with values are satisfied.


is_blank

$boolean = $searchexp->is_blank

Return true is this searchexpression has no conditions set, otherwise true.

If any field is set to "exact" then it can never count as unset.


serialise

$string = $searchexp->serialise

Return a text representation of the search expression, for persistent storage. Doesn't store table or the order by fields, just the field names, values, default order and satisfy_all.


from_string

$searchexp->from_string( $string )

Unserialises the contents of $string but only into the fields alrdeady existing in $searchexp. Set the order and satisfy_all mode but do not affect the dataset or allow blank.


clone

$newsearchexp = $searchexp->clone

Return a new search expression which is a duplicate of this one.


get_conditons

$conditions = $searchexp->get_conditons

Return a tree of EPrints::Search::Condition objects describing the simple steps required to perform this search.


get_dataset

$dataset = $searchexp->get_dataset

Return the EPrints::DataSet which this search relates to.


set_dataset

$searchexp->set_dataset( $dataset )

Set the EPrints::DataSet which this search relates to.


render_description

$xhtml = $searchexp->render_description

Return an XHTML DOM description of this search expressions current parameters.


render_conditions_description

$xhtml = $searchexp->render_conditions_description

Return an XHTML DOM description of this search expressions conditions. ie title is "foo"


render_order_description

$xhtml = $searchexp->render_order_description

Return an XHTML DOM description of how this search is ordered.


set_property

$searchexp->set_property( $property, $value );

Set any single property of this search, such as the order.


get_searchfields

@search_fields = $searchexp->get_searchfields()

Return the EPrints::Search::Field objects relating to this search.


get_non_filter_searchfields

@search_fields = $searchexp->get_non_filter_searchfields();

Return the EPrints::Search::Field objects relating to this search, which are normal search fields, and not "filters".


get_set_searchfields

@search_fields = $searchexp->get_set_searchfields

Return the searchfields belonging to this search expression which have a value set.


get_cache_id

$cache_id = $searchexp->get_cache_id

Return the ID of the cache containing the results of this search, if known.


perform_search

$results = $searchexp->perform_search

Execute this search and return a EPrints::List object representing the results.


perform_distinctby

$ids_map = $searchexp->perform_distinctby( $fields )

Perform a DISTINCT on $fields to find all unique ids by value.


perform_groupby

($values, $counts) = $searchexp->perform_groupby( $field )

Perform a SQL GROUP BY on $field based on the current search parameters.

Returns two array references, one containing a list of unique values and one a list of counts for each value.


get_ids_by_field_values

$hash = $searchexp->get_ids_by_field_values( $field )

Find the ids for each unique value in $field.



COPYRIGHT

Copyright 2000-2011 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

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

EPrints 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.