.. _chapter_oerecord:

********************************************************************************
OERecord
********************************************************************************

An :ref:`OERecord <OEDataFlow_OERecord>` is a data container that holds a
variety of strongly-typed, named values, plus associated metadata. It is used
to pass data between cubes in Orion workfloes, and is the main mechanism by
which data is communicated to and from Orion. OERecords also provide a 
general way to create and store structured data within the **OpenEye** 
ecosystem.

The most straightforward use of an :ref:`OERecord <OEDataFlow_OERecord>` is
for storage and retrieval of simple values. The following example illustrates 
how to use a record to store and retrieve integer, string, and floating point 
values.

.. oe:source:: OERecord.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SET-DATA-VALUES

.. oe:source:: OERecord.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SET-DATA-VALUES

:ref:`OERecord <OEDataFlow_OERecord>` has methods that allow you to
interrogate the record for the presence of fields and values.

.. oe:source:: OERecord.py
  :language: python
  :noindent:
  :frag:     SNIPPET-TEST-FIELDS

.. oe:source:: OERecord.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-TEST-FIELDS


Other types of data can be stored on OERecords, including molecules and even
other OERecords.

.. oe:source:: OERecord.py
  :language: python
  :noindent:
  :frag:     SNIPPET-OTHER-DATA

.. oe:source:: OERecord.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-OTHER-DATA

OERecords can be written to files and read from files using the 
:ref:`OEWriteRecord <OEDataFlow_OEWriteRecord>`  and
:ref:`OEReadRecord <OEDataFlow_OEReadRecord>` functions.


.. oe:source:: OERecord.py
  :language: python
  :noindent:
  :frag:     SNIPPET-RECORD-IO

.. oe:source:: OERecord.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-RECORD-IO


Metadata on fields
=======================================================================

.. oe:language:: c++

   In addition to holding various types of data, 
   :ref:`OERecord <OEDataFlow_OERecord>` can also hold various pieces of
   metadata about its fields. The metadata is stored onto field objects using the
   :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` class and constants from the
   :ref:`OEMetadata <OEDataFlow_OEMetadata>` class.

.. oe:language:: python

   In addition to holding various types of data, 
   :ref:`OERecord <OEDataFlow_OERecord>` can also hold various pieces of
   metadata about its fields. The metadata is stored onto field objects using the
   :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` class and constants from the
   :ref:`OEMetadata <OEDataFlow_OEMetadata>` class.

There are two types of metadata: *options* which are simple flags, and 
*attributes* which are key/value pairs with user-supplied values.

In the following example, two pieces of metadata, one option and one attribute,
are put on a field to describe the contents of that field.

.. oe:source:: OERecord.py
  :language: python
  :noindent:
  :frag:     SNIPPET-FIELD-METADATA

.. oe:source:: OERecord.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-FIELD-METADATA


Metadata can also be used to designate relationships between fields on a
record. The following example shows how to attach error values to a field using
metadata.

.. oe:source:: OERecord.py
  :language: python
  :noindent:
  :frag:     SNIPPET-FIELD-METADATA-RELATION

.. oe:source:: OERecord.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-FIELD-METADATA-RELATION

.. seealso::

   * :ref:`chapter_oemolrecord` chapter
