Difference between revisions of "API:EPrints/DataSet"

From EPrints Documentation
Jump to: navigation, search
Line 54: Line 54:
 
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 [[API:EPrints/Repository|EPrints::Repository]]).
 
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 [[API:EPrints/Repository|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.
+
A normal dataset (eg. "user") has a package associated with it  (eg. [[API:EPrints/DataObj/User|EPrints::DataObj::User]]) which must be a subclass of [[API:EPrints/DataObj|EPrints::DataObj]] and a number of SQL tables which are prefixed with the dataset name. Most datasets also have a set of associated [[API:EPrints/MetaField|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.
 
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.
+
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 [[API:EPrints/DataObj/EPrints|EPrints::DataObj::EPrints]]. You can define your  own virtual datasets which opperate on existing 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 82: Line 82:
 
   $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:EPrints/DataSet#id|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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 222: Line 222:
 
====$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:EPrints/DataSet#prepare_search|prepare_search]]( %options )-&gt;execute.
 +
 
 +
<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_satisfy_all_1 -->
 +
===="satisfy_all"=&gt;1 ====
 +
 
 +
Satify all conditions specified. 0 means satisfy any of the conditions specified. Default is 1
 +
 
 +
<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_staff_1 -->
 +
===="staff"=&gt;1====
 +
 
 +
Do search as an adminstrator means you get everything back
 +
 
 +
<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_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
 +
 
 +
<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_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)
 +
 
 +
<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_limit_10 -->
 +
===="limit" =&gt; 10====
 +
 
 +
Only return 10 results
  
 
<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 236: Line 296:
 
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=head_copyright -->
 +
==COPYRIGHT==
 
<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>

Revision as of 10:46, 25 August 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 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


"satisfy_all"=>1

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

User Comments


"staff"=>1

Do search as an adminstrator means you get everything back

User Comments


"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"});

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

User Comments


"limit" => 10

Only return 10 results

User Comments


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

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

User Comments


COPYRIGHT

User Comments


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