Get desktop application:
View/edit binary Protocol Buffers messages
Used in:
A [Datum] is a chunk of data that can be serialized to disk or returned to the user in a Response. Currently we only support JSON types, but we may support other types in the future (e.g., a date type or an integer type).
Used in:
, ,Used in:
Used in:
a double
This [DatumType] will only be used if [accepts_r_json] is set to [true] in [Query]. [r_str] will be filled with a JSON encoding of the [Datum].
uses r_str
A backtrace frame (see `backtrace` in Response below)
Used in:
The index of the positional argument.
The name of the optional argument.
Used in:
Error occured in a positional argument.
Error occured in an optional argument.
You send one of: * A [START] query with a [Term] to evaluate and a unique-per-connection token. * A [CONTINUE] query with the same token as a [START] query that returned [SUCCESS_PARTIAL] in its [Response]. * A [STOP] query with the same token as a [START] query that you want to stop. * A [NOREPLY_WAIT] query with a unique per-connection token. The server answers with a [WAIT_COMPLETE] [Response].
A [Term] is how we represent the operations we want a query to perform.
only present when [type] = [START]
This flag is ignored on the server. `noreply` should be added to `global_optargs` instead (the key "noreply" should map to either true or false).
If this is set to [true], then [Datum] values will sometimes be of [DatumType] [R_JSON] (see below). This can provide enormous speedups in languages with poor protobuf libraries.
Used in:
Used in:
Start a new query.
Continue a query that returned [SUCCESS_PARTIAL]
(see [Response]).
Stop a query partway through executing.
Wait for noreply operations to finish.
You get back a response with the same [token] as your query.
Indicates what [Query] this response corresponds to.
[response] contains 1 RQL datum if [type] is [SUCCESS_ATOM], or many RQL data if [type] is [SUCCESS_SEQUENCE] or [SUCCESS_PARTIAL]. It contains 1 error message (of type [R_STR]) in all other cases.
If [type] is [CLIENT_ERROR], [TYPE_ERROR], or [RUNTIME_ERROR], then a backtrace will be provided. The backtrace says where in the query the error occured. Ideally this information will be presented to the user as a pretty-printed version of their query with the erroneous section underlined. A backtrace is a series of 0 or more [Frame]s, each of which specifies either the index of a positional argument or the name of an optional argument. (Those words will make more sense if you look at the [Term] message below.)
Contains n [Frame]s when you get back an error.
If the [global_optargs] in the [Query] that this [Response] is a response to contains a key "profile" which maps to a static value of true then [profile] will contain a [Datum] which provides profiling information about the execution of the query. This field should be returned to the user along with the result that would normally be returned (a datum or a cursor). In official drivers this is accomplished by putting them inside of an object with "value" mapping to the return value and "profile" mapping to the profile object.
ResponseNotes are used to provide information about the query response that may be useful for people writing drivers or ORMs. Currently all the notes we send indicate that a stream has certain special properties.
Used in:
The stream is a changefeed stream (e.g. `r.table('test').changes()`).
The stream is a point changefeed stream (e.g. `r.table('test').get(0).changes()`).
The stream is an order_by_limit changefeed stream (e.g. `r.table('test').order_by(index: 'id').limit(5).changes()`).
The stream is a union of multiple changefeed types that can't be collapsed to a single type (e.g. `r.table('test').changes().union(r.table('test').get(0).changes())`).
The stream is a changefeed stream and includes notes on what state the changefeed stream is in (e.g. objects of the form `{state: 'initializing'}`).
Used in:
These response types indicate success.
Query returned a single RQL datatype.
Query returned a sequence of RQL datatypes.
Query returned a partial sequence of RQL
datatypes. If you send a [CONTINUE] query with the same token as this response, you will get more of the sequence. Keep sending [CONTINUE] queries until you get back [SUCCESS_SEQUENCE].
A [NOREPLY_WAIT] query completed.
These response types indicate failure.
Means the client is buggy. An example is if the
client sends a malformed protobuf, or tries to send [CONTINUE] for an unknown token.
Means the query failed during parsing or type
checking. For example, if you pass too many arguments to a function.
Means the query failed at runtime. An example is
A [Term] is either a piece of data (see **Datum** above), or an operator and its operands. If you have a [Datum], it's stored in the member [datum]. If you have an operator, its positional arguments are stored in [args] and its optional arguments are stored in [optargs]. A note about type signatures: We use the following notation to denote types: arg1_type, arg2_type, argrest_type... -> result_type So, for example, if we have a function `avg` that takes any number of arguments and averages them, we might write: NUMBER... -> NUMBER Or if we had a function that took one number modulo another: NUMBER, NUMBER -> NUMBER Or a function that takes a table and a primary key of any Datum type, then retrieves the entry with that primary key: Table, DATUM -> OBJECT Some arguments must be provided as literal values (and not the results of sub terms). These are marked with a `!`. Optional arguments are specified within curly braces as argname `:` value type (e.x `{use_outdated:BOOL}`) Many RQL operations are polymorphic. For these, alterantive type signatures are separated by `|`. The RQL type hierarchy is as follows: Top DATUM NULL BOOL NUMBER STRING OBJECT SingleSelection ARRAY Sequence ARRAY Stream StreamSelection Table Database Function Ordering - used only by ORDER_BY Pathspec -- an object, string, or array that specifies a path Error
Used in:
, ,This is only used when type is DATUM.
Holds the positional arguments of the query.
Holds the optional arguments of the query.
Used in:
Used in:
A RQL datum, stored in `datum` below.
DATUM... -> ARRAY
Evaluate the terms in [optargs] and make an object
{...} -> OBJECT
Takes an integer representing a variable and returns the value stored in that variable. It's the responsibility of the client to translate from their local representation of a variable to a unique _non-negative_ integer for that variable. (We do it this way instead of letting clients provide variable names as strings to discourage variable-capturing client libraries, and because it's more efficient on the wire.)
!NUMBER -> DATUM
Takes some javascript code and executes it.
STRING {timeout: !NUMBER} -> DATUM |
STRING {timeout: !NUMBER} -> Function(*)
() -> DATUM
Takes an HTTP URL and gets it. If the get succeeds and returns valid JSON, it is converted into a DATUM
STRING {data: OBJECT | STRING,
Takes a string and throws an error with that message. Inside of a `default` block, you can omit the first argument to rethrow whatever error you catch (this is most useful as an argument to the `default` filter optarg).
STRING -> Error | -> Error
Takes nothing and returns a reference to the implicit variable.
-> DATUM
* Data Operators Returns a reference to a database.
STRING -> Database
Returns a reference to a table.
Database, STRING, {use_outdated:BOOL, identifier_format:STRING} -> Table
STRING, {use_outdated:BOOL, identifier_format:STRING} -> Table Gets a single element from a table by its primary or a secondary key.
Table, STRING -> SingleSelection | Table, NUMBER -> SingleSelection |
Table, STRING -> NULL | Table, NUMBER -> NULL |
Table, DATUM..., {index:!STRING} => ARRAY
Simple DATUM Ops
DATUM... -> BOOL
DATUM... -> BOOL
DATUM... -> BOOL
DATUM... -> BOOL
DATUM... -> BOOL
DATUM... -> BOOL
BOOL -> BOOL
ADD can either add two numbers or concatenate two arrays.
NUMBER... -> NUMBER | STRING... -> STRING
NUMBER... -> NUMBER
NUMBER... -> NUMBER
NUMBER... -> NUMBER
NUMBER, NUMBER -> NUMBER
NUMBER -> NUMBER
NUMBER -> NUMBER
NUMBER -> NUMBER
DATUM Array Ops Append a single element to the end of an array (like `snoc`).
ARRAY, DATUM -> ARRAY
Prepend a single element to the end of an array (like `cons`).
ARRAY, DATUM -> ARRAY
Remove the elements of one array from another array.
ARRAY, ARRAY -> ARRAY
DATUM Set Ops Set ops work on arrays. They don't use actual sets and thus have performance characteristics you would expect from arrays rather than from sets. All set operations have the post condition that they array they return contains no duplicate values.
ARRAY, DATUM -> ARRAY
ARRAY, ARRAY -> ARRAY
ARRAY, ARRAY -> ARRAY
ARRAY, ARRAY -> ARRAY
Sequence, NUMBER, NUMBER -> Sequence
Sequence, NUMBER -> Sequence
Sequence, NUMBER -> Sequence
Sequence, DATUM -> Sequence | Sequence, Function(1) -> Sequence
Sequence, DATUM -> BOOL | Sequence, Function(1) -> BOOL
Stream/Object Ops Get a particular field from an object, or map that over a sequence.
OBJECT, STRING -> DATUM
| Sequence, STRING -> Sequence Return an array containing the keys of the object.
OBJECT -> ARRAY
Creates an object
STRING, DATUM, ... -> OBJECT
Check whether an object contains all the specified fields, or filters a sequence so that all objects inside of it contain all the specified fields.
OBJECT, Pathspec... -> BOOL
x.with_fields(...) <=> x.has_fields(...).pluck(...)
Sequence, Pathspec... -> Sequence
Get a subset of an object by selecting some attributes to preserve, or map that over a sequence. (Both pick and pluck, polymorphic.)
Sequence, Pathspec... -> Sequence | OBJECT, Pathspec... -> OBJECT
Get a subset of an object by selecting some attributes to discard, or map that over a sequence. (Both unpick and without, polymorphic.)
Sequence, Pathspec... -> Sequence | OBJECT, Pathspec... -> OBJECT
Merge objects (right-preferential)
OBJECT... -> OBJECT | Sequence -> Sequence
Sequence Ops Get all elements of a sequence between two values. Half-open by default, but the openness of either side can be changed by passing 'closed' or 'open for `right_bound` or `left_bound`.
Deprecated version of between, which allows `null` to specify unboundedness
With the newer version, clients should use `r.minval` and `r.maxval` for unboundedness
StreamSelection, DATUM, DATUM, {index:!STRING, right_bound:STRING, left_bound:STRING} -> StreamSelection
Sequence, Function(2) -> DATUM
Sequence, Function(1) -> Sequence
Filter a sequence with either a function or a shortcut object (see API docs for details). The body of FILTER is wrapped in an implicit `.default(false)`, and you can change the default value by specifying the `default` optarg. If you make the default `r.error`, all errors caught by `default` will be rethrown as if the `default` did not exist.
Sequence, Function(1), {default:DATUM} -> Sequence |
Sequence, OBJECT, {default:DATUM} -> Sequence Map a function over a sequence and then concatenate the results together.
Sequence, Function(1) -> Sequence
Order a sequence based on one or more attributes.
Sequence, (!STRING | Ordering)... -> Sequence
Get all distinct elements of a sequence (like `uniq`).
Sequence -> Sequence
Count the number of elements in a sequence, or only the elements that match a given filter.
Sequence -> NUMBER | Sequence, DATUM -> NUMBER | Sequence, Function(1) -> NUMBER
Sequence -> BOOL
Take the union of multiple sequences (preserves duplicate elements! (use distinct)).
Sequence... -> Sequence
Get the Nth element of a sequence.
Sequence, NUMBER -> DATUM
do NTH or GET_FIELD depending on target object
Sequence | OBJECT, NUMBER | STRING -> DATUM
Sequence, Sequence, Function(2) -> Sequence
Sequence, Sequence, Function(2) -> Sequence
An inner-join that does an equality comparison on two attributes.
Sequence, !STRING, Sequence, {index:!STRING} -> Sequence
Sequence -> Sequence
-> Sequence [0, +inf)
Array Ops Insert an element in to an array at a given index.
ARRAY, NUMBER, DATUM -> ARRAY
Remove an element at a given index from an array.
ARRAY, NUMBER -> ARRAY |
ARRAY, NUMBER, NUMBER -> ARRAY Change the element at a given index of an array.
ARRAY, NUMBER, DATUM -> ARRAY
Splice one array in to another array.
ARRAY, NUMBER, ARRAY -> ARRAY
* Type Ops Coerces a datum to a named type (e.g. "bool"). If you previously used `stream_to_array`, you should use this instead with the type "array".
Top, STRING -> Top
Returns the named type of a datum (e.g. TYPE_OF(true) = "BOOL")
Top -> STRING
* Write Ops (the OBJECTs contain data about number of errors etc.) Updates all the rows in a selection. Calls its Function with the row to be updated, and then merges the result of that call.
StreamSelection, Function(1), {non_atomic:BOOL, durability:STRING, return_changes:BOOL} -> OBJECT |
SingleSelection, Function(1), {non_atomic:BOOL, durability:STRING, return_changes:BOOL} -> OBJECT | StreamSelection, OBJECT, {non_atomic:BOOL, durability:STRING, return_changes:BOOL} -> OBJECT | SingleSelection, OBJECT, {non_atomic:BOOL, durability:STRING, return_changes:BOOL} -> OBJECT Deletes all the rows in a selection.
StreamSelection, {durability:STRING, return_changes:BOOL} -> OBJECT | SingleSelection -> OBJECT
Replaces all the rows in a selection. Calls its Function with the row to be replaced, and then discards it and stores the result of that call.
StreamSelection, Function(1), {non_atomic:BOOL, durability:STRING, return_changes:BOOL} -> OBJECT | SingleSelection, Function(1), {non_atomic:BOOL, durability:STRING, return_changes:BOOL} -> OBJECT
Inserts into a table. If `conflict` is replace, overwrites entries with the same primary key. If `conflict` is update, does an update on the entry. If `conflict` is error, or is omitted, conflicts will trigger an error.
Table, OBJECT, {conflict:STRING, durability:STRING, return_changes:BOOL} -> OBJECT | Table, Sequence, {conflict:STRING, durability:STRING, return_changes:BOOL} -> OBJECT
* Administrative OPs Creates a database with a particular name.
STRING -> OBJECT
Drops a database with a particular name.
STRING -> OBJECT
Lists all the databases by name. (Takes no arguments)
-> ARRAY
Creates a table with a particular name in a particular database. (You may omit the first argument to use the default database.)
Database, STRING, {primary_key:STRING, shards:NUMBER, replicas:NUMBER, primary_replica_tag:STRING} -> OBJECT
Database, STRING, {primary_key:STRING, shards:NUMBER, replicas:OBJECT, primary_replica_tag:STRING} -> OBJECT STRING, {primary_key:STRING, shards:NUMBER, replicas:NUMBER, primary_replica_tag:STRING} -> OBJECT STRING, {primary_key:STRING, shards:NUMBER, replicas:OBJECT, primary_replica_tag:STRING} -> OBJECT Drops a table with a particular name from a particular database. (You may omit the first argument to use the default database.)
Database, STRING -> OBJECT
STRING -> OBJECT Lists all the tables in a particular database. (You may omit the first argument to use the default database.)
Database -> ARRAY
-> ARRAY Returns the row in the `rethinkdb.table_config` or `rethinkdb.db_config` table that corresponds to the given database or table.
Database -> SingleSelection
Table -> SingleSelection Returns the row in the `rethinkdb.table_status` table that corresponds to the given table.
Table -> SingleSelection
Called on a table, waits for that table to be ready for read/write operations. Called on a database, waits for all of the tables in the database to be ready. Returns the corresponding row or rows from the `rethinkdb.table_status` table.
Table -> OBJECT
Database -> OBJECT Generates a new config for the given table, or all tables in the given database The `shards` and `replicas` arguments are required
Database, {shards:NUMBER, replicas:NUMBER[, primary_replica_tag:STRING, dry_run:BOOLEAN]} -> OBJECT
Database, {shards:NUMBER, replicas:OBJECT[, primary_replica_tag:STRING, dry_run:BOOLEAN]} -> OBJECT Table, {shards:NUMBER, replicas:NUMBER[, primary_replica_tag:STRING, dry_run:BOOLEAN]} -> OBJECT Table, {shards:NUMBER, replicas:OBJECT[, primary_replica_tag:STRING, dry_run:BOOLEAN]} -> OBJECT Balances the table's shards but leaves everything else the same. Can also be applied to an entire database at once.
Table -> OBJECT
Ensures that previously issued soft-durability writes are complete and written to disk.
Table -> OBJECT
* Secondary indexes OPs Creates a new secondary index with a particular name and definition.
Table, STRING, Function(1), {multi:BOOL} -> OBJECT
Drops a secondary index with a particular name from the specified table.
Table, STRING -> OBJECT
Lists all secondary indexes on a particular table.
Table -> ARRAY
Gets information about whether or not a set of indexes are ready to be accessed. Returns a list of objects that look like this: {index:STRING, ready:BOOL[, blocks_processed:NUMBER, blocks_total:NUMBER]}
Table, STRING... -> ARRAY
Blocks until a set of indexes are ready to be accessed. Returns the same values INDEX_STATUS.
Table, STRING... -> ARRAY
Renames the given index to a new name
Table, STRING, STRING, {overwrite:BOOL} -> OBJECT
* Control Operators Calls a function on data
Function(*), DATUM... -> DATUM
Executes its first argument, and returns its second argument if it got [true] or its third argument if it got [false] (like an `if` statement).
BOOL, Top, Top -> Top
Returns true if any of its arguments returns true (short-circuits).
BOOL... -> BOOL
Returns true if all of its arguments return true (short-circuits).
BOOL... -> BOOL
Calls its Function with each entry in the sequence and executes the array of terms that Function returns.
Sequence, Function(1) -> OBJECT
An anonymous function. Takes an array of numbers representing variables (see [VAR] above), and a [Term] to execute with those in scope. Returns a function that may be passed an array of arguments, then executes the Term with those bound to the variable names. The user will never construct this directly. We use it internally for things like `map` which take a function. The "arity" of a [Function] is the number of arguments it takes. For example, here's what `_X_.map{|x| x+2}` turns into: Term { type = MAP; args = [_X_, Term { type = Function; args = [Term { type = DATUM; datum = Datum { type = R_ARRAY; r_array = [Datum { type = R_NUM; r_num = 1; }]; }; }, Term { type = ADD; args = [Term { type = VAR; args = [Term { type = DATUM; datum = Datum { type = R_NUM; r_num = 1}; }]; }, Term { type = DATUM; datum = Datum { type = R_NUM; r_num = 2; }; }]; }]; }];
ARRAY, Top -> ARRAY -> Top
Indicates to ORDER_BY that this attribute is to be sorted in ascending order.
!STRING -> Ordering
Indicates to ORDER_BY that this attribute is to be sorted in descending order.
!STRING -> Ordering
Gets info about anything. INFO is most commonly called on tables.
Top -> OBJECT
`a.match(b)` returns a match object if the string `a` matches the regular expression `b`.
STRING, STRING -> DATUM
Change the case of a string.
STRING -> STRING
STRING -> STRING
Select a number of elements from sequence with uniform distribution.
Sequence, NUMBER -> Sequence
Evaluates its first argument. If that argument returns NULL or throws an error related to the absence of an expected value (for instance, accessing a non-existent field or adding NULL to an integer), DEFAULT will either return its second argument or execute it if it's a function. If the second argument is a function, it will be passed either the text of the error or NULL as its argument.
Top, Top -> Top
Parses its first argument as a json string and returns it as a datum.
STRING -> DATUM
Returns the datum as a JSON string. N.B.: we would really prefer this be named TO_JSON and that exists as an alias in Python and JavaScript drivers; however it conflicts with the standard `to_json` method defined by Ruby's standard json library.
DATUM -> STRING
Parses its first arguments as an ISO 8601 time and returns it as a datum.
STRING -> PSEUDOTYPE(TIME)
Prints a time as an ISO 8601 time.
PSEUDOTYPE(TIME) -> STRING
Returns a time given seconds since epoch in UTC.
NUMBER -> PSEUDOTYPE(TIME)
Returns seconds since epoch in UTC given a time.
PSEUDOTYPE(TIME) -> NUMBER
The time the query was received by the server.
-> PSEUDOTYPE(TIME)
Puts a time into an ISO 8601 timezone.
PSEUDOTYPE(TIME), STRING -> PSEUDOTYPE(TIME)
a.during(b, c) returns whether a is in the range [b, c)
PSEUDOTYPE(TIME), PSEUDOTYPE(TIME), PSEUDOTYPE(TIME) -> BOOL
Retrieves the date portion of a time.
PSEUDOTYPE(TIME) -> PSEUDOTYPE(TIME)
x.time_of_day == x.date - x
PSEUDOTYPE(TIME) -> NUMBER
Returns the timezone of a time.
PSEUDOTYPE(TIME) -> STRING
These access the various components of a time.
PSEUDOTYPE(TIME) -> NUMBER
PSEUDOTYPE(TIME) -> NUMBER
PSEUDOTYPE(TIME) -> NUMBER
PSEUDOTYPE(TIME) -> NUMBER
PSEUDOTYPE(TIME) -> NUMBER
PSEUDOTYPE(TIME) -> NUMBER
PSEUDOTYPE(TIME) -> NUMBER
PSEUDOTYPE(TIME) -> NUMBER
Construct a time from a date and optional timezone or a date+time and optional timezone.
NUMBER, NUMBER, NUMBER, STRING -> PSEUDOTYPE(TIME) |
Constants for ISO 8601 days of the week.
-> 1
-> 2
-> 3
-> 4
-> 5
-> 6
-> 7
Constants for ISO 8601 months.
-> 1
-> 2
-> 3
-> 4
-> 5
-> 6
-> 7
-> 8
-> 9
-> 10
-> 11
-> 12
Indicates to MERGE to replace, or remove in case of an empty literal, the other object rather than merge it.
-> Merging
SEQUENCE, STRING -> GROUPED_SEQUENCE | SEQUENCE, FUNCTION -> GROUPED_SEQUENCE
`str.split()` splits on whitespace `str.split(" ")` splits on spaces only `str.split(" ", 5)` splits on spaces with at most 5 results `str.split(nil, 5)` splits on whitespace with at most 5 results
STRING -> ARRAY | STRING, STRING -> ARRAY | STRING, STRING, NUMBER -> ARRAY | STRING, NULL, NUMBER -> ARRAY
GROUPED_DATA -> ARRAY
Takes a range of numbers and returns a random number within the range
NUMBER, NUMBER {float:BOOL} -> DATUM
TABLE -> STREAM
ARRAY -> SPECIAL (used to splice arguments)
BINARY is client-only at the moment, it is not supported on the server
STRING -> PSEUDOTYPE(BINARY)
OBJECT -> PSEUDOTYPE(GEOMETRY)
PSEUDOTYPE(GEOMETRY) -> OBJECT
NUMBER, NUMBER -> PSEUDOTYPE(GEOMETRY)
(ARRAY | PSEUDOTYPE(GEOMETRY))... -> PSEUDOTYPE(GEOMETRY)
(ARRAY | PSEUDOTYPE(GEOMETRY))... -> PSEUDOTYPE(GEOMETRY)
PSEUDOTYPE(GEOMETRY), PSEUDOTYPE(GEOMETRY) {geo_system:STRING, unit:STRING} -> NUMBER
PSEUDOTYPE(GEOMETRY), PSEUDOTYPE(GEOMETRY) -> BOOL
PSEUDOTYPE(GEOMETRY), PSEUDOTYPE(GEOMETRY) -> BOOL
PSEUDOTYPE(GEOMETRY), NUMBER {num_vertices:NUMBER, geo_system:STRING, unit:STRING, fill:BOOL} -> PSEUDOTYPE(GEOMETRY)
TABLE, PSEUDOTYPE(GEOMETRY) {index:!STRING} -> StreamSelection
PSEUDOTYPE(GEOMETRY) -> PSEUDOTYPE(GEOMETRY)
TABLE, PSEUDOTYPE(GEOMETRY) {index:!STRING, max_results:NUM, max_dist:NUM, geo_system:STRING, unit:STRING} -> ARRAY
PSEUDOTYPE(GEOMETRY), PSEUDOTYPE(GEOMETRY) -> PSEUDOTYPE(GEOMETRY)
Constants for specifying key ranges
We need to wrap it like this for some
(message has no fields)
The protocol to use after the handshake, specified in V0_3
non-conforming protobuf libraries This enum contains the magic numbers for your version. See **THE HIGH-LEVEL VIEW** for what to do with it.
Authorization key during handshake
Authorization key and protocol during handshake
Queries execute in parallel