Run Helpers

The official RethinkDB drivers expect developers to know the type of response returned from a given query. The C# and Java follow the same paradigm.

In order for the C# driver to maintain API compatibility with the official drivers, the .run() method return a dynamic type. The underlying dynamic type is determined by Newtonsoft and represents a best effort guess as to what the underlying type is. The Dynamic Language Runtime (DLR) Integration goes into further detail.

There are two consequences to using the .run() method:

1. The execution context of .run() goes through the DLR. The DLR does incur a slight performance tax.
2. An extra syntax burden is placed on the developer to get a strongly-typed result from .run().

The use of run helpers solve both issues above. To illustrate, consider the following example:

Cursor<Change<Hero>> changeFeed = r.db("marvel").table("heros")
                                   .changes().run<Cursor<Change<Foo>>();

The syntax is a bit verbose and it invokes the DLR via .run<T>(). The above query can be written more simply (and gain a slight edge in performance) by using the .runChanges helper as shown below:

var changeFeed = r.db("marvel").table("heros")
                  .changes().runChanges<Hero>();

The full list of Run Helpers are outlined here:

---

.runAtom

When the response type for a query is a SUCCESS_ATOM the driver is expected to return an object of T. Typically, queries that return singleRowSelection are atom responses.

Hero result = r.db("marvel").table("heros")
              .get("iron_man")
              .run<Hero>(conn);

var result = r.db("marvel").table("heros")
              .get("iron_man")
              .runAtom<Hero>(conn);

---

.runCursor

When the response type for a query is a SUCCESS_SEQUENCE or SUCCESS_PARTIAL the driver is expected to return a cursor.

Cursor<Hero> all = r.db("marvel")
                   .table("heros")
                   .getAll("iron_man", "hulk", "thor")
                   .run<Hero>(conn);

var all = r.db("marvel")
           .table("heros")
           .getAll("iron_man", "hulk", "thor")
           .runCursor<Hero>(conn);

---

.runResult

.runResult() helps with DML type of result queries:

var result = r.db("marvel").table("heros")
              .insert({"name":"Iron Man"})
              .runResult(conn);
/*
{
    "deleted": 0,
    "errors": 0,
    "inserted": 1,
    "replaced": 0,
    "skipped": 0,
    "unchanged": 0
}
*/

In the example above, result is a strongly typed Result helper type with strongly typed properties.

Result Assertions

With Result types, assertions can be made about the result. For example:

var result = r.db("marvel").table("heros")
              .insert({"name":"Iron Man"})
              .runResult(conn)
              .AssertNoErrors()
              .AssertInserted(1);

The example above ensures that there are 0 errors and 1 document inserted. Otherwise an exception is thrown.

---

.runChanges<T>()

Change feed declaraitons can be combersome. For exmaple,

Cursor<Change<Hero>> changeFeed = r.db("marvel").table("heros")
                                   .changes().run<Cursor<Change<Foo>>();

Using the runChanges<T> helper reduces verbosity while type safety for changeFeed is preserved as Cursor<Change<Hero>>:

var changeFeed = r.db("marvel").table("heros")
                  .changes().runChanges<Hero>();

Change<T> is a helper type that contains two properties, NewValue and OldValue of type T. When subscribing to .changes() the changeFeed cursor will fill with Change<T> items when the changeFeed cursor is enumerated over and as changes happen.

---

.runGrouping<TKey,TItem>()

Consider the following query:

IEnumerable<GroupedResult<string,Game>> result = 
    r.expr(games).group("player")
    .run<GroupedResult<string, Game>>(conn);

foreach( var group in result )
{
    Console.WriteLine($">>>> KEY:{group.Key}");
    group.Dump();
}

The same query can be simplified with the runGrouping helper:

var result = 
    r.expr(games).group("player")
    .runGrouping<string, Game>(conn);

foreach( var group in result )
{
    Console.WriteLine($">>>> KEY:{group.Key}");
    group.Dump();
}

result is still typed as IEnumerable<GroupedResult<string,Game>>.