Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-rethinkdb Reference Manual, version 0.6.7, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 04:07:05 2022 GMT+0.
Next: Systems, Previous: The cl-rethinkdb Reference Manual, Up: The cl-rethinkdb Reference Manual [Contents][Index]
This is an async RethinkDB driver for everyone's favorite programming language. It does its best to follow the query language specification. If it's missing any functions or has implemented any of them incorrectly, please open an issue.
This driver is up to date with RethinkDB's v2.0.x protocol.
As with most of my drivers, cl-rethinkdb requires cl-async, and makes heavy use of cl-async's promises.
This driver is built so that later on, more than one TCP backend can be used. Right now, the only one implemented is cl-async, but usocket/IOLib could just as easily be used if someone puts in the time.
The driver makes extensive use of promises, as mentioned, so be sure to know your way around the promise syntax macros when using it.
Everything needed to use the driver is exported out of the cl-rethinkdb
package, which has the nickname r.
cl-rethinkdb makes use of a query DSL that maps keyword function calls to normal function calls. It does this so that predefined common lisp functions can be used instead of giving them rediculous names to avoid naming clashes.
The DSL is activated by using either the r macro (used to build query forms) or the fn macro (used to build anonymous functions).
Note that this section only covers the DSL itself. Check out the full list of commands to start building the query of your dreams.
This macro translates keyword functions into ReQL function calls:
;; grab first 10 records from the `users` table
(r (:limit (:table "users") 10))
This translates to
(cl-rethinkdb-reql::limit (cl-rethinkdb-reql::table "users") 10)
This macro creates an anonymous function for use in a RethinkDB query.
It works very much like the r macro, and in fact wraps its inner
forms in r so that you can use the query DSL from within a function.
;; return an anonymous function that adds `3` to the given argument
(fn (x) (:+ x 3))
Functions can be mixed in with r queries:
;; find all users older than 24
(r (:filter (:table "users")
(fn (user)
(:< 24 (:attr user "age")))))
Note how inside the fn body, we're still using functions prefixed with :.
Once you've constructed a query via r, you need to send it to the server. When the server responds successfully, you will get either an atom (a single value: integer, boolean, hash, array, etc). or a cursor which provides an interface to iterate over a set of atoms.
(defun connect (host port &key db use-outdated noreply profile read-timeout auth))
=> promise (tcp-socket)
Connects a socket to the given host/port and returns a promise that's finished with the socket.
Usage:
(alet ((sock (connect "127.0.0.1" 28015 :db "test")))
;; ... do stuff ...
(disconnect sock))
(defun run (sock query-form))
=> promise (atom/cursor profile-data)
Run a query against the given socket (connected using connect). Returns a promise finished with either the atom the query returns or a cursor to the query results.
If profile is t when calling connect, the second promise value
will be the profile data returned with the query.
run can signal the following errors on the promise it returns:
Example
(alet* ((sock (connect "127.0.0.1" 28015))
(query (r (:get (:table "users") 12))) ; get user id 12
(value (run sock query)))
(format t "My user is: ~s~%" value)
(disconnect sock))
(defun wait-complete (sock))
=> promise (t)
Waits for all queries sent on this socket with noreply => t to finish. This
lets you queue up a number of write operations on a socket. You can then call
wait-complete on the socket and it will return the response when all the
queued operations finish.
The cursor class keeps track of queries where a sequence of results is returned (as opposed to an atom). It is generally opaque, having no public accessors.
Cursor functions/methods:
(defun cursorp (cursor))
=> t/nil
Convenience function to tell if the given object is a cursor.
(defun next (sock cursor))
=> promise (atom)
Gets the next result from a cursor. Returns a promise that's finished with the next result. The result could be stored locally already, but it also may need to be retrieved from the server.
next can signal two errors on the promise it returns:
(alet* ((sock (connect "127.0.0.1" 28015))
(query (r (:table "users"))) ; get all users
(cursor (run sock query)))
;; grab the first result from the cursor.
(alet ((user (next sock cursor)))
(format t "first user is: ~s~%" user)
;; let's grab another user
(alet ((user (next sock cursor)))
(format t "second user is: ~s~%" user)
;; let the server/driver know we're done with this result set
(stop/disconnect sock cursor))))
(defun has-next (cursor))
=> t/nil
Determines if a cursor has more results available.
(defun to-sequence (sock cursor))
=> promise (sequence)
Given a socket and a cursor, to-sequence grabs ALL the results from the cursor,
going out to the server to get more if it has to, and returns them as a sequence
through the returned promise. The sequence type (vector/list) depends on the
value of *sequence-type*.
(defun to-array (sock cursor))
=> promise (vector)
Given a socket and a cursor, to-array grabs ALL the results from the cursor,
going out to the server to get more if it has to, and returns them as an array
through the returned promise.
(alet* ((sock (connect "127.0.0.1" 28015))
(query (r (:table "users"))) ; get all users
(cursor (run sock query))
(all-records (to-array sock cursor)))
(format t "All users: ~s~%" all-records)
;; cleanup
(stop/disconnect sock cursor))
Don't call to-array on a cursor returned from a changefeed. It will just sit
there endlessly saving results to a list it will never return.
(defun each (sock cursor function))
=> promise
Call the given function on each of the results of a cursor. The returned promise is finished when all results have been iterated over.
(alet* ((sock (connect "127.0.0.1" 28015))
(cursor (run sock (r (:table "users")))))
;; print each user
(wait (each sock cursor
(lambda (x) (format t "user: ~s~%" x)))
;; cleanup
(wait (stop sock cursor)
(disconnect sock))))
each is the function you want to use for listening to changes on a cursor that
is returned from a changefeed.
(defun stop (sock cursor))
=> promise
Stops a currently open query/cursor. This cleans up the cursor locally, and also lets RethinkDB know that the results for this cursor are no longer needed. Returns a promise that is finished with no values when the operation is complete.
(defun stop/disconnect (sock cursor))
=> nil
Calls stop on a cursor, and after the stop operation is done closes the passed socket. Useful as a final termination to an operation that uses a cursor.
Note that this function checks if the object passed is indeed a cursor, and if not, just disconnects the socket without throwing any errors.
(defun disconnect (sock))
=> nil
Disconnect a connection to a RethinkDB server.
Binary data is now part of the driver. Using it is simple...you pass in an
unsigned byte array (ie (simple-erray (unsigned-byte 8) (*))) and the driver
will handle encoding of the binary data for you. Binary data passed in must
be of the unsigned-byte type, or your data will just be encoded as an array (or
whatever type it actually is).
When an object is returned that has binary data, the driver converts it back to an unsigned byte array.
You can also force usage of the binary type by using the (:binary ...)
type in the DSL. It takes 1 argument: a base64 string of your data. Note,
however, that if you do use (:binary "ZG93biB3aXRoIHRoZSBvcHByZXNzaXZlIGNhcGl0YWxpc3QgcmVnaW1l"),
when you pull that document out, the data will be encoded as a raw unsigned-byte
array (not a base64 string).
These mainly have to do with how you want data returned.
When a sequence is returned from RethinkDB, it can be either returned as a list
(if *sequence-type* is :list or as a vector (if *sequence-type* is
:array). It's really a matter of preference on how you're going to access the
data. (But you may also want to read
on-sequence-type for a
warning about round tripping rethinkdb documents while using :list).
Default: :list
If an object (as in, key/value object) is returned from RethinkDB, it can be
encoded as a hash table (if *object-type* is :hash) or as an association
list (if *object-type* is :alist). Hash tables are almost always more
performant, but alists can be easier to debug. Your choice.
Default: :hash
cl-rethinkdb stores all its global state in one variable: *state*, which is
exported in the cl-rethinkdb package. The *state* variable is an instance of
the cl-rethinkdb:state CLOS class. This lets you declare a thread-local
variable when starting a thread so there are no collisions when accessing the
library from multiple threads:
(let ((cl-rethinkdb:*state* (make-instance 'cl-rethinkdb:state)))
(as:with-event-loop ()
;; run queries in this context
))
Using let in the above context declares *state* as a thread local variable,
as opposed to using setf, which will just modify the global, shared context.
Be sure that the let form happens at the start of the thread and encompasses
the event loop form.
All of the following are accessible via the r DSL macro by prefixing
the name with a :. So (table "users") becomes (:table "users").
These are almost 100% compatible with the ReQL specification, so if you familiarize yourself with the query language, you will automatically get a good handle on the following.
For a better understanding of the return types of the following commands, see the REQL type hierarchy in the protobuf specification.
db (db-name) => databasedb-drop (db-name) => objectdb-list () => objecttable-create (db table-name &key datacenter primary-key durability) => objecttable-drop (db table-name) => objecttable-list (db) => objectsync (table) => objectindex-create (table name &key function multi) => objectindex-drop (table name) => objectindex-list (table) => arrayindex-status (table &rest names) => arrayindex-wait (table &rest names) => arraychanges (select &key squash include-states) => cursorargs (arg-list) => specialbinary (base64-string) => binaryinsert (table sequence/object &key conflict durability return-changes) => objectupdate (select object/function &key non-atomic durability return-changes) => objectreplace (select object/function &key non-atomic durability return-changes) => objectdelete (select &key durability return-changes) => objectdb (db-name) => dbtable (db table-name &key read-mode identifier-format) => sequenceget (table item-id) => objectget-all (table key/keys &key index) => arraykey/keys can be either a string type or a list of string types)between (sequence left right &key index) => sequenceminval () => constantmaxval () => constantfilter (sequence object/function &key default) => sequenceinner-join (sequence1 sequence2 function) => sequenceouter-join (sequence1 sequence2 function) => sequenceeq-join (sequence1 field sequence2 &key index) => sequencezip (sequence) => sequencemap (sequence function) => sequencewith-fields (sequence &rest strings) => sequenceconcat-map (sequence function) => sequenceorder-by (sequence field &rest fields) => sequenceasc (field) => fielddesc (field) => fieldskip (sequence number) => sequencelimit (sequence number) => sequenceslice (sequence start end) => sequencenth (sequence number) => objectoffsets-of (sequence object/reql-function) => sequenceis-empty (sequence) => booleanunion (sequence &rest sequences) => sequencesample (sequence count) => sequencerandom (lower &optional upper &key float) => numbergroup (sequence fields-or-functions &key index) => grouped_sequenceungroup (grouped-sequence) => sequencereduce (sequence function) => objectcount (sequence &optional object/reql-function) => numbersum (sequence &optional field-or-function) => numberavg (sequence &optional field-or-function) => numbermin (sequence &optional field-or-function) => type-of-object-in-sequencemax (sequence &optional field-or-function) => type-of-object-in-sequencedistinct (sequence) => sequencecontains (sequence object) => booleancount-reduce () => functionsum-reduce (field) => functionavg-reduce (field) => functionattr (object field) => objectrow (&optional field) => objectpluck (sequence/object field &rest fields) => sequence/objectwithout (sequence/object field &rest fields) => sequence/objectmerge (object &rest objects) => objectappend (array object) => arrayprepend (array object) => arraydifference (array1 array2) => arrayset-insert (array object) => arrayset-intersection (array1 array2) => arrayset-union (array1 array2) => arrayset-difference (array1 array2) => arrayhas-fields (object string &rest strings) => boolinsert-at (array index object) => arraysplice-at (array1 index array2) => arraydelete-at (array index) => arraychange-at (array index object) => arraykeys (object) => arrayobject (key val &rest) => object\+ (number/string &rest numbers/strings) => number/string\- (number &rest numbers) => number\* (number &rest numbers) => number/ (number &rest numbers) => number% (number mod) => number&& (boolean &rest booleans) => boolean|| (boolean &rest booleans) => boolean== (object &rest objects) => boolean!= (object &rest objects) => boolean< (object &rest objects) => boolean<= (object &rest objects) => boolean> (object &rest objects) => boolean>= (object &rest objects) => boolean~ (boolean) => booleanmatch (string string-regex) => objectsplit (string &optional separator max-splits) => arrayupcase (string) => stringdowncase (string) => stringnow () => timetime (timezone year month day &optional hour minute second) => timeepoch-time (timestamp) => timeiso8601 (date &key timezone) => timein-timezone (time timezone) => timetimezone (time) => stringduring (time start end) => booleandate (time) => timetime-of-day (time) => numberyear (time) => numbermonth (time) => numberday (time) => numberday-of-week (time) => numberday-of-year (time) => numberhours (time) => numberminutes (time) => numberseconds (time) => numberto-iso8601 (time) => stringto-epoch-time (time) => numbermonday () => timetuesday () => timewednesday () => timethursday () => timefriday () => timesaturday () => timesunday () => timejanuary () => timefebruary () => timemarch () => timeapril () => timemay () => timejune () => timejuly () => timeaugust () => timeseptember () => timeoctober () => timenovember () => timedecember () => timedo (function &rest args) => objectbranch (boolean true-expr false-expr) => objectfor-each (sequence function) => objecterror (message) => errordefault (top1 top2) => topexpr (lisp-object) => RethinkDB objectjs (javascript-str) => object/functioncoerce-to (object type) => objecttypeof (object) => type-stringinfo (object) => objectjson (string) => objectto-json-string (object) => stringliteral (&optional object) => objectgeojson (object)) => geometryto-geojson (geo)) => objectpoint (lat long)) => geometryline (&rest array/geo)) => geometrypolygon (&rest array/geo)) => geometrydistance (geo-from geo-to &key geo-system unit)) => numberintersects (geo1 geo2)) => boolincludes (geo1 geo2)) => boolcircle (geo radius &key num-vertices geo-system unit fill)) => geometryget-intersecting (table geo &key index)) => streamfill (geo)) => geometryget-nearest (table geo &key index max-results max-dist geo-system unit)) => arraypolygon-sub (geo1 geo2)) => geometryThese are the errors you may encounter while using this driver. Most (if not all) errors will be signalled on a promise instead of thrown directly. Errors on a promise can be caught via catcher.
A general query error.
extends query-error
Thrown when the driver sucks. If you get this, open an issue.
extends query-error
Thrown when a query cannot compile. If you get this, take a close look at your query forms.
extends query-error
Thrown when the database has a runtime error.
A general error with a cursor.
extends cursor-error
Thrown when next is called on a cursor, but the cursor is currently grabbing more results.
extends cursor-error
Thrown when next is called on a cursor that has no more results. You can test this by using has-next.
A REQL error. This is thrown when there's an error in the returned REQL data from the database. For instance, if a time value comes back without a timestamp or binary data type comes back without the payload. Generally, if the database itself is functioning correctly, you won't see this error.
MIT. Enjoy.
Next: Modules, Previous: Introduction, Up: The cl-rethinkdb Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
A RethinkDB driver for Common Lisp
Andrew Danger Lyon <orthecreedence@gmail.com>
MIT
0.6.7
Next: Files, Previous: Systems, Up: The cl-rethinkdb Reference Manual [Contents][Index]
Modules are listed depth-first from the system components tree.
config.lisp (file).
cl-rethinkdb (system).
Next: Packages, Previous: Modules, Up: The cl-rethinkdb Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: cl-rethinkdb/util.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
cl-rethinkdb (system).
Next: cl-rethinkdb/package.lisp, Previous: cl-rethinkdb/cl-rethinkdb.asd, Up: Lisp [Contents][Index]
cl-rethinkdb (system).
Next: cl-rethinkdb/config.lisp, Previous: cl-rethinkdb/util.lisp, Up: Lisp [Contents][Index]
util.lisp (file).
cl-rethinkdb (system).
Next: cl-rethinkdb/protocol.lisp, Previous: cl-rethinkdb/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
cl-rethinkdb (system).
Next: cl-rethinkdb/reql/types.lisp, Previous: cl-rethinkdb/config.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
cl-rethinkdb (system).
Next: cl-rethinkdb/reql/function.lisp, Previous: cl-rethinkdb/protocol.lisp, Up: Lisp [Contents][Index]
reql (module).
Next: cl-rethinkdb/reql/commands.lisp, Previous: cl-rethinkdb/reql/types.lisp, Up: Lisp [Contents][Index]
types.lisp (file).
reql (module).
fn (macro).
Next: cl-rethinkdb/reql/dsl.lisp, Previous: cl-rethinkdb/reql/function.lisp, Up: Lisp [Contents][Index]
function.lisp (file).
reql (module).
Next: cl-rethinkdb/reql/pseudotypes.lisp, Previous: cl-rethinkdb/reql/commands.lisp, Up: Lisp [Contents][Index]
commands.lisp (file).
reql (module).
r (macro).
Next: cl-rethinkdb/connection.lisp, Previous: cl-rethinkdb/reql/dsl.lisp, Up: Lisp [Contents][Index]
dsl.lisp (file).
reql (module).
Next: cl-rethinkdb/query.lisp, Previous: cl-rethinkdb/reql/pseudotypes.lisp, Up: Lisp [Contents][Index]
cl-rethinkdb (system).
Previous: cl-rethinkdb/connection.lisp, Up: Lisp [Contents][Index]
cl-rethinkdb (system).
Next: Definitions, Previous: Files, Up: The cl-rethinkdb Reference Manual [Contents][Index]
Packages are listed by definition order.
Next: cl-rethinkdb, Previous: Packages, Up: Packages [Contents][Index]
reql
Next: cl-rethinkdb-util, Previous: cl-rethinkdb-reql, Up: Packages [Contents][Index]
r
Previous: cl-rethinkdb, Up: Packages [Contents][Index]
Next: Indexes, Previous: Packages, Up: The cl-rethinkdb Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
Defines whether data returned as an object should be an :alist or :hash.
Defines whether data returned as a sequence should be a :list or :array.
Holds all tracking state for the RethinkDB driver.
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
Generifies looping over a hash table or alist.
Generifies looping over a list OR vector.
Makes creating anonymous REQL functions easy. Takes a list of arguments (this is not a real lambda list, just a flat list of args) and wraps the body in the REQL-generating form ’r’.
Wraps query generation in a macro that takes care of pesky function naming
issues. For instance, the function ‘count‘ is reserved in CL, so importing
cl-rethinkdb-reql:count into your app might mess a lot of things up.
Instead, you can wrap your queries in (r ...) and use *keywords* for function
names, and all will be well. For instance:
(r::insert (r::table "users") ’(("name" . "larry")))
becomes:
(r (:insert (:table "users") ’(("name" . "larry"))))
This allows you to separate CL functions from query functions both logically
and visually.
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
Connect to a RethinkDB database, optionally specifying the database.
Recursively handle RethinkDB’s pseudotypes in returned objects.
Determine if the given object is a cursor.
Disconnect a RethinkDB connection.
Call the given function on every result in the given cursor.
Convert a number into N bytes little endian.
Determine if a cursor has more results.
Grab the next result from a cursor. Always returns a future since it may have to get more results from the server.
This function runs the given query, and returns a future that’s finished when the query response comes in.
Cleanup a cursor both locally and in the database. Returns a future that is finished with *no values* once the stop operation has completed.
Call stop on a cursor and disconnect the passed socket.
Grab ALL results from a cursor. Returns a future finished with the final array.
Takes a socket and a cursor an returns a sequence of all the items that cursor points to (the type of sequence returned depends on *sequence-type*)
Turns N number of bytes at offset in bytes into an integer.
Wait for noreply => t queries to come back LOL.
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
msg.
Next: Conditions, Previous: Generic functions, Up: Public Interface [Contents][Index]
Next: Classes, Previous: Standalone methods, Up: Public Interface [Contents][Index]
Describes a general query error.
Thrown when a cursor has no more results on it.
Thrown when a cursor has no more results on it.
Thrown when a cursor that has a pending operation is stopped.
A client error condition.
A query compile error condition.
A general query failure condition.
simple-error.
(quote nil)
:token
This slot is read-only.
(quote nil)
:query
This slot is read-only.
(quote nil)
:backtrace
This slot is read-only.
(quote "")
:msg
This slot is read-only.
A query runtime error condition.
A general reql error
simple-error.
(quote "")
:msg
This slot is read-only.
Previous: Conditions, Up: Public Interface [Contents][Index]
The query class holds the state of a query, as well as the future that will be finished when the query returns results.
dispatch.
Describes the current state of the query (new, complete, etc).
:new
:state
Holds the future that will be finished with the results from this query.
:future
Holds the token for this query.
:token
Tracks the last time the query changed state.
0
Holds the current result set from the query.
Tracks which record the cursor points to.
0
Holds freeform debug info for this cursor.
common-lisp.
:debug
Tracks all state for the driver.
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Special variables, Previous: Internals, Up: Internals [Contents][Index]
Holds name -> lambda mappings for our commands.
An empty data set for setting callbacks. Perhaps a cl-async API for this is in order??
Used to track lambda variables in functions.
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Wraps creation of commands.
Allow storing of arbitrary data with a socket.
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
Determine if the given object is an alist.
Call a command by name.
Makes sure all DATA (not command) arrays are wrapped in a make-array cmd.
Handle pseudotypes.
Close the given socket.
Create a connection to the given host/port, and optionally db.
Make sure a connection to the DB was successful.
Make sure a socket that just had query data sent over it is ready to handle the response.
Returns ’unique’ variable ’names’ for ’anonymous’ ’functions’ ;) ;) if you know what I mean heh heh ;) ;) ;).
Generates a new token value for a query.
Grab a cursor associated with a token. Returns nil if no cursor exists for that token
This function returns a closure that can be called multiple times with data from a RethinkDB response. If a full response is received (over one or more calls) it returns the *full byte array of the response*, otherwise nil.
Note that the response chunks MUST be passed in in the order received.
Continue a query.
Given a full response byte array, parse it, find the attached cursor (by token), and either resolve/reject the cursor’s promise with the return of the query.
Remove a cursor/token from state tracking.
Associate a cursor with a token. Retrievable through get-cursor.
Turn a query into a byte array.
Wraps setting socket callbacks.
Send data on a rethinkdb connection.
Next: Conditions, Previous: Ordinary functions, Up: Internals [Contents][Index]
automatically generated reader method
kv.
automatically generated writer method
kv.
msg.
msg.
Next: Classes, Previous: Generic functions, Up: Internals [Contents][Index]
A general connection error condition.
simple-error.
(quote "")
:msg
This slot is read-only.
Next: Types, Previous: Conditions, Up: Internals [Contents][Index]
Holds per-connection options.
:kv
Describes a REQL command.
Previous: Definitions, Up: The cl-rethinkdb Reference Manual [Contents][Index]
| Jump to: | !
%
&
(
*
+
-
/
<
=
>
~
∅
A B C D E F G H I J K L M N O P Q R S T U V W Y Z |
|---|
| Jump to: | !
%
&
(
*
+
-
/
<
=
>
~
∅
A B C D E F G H I J K L M N O P Q R S T U V W Y Z |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
+
A B C D F K L M N O Q R S T |
|---|
| Jump to: | *
+
A B C D F K L M N O Q R S T |
|---|
| Jump to: | A C D F M P Q R S T U |
|---|
| Jump to: | A C D F M P Q R S T U |
|---|