ReQL command: run

Command syntax

query.run(conn[, options]) → cursor
query.run(conn[, options]) → object

Description

Run a query on a connection, returning either a single JSON result or a cursor, depending on the query.

The options can be:

• read_mode: One of three possible values affecting the consistency guarantee for the query (default: 'single').
  • 'single' (the default) returns values that are in memory (but not necessarily written to disk) on the primary replica.
  • 'majority' will only return values that are safely committed on disk on a majority of replicas. This requires sending a message to every replica on each read, so it is the slowest but most consistent.
  • 'outdated' will return values that are in memory on an arbitrarily-selected replica. This is the fastest but least consistent.
• time_format: what format to return times in (default: 'native'). Set this to 'raw' if you want times returned as JSON objects for exporting.
• profile: whether or not to return a profile of the query’s execution (default: false).
• durability: possible values are 'hard' and 'soft'. In soft durability mode RethinkDB will acknowledge the write immediately after receiving it, but before the write has been committed to disk.
• group_format: what format to return grouped_data and grouped_streams in (default: 'native'). Set this to 'raw' if you want the raw pseudotype.
• noreply: set to true to not receive the result object or cursor and return immediately.
• db: the database to run this query against, specified with the db command. The default is the database specified in the db parameter to connect (which defaults to test). The database may also be specified separately with the db command.
• array_limit: the maximum numbers of array elements that can be returned by a query (default: 100,000). This affects all ReQL commands that return arrays. Note that it has no effect on the size of arrays being written to the database; those always have an upper limit of 100,000 elements.
• binary_format: what format to return binary data in (default: 'native'). Set this to 'raw' if you want the raw pseudotype.
• min_batch_rows: minimum number of rows to wait for before batching a result set (default: 8). This is an integer.
• max_batch_rows: maximum number of rows to wait for before batching a result set (default: unlimited). This is an integer.
• max_batch_bytes: maximum number of bytes to wait for before batching a result set (default: 1MB). This is an integer.
• max_batch_seconds: maximum number of seconds to wait before batching a result set (default: 0.5). This is a float (not an integer) and may be specified to the microsecond.
• first_batch_scaledown_factor: factor to scale the other parameters down by on the first batch (default: 4). For example, with this set to 8 and max_batch_rows set to 80, on the first batch max_batch_rows will be adjusted to 10 (80 / 8). This allows the first batch to return faster.

Example: Run a query on the connection conn and print out every row in the result.

r.table('marvel').run(conn).each { |x| p x }

Example: If you are OK with potentially out of date data from all the tables involved in this query and want potentially faster reads, pass a flag allowing out of date data in an options object. Settings for individual tables will supercede this global setting for all tables in the query.

r.table('marvel').run(conn, :read_mode => 'outdated')

Example: If you just want to send a write and forget about it, you can set noreply to true in the options. In this case run will return immediately.

r.table('marvel').run(conn, :noreply => true)

Example: If you want to specify whether to wait for a write to be written to disk (overriding the table’s default settings), you can set durability to 'hard' or 'soft' in the options.

r.table('marvel')
    .insert({ :superhero => 'Iron Man', :superpower => 'Arc Reactor' })
    .run(conn, :noreply => true, :durability => 'soft')

Example: If you do not want a time object to be converted to a native date object, you can pass a time_format flag to prevent it (valid flags are “raw” and “native”). This query returns an object with two fields (epoch_time and $reql_type$) instead of a native date object.

r.now().run(conn, :time_format=>"raw")

Example: Specify the database to use for the query.

r.table('marvel').run(conn, :db => r.db('heroes')).each { |x| p x }

This is equivalent to using the db command to specify the database:

r.db('heroes').table('marvel').run(conn) ...

Example: Change the batching parameters for this query.

r.table('marvel').run(conn, :max_batch_rows => 16, :max_batch_bytes => 2048)

Example: Use run with a Ruby block. This style allows you to pass a cursor to the block as its argument, closing the cursor when execution reaches the end of the block.

r.table('marvel').run(conn) { |cursor|
    cursor.each { |hero| fight(hero) }
}

```