Editing API:EPrints/DataSet

<!-- 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.
 -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/DataSet.pm|package_name=EPrints::DataSet}}[[Category:API|DATASET]][[Category:API:EPrints/DataSet|DATASET]]<div><!-- Edit below this comment -->


<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
==NAME==
'''EPrints::DataSet''' - a set of records with the same metadata scheme

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_synopsis -->
==SYNOPSIS==
<source lang="perl">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 );</source>

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_description -->
==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 [[API:EPrints/Repository|EPrints::Repository]]).

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 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 [[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]]. You can define your  own virtual datasets which opperate on existing datasets.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_creating_custom_datasets -->
==CREATING CUSTOM DATASETS==
New datasets can be defined in a configuration file, e.g.

<pre>  $c-&gt;{datasets}-&gt;{bread} = {
    class =&gt; "EPrints::DataObj::Bread",
    sqlname =&gt; "bread",
  };</pre>

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

Other optional properties:

<pre>  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)</pre>

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

<pre>  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</pre>

As with system datasets, the [[API:EPrints/MetaField|EPrints::MetaField]]s can be defined via [[API:EPrints/DataObj#get_system_field_info|EPrints::DataObj/get_system_field_info]] or via configuration:

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

See [[API:EPrints/RepositoryConfig#add_dataset_field|EPrints::RepositoryConfig/add_dataset_field]] for details on <code>add_dataset_field</code>.

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

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

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_methods -->
==METHODS==
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_class_methods -->
===Class Methods===
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_object_methods -->
===Object Methods===
 $id = $ds-&gt;base_id
<pre>  $ds = $repo-&gt;dataset( "inbox" );
  $id = $ds-&gt;base_id; # returns "eprint"</pre>

Returns the identifier of the base dataset for this dataset (same as [[API:EPrints/DataSet#id|id]] unless this dataset is virtual).

 $metafield = $ds-&gt;field( $fieldname )
Returns the [[API:EPrints/MetaField|EPrints::MetaField]] from this dataset with the given name, or undef.

 $id = $ds-&gt;id
Return the id of this dataset.

 $n = $ds-&gt;count( $session )
Return the number of records in this dataset.

 @fields = $ds-&gt;fields
Returns a list of the [[API:EPrints/MetaField|EPrints::MetaField]]s belonging to this dataset.

 $field = $ds-&gt;key_field
Return the [[API:EPrints/MetaField|EPrints::MetaField]] representing the primary key field.

Always the first field.

 $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]].

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

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

 $obj = $ds-&gt;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.

 $dataobj = $ds-&gt;dataobj( $id )
Returns the object from this dataset with the given id, or undefined.

 $repository = $ds-&gt;repository
Returns the [[API:EPrints/Repository|EPrints::Repository]] to which this dataset belongs.

 $searchexp = $ds-&gt;prepare_search( %options )
Returns a [[API:EPrints/Search|EPrints::Search]] for this dataset with %options.

 $list = $ds-&gt;search( %options )
Short-cut to [[API:EPrints/DataSet#prepare_search|prepare_search]]( %options )-&gt;execute.

* satisfy_all
<pre>   satisfy_all"=&gt;1</pre>

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

* staff
<pre>  "staff"=&gt;1</pre>

: Do search as an adminstrator means you get everything back

* custom_order
<pre>  "custom_order" =&gt; "field1/-field2/field3"</pre>

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

* filters
<pre>  "filters" =&gt; \@(
                         { meta_fields=&gt;[ "field1", "field2" "document.field3" ],
                           merge=&gt;"ANY", match=&gt;"EX",
                           value=&gt;"bees"
                         },
                         { meta_fields=&gt;[ "field4" ],
                           value=&gt; qw( honey ),
                           match=&gt;"IN"
                         }
                       );</pre>

: This searchs for 'bees' in <code>field1</code> or <code>field2</code> or <code>document.field3</code>, and 'honey' in <code>field4</code>

: For details on the <code>merge</code> and <code>match</code> parameters, refer to [[API:EPrints/Search/Field|EPrints::Search::Field]]

<pre>  "limit" =&gt; 10</pre>

Only return 10 results

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_list -->
===list===

<source lang="perl">$list = $ds->list( $ids )

</source>
Returns a [[API:EPrints/List|EPrints::List]] for this dataset for the given $ids list.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_search_config -->
===search_config===

<source lang="perl">$sconf = $dataset->search_config( $searchid )

</source>
Retrieve the search configuration $searchid for this dataset. This typically contains a set of fields to search over, order values and rendering parameters.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_copyright -->
==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/.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=_postamble_ -->
<!-- Edit below this comment -->