Simple.Data

Simple.Data defines a number of commands for retrieving data from a data store. These can then be daisychained in a LINQ-like fashion with further methods to modify the basic query. For example, Simple.Data includes four similar methods to cast the result of a query back into its simple type or a collection of scalar types instead of having to retrieve it as the property of a SimpleRecord with an empty string.

ToScalar

ToScalar and ToScalar<T> return a property from the results of a query as a scalar value. ToScalar returns the value as its default type. ToScalar<T> allows you to determine the type the value will be cast to. Both methods work against SimpleRecord and SimpleQuery types, but with slightly different rules.

SimpleRecords

In the code below, album is returned as a dynamic object, created as a SimpleRecord instance, and will return values for all the Album fields in the table.

var album = db.Albums.Get(1);

Calling ToScalar on this will return the first property in the SimpleRecord as a scalar value. In this case, it will return the AlbumId property as an int. Calling ToScalar<T> allows you to cast that scalar value into another type.

int AlbumId = db.Albums.Get(1).ToScalar();

If you include a Select method in your query, ToScalar will return the first field identified in that method. For example, the following code will return the Title field as a string.

string Title = db.Albums.Select(db.Albums.Title).Get(1).ToScalar();

Exceptions

  • ToScalar and ToScalar<T> will throw a RuntimeBinderException if the query you apply them to returns no rows (null).
  • ToScalar<T> will throw an InvalidCastException if the value you are targetting cannot be cast to type T.

SimpleQueries

ToScalar and ToScalar<T> may only be applied to SimpleQueries that contain one result. For example

var albums = db.Albums.FindAllByGenreId(1).FirstOrDefault();

As with SimpleRecords, calling ToScalar on this will return the first property in the first SimpleRecord result as a scalar value. Calling ToScalar<T> allows you to cast that scalar value into another type. In this case, it will return the AlbumId property as an int.

int AlbumId = db.Albums.FindAllByGenreId(1).FirstOrDefault().ToScalar();

If you include a Select method in your query, ToScalar will return the first field identified in that method. For example, the following code will return the Title field as a string.

string Title = db.Albums.FindAllByGenreId(1).Select(db.Albums.Title).FirstOrDefault().ToScalar();

Exceptions

  • ToScalar and ToScalar<T> will throw a SimpleDataException if the query you apply them to returns no rows (i.e. is null) or returns more than one row
  • ToScalar<T> will throw an InvalidCastException if the value you are targetting cannot be cast to type T.

ToScalarOrDefault

ToScalarOrDefault and ToScalarOrDefault<T> return a property from the results of a query as a scalar value. ToScalarOrDefault returns the value as its default type. ToScalarOrDefault<T> allows you to determine the type the value will be cast to. If the property is null, ToScalarOrDefault<T> will return default(T).

ToScalarOrDefault and ToScalarOrDefault<T> may only be applied to SimpleQueries that contain zero or one result. For example

var albums = db.Albums.FindAllByAlbumId(1);

If the query returned zero results and albums was set to null, ToScalarOrDefault would also return null and ToScalarOrDefault<T> would return default(T). If the one result has more than one property, it will throw an exception. If the query returns one result with only one property, it will return the scalar value. For example, the following code will return the Title field as a string.

string Title = db.Albums.FindAllByAlbumId(1).Select(db.Albums.Title).ToScalarOrDefault();

Exceptions

  • ToScalarOrDefault and ToScalarOrDefault<T> will throw an UnresolvableObjectException if the query you apply them to returns a single result as a SimpleRecord instance rather than a SimpleQuery.
  • ToScalarOrDefault and ToScalarOrDefault<T> will throw a SimpleDataException if the query you apply them to returns more than one row
  • ToScalarOrDefault and ToScalarOrDefault<T> will throw a SimpleDataException if the query you apply them to returns one row with more than one property in it
  • ToScalarOrDefault<T> will throw an InvalidCastException if the value you are targetting cannot be cast to type T.

ToScalarList

ToScalarList and ToScalarList<T> take a set of results and return a List of one value from each of those results (as a scalar value). ToScalarList returns each value as its default type. ToScalarList<T> allows you to determine the type the value will be cast to.

ToScalarList and ToScalarList<T> may only be applied to SimpleQueries. For example

var albums = db.Albums.FindAllByGenreId(1);

Calling ToScalarList on albums will return a list of the first property in each Album as a scalar value - in this case, the integer albumid - instantiated as a List<dynamic>. Calling ToScalarList<int> would return the list of albumids as List<int> 

List<dynamic> albums = db.Albums.FindAllByGenreId(1).ToScalarList();
List<int> albums = db.Albums.FindAllByGenreId(1).ToScalarList<int>();

If you include a Select method in your query, ToScalarList will return a List of the first field identified in that method. For example, the following code will return the Title fields as a List<dynamic> / List<string>.

List<dynamic> albums = db.Albums.FindAllByGenreId(1).Select(db.Albums.Title).ToScalarList();
List<string> albums = db.Albums.FindAllByGenreId(1).Select(db.Albums.Title).ToScalarList<string>();

EXCEPTIONS

  • ToScalarList and ToScalarList<T> will throw a RuntimeBinderException if the query you apply them to returns null (no results).
  • ToScalarList and ToScalarList<T> will throw an UnresolvableObjectException if the query you apply them to returns a single result as a SimpleRecord instance rather than a SimpleQuery.
  • ToScalarList<T> will throw an InvalidCastException if the value you are targetting cannot be cast to type T.

ToScalarArray

ToScalarArray and ToScalarArray<T> take a set of results and return an array of one value from each of those results (as a scalar value). ToScalarArray returns each value as its default type. ToScalarArray<T> allows you to determine the type the value will be cast to.

ToScalarArray and ToScalarArray<T> may only be applied to SimpleQueries. For example

var albums = db.Albums.FindAllByGenreId(1);

Calling ToScalarArray on albums will return an array of the first property in each Album as a scalar value - in this case, the integer albumid - instantiated as a dynamic[]. Calling ToScalarArray<int> would return the array of albumids as int[] 

dynamic[] albums = db.Albums.FindAllByGenreId(1).ToScalarArray();
int[] albums = db.Albums.FindAllByGenreId(1).ToScalarArray<int>();

If you include a Select method in your query, ToScalarArray will return an array of the first field identified in that method. For example, the following code will return the Title fields as a dynamic[] / string[].

dynamic[] albums = db.Albums.FindAllByGenreId(1).Select(db.Albums.Title).ToScalarArray();
string[] albums = db.Albums.FindAllByGenreId(1).Select(db.Albums.Title).ToScalarArray<string>();

EXCEPTIONS

  • ToScalarArray and ToScalarArray<T> will throw a RuntimeBinderException if the query you apply them to returns null (no results).
  • ToScalarArray and ToScalarArray<T> will throw an UnresolvableObjectException if the query you apply them to returns a single result as a SimpleRecord instance rather than a SimpleQuery.
  • ToScalarArray<T> will throw an InvalidCastException if the value you are targetting cannot be cast to type T.