//////////////////////////////////////////////////////////////////////////////// // THE HIGH-LEVEL VIEW // //////////////////////////////////////////////////////////////////////////////// // Process: When you first open a connection, send the magic number // for the version of the protobuf you're targeting (in the [Version] // enum). This should **NOT** be sent as a protobuf; just send the // little-endian 32-bit integer over the wire raw. This number should // only be sent once per connection. // The magic number shall be followed by an authorization key. The // first 4 bytes are the length of the key to be sent as a little-endian // 32-bit integer, followed by the key string. Even if there is no key, // an empty string should be sent (length 0 and no data). // Following the authorization key, the client shall send a magic number // for the communication protocol they want to use (in the [Protocol] // enum). This shall be a little-endian 32-bit integer. // The server will then respond with a NULL-terminated string response. // "SUCCESS" indicates that the connection has been accepted. Any other // response indicates an error, and the response string should describe // the error. // Next, for each query you want to send, construct a [Query] protobuf // and serialize it to a binary blob. Send the blob's size to the // server encoded as a little-endian 32-bit integer, followed by the // blob itself. You will recieve a [Response] protobuf back preceded // by its own size, once again encoded as a little-endian 32-bit // integer. You can see an example exchange below in **EXAMPLE**. // A query consists of a [Term] to evaluate and a unique-per-connection // [token]. // Tokens are used for two things: // * Keeping track of which responses correspond to which queries. // * Batched queries. Some queries return lots of results, so we send back // batches of <1000, and you need to send a [CONTINUE] query with the same // token to get more results from the original query. //////////////////////////////////////////////////////////////////////////////// syntax = "proto2"; message VersionDummy { // We need to wrap it like this for some // non-conforming protobuf libraries // This enum contains the magic numbers for your version. See **THE HIGH-LEVEL // VIEW** for what to do with it. enum Version { V0_1 = 0x3f61ba36; V0_2 = 0x723081e1; // Authorization key during handshake V0_3 = 0x5f75e83e; // Authorization key and protocol during handshake V0_4 = 0x400c2d20; // Queries execute in parallel V1_0 = 0x34c2bdc3; // Users and permissions } // The protocol to use after the handshake, specified in V0_3 enum Protocol { PROTOBUF = 0x271ffc41; JSON = 0x7e6970c7; } } // 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 [SERVER_INFO] query. The server answers with a [SERVER_INFO] [Response]. message Query { enum QueryType { START = 1; // Start a new query. CONTINUE = 2; // Continue a query that returned [SUCCESS_PARTIAL] // (see [Response]). STOP = 3; // Stop a query partway through executing. NOREPLY_WAIT = 4; // Wait for noreply operations to finish. SERVER_INFO = 5; // Get server information. } optional QueryType type = 1; // A [Term] is how we represent the operations we want a query to perform. optional Term query = 2; // only present when [type] = [START] optional int64 token = 3; // 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). optional bool OBSOLETE_noreply = 4 [default = 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. optional bool accepts_r_json = 5 [default = false]; message AssocPair { optional string key = 1; optional Term val = 2; } repeated AssocPair global_optargs = 6; } // A backtrace frame (see `backtrace` in Response below) message Frame { enum FrameType { POS = 1; // Error occurred in a positional argument. OPT = 2; // Error occurred in an optional argument. } optional FrameType type = 1; optional int64 pos = 2; // The index of the positional argument. optional string opt = 3; // The name of the optional argument. } message Backtrace { repeated Frame frames = 1; } // You get back a response with the same [token] as your query. message Response { enum ResponseType { // These response types indicate success. SUCCESS_ATOM = 1; // Query returned a single RQL datatype. SUCCESS_SEQUENCE = 2; // Query returned a sequence of RQL datatypes. SUCCESS_PARTIAL = 3; // 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]. WAIT_COMPLETE = 4; // A [NOREPLY_WAIT] query completed. SERVER_INFO = 5; // The data for a [SERVER_INFO] request. This is // the same as `SUCCESS_ATOM` except that there will // never be profiling data. // These response types indicate failure. CLIENT_ERROR = 16; // Means the client is buggy. An example is if the // client sends a malformed protobuf, or tries to // send [CONTINUE] for an unknown token. COMPILE_ERROR = 17; // Means the query failed during parsing or type // checking. For example, if you pass too many // arguments to a function. RUNTIME_ERROR = 18; // Means the query failed at runtime. An example is // if you add together two values from a table, but // they turn out at runtime to be booleans rather // than numbers. } optional ResponseType type = 1; // If `ResponseType` is `RUNTIME_ERROR`, this may be filled in with more // information about the error. enum ErrorType { INTERNAL = 1000000; RESOURCE_LIMIT = 2000000; QUERY_LOGIC = 3000000; NON_EXISTENCE = 3100000; OP_FAILED = 4100000; OP_INDETERMINATE = 4200000; USER = 5000000; PERMISSION_ERROR = 6000000; } optional ErrorType error_type = 7; // 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. enum ResponseNote { // The stream is a changefeed stream (e.g. `r.table('test').changes()`). SEQUENCE_FEED = 1; // The stream is a point changefeed stream // (e.g. `r.table('test').get(0).changes()`). ATOM_FEED = 2; // The stream is an order_by_limit changefeed stream // (e.g. `r.table('test').order_by(index: 'id').limit(5).changes()`). ORDER_BY_LIMIT_FEED = 3; // 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())`). UNIONED_FEED = 4; // 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'}`). INCLUDES_STATES = 5; } repeated ResponseNote notes = 6; optional int64 token = 2; // Indicates what [Query] this response corresponds to. // [response] contains 1 RQL datum if [type] is [SUCCESS_ATOM] or // [SERVER_INFO]. [response] contains many RQL data if [type] is // [SUCCESS_SEQUENCE] or [SUCCESS_PARTIAL]. [response] contains 1 // error message (of type [R_STR]) in all other cases. repeated Datum response = 3; // 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 occurred. 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.) optional Backtrace backtrace = 4; // 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. optional Datum profile = 5; } // 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). message Datum { enum DatumType { R_NULL = 1; R_BOOL = 2; R_NUM = 3; // a double R_STR = 4; R_ARRAY = 5; R_OBJECT = 6; // 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]. R_JSON = 7; // uses r_str } optional DatumType type = 1; optional bool r_bool = 2; optional double r_num = 3; optional string r_str = 4; repeated Datum r_array = 5; message AssocPair { optional string key = 1; optional Datum val = 2; } repeated AssocPair r_object = 6; } // 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 `{noreply: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 message Term { enum TermType { // A RQL datum, stored in `datum` below. DATUM = 1; MAKE_ARRAY = 2; // DATUM... -> ARRAY // Evaluate the terms in [optargs] and make an object MAKE_OBJ = 3; // {...} -> OBJECT // * Compound types // 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.) VAR = 10; // !NUMBER -> DATUM // Takes some javascript code and executes it. JAVASCRIPT = 11; // STRING {timeout: !NUMBER} -> DATUM | // STRING {timeout: !NUMBER} -> Function(*) UUID = 169; // () -> DATUM // Takes an HTTP URL and gets it. If the get succeeds and // returns valid JSON, it is converted into a DATUM HTTP = 153; // STRING {data: OBJECT | STRING, // timeout: !NUMBER, // method: STRING, // params: OBJECT, // header: OBJECT | ARRAY, // attempts: NUMBER, // redirects: NUMBER, // verify: BOOL, // page: FUNC | STRING, // page_limit: NUMBER, // auth: OBJECT, // result_format: STRING, // } -> STRING | STREAM // 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). ERROR = 12; // STRING -> Error | -> Error // Takes nothing and returns a reference to the implicit variable. IMPLICIT_VAR = 13; // -> DATUM // * Data Operators // Returns a reference to a database. DB = 14; // STRING -> Database // Returns a reference to a table. TABLE = 15; // Database, STRING, {read_mode:STRING, identifier_format:STRING} -> Table // STRING, {read_mode:STRING, identifier_format:STRING} -> Table // Gets a single element from a table by its primary or a secondary key. GET = 16; // Table, STRING -> SingleSelection | Table, NUMBER -> SingleSelection | // Table, STRING -> NULL | Table, NUMBER -> NULL | GET_ALL = 78; // Table, DATUM..., {index:!STRING} => ARRAY // Simple DATUM Ops EQ = 17; // DATUM... -> BOOL NE = 18; // DATUM... -> BOOL LT = 19; // DATUM... -> BOOL LE = 20; // DATUM... -> BOOL GT = 21; // DATUM... -> BOOL GE = 22; // DATUM... -> BOOL NOT = 23; // BOOL -> BOOL // ADD can either add two numbers or concatenate two arrays. ADD = 24; // NUMBER... -> NUMBER | STRING... -> STRING SUB = 25; // NUMBER... -> NUMBER MUL = 26; // NUMBER... -> NUMBER DIV = 27; // NUMBER... -> NUMBER MOD = 28; // NUMBER, NUMBER -> NUMBER FLOOR = 183; // NUMBER -> NUMBER CEIL = 184; // NUMBER -> NUMBER ROUND = 185; // NUMBER -> NUMBER // DATUM Array Ops // Append a single element to the end of an array (like `snoc`). APPEND = 29; // ARRAY, DATUM -> ARRAY // Prepend a single element to the end of an array (like `cons`). PREPEND = 80; // ARRAY, DATUM -> ARRAY //Remove the elements of one array from another array. DIFFERENCE = 95; // 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. SET_INSERT = 88; // ARRAY, DATUM -> ARRAY SET_INTERSECTION = 89; // ARRAY, ARRAY -> ARRAY SET_UNION = 90; // ARRAY, ARRAY -> ARRAY SET_DIFFERENCE = 91; // ARRAY, ARRAY -> ARRAY SLICE = 30; // Sequence, NUMBER, NUMBER -> Sequence SKIP = 70; // Sequence, NUMBER -> Sequence LIMIT = 71; // Sequence, NUMBER -> Sequence OFFSETS_OF = 87; // Sequence, DATUM -> Sequence | Sequence, Function(1) -> Sequence CONTAINS = 93; // Sequence, (DATUM | Function(1))... -> BOOL // Stream/Object Ops // Get a particular field from an object, or map that over a // sequence. GET_FIELD = 31; // OBJECT, STRING -> DATUM // | Sequence, STRING -> Sequence // Return an array containing the keys of the object. KEYS = 94; // OBJECT -> ARRAY // Return an array containing the values of the object. VALUES = 186; // OBJECT -> ARRAY // Creates an object OBJECT = 143; // 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. HAS_FIELDS = 32; // OBJECT, Pathspec... -> BOOL // x.with_fields(...) <=> x.has_fields(...).pluck(...) WITH_FIELDS = 96; // 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.) PLUCK = 33; // 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.) WITHOUT = 34; // Sequence, Pathspec... -> Sequence | OBJECT, Pathspec... -> OBJECT // Merge objects (right-preferential) MERGE = 35; // 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`. BETWEEN_DEPRECATED = 36; // Deprecated version of between, which allows `null` to specify unboundedness // With the newer version, clients should use `r.minval` and `r.maxval` for unboundedness BETWEEN = 182; // StreamSelection, DATUM, DATUM, {index:!STRING, right_bound:STRING, left_bound:STRING} -> StreamSelection REDUCE = 37; // Sequence, Function(2) -> DATUM MAP = 38; // Sequence, Function(1) -> Sequence // The arity of the function should be // Sequence..., Function(sizeof...(Sequence)) -> Sequence FOLD = 187; // Sequence, Datum, Function(2), {Function(3), Function(1) // 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. FILTER = 39; // Sequence, Function(1), {default:DATUM} -> Sequence | // Sequence, OBJECT, {default:DATUM} -> Sequence // Map a function over a sequence and then concatenate the results together. CONCAT_MAP = 40; // Sequence, Function(1) -> Sequence // Order a sequence based on one or more attributes. ORDER_BY = 41; // Sequence, (!STRING | Ordering)..., {index: (!STRING | Ordering)} -> Sequence // Get all distinct elements of a sequence (like `uniq`). DISTINCT = 42; // Sequence -> Sequence // Count the number of elements in a sequence, or only the elements that match // a given filter. COUNT = 43; // Sequence -> NUMBER | Sequence, DATUM -> NUMBER | Sequence, Function(1) -> NUMBER IS_EMPTY = 86; // Sequence -> BOOL // Take the union of multiple sequences (preserves duplicate elements! (use distinct)). UNION = 44; // Sequence... -> Sequence // Get the Nth element of a sequence. NTH = 45; // Sequence, NUMBER -> DATUM // do NTH or GET_FIELD depending on target object BRACKET = 170; // Sequence | OBJECT, NUMBER | STRING -> DATUM // OBSOLETE_GROUPED_MAPREDUCE = 46; // OBSOLETE_GROUPBY = 47; INNER_JOIN = 48; // Sequence, Sequence, Function(2) -> Sequence OUTER_JOIN = 49; // Sequence, Sequence, Function(2) -> Sequence // An inner-join that does an equality comparison on two attributes. EQ_JOIN = 50; // Sequence, !STRING, Sequence, {index:!STRING} -> Sequence ZIP = 72; // Sequence -> Sequence RANGE = 173; // -> Sequence [0, +inf) // NUMBER -> Sequence [0, a) // NUMBER, NUMBER -> Sequence [a, b) // Array Ops // Insert an element in to an array at a given index. INSERT_AT = 82; // ARRAY, NUMBER, DATUM -> ARRAY // Remove an element at a given index from an array. DELETE_AT = 83; // ARRAY, NUMBER -> ARRAY | // ARRAY, NUMBER, NUMBER -> ARRAY // Change the element at a given index of an array. CHANGE_AT = 84; // ARRAY, NUMBER, DATUM -> ARRAY // Splice one array in to another array. SPLICE_AT = 85; // 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". COERCE_TO = 51; // Top, STRING -> Top // Returns the named type of a datum (e.g. TYPE_OF(true) = "BOOL") TYPE_OF = 52; // 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. UPDATE = 53; // 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. DELETE = 54; // 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. REPLACE = 55; // 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. INSERT = 56; // 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. DB_CREATE = 57; // STRING -> OBJECT // Drops a database with a particular name. DB_DROP = 58; // STRING -> OBJECT // Lists all the databases by name. (Takes no arguments) DB_LIST = 59; // -> ARRAY // Creates a table with a particular name in a particular // database. (You may omit the first argument to use the // default database.) TABLE_CREATE = 60; // 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.) TABLE_DROP = 61; // Database, STRING -> OBJECT // STRING -> OBJECT // Lists all the tables in a particular database. (You may // omit the first argument to use the default database.) TABLE_LIST = 62; // Database -> ARRAY // -> ARRAY // Returns the row in the `rethinkdb.table_config` or `rethinkdb.db_config` table // that corresponds to the given database or table. CONFIG = 174; // Database -> SingleSelection // Table -> SingleSelection // Returns the row in the `rethinkdb.table_status` table that corresponds to the // given table. STATUS = 175; // 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. WAIT = 177; // 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. If `emergency_repair` is // specified, it will enter a completely different mode of repairing a table // which has lost half or more of its replicas. RECONFIGURE = 176; // Database|Table, {shards:NUMBER, replicas:NUMBER [, // dry_run:BOOLEAN] // } -> OBJECT // Database|Table, {shards:NUMBER, replicas:OBJECT [, // primary_replica_tag:STRING, // nonvoting_replica_tags:ARRAY, // dry_run:BOOLEAN] // } -> OBJECT // Table, {emergency_repair: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. REBALANCE = 179; // Table -> OBJECT // Database -> OBJECT // Ensures that previously issued soft-durability writes are complete and // written to disk. SYNC = 138; // Table -> OBJECT // Set global, database, or table-specific permissions GRANT = 188; // -> OBJECT // Database -> OBJECT // Table -> OBJECT // * Secondary indexes OPs // Creates a new secondary index with a particular name and definition. INDEX_CREATE = 75; // Table, STRING, Function(1), {multi:BOOL} -> OBJECT // Drops a secondary index with a particular name from the specified table. INDEX_DROP = 76; // Table, STRING -> OBJECT // Lists all secondary indexes on a particular table. INDEX_LIST = 77; // 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[, progress:NUMBER]} INDEX_STATUS = 139; // Table, STRING... -> ARRAY // Blocks until a set of indexes are ready to be accessed. Returns the // same values INDEX_STATUS. INDEX_WAIT = 140; // Table, STRING... -> ARRAY // Renames the given index to a new name INDEX_RENAME = 156; // Table, STRING, STRING, {overwrite:BOOL} -> OBJECT // * Write hook Function OPs // Creates a new write hook function with a particular definition SET_WRITE_HOOK = 189; // Table, Function(2) // Gets an existing write hook function on a table GET_WRITE_HOOK = 190; // Table // * Control Operators // Calls a function on data FUNCALL = 64; // 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). BRANCH = 65; // BOOL, Top, Top -> Top // Returns true if any of its arguments returns true (short-circuits). OR = 66; // BOOL... -> BOOL // Returns true if all of its arguments return true (short-circuits). AND = 67; // BOOL... -> BOOL // Calls its Function with each entry in the sequence // and executes the array of terms that Function returns. FOR_EACH = 68; // Sequence, Function(1) -> OBJECT //////////////////////////////////////////////////////////////////////////////// ////////// Special Terms //////////////////////////////////////////////////////////////////////////////// // 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; }; // }]; // }]; // }]; FUNC = 69; // ARRAY, Top -> ARRAY -> Top // Indicates to ORDER_BY that this attribute is to be sorted in ascending order. ASC = 73; // !STRING -> Ordering // Indicates to ORDER_BY that this attribute is to be sorted in descending order. DESC = 74; // !STRING -> Ordering // Gets info about anything. INFO is most commonly called on tables. INFO = 79; // Top -> OBJECT // `a.match(b)` returns a match object if the string `a` // matches the regular expression `b`. MATCH = 97; // STRING, STRING -> DATUM // Change the case of a string. UPCASE = 141; // STRING -> STRING DOWNCASE = 142; // STRING -> STRING // Select a number of elements from sequence with uniform distribution. SAMPLE = 81; // 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. DEFAULT = 92; // Top, Top -> Top // Parses its first argument as a json string and returns it as a // datum. JSON = 98; // STRING -> DATUM // Parses its first arguments as an ISO 8601 time and returns it as a // datum. ISO8601 = 99; // STRING -> PSEUDOTYPE(TIME) // Prints a time as an ISO 8601 time. TO_ISO8601 = 100; // PSEUDOTYPE(TIME) -> STRING // Returns a time given seconds since epoch in UTC. EPOCH_TIME = 101; // NUMBER -> PSEUDOTYPE(TIME) // Returns seconds since epoch in UTC given a time. TO_EPOCH_TIME = 102; // PSEUDOTYPE(TIME) -> NUMBER // The time the query was received by the server. NOW = 103; // -> PSEUDOTYPE(TIME) // Puts a time into an ISO 8601 timezone. IN_TIMEZONE = 104; // PSEUDOTYPE(TIME), STRING -> PSEUDOTYPE(TIME) // a.during(b, c) returns whether a is in the range [b, c) DURING = 105; // PSEUDOTYPE(TIME), PSEUDOTYPE(TIME), PSEUDOTYPE(TIME) -> BOOL // Retrieves the date portion of a time. DATE = 106; // PSEUDOTYPE(TIME) -> PSEUDOTYPE(TIME) // x.time_of_day == x.date - x TIME_OF_DAY = 126; // PSEUDOTYPE(TIME) -> NUMBER // Returns the timezone of a time. TIMEZONE = 127; // PSEUDOTYPE(TIME) -> STRING // These access the various components of a time. YEAR = 128; // PSEUDOTYPE(TIME) -> NUMBER MONTH = 129; // PSEUDOTYPE(TIME) -> NUMBER DAY = 130; // PSEUDOTYPE(TIME) -> NUMBER DAY_OF_WEEK = 131; // PSEUDOTYPE(TIME) -> NUMBER DAY_OF_YEAR = 132; // PSEUDOTYPE(TIME) -> NUMBER HOURS = 133; // PSEUDOTYPE(TIME) -> NUMBER MINUTES = 134; // PSEUDOTYPE(TIME) -> NUMBER SECONDS = 135; // PSEUDOTYPE(TIME) -> NUMBER // Construct a time from a date and optional timezone or a // date+time and optional timezone. TIME = 136; // NUMBER, NUMBER, NUMBER, STRING -> PSEUDOTYPE(TIME) | // NUMBER, NUMBER, NUMBER, NUMBER, NUMBER, NUMBER, STRING -> PSEUDOTYPE(TIME) | // Constants for ISO 8601 days of the week. MONDAY = 107; // -> 1 TUESDAY = 108; // -> 2 WEDNESDAY = 109; // -> 3 THURSDAY = 110; // -> 4 FRIDAY = 111; // -> 5 SATURDAY = 112; // -> 6 SUNDAY = 113; // -> 7 // Constants for ISO 8601 months. JANUARY = 114; // -> 1 FEBRUARY = 115; // -> 2 MARCH = 116; // -> 3 APRIL = 117; // -> 4 MAY = 118; // -> 5 JUNE = 119; // -> 6 JULY = 120; // -> 7 AUGUST = 121; // -> 8 SEPTEMBER = 122; // -> 9 OCTOBER = 123; // -> 10 NOVEMBER = 124; // -> 11 DECEMBER = 125; // -> 12 // Indicates to MERGE to replace, or remove in case of an empty literal, the // other object rather than merge it. LITERAL = 137; // -> Merging // JSON -> Merging // SEQUENCE, STRING -> GROUPED_SEQUENCE | SEQUENCE, FUNCTION -> GROUPED_SEQUENCE GROUP = 144; SUM = 145; AVG = 146; MIN = 147; MAX = 148; // `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 SPLIT = 149; // STRING -> ARRAY | STRING, STRING -> ARRAY | STRING, STRING, NUMBER -> ARRAY | STRING, NULL, NUMBER -> ARRAY UNGROUP = 150; // GROUPED_DATA -> ARRAY // Takes a range of numbers and returns a random number within the range RANDOM = 151; // NUMBER, NUMBER {float:BOOL} -> DATUM CHANGES = 152; // TABLE -> STREAM ARGS = 154; // ARRAY -> SPECIAL (used to splice arguments) // BINARY is client-only at the moment, it is not supported on the server BINARY = 155; // STRING -> PSEUDOTYPE(BINARY) GEOJSON = 157; // OBJECT -> PSEUDOTYPE(GEOMETRY) TO_GEOJSON = 158; // PSEUDOTYPE(GEOMETRY) -> OBJECT POINT = 159; // NUMBER, NUMBER -> PSEUDOTYPE(GEOMETRY) LINE = 160; // (ARRAY | PSEUDOTYPE(GEOMETRY))... -> PSEUDOTYPE(GEOMETRY) POLYGON = 161; // (ARRAY | PSEUDOTYPE(GEOMETRY))... -> PSEUDOTYPE(GEOMETRY) DISTANCE = 162; // PSEUDOTYPE(GEOMETRY), PSEUDOTYPE(GEOMETRY) {geo_system:STRING, unit:STRING} -> NUMBER INTERSECTS = 163; // PSEUDOTYPE(GEOMETRY), PSEUDOTYPE(GEOMETRY) -> BOOL INCLUDES = 164; // PSEUDOTYPE(GEOMETRY), PSEUDOTYPE(GEOMETRY) -> BOOL CIRCLE = 165; // PSEUDOTYPE(GEOMETRY), NUMBER {num_vertices:NUMBER, geo_system:STRING, unit:STRING, fill:BOOL} -> PSEUDOTYPE(GEOMETRY) GET_INTERSECTING = 166; // TABLE, PSEUDOTYPE(GEOMETRY) {index:!STRING} -> StreamSelection FILL = 167; // PSEUDOTYPE(GEOMETRY) -> PSEUDOTYPE(GEOMETRY) GET_NEAREST = 168; // TABLE, PSEUDOTYPE(GEOMETRY) {index:!STRING, max_results:NUM, max_dist:NUM, geo_system:STRING, unit:STRING} -> ARRAY POLYGON_SUB = 171; // PSEUDOTYPE(GEOMETRY), PSEUDOTYPE(GEOMETRY) -> PSEUDOTYPE(GEOMETRY) // 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. TO_JSON_STRING = 172; // DATUM -> STRING // Constants for specifying key ranges MINVAL = 180; MAXVAL = 181; // Bitwise operations BIT_AND = 191; BIT_OR = 192; BIT_XOR = 193; BIT_NOT = 194; BIT_SAL = 195; BIT_SAR = 196; } optional TermType type = 1; // This is only used when type is DATUM. optional Datum datum = 2; repeated Term args = 3; // Holds the positional arguments of the query. message AssocPair { optional string key = 1; optional Term val = 2; } repeated AssocPair optargs = 4; // Holds the optional arguments of the query. // (Note that the order of the optional arguments doesn't matter; think of a // Hash.) } //////////////////////////////////////////////////////////////////////////////// // EXAMPLE // //////////////////////////////////////////////////////////////////////////////// // ```ruby // r.table('tbl', {:read_mode => 'outdated'}).insert([{:id => 0}, {:id => 1}]) // ``` // Would turn into: // Term { // type = INSERT; // args = [Term { // type = TABLE; // args = [Term { // type = DATUM; // datum = Datum { type = R_STR; r_str = "tbl"; }; // }]; // optargs = [["read_mode", // Term { // type = DATUM; // datum = Datum { type = R_STR; r_bool = "outdated"; }; // }]]; // }, // Term { // type = MAKE_ARRAY; // args = [Term { // type = DATUM; // datum = Datum { type = R_OBJECT; r_object = [["id", 0]]; }; // }, // Term { // type = DATUM; // datum = Datum { type = R_OBJECT; r_object = [["id", 1]]; }; // }]; // }] // } // And the server would reply: // Response { // type = SUCCESS_ATOM; // token = 1; // response = [Datum { type = R_OBJECT; r_object = [["inserted", 2]]; }]; // } // Or, if there were an error: // Response { // type = RUNTIME_ERROR; // token = 1; // response = [Datum { type = R_STR; r_str = "The table `tbl` doesn't exist!"; }]; // backtrace = [Frame { type = POS; pos = 0; }, Frame { type = POS; pos = 0; }]; // }