Difference between revisions of "API:EPrints/DataSet"

From EPrints Documentation
Jump to: navigation, search
Line 132: Line 132:
 
   };
 
   };
 
    
 
    
 +
<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%; '>
 
<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>
 
<span style='display:none'>User Comments</span>
Line 149: Line 167:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_base_id -->
 
<!-- Pod2Wiki=item_base_id -->
====$id = $ds-&gt;base_id====
+
====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"
Line 164: Line 183:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_field -->
 
<!-- Pod2Wiki=item_field -->
====$metafield = $ds-&gt;field( $fieldname )====
+
====field====
  
 +
$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.
  
Line 176: Line 196:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_id -->
 
<!-- Pod2Wiki=item_id -->
====$id = $ds-&gt;id====
+
====id====
  
 +
$id = $ds-&gt;id
 
Return the id of this dataset.
 
Return the id of this dataset.
  
Line 188: Line 209:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_count -->
 
<!-- Pod2Wiki=item_count -->
====$n = $ds-&gt;count( $session )====
+
====count====
  
 +
$n = $ds-&gt;count( $session )
 
Return the number of records in this dataset.
 
Return the number of records in this dataset.
  
Line 200: Line 222:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_fields -->
 
<!-- Pod2Wiki=item_fields -->
====@fields = $ds-&gt;fields====
+
====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 212: Line 235:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_key_field -->
 
<!-- Pod2Wiki=item_key_field -->
====$field = $ds-&gt;key_field====
+
====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 226: Line 250:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_make_dataobj -->
 
<!-- Pod2Wiki=item_make_dataobj -->
====$dataobj = $ds-&gt;make_dataobj( $epdata )====
+
====make_dataobj====
  
 +
$dataobj = $ds-&gt;make_dataobj( $epdata )
 
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 [[API:EPrints/DataObj|EPrints::DataObj]].
  
Line 242: Line 267:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_create_dataobj -->
 
<!-- Pod2Wiki=item_create_dataobj -->
====$obj = $ds-&gt;create_dataobj( $data )====
+
====create_dataobj====
  
 +
$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.
  
Line 256: Line 282:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_dataobj -->
 
<!-- Pod2Wiki=item_dataobj -->
====$dataobj = $ds-&gt;dataobj( $id )====
+
====dataobj====
  
 +
$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.
  
Line 268: Line 295:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_repository -->
 
<!-- Pod2Wiki=item_repository -->
====$repository = $ds-&gt;repository====
+
====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.
  
Line 280: Line 308:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_prepare_search -->
 
<!-- Pod2Wiki=item_prepare_search -->
====$searchexp = $ds-&gt;prepare_search( %options )====
+
====prepare_search====
  
 +
$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 292: Line 321:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_search -->
 
<!-- Pod2Wiki=item_search -->
====$list = $ds-&gt;search( %options )====
+
====search====
  
 +
$list = $ds-&gt;search( %options )
 
Short-cut to [[API:EPrints/DataSet#prepare_search|prepare_search]]( %options )-&gt;execute.
 
Short-cut to [[API:EPrints/DataSet#prepare_search|prepare_search]]( %options )-&gt;execute.
  
Line 304: Line 334:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_satisfy_all_1 -->
 
<!-- Pod2Wiki=item_satisfy_all_1 -->
===="satisfy_all"=&gt;1 ====
+
====satisfy_all_1====
  
 +
"satisfy_all"=&gt;1
 
Satify all conditions specified. 0 means satisfy any of the conditions specified. Default is 1
 
Satify all conditions specified. 0 means satisfy any of the conditions specified. Default is 1
  
Line 316: Line 347:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_staff_1 -->
 
<!-- Pod2Wiki=item_staff_1 -->
===="staff"=&gt;1====
+
====staff_1====
  
 +
"staff"=&gt;1
 
Do search as an adminstrator means you get everything back
 
Do search as an adminstrator means you get everything back
  
Line 328: Line 360:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_custom_order_field1_field2_field3 -->
 
<!-- Pod2Wiki=item_custom_order_field1_field2_field3 -->
===="custom_order" =&gt; "field1/-field2/field3"====
+
====custom_order_field1_field2_field3====
  
 +
"custom_order" =&gt; "field1/-field2/field3"
 
Order the search results by field order. prefixing the field name with a "-" results in reverse ordering
 
Order the search results by field order. prefixing the field name with a "-" results in reverse ordering
  
Line 340: Line 373:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_search_fields_meta_fields_field1_field2_document_field3_merge_any_match_ex_value_bees_meta_fields_field4_value_honey -->
 
<!-- Pod2Wiki=item_search_fields_meta_fields_field1_field2_document_field3_merge_any_match_ex_value_bees_meta_fields_field4_value_honey -->
===="search_fields" =&gt; \@({meta_fields=&gt;[ "field1", "field2" "document.field3" ], merge=&gt;"ANY", match=&gt;"EX", value=&gt;"bees"}, {meta_fields=&gt;[ "field4" ], value=&gt;"honey"});====
+
====search_fields_meta_fields_field1_field2_document_field3_merge_any_match_ex_value_bees_meta_fields_field4_value_honey====
  
 +
"search_fields" =&gt; \@({meta_fields=&gt;[ "field1", "field2" "document.field3" ], merge=&gt;"ANY", match=&gt;"EX", value=&gt;"bees"}, {meta_fields=&gt;[ "field4" ], value=&gt;"honey"});
 
Return values where field1 field2 or field3 is "bees" and field2  is "honey" (assuming satisfy all is set)
 
Return values where field1 field2 or field3 is "bees" and field2  is "honey" (assuming satisfy all is set)
  
Line 352: Line 386:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_limit_10 -->
 
<!-- Pod2Wiki=item_limit_10 -->
===="limit" =&gt; 10====
+
====limit_10====
  
 +
"limit" =&gt; 10
 
Only return 10 results
 
Only return 10 results
  
Line 364: Line 399:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_list -->
 
<!-- Pod2Wiki=item_list -->
====$list = $ds-&gt;list( $ids )====
+
====list====
  
 +
$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.
  

Revision as of 11:41, 14 September 2011

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 set of records with the same metadata scheme

User Comments


SYNOPSIS

 my $dataset = $repository->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 a dataset.

A repository has several datasets that make up the repository's metadata schema. 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 required 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 "deletion" 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


CREATING CUSTOM DATASETS

New datasets can be defined in a configuration file, e.g.

 $c->{datasets}->{bread} = {
   class => "EPrints::DataObj::Bread",
   sqlname => "bread",
 };
 

This defines a dataset with the id bread (must be unique). The dataobj package (class) to instantiate objects with is EPrints::DataObj::Bread, which must be a sub-class of EPrints::DataObj. Lastly, the database tables used by the dataset will be called 'bread' or prefixed 'bread_'.

Other optional properties:

 columns - an array ref of field ids to default the user view to
 datestamp - field id to use to sort this dataset
 import - is the dataset importable?
 index - is the dataset text-indexed?
 order - is the dataset orderable?
 virtual - completely virtual dataset (no database tables)
 

To make one dataset a virtual dataset of another (as 'inbox' is to 'eprint') use the following properties:

 confid - the super-dataset this is a virtual sub-dataset of
 dataset_id_field - the field containing the sub-dataset id
 filters - an array ref of filters to apply when retrieving records
 

As with system datasets, the EPrints::MetaFields can be defined via EPrints::DataObj/get_system_field_info or via configuration:

 $c->add_dataset_field(
   "bread",
   { name => "breadid", type => "counter", sql_counter => "bread" }
 );
 $c->add_dataset_field(
   "bread",
   { name => "toasted", type => "bool", }
 );
 $c->add_dataset_field(
   "bread",
   { name => "description", type => "text", }
 );
 

See EPrints::RepositoryConfig/add_dataset_field for details on add_dataset_field.

Creating a fully-operational dataset will require more configuration files. You will probably want at least a workflow, citations for the summary page, search results etc, and permissions and searching settings:

 push @{$c->{user_roles}->{admin}}, qw(
   +bread/create
   +bread/edit
   +bread/view
   +bread/destroy
   +bread/details
 );
 push @{$c->{plugins}->{"Export::SummaryPage"}->{params}->{accept}}, qw(
   dataobj/bread
 );
 $c->{datasets}->{bread}->{search}->{simple} = {
   search_fields => {
     id => "q",
     meta_fields => [qw(
       breadid
       description
     )],
   },
 };
 

User Comments


METHODS

User Comments


Class Methods

User Comments


Object Methods

User Comments


base_id

$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


field

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

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

User Comments


id

$id = $ds->id

Return the id of this dataset.

User Comments


count

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

Return the number of records in this dataset.

User Comments


fields

@fields = $ds->fields

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

User Comments


key_field

$field = $ds->key_field

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

Always the first field.

User Comments


make_dataobj

$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


create_dataobj

$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

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

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

User Comments


repository

$repository = $ds->repository

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

User Comments


prepare_search

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

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

User Comments


search

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

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

User Comments


satisfy_all_1

"satisfy_all"=>1 

Satify all conditions specified. 0 means satisfy any of the conditions specified. Default is 1

User Comments


staff_1

"staff"=>1

Do search as an adminstrator means you get everything back

User Comments


custom_order_field1_field2_field3

"custom_order" => "field1/-field2/field3"

Order the search results by field order. prefixing the field name with a "-" results in reverse ordering

User Comments


search_fields_meta_fields_field1_field2_document_field3_merge_any_match_ex_value_bees_meta_fields_field4_value_honey

"search_fields" => \@({meta_fields=>[ "field1", "field2" "document.field3" ], merge=>"ANY", match=>"EX", value=>"bees"}, {meta_fields=>[ "field4" ], value=>"honey"});

Return values where field1 field2 or field3 is "bees" and field2 is "honey" (assuming satisfy all is set)

User Comments


limit_10

"limit" => 10

Only return 10 results

User Comments


list

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

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

User Comments


COPYRIGHT

User Comments