Difference between revisions of "API:EPrints/DataSet"

From EPrints Documentation
Jump to: navigation, search
Line 21: Line 21:
 
   print sprintf("There are %d records in the inbox\n",
 
   print sprintf("There are %d records in the inbox\n",
 
     $dataset->count);
 
     $dataset->count);
 +
 
 +
  $string = $dataset->base_id; # eprint
 +
  $string = $dataset->id; # inbox
 +
 
 +
  $dataobj = $dataset->create_dataobj( $data );
 +
  $user = $dataset->dataobj( 23 );
 +
 
 +
  $search = $dataset->prepare_search( %options );
 +
  $list = $dataset->search( %options ); # prepare_search( %options )->execute
 +
  $list = $dataset->search; # match ALL
 +
 
 +
  $metafield = $dataset->field( $fieldname );
 +
  $metafield = $dataset->key_field;
 +
  @metafields = $dataset->fields;
 +
 
 +
  $dataset->search->map( sub {}, $ctx );
 +
  $n = $dataset->search->count;
 +
  $ids = $dataset->search->ids;
 +
  $list = $dataset->list( \@ids );
 
    
 
    
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 37: Line 56:
 
A normal dataset (eg. "user") has a package associated with it  (eg. EPrints::DataObj::User) which must be a subclass of EPrints::DataObj  and a number of SQL tables which are prefixed with the dataset name. Most datasets also have a set of associated EPrints::MetaField's which may be optional or compulsary depending on the type eg. books have editors but posters don't but they are both EPrints.
 
A normal dataset (eg. "user") has a package associated with it  (eg. EPrints::DataObj::User) which must be a subclass of EPrints::DataObj  and a number of SQL tables which are prefixed with the dataset name. Most datasets also have a set of associated EPrints::MetaField's which may be optional or compulsary depending on the type eg. books have editors but posters don't but they are both EPrints.
  
−
The fields contained in a dataset are defined by the data object and by any additional fields defined in cfg.d. Some datasets don't have any fields while others may just be "virtual" datasets made from others.
+
The fields contained in a dataset are defined by the data object and by any additional fields defined in cfg.d. Some datasets don't have any fields.
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_cachemap_counter -->
 
−
===cachemap, counter===
 
−
 
 
−
Don't have a package or metadata fields associated.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_archive_buffer_inbox_deletion -->
 
−
===archive, buffer, inbox, deletion===
 
−
 
 
−
All have the same package and metadata fields as '''eprints''', but are filtered by '''eprint_status'''.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=head_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%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=head_class_methods -->
 
−
===Class Methods===
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_new -->
 
−
====new====
 
−
 
 
−
$ds = EPrints::DataSet-&gt;new( %properties )
 
−
Creates and returns a new dataset based on %properties.
 
−
 
 
−
Requires at least '''repository''' and '''name''' properties.
 
−
 
 
−
Available properties:
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_repository -->
 
−
====repository====
 
−
 
 
−
repository OBJ
 
−
Reference to the repository object.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_name -->
 
−
====name====
 
−
 
 
−
name STRING
 
−
Name of the dataset.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_confid -->
 
−
====confid====
 
−
 
 
−
confid STRING
 
−
Name of the dataset this dataset is a subset of (e.g. 'archive' is a subset of 'eprint'). If defined requires dataset_id_field.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_dataset_id_field -->
 
−
====dataset_id_field====
 
−
 
 
−
dataset_id_field
 
−
Name of the text field that contains the subset dataset id.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_sql_name -->
 
−
====sql_name====
 
−
 
 
−
sql_name STRING
 
−
Name of the primary database table.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_virtual -->
 
−
====virtual====
 
−
 
 
−
virtual BOOL
 
−
Set to 1 if this dataset doesn't require it's own database tables.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_type -->
 
−
====type====
 
−
 
 
−
type STRING
 
−
Type of data object the dataset contains e.g. for [[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]] specify "EPrint".
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_class -->
 
−
====class====
 
−
 
 
−
class STRING
 
−
Explicit class to use for data objects. To use the default object specify [[API:EPrints/DataObj|EPrints::DataObj]].
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
  
−
<!-- Pod2Wiki= -->
+
Some datasets are "virtual" datasets made from others. Examples include "inbox", "archive", "buffer" and "retired" which are all virtual datasets of of the "eprint" dataset. That is to say "inbox" is a subset of "eprint" and by inference contains EPrints::DataObj::EPrints. You can define your own virtual datasets which opperate on existing datasets.
−
</div>
 
−
<!-- Pod2Wiki=item_filters -->
 
−
====filters====
 
−
 
 
−
filters ARRAYREF
 
−
Filters to apply to this dataset before searching (see [[API:EPrints/Search|EPrints::Search]]).
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_datestamp -->
 
−
====datestamp====
 
−
 
 
−
  datestamp STRING
 
−
The field name that contains a datestamp to order this dataset by.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_index -->
 
−
====index====
 
−
 
 
−
index BOOL
 
−
Whether this dataset should be indexed.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_import -->
 
−
====import====
 
−
 
 
−
import BOOL
 
−
Whether you can import into this dataset.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_system_dataset_info -->
 
−
====get_system_dataset_info====
 
−
 
 
−
  $info = EPrints::DataSet::get_system_dataset_info()
 
−
Returns a hash reference of core system datasets.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 284: Line 77:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_base_id -->
 
<!-- Pod2Wiki=item_base_id -->
−
====base_id====
+
====$id = $ds-&gt;base_id====
  
−
$id = $ds-&gt;base_id
 
 
   $ds = $repo-&gt;dataset( "inbox" );
 
   $ds = $repo-&gt;dataset( "inbox" );
 
   $id = $ds-&gt;base_id; # returns "eprint"
 
   $id = $ds-&gt;base_id; # returns "eprint"
 
    
 
    
 
Returns the identifier of the base dataset for this dataset (same as {{API:PodLink|file=|package_name=|section=id|text=/id}} unless this dataset is virtual).
 
Returns the identifier of the base dataset for this dataset (same as {{API:PodLink|file=|package_name=|section=id|text=/id}} unless this dataset is virtual).
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_process_field -->
 
−
====process_field====
 
−
 
−
$field = $ds-&gt;process_field( $data [, $system ] )
 
−
Creates a new field in this dataset based on $data. If $system is true defines the new field as a "core" field.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_register_field -->
 
−
====register_field====
 
−
 
−
$ds-&gt;register_field( $field [, $system ] )
 
−
Register a new field with this dataset.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_unregister_field -->
 
−
====unregister_field====
 
−
 
−
$ds-&gt;unregister_field( $field )
 
−
Unregister a field from this dataset.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 339: Line 92:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_field -->
 
<!-- Pod2Wiki=item_field -->
−
====field====
+
====$metafield = $ds-&gt;field( $fieldname )====
  
−
$metafield = $ds-&gt;field( $fieldname )
 
 
Returns the [[API:EPrints/MetaField|EPrints::MetaField]] from this dataset with the given name, or undef.
 
Returns the [[API:EPrints/MetaField|EPrints::MetaField]] from this dataset with the given name, or undef.
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_has_field -->
 
−
====has_field====
 
−
 
−
$bool = $ds-&gt;has_field( $fieldname )
 
−
True if the dataset has a field of that name.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_default_order -->
 
−
====default_order====
 
−
 
−
$ordertype = $ds-&gt;default_order
 
−
Return the id string of the default order for this dataset.
 
−
 
−
For example "bytitle" for eprints.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 380: Line 104:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_id -->
 
<!-- Pod2Wiki=item_id -->
−
====id====
+
====$id = $ds-&gt;id====
  
−
$id = $ds-&gt;id
 
 
Return the id of this dataset.
 
Return the id of this dataset.
  
Line 393: Line 116:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_count -->
 
<!-- Pod2Wiki=item_count -->
−
====count====
+
====$n = $ds-&gt;count( $session )====
  
−
$n = $ds-&gt;count( $session )
 
 
Return the number of records in this dataset.
 
Return the number of records in this dataset.
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_sql_table_name -->
 
−
====get_sql_table_name====
 
−
 
−
$tablename = $ds-&gt;get_sql_table_name
 
−
Return the name of the main SQL Table containing this dataset. the other SQL tables names are based on this name.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_sql_index_table_name -->
 
−
====get_sql_index_table_name====
 
−
 
−
$tablename = $ds-&gt;get_sql_index_table_name
 
−
Return the name of the SQL table which contains the free text indexing information.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_sql_grep_table_name -->
 
−
====get_sql_grep_table_name====
 
−
 
−
$tablename = $ds-&gt;get_sql_grep_table_name
 
−
Reutrn the name of the SQL table which contains the strings to be used with LIKE in a final pass of a search.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_sql_rindex_table_name -->
 
−
====get_sql_rindex_table_name====
 
−
 
−
$tablename = $ds-&gt;get_sql_rindex_table_name
 
−
Reutrn the name of the SQL table which contains the reverse text indexing information. (Used for deleting freetext indexes when removing a record).
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_ordervalues_table_name -->
 
−
====get_ordervalues_table_name====
 
−
 
−
$tablename = $ds-&gt;get_ordervalues_table_name( $langid )
 
−
Return the name of the SQL table containing values used for ordering this dataset.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_sql_sub_table_name -->
 
−
====get_sql_sub_table_name====
 
−
 
−
$tablename = $ds-&gt;get_sql_sub_table_name( $field )
 
−
Returns the name of the SQL table which contains the information on the "multiple" field. $field is an EPrints::MetaField belonging to this dataset.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 484: Line 128:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_fields -->
 
<!-- Pod2Wiki=item_fields -->
−
====fields====
+
====@fields = $ds-&gt;fields====
  
−
@fields = $ds-&gt;fields
 
 
Returns a list of the [[API:EPrints/MetaField|EPrints::MetaField]]s belonging to this dataset.
 
Returns a list of the [[API:EPrints/MetaField|EPrints::MetaField]]s belonging to this dataset.
  
Line 497: Line 140:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_key_field -->
 
<!-- Pod2Wiki=item_key_field -->
−
====key_field====
+
====$field = $ds-&gt;key_field====
  
−
$field = $ds-&gt;key_field
 
 
Return the [[API:EPrints/MetaField|EPrints::MetaField]] representing the primary key field.
 
Return the [[API:EPrints/MetaField|EPrints::MetaField]] representing the primary key field.
  
Line 511: Line 153:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
−
<!-- Pod2Wiki=item_make_object -->
+
<!-- Pod2Wiki=item_make_dataobj -->
−
====make_object====
+
====$dataobj = $ds-&gt;make_dataobj( $epdata )====
  
−
$obj = $ds-&gt;make_object( $session, $data )
+
Return an object of the class associated with this dataset, always a subclass of [[API:EPrints/DataObj|EPrints::DataObj]].
−
Return an object of the class associated with this dataset, always a subclass of EPrints::DataObj.
 
  
−
$data is a hash of values for fields of a record in this dataset.
+
$epdata is a hash of values for fields in this dataset.
  
−
Return $data if no class associated with this dataset.
+
Returns $epdata if no class is associated with this dataset.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 529: Line 170:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_create_dataobj -->
 
<!-- Pod2Wiki=item_create_dataobj -->
−
====create_dataobj====
+
====$obj = $ds-&gt;create_dataobj( $data )====
  
−
$obj = $ds-&gt;create_dataobj( $data )
 
 
Returns a new object in this dataset based on $data or undef on failure.
 
Returns a new object in this dataset based on $data or undef on failure.
  
 
If $data describes sub-objects then those will also be created.
 
If $data describes sub-objects then those will also be created.
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_object_class -->
 
−
====get_object_class====
 
−
 
−
$class = $ds-&gt;get_object_class;
 
−
Return the perl class to which objects in this dataset belong.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_object -->
 
−
====get_object====
 
−
 
−
$obj = $ds-&gt;get_object( $session, $id );
 
−
Return the object from this dataset with the given id, or undefined.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 570: Line 184:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_dataobj -->
 
<!-- Pod2Wiki=item_dataobj -->
−
====dataobj====
+
====$dataobj = $ds-&gt;dataobj( $id )====
  
−
$dataobj = $ds-&gt;dataobj( $id )
 
 
Returns the object from this dataset with the given id, or undefined.
 
Returns the object from this dataset with the given id, or undefined.
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_object_from_uri -->
 
−
====get_object_from_uri====
 
−
 
−
$dataobj = EPrints::DataSet-&gt;get_object_from_uri( $session, $uri )
 
−
Returns a the dataobj identified by internal URI $uri.
 
−
 
−
Returns undef if $uri isn't an internal URI or the object is no longer available.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_render_name -->
 
−
====render_name====
 
−
 
−
$xhtml = $ds-&gt;render_name( $session )
 
−
Return a piece of XHTML describing this dataset, in the language of the current session.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_map -->
 
−
====map====
 
−
 
−
$ds-&gt;map( $session, $fn, $info )
 
−
Maps the function $fn onto every record in this dataset. See  Search for a full explanation.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 624: Line 196:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_repository -->
 
<!-- Pod2Wiki=item_repository -->
−
====repository====
+
====$repository = $ds-&gt;repository====
  
−
$repository = $ds-&gt;repository
 
 
Returns the [[API:EPrints/Repository|EPrints::Repository]] to which this dataset belongs.
 
Returns the [[API:EPrints/Repository|EPrints::Repository]] to which this dataset belongs.
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_reindex -->
 
−
====reindex====
 
−
 
−
$ds-&gt;reindex( $session )
 
−
Recommits all the items in this dataset. This could take a real long  time on a large set of records.
 
−
 
−
Really should not be called reindex anymore as it doesn't.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_dataset_ids -->
 
−
====get_dataset_ids====
 
−
 
−
@ids = EPrints::DataSet::get_dataset_ids()
 
−
Deprecated, use $repository-&gt;get_dataset_ids().
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_sql_dataset_ids -->
 
−
====get_sql_dataset_ids====
 
−
 
−
@ids = EPrints::DataSet::get_sql_dataset_ids()
 
−
Deprecated, use $repository-&gt;get_sql_dataset_ids().
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_count_indexes -->
 
−
====count_indexes====
 
−
 
−
$n = $ds-&gt;count_indexes
 
−
Return the number of indexes required for the main SQL table of this dataset. Used to check it's not over 32 (the current maximum allowed by MySQL)
 
−
 
−
Assumes things either have 1 or 0 indexes which might not always be true.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_item_ids -->
 
−
====get_item_ids====
 
−
 
−
@ids = $dataset-&gt;get_item_ids( $session )
 
−
Return a list of the id's of all items in this set.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_is_virtual -->
 
−
====is_virtual====
 
−
 
−
$bool = $dataset-&gt;is_virtual()
 
−
Returns whether this dataset is virtual (i.e. has no database tables).
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_get_datestamp_field -->
 
−
====get_datestamp_field====
 
−
 
−
$field = $dataset-&gt;get_datestamp_field()
 
−
Returns the datestamp field for this dataset which may be used for incremental harvesting. Returns undef if no such field is available.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 732: Line 208:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_prepare_search -->
 
<!-- Pod2Wiki=item_prepare_search -->
−
====prepare_search====
+
====$searchexp = $ds-&gt;prepare_search( %options )====
  
−
$searchexp = $ds-&gt;prepare_search( %options )
 
 
Returns a [[API:EPrints/Search|EPrints::Search]] for this dataset with %options.
 
Returns a [[API:EPrints/Search|EPrints::Search]] for this dataset with %options.
  
Line 745: Line 220:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_search -->
 
<!-- Pod2Wiki=item_search -->
−
====search====
+
====$list = $ds-&gt;search( %options )====
  
−
$list = $ds-&gt;search( %options )
 
 
Short-cut to {{API:PodLink|file=|package_name=|section=prepare_search|text=/prepare_search}}( %options )-&gt;execute.
 
Short-cut to {{API:PodLink|file=|package_name=|section=prepare_search|text=/prepare_search}}( %options )-&gt;execute.
  
Line 758: Line 232:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_list -->
 
<!-- Pod2Wiki=item_list -->
−
====list====
+
====$list = $ds-&gt;list( $ids )====
  
−
$list = $ds-&gt;list( $ids )
 
 
Returns a [[API:EPrints/List|EPrints::List]] for this dataset for the given $ids list.
 
Returns a [[API:EPrints/List|EPrints::List]] for this dataset for the given $ids list.
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_columns -->
 
−
====columns====
 
−
 
−
$fields = $dataset-&gt;columns()
 
−
Returns the default list of fields to show the user when browsing this dataset in a table. Returns an array ref of [[API:EPrints/MetaField|EPrints::MetaField]] objects.
 
−
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<span style='display:none'>User Comments</span>
 
−
<!-- Edit below this comment -->
 
−
 
−
 
−
<!-- Pod2Wiki= -->
 
−
</div>
 
−
<!-- Pod2Wiki=item_run_trigger -->
 
−
====run_trigger====
 
−
 
−
$dataset-&gt;run_trigger( TRIGGER_ID, %params )
 
−
Runs all of the registered triggers for TRIGGER_ID on this dataset.
 
−
 
−
%params is passed to the trigger functions.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>

Revision as of 17:23, 31 December 2010

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.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::DataSet - a dataset is a set of records in the eprints system with the same metadata.

User Comments


SYNOPSIS

 my $dataset = $repository->get_dataset( "inbox" );
 
 print sprintf("There are %d records in the inbox\n",
   $dataset->count);
 
 $string = $dataset->base_id; # eprint
 $string = $dataset->id; # inbox
 
 $dataobj = $dataset->create_dataobj( $data );
 $user = $dataset->dataobj( 23 );
 
 $search = $dataset->prepare_search( %options );
 $list = $dataset->search( %options ); # prepare_search( %options )->execute
 $list = $dataset->search; # match ALL
 
 $metafield = $dataset->field( $fieldname );
 $metafield = $dataset->key_field;
 @metafields = $dataset->fields; 
 
 $dataset->search->map( sub {}, $ctx );
 $n = $dataset->search->count; 
 $ids = $dataset->search->ids;
 $list = $dataset->list( \@ids );

User Comments


DESCRIPTION

This module describes an EPrint dataset.

A repository has several datasets that make up the repository's database. The list of dataset ids can be obtained from the repository object (see EPrints::Repository).

A normal dataset (eg. "user") has a package associated with it (eg. EPrints::DataObj::User) which must be a subclass of EPrints::DataObj and a number of SQL tables which are prefixed with the dataset name. Most datasets also have a set of associated EPrints::MetaField's which may be optional or compulsary depending on the type eg. books have editors but posters don't but they are both EPrints.

The fields contained in a dataset are defined by the data object and by any additional fields defined in cfg.d. Some datasets don't have any fields.

Some datasets are "virtual" datasets made from others. Examples include "inbox", "archive", "buffer" and "retired" which are all virtual datasets of of the "eprint" dataset. That is to say "inbox" is a subset of "eprint" and by inference contains EPrints::DataObj::EPrints. You can define your own virtual datasets which opperate on existing datasets.

User Comments


Object Methods

User Comments


$id = $ds->base_id

 $ds = $repo->dataset( "inbox" );
 $id = $ds->base_id; # returns "eprint"

Returns the identifier of the base dataset for this dataset (same as /id unless this dataset is virtual).

User Comments


$metafield = $ds->field( $fieldname )

Returns the EPrints::MetaField from this dataset with the given name, or undef.

User Comments


$id = $ds->id

Return the id of this dataset.

User Comments


$n = $ds->count( $session )

Return the number of records in this dataset.

User Comments


@fields = $ds->fields

Returns a list of the EPrints::MetaFields belonging to this dataset.

User Comments


$field = $ds->key_field

Return the EPrints::MetaField representing the primary key field.

Always the first field.

User Comments


$dataobj = $ds->make_dataobj( $epdata )

Return an object of the class associated with this dataset, always a subclass of EPrints::DataObj.

$epdata is a hash of values for fields in this dataset.

Returns $epdata if no class is associated with this dataset.

User Comments


$obj = $ds->create_dataobj( $data )

Returns a new object in this dataset based on $data or undef on failure.

If $data describes sub-objects then those will also be created.

User Comments


$dataobj = $ds->dataobj( $id )

Returns the object from this dataset with the given id, or undefined.

User Comments


$repository = $ds->repository

Returns the EPrints::Repository to which this dataset belongs.

User Comments


$searchexp = $ds->prepare_search( %options )

Returns a EPrints::Search for this dataset with %options.

User Comments


$list = $ds->search( %options )

Short-cut to /prepare_search( %options )->execute.

User Comments


$list = $ds->list( $ids )

Returns a EPrints::List for this dataset for the given $ids list.

User Comments


Retrieved from ‘https://wiki.eprints.org/w/index.php?title=API:EPrints/DataSet&oldid=9723’