ChadoRecord Class Reference

Public Member Functions
	__construct ($table_name, $record_id=NULL)
	getID ()
	getTable ()
	getSchema ()
	save ()
	insert ()
	update ()
	delete ()
	setValues ($values)
	getValues ()
	setValue ($column_name, $value)
	getValue ($column_name)
	find ()

Protected Attributes
	$table_name = ''
	$schema = []
	$values = []
	$required_cols = []
	$missing_required_col = []
	$record_id = NULL
	$pkey = ''
	$column_names = []

Detailed Description

Provide a class for basic querying of Chado.

Specifically tihs class provides select, insert, update and delete.

Eventually this class is meants to replace the existing chado_select_record(), chado_insert_record(), chado_update_record() and chado_delete_record() API functions to create a cleaner, more maintainable and more easily tested interface to querying Chado.

Todo:

Add documentation for save() and delete().

Basic Usage:

• Select/Find The following example selects an organism with the scientific name "Tripalus databasica" from the organism table of Chado.

  // First we create an instance of the ChadoRecord class
  // specifying the table we want to query.
  $record = new \ChadoRecord('organism');
   
  // Next we indicate the values we know.
  $record->setValues([
  'genus' => 'Tripalus',
  'species' => 'databasica',
  ]);
   
  // And finally we simply ask the class to find the chado record
  // we indicated when we set the values above.
  $success = $record->find();
  if ($success) {
  // Retrieve the values if we were successful in finding the record.
  $result = $record->getValues();
  }

• Insert: The following example inserts a sample record into the stock table.

  // First we create an instance of the ChadoRecord class
  // specifying the table we want to query.
  $record = new \ChadoRecord('stock');
   
  // Next we indicate the values we know.
  $record->setValues([
  'name' => 'My Favourite Plant',
  'uniquename' => 'Plectranthus scutellarioides Trailing Plum Brocade',
  'organism_id' => [ 'genus' => 'Tripalus', 'species' => 'databasica' ],
  'type_id' => [ 'name' => 'sample', 'cv_id' => [ 'name' => 'Sample processing
    and separation techniques' ] ],
  ]);
   
  // And finally, we ask the class to insert the chado record
  // we described when we set the values above.
  $result = $record->insert();

• Update: The following example updates the "Tripalus databasica" record to specify the common name.

  // For brevity we're going to hardcode the original record
  // including the id although you would Never do this in practice.
  // Rather you would first find the record as shown in a previous example.
  $original_record = [
  'organism_id' => 1,
  'genus' => 'Tripalus',
  'species' => 'databasica',
  ];
   
  // First we create an instance of the ChadoRecord class
  // specifying the table we want to query.
  // NOTICE: this time we set the record_id when creating the instance.
  $record = new \ChadoRecord('organism', $original_record['organism_id']);
   
  // Now we set the values we want to change.
  $record->setValues([
  'common_name' => 'Tripal',
  ]);
   
  // And then tell the class to update the record.
  $record->update();

Constructor & Destructor Documentation

__construct()

ChadoRecord::__construct	(		$table_name,
			$record_id = NULL
	)

The ChadoRecord constructor

Parameters

string	$table_name	The name of the table that the record belongs to.
string	$record_id	An optional record ID if this record is already present in Chado.

Member Function Documentation

delete()

ChadoRecord::delete

(

)

Deletes the record that matches the given values.

A record ID must be part of the current values.

Exceptions

Exception

find()

ChadoRecord::find

(

)

Uses the current values given to this object to find a record.

Use the setValues function first to set values for searching, then call this function to find matching record. The values provided to the setValues function must uniquely identify a record.

Todo:

Support options from chado_select_record: skip_validation, has_record, return_sql, case_insensitive_columns, regex_columns, order_by, is_duplicate, pager, limit, offset.

Support following the foreign key

Support complex filtering (e.g. fmin > 50)

Support multiple records being returned?

Returns

The number of matches found. If 1 is returned then the query successfully found a match. If 0 then no matching records were found.

Exceptions

Exception

getID()

ChadoRecord::getID

(

)

Retrieves the record ID.

Returns

number

getSchema()

ChadoRecord::getSchema

(

)

Retrieves the table schema.

Returns

array The Drupal schema array for the table.

getTable()

ChadoRecord::getTable

(

)

Retrieves the table name.

Returns

string The name of the table that the record belongs to.

getValue()

ChadoRecord::getValue

(

$column_name

)

Returns the value of a specific column.

Parameters

string

$column_name

The name of a column from the table from which to retrieve the value.

getValues()

ChadoRecord::getValues

(

)

Returns all values for the record.

Todo:

We need to follow foreign key constraints.

Returns

array

insert()

ChadoRecord::insert

(

)

Inserts the values of this object as a new record.

Todo:

Support options from chado_insert_record: return_record.

check for violation of unique constraint.

Exceptions

Exception

save()

ChadoRecord::save

(

)

Performs either an update or insert into the table using the values.

If the record already exists it will be updated. If the record does not exist it will be inserted. This function adds a bit more overhead by checking for the existence of the record and performing the appropriate action. You can save time by using the insert or update functions directly if you only need to do one of those actions specifically.

Exceptions

Exception

setValue()

ChadoRecord::setValue	(		$column_name,
			$value
	)

Sets the value for a specific column.

Todo:

Support options from chado_insert_record: skip_validation.

Validate the types match what is expected based on the schema.

Set default values for columns not in this array?

Support foreign key relationships: lookup the key.

Support value = [a, b, c] for IN select statements?

Parameters

string	$column_name	The name of the column to which the value should be set.
	$value	The value to set.

setValues()

ChadoRecord::setValues

(

$values

)

A general-purpose setter function to set the column values for the record.

This function should be used prior to insert or update of a record. For an update, be sure to include the record ID in the list of values passed to the function.

Todo:

Support options from chado_insert_record: skip_validation.

Validate the types match what is expected based on the schema.

Set default values for columns not in this array?

Support foreign key relationships: lookup the key.

Support value = [a, b, c] for IN select statements?

Parameters

array

$values

An associative array where the keys are the table column names and the values are the record values for each column.

Exceptions

Exception

update()

ChadoRecord::update

(

)

Updates the values of this object as a new record.

Todo:

set defaults for columns not already set in values.

Support options from chado_update_record: return_record.

check for violation of unique constraint.

if record_id not set then try finding it.

Exceptions

Exception

---

The documentation for this class was generated from the following file:

• tripal_chado/api/ChadoRecord.inc