Accessing Data

There are several ways in which your data is made available once in Dataset. Specifically all these ways fall into the following categories:

Direct Access

The following methods allow you to have access to parts of Dataset directly - as in, you can directly interface with the objects that make up your Dataset instance. While convenient, if you change the data in a matter other than the one specified, you can create inconsistancies in our index.

The methods that give you direct access are:

  • ds.column(name)
    This returns the actual column object. Note that because the order of columns is not guaranteed (or should matter,) the fetching of columns is always done by name.
  • col.data
    After fetching a column using ds.column(name), you can get a hold of the data in it directly by referencing the data array. This is NOT recommended as all updates should go through the add/remove/update methods.
  • col.name
    After fetching a column using ds.column(name), you can get a hold of the column name directly.
  • col.type
    After fetching a column using ds.column(name), you can get a hold of the column name directly.

Indirect Access

The following methods give you access to the content, but it is first separated form the actual Dataset. This is for two reasons: First, because 'rows' are a more logical interaction unit it makes more sense to provide an API that can access data in this way. Because we don't actually store the data in this way, we have to make the row objects. The actual data is stored in column arrays and is only tied together by position.

The methods that give you indirect access are:

  • ds.columnNames()
    Returns an array of column names.
  • ds.rowByPosition(pos)
    To get the Nth row in your dataset, just pass the position into rowByPosition. An object representing the row will be returned.
  • ds.rowById(id)
    To get the row with a specfic _id value. An object representing the row will be returned. Note, the _id value is an auto generated value and should never be changed.
  • ds.each(iterator, context)
    Iterates over all rows.
    ds.each(function(row, rowIndex) {
      // do what you need here.
    });
  • ds.eachColumn(iterator, context)
    Iterates over available columns (not including _id column.)
    ds.eachColumn(function(columnName, column, index) {
      // do what you need here.
    });

Data Views

Dataset offers a pretty versatile selection mechanism. To allow for an interface identical to your Dataset's instance, while operating on a subset we return a DataView object. A DataView functions very much like Dataset (in fact Dataset inherits from DataView). The major difference is that DataViews are immutable - they do not offer any way to change the selected data. This is because they are tied to the original data.

The methods that give you DataView objects:

  • ds.where(filter, options)
    Returns a subset of rows that meet the specified filter requirement.
  • ds.columns(nameArray)
    Returns a subset of columns. Shorthand for ds.where({ columns : nameArray })
  • ds.rows(rowFilter, options)
    Returns a subset of rows. Shorthand for ds.where({ rows : rowFilter })
  • dv.parent
    Assume dv is an existing selection that was created using one of the above methods. Calling parent returns a handle to the original parent dataset or dataview from which this selection was created.

Synchronization

By default, a selection does not maintain a direct relationship to the data if the original data is changed. For example, if you try to select all rows where a particualr column's value is even and then change a row that matched the original selection to no longer match it, the DataView returned by the selection will still contain it. To prevent this from happening, you can indicate that all DataViews created from a Dataset (or other DataViews!) should sync with the original data. You can do that by setting the sync property to true when initializing your Dataset. For example:

You can edit the code in this block and rerun it.

« Data Types

Syncronization & Events »