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, methods like .run() return a dynamic type. The dynamic is determined by Newtonsoft 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 is using the DLR via .run<T>(). The above query can be written more simply (and gain a slight edge in performance) 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 from 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 from 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();
/*
{
    "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()
              .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>>.