Database.RethinkDB

RethinkDB client library for Haskell

Modelled upon the official Javascript and Python API: http://www.rethinkdb.com/api/

How to use

>>> import Database.RethinkDB
>>> import qualified Database.RethinkDB.Functions as R

Accessing RethinkDB

data RethinkDBHandle

A connection to the database server

openConnection :: HostName -> Maybe PortID -> Maybe String -> IO RethinkDBHandle

Create a new connection to the database server

Example: connect using the default port (28015) and specifying the default database for all queries.

>>> h <- openConnection "localhost" Nothing (Just "test")

closeConnection :: RethinkDBHandle -> IO ()

Close an open connection

>>> closeConnection h

use :: RethinkDBHandle -> Database -> RethinkDBHandle

Set the default connection

The new handle is an alias for the old one. Calling closeConnection on either one will close both.

>>> let h' = h `use` (db "players")

run :: ToQuery a v => RethinkDBHandle -> a -> IO v

Run a query on the connection

The return value depends on the type of the second argument.

When the return value is polymorphic, type annotations may be required.

>>> run h $ table "fruits" :: IO [(Document, Value)]

runMaybe :: ToQuery a v => RethinkDBHandle -> a -> IO (Maybe v)

Run a query on the connection, returning Nothing on error

runEither :: ToQuery a v => RethinkDBHandle -> a -> IO (Either String v)

Run a query on the connection, returning (Left message) on error

runRaw :: (ToBuildQuery q, JSONQuery (BuildViewQuery q)) => RethinkDBHandle -> q -> IO Response

Run a query on the connection and return the raw response

runJSON :: (JSONQuery (BuildViewQuery q), ToBuildQuery q) => RethinkDBHandle -> q -> IO [Value]

Run a query on the connection and return the resulting JSON value

runBatch :: ToQuery q [a] => RethinkDBHandle -> q -> IO (Results a)

Run a query on the connection and a return a lazy result list

>>> res <- runBatch h <- (arrayToStream [1,2,3] :: NumberStream)
>>> next res
Just 1
>>> collect res
[2,3]

next :: Results a -> IO (Maybe a)

Read the next value from a lazy query. Fetch it from the server if needed.

collect :: Results a -> IO [a]

Return all the results of a lazy query.

resultsError :: Results a -> IO (Maybe String)

Get the last error from a lazy query.

If both next and resultsError return Nothing, then all results have been fetched without error.

Manipulating databases

data Database

A database, referenced by name

Constructors

Database

Fields

databaseName :: String

Instances

Eq Database

Ord Database

Show Database

db :: String -> Database

Create a Database reference

dbCreate :: String -> Query False Database

Create a database on the server

dbDrop :: Database -> Query False ()

Drop a database

dbList :: Query False [Database]

List the databases on the server

>>> run h $ dbList
[test, dev, prod]

Manipulating Tables

data Table

A table description

Constructors

Table

Fields

tableDatabase :: Maybe Database

when Nothing, use the rdbDatabase

tableName :: String

_tablePrimaryAttr :: Maybe String

when Nothing, id is used

Instances

Eq Table

Ord Table

Show Table

ToValue Table

ToExpr Table

ToStream Table

ToBuildQuery Table

(ToBuildQuery Table, FromJSON a) => ToQuery Table [(Document, a)]

tablePrimaryAttr :: Table -> String

data TableCreateOptions

Options used to create a table

Constructors

TableCreateOptions

Fields

tableDataCenter :: Maybe String

tableCacheSize :: Maybe Int64

Instances

Default TableCreateOptions

table :: String -> Table

Create a simple table refence with no associated database or primary key

>>> table "music"

Another way to create table references is to use the Table constructor:

>>> Table (Just "mydatabase") "music" (Just "tuneid")

tableCreate :: Table -> TableCreateOptions -> Query False Table

Create a table on the server

def can be imported from Data.Default

>>> t <- run h $ tableCreate (table "fruits") def

tableDrop :: Table -> Query False ()

Drop a table

tableList :: Database -> Query False [Table]

List the tables in a database

Writing data

data Document

A reference to a document

Constructors

Document

Fields

documentTable :: Table

documentKey :: Value

Instances

Eq Document

Show Document

ToValue Document

ToExpr Document

ToStream Document

ToBuildQuery Document

(ToBuildQuery Document, FromJSON a) => ToQuery Document a

(ToBuildQuery Table, FromJSON a) => ToQuery Table [(Document, a)]

(ToBuildQuery (Expr (StreamType True v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (StreamType True v)) [(Document, a)]

insert :: (ToValue a, ToValueType (ExprType a) ~ ObjectType) => Table -> a -> WriteQuery Document

Insert a document into a table

>>> d <- run h $ insert t (object ["name" .= "banana", "color" .= "red"])

insertMany :: (ToValue a, ToValueType (ExprType a) ~ ObjectType) => Table -> [a] -> WriteQuery [Document]

Insert many documents into a table

upsert :: (ToValue a, ToValueType (ExprType a) ~ ObjectType) => Table -> a -> WriteQuery Document

Insert a document into a table, overwriting a document with the same primary key if one exists.

upsertMany :: (ToValue a, ToValueType (ExprType a) ~ ObjectType) => Table -> [a] -> WriteQuery [Document]

Insert many documents into a table, overwriting any existing documents with the same primary key.

update :: (ToExpr sel, ExprType sel ~ StreamType True out, ToMapping map, MappingFrom map ~ out, MappingTo map ~ ObjectType) => sel -> map -> WriteQuery ()

Update a table

>>> t <- run h $ tableCreate (table "example") def
>>> run h $ insertMany t [object ["a" .= 1, "b" .= 11], object ["a" .= 2, "b" .= 12]]
>>> run h $ update t (object ["b" .= 20])
>>> run h $ t

replace :: (ToExpr sel, ExprIsView sel ~ True, ToJSON a) => sel -> a -> WriteQuery ()

Replace documents in a table

delete :: (ToExpr sel, ExprIsView sel ~ True) => sel -> WriteQuery ()

Delete one or more documents from a table

Selecting data

get :: (ToExpr e, ExprType e ~ StreamType True ObjectType, ToValue k) => e -> k -> ObjectExpr

Get a document by primary key

filter' :: (ToMapping m, ToStream e, MappingFrom m `HasToStreamValueOf` e) => m -> e -> Expr (ExprType e)

Get all the documents for which the given predicate is true

between :: (ToJSON a, ToStream e, ObjectType `HasToStreamValueOf` e) => Maybe a -> Maybe a -> e -> Expr (ExprType e)

Get all documents between two primary keys (both keys are inclusive)

Joins

innerJoin :: (ToStream a, l `HasToStreamValueOf` a, ToStream b, r `HasToStreamValueOf` b) => a -> b -> (ValueExpr l -> ValueExpr r -> BoolExpr) -> Expr (StreamType False ObjectType)

outerJoin :: (ToStream a, l `HasToStreamValueOf` a, ToStream b, r `HasToStreamValueOf` b) => a -> b -> (ValueExpr l -> ValueExpr r -> BoolExpr) -> Expr (StreamType False ObjectType)

eqJoin :: (ToStream a, ObjectType `HasToStreamValueOf` a, ToExpr b, ExprType b ~ ExprType Selection) => a -> String -> b -> Expr (StreamType False ObjectType)

zip' :: (ToStream e, ObjectType `HasToStreamValueOf` e) => e -> Expr (StreamType False ObjectType)

Transformations

map' :: (ToMapping m, ToStream e, MappingFrom m `HasToStreamValueOf` e) => m -> e -> Expr (StreamType False (MappingTo m))

concatMap' :: (ToMapping m, MappingTo m ~ ArrayType, ToStream e, MappingFrom m `HasToStreamValueOf` e) => m -> e -> Expr (StreamType False t)

orderBy :: (ToOrder o, ToStream e, a `HasToStreamValueOf` e) => [o] -> e -> Expr (StreamType (ExprIsView e) a)

skip :: (ToStream e, t `HasToStreamValueOf` e, ToExpr n, ExprType n ~ ValueType NumberType) => e -> n -> Expr (StreamType (ExprIsView e) t)

limit :: (ToStream e, t `HasToStreamValueOf` e, ToExpr n, ExprType n ~ ValueType NumberType) => e -> n -> Expr (StreamType (ExprIsView e) t)

slice :: (ToStream e, t `HasToStreamValueOf` e, ToExpr n, ExprType n ~ ValueType NumberType, ToExpr m, ExprType m ~ ValueType NumberType) => e -> n -> m -> Expr (StreamType (ExprIsView e) t)

nth :: (ToStream e, t `HasToStreamValueOf` e, ToExpr n, ExprType n ~ ValueType NumberType) => e -> n -> ValueExpr t

pluck :: (ToStream e, ObjectType `HasToStreamValueOf` e) => [String] -> e -> Expr (StreamType False ObjectType)

without :: (ToStream e, ObjectType `HasToStreamValueOf` e) => [String] -> e -> Expr (StreamType False ObjectType)

union' :: (ToStream a, t `HasToStreamValueOf` a, ToStream b, t `HasToStreamValueOf` b) => a -> b -> Expr (StreamType False t)

Aggregation

reduce :: (ToValue z, ToValueType (ExprType z) ~ a, ToStream e, b `HasToStreamValueOf` e, ToExpr c, ExprIsView c ~ False) => e -> z -> (ValueExpr a -> ValueExpr b -> c) -> Expr (ExprType c)

count :: (ToExpr e, Sequence (ExprType e)) => e -> NumberExpr

distinct :: (ToStream e, v `HasToStreamValueOf` e) => e -> Expr (StreamType False v)

groupedMapReduce :: (ToValue group, ToValue value, ToValue acc, ToValueType (ExprType acc) ~ b, ToValue acc', ToValueType (ExprType acc') ~ b, ToStream e, a `HasToStreamValueOf` e) => (ValueExpr a -> group) -> (ValueExpr a -> value) -> acc -> (ValueExpr b -> ValueExpr v -> acc') -> e -> Expr (StreamType False b)

groupBy' :: (ToStream e, ObjectType `HasToStreamValueOf` e) => [String] -> MapReduce ObjectType b c d -> e -> Expr (StreamType False d)

Reductions

count' :: MapReduce ObjectType NoneType NumberType NumberType

sum' :: String -> MapReduce ObjectType NumberType NumberType NumberType

avg :: String -> MapReduce ObjectType ArrayType ArrayType NumberType

Document manipulation

pick :: HasValueType e ObjectType => [String] -> e -> ObjectExpr

unpick :: HasValueType e ObjectType => [String] -> e -> ObjectExpr

merge :: (ToExpr a, ExprType a ~ ValueType ObjectType, ToExpr b, ExprType b ~ ValueType ObjectType) => a -> b -> ObjectExpr

append :: (HasValueType a ArrayType, HasValueType b x) => a -> b -> ArrayExpr

(!) :: (ToExpr a, ExprValueType a ~ ObjectType) => a -> String -> ValueExpr t

Get the value of the field of an object

When GHC thinks the result is ambiguous, it may have to be annotated.

>>> run h $ (get (table "tea") "black" ! "water_temperature" :: NumberExpr)
95

(!?) :: HasValueType a ObjectType => a -> String -> BoolExpr

Operators

concat :: (HaveValueType a b v, CanConcat v) => a -> b -> Expr (ValueType v)

add :: HaveValueType a b NumberType => a -> b -> NumberExpr

sub :: HaveValueType a b NumberType => a -> b -> NumberExpr

mul :: HaveValueType a b NumberType => a -> b -> NumberExpr

div' :: HaveValueType a b NumberType => a -> b -> NumberExpr

mod :: HaveValueType a b NumberType => a -> b -> NumberExpr

and' :: HaveValueType a b BoolType => a -> b -> BoolExpr

or' :: HaveValueType a b BoolType => a -> b -> BoolExpr

eq :: (HasValueType a x, HasValueType b y) => a -> b -> BoolExpr

ne :: (HasValueType a x, HasValueType b y) => a -> b -> BoolExpr

gt :: (HaveValueType a b v, CanCompare v) => a -> b -> BoolExpr

ge :: (HaveValueType a b v, CanCompare v) => a -> b -> BoolExpr

lt :: (HaveValueType a b v, CanCompare v) => a -> b -> BoolExpr

le :: (HaveValueType a b v, CanCompare v) => a -> b -> BoolExpr

not' :: HasValueType a BoolType => a -> BoolExpr

Control structures

bind :: ToValue e => e -> (ValueExpr (ToValueType (ExprType e)) -> Expr t) -> Expr t

let' :: [Attribute] -> Expr t -> Expr t

var :: ExprIsView (Expr t) ~ False => String -> Expr t

if' :: (ToValue e, ToValueType (ExprType e) ~ BoolType, ToExpr a, ExprTypeNoView (ExprType a) ~ x, ToExpr b, ExprTypeNoView (ExprType b) ~ x, ExprTypeIsView x ~ False) => e -> a -> b -> Expr x

forEach :: (ToStream a, v `HasToStreamValueOf` a) => a -> (ValueExpr v -> WriteQuery b) -> WriteQuery ()

Execute a write query for each element of the stream

>>> run h $ forEach [1,2,3::Int] (\x -> insert (table "fruits") (obj ["n" := x]))

error' :: ExprTypeIsView t ~ False => String -> Expr t

js :: String -> Expr (ValueType any)

A javascript expression

It is often necessary to specify the result type:

>>> run h $ (js "1 + 2" :: NumberExpr)
3

jsfun :: ToValue e => String -> e -> Expr (ValueType y)

A javascript function

>>> let squareRoot = jsfun "Math.sqrt" :: NumberExpr -> NumberExpr
>>> run h $ squareRoot 5 :: IO Double
2.23606797749979

Sequence conversion

streamToArray :: (ToExpr e, ExprType e ~ StreamType w t) => e -> Expr (ValueType ArrayType)

Convert a stream into an array

arrayToStream :: (ToExpr e, ExprType e ~ ValueType ArrayType) => e -> Expr (StreamType False t)

Convert an array into a stream

asArray :: ToExpr e => e -> ArrayExpr

Short constructors

data Obj

A list of String/Expr pairs

Instances

ToValue Obj

ToExpr Obj

ToMapping Obj

data Attribute

Constructors

forall e . ToValue e => String := e

obj :: [Attribute] -> Obj

Build an Obj

str :: String -> Text

nil :: ValueExpr ArrayType

The empty list expression

Types and type classes

data Query b a

A query returning a

Instances

Functor (Query w)

ToBuildQuery (Query w a)

ToBuildQuery (Query w a) => ToQuery (Query w a) a

class ToBuildQuery a => ToQuery a b | a -> b where

Methods

toQuery :: a -> Query (BuildViewQuery a) b

Instances

(ToBuildQuery Document, FromJSON a) => ToQuery Document a

(ToBuildQuery Table, FromJSON a) => ToQuery Table [(Document, a)]

(ToBuildQuery (Expr (ValueType v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (ValueType v)) a

ToBuildQuery (WriteQuery a) => ToQuery (WriteQuery a) a

(ToBuildQuery (Expr (StreamType False v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (StreamType False v)) [a]

(ToBuildQuery (Expr (StreamType True v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (StreamType True v)) [(Document, a)]

ToBuildQuery (Query w a) => ToQuery (Query w a) a

data ValueTypeKind

The types of values

Constructors

NumberType

BoolType

ObjectType

ArrayType

StringType

NoneType

OtherValueType

Instances

FromJSON a => ExtractValue ValueTypeKind OtherValueType a

ExtractValue ValueTypeKind NoneType ()

(IsString a, FromJSON a) => ExtractValue ValueTypeKind StringType a

FromJSON a => ExtractValue ValueTypeKind ArrayType a

FromJSON a => ExtractValue ValueTypeKind ObjectType a

ExtractValue ValueTypeKind BoolType Bool

(Num a, FromJSON a) => ExtractValue ValueTypeKind NumberType a

data ExprTypeKind

The type of a RQL expression

The type hierarchy has 3 branches:

• A read-only sequence: StreamType False
• A selection (also called a view): StreamType True
• A value (a JSON object, array or primitive type): ExprType

Constructors

StreamType Bool ValueTypeKind

When the flag is true, it can be updated or deleted

ValueType ValueTypeKind

type ExprIsView e = ExprTypeIsView (ExprType e)

type family ExprValueType expr :: ValueTypeKind

The type of the value of an Expr

data Expr t where

An RQL expression

Constructors

Expr :: QueryM (MaybeView (ExprIsView (Expr t)), Term) -> Expr t

SpotExpr :: Document -> Expr (StreamType True ObjectType)

Instances

Fractional (Expr (ValueType NumberType))

Num (Expr (ValueType NumberType))

ToValue (Expr (ValueType t))

ToValue (Expr (StreamType w t))

ToExpr (Expr t)

ToMapping (Expr (ValueType t))

ToStream (Expr (ValueType ArrayType))

ToExpr (Expr (StreamType w t)) => ToStream (Expr (StreamType w t))

ToBuildQuery (Expr (ValueType v))

ToBuildQuery (Expr (StreamType False v))

ToBuildQuery (Expr (StreamType True v))

(ToBuildQuery (Expr (ValueType v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (ValueType v)) a

(ToBuildQuery (Expr (StreamType False v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (StreamType False v)) [a]

(ToBuildQuery (Expr (StreamType True v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (StreamType True v)) [(Document, a)]

class ToExpr o where

Convert something into an Expr

Associated Types

type ExprType o :: ExprTypeKind

Methods

toExpr :: o -> Expr (ExprType o)

Instances

ToExpr Char

ToExpr Double

ToExpr Int

ToExpr Integer

ToExpr ()

ToExpr Text

ToExpr Obj

ToExpr Document

ToExpr Table

ToExpr a => ToExpr [a]

ToExpr (Expr t)

class ToValue e where

Convert something into a value Expr

Methods

toValue :: e -> Expr (ValueType (ToValueType (ExprType e)))

Instances

ToValue Double

ToValue Int

ToValue Integer

ToValue ()

ToValue Text

ToValue Obj

ToValue Document

ToValue Table

ToExpr a => ToValue [a]

ToValue (Expr (ValueType t))

ToValue (Expr (StreamType w t))

type HasValueType a v = (ToValue a, ToValueType (ExprType a) ~ v)

Aliases for type constraints on expressions

type HaveValueType a b v = (HasValueType a v, HasValueType b v)

type NumberExpr = Expr (ValueType NumberType)

Simple aliases for different Expr types

type BoolExpr = Expr (ValueType BoolType)

type ObjectExpr = Expr (ValueType ObjectType)

type ArrayExpr = Expr (ValueType ArrayType)

type StringExpr = Expr (ValueType StringType)

type ValueExpr t = Expr (ValueType t)

type NumberStream = Expr (StreamType False NumberType)

type BoolStream = Expr (StreamType False BoolType)

type ObjectStream = Expr (StreamType False ObjectType)

type ArrayStream = Expr (StreamType False ArrayType)

type StringStream = Expr (StreamType False StringType)

type Selection = Expr (StreamType True ObjectType)

class CanCompare a

What values can be compared with eq, ne, lt, gt, le and ge

Instances

CanCompare StringType

CanCompare NumberType

data Order

Constructors

Asc

Fields

orderAttr :: String

Desc

Fields

orderAttr :: String

Instances

ToOrder Order

class ToOrder a where

Methods

toOrder :: a -> Order

Instances

ToOrder String

ToOrder Order

class Sequence e

A sequence is either a stream or an array

Associated Types

type SequenceType e t :: Constraint

Instances

~ ValueTypeKind a ArrayType => Sequence (ValueType a)

Sequence (StreamType w t)

data Mapping from to

A mapping is a like single-parameter function

Constructors

Mapping (QueryM Mapping)

class ToMapping map where

Convert objects into mappings

Associated Types

type MappingFrom map :: ValueTypeKind

type MappingTo map :: ValueTypeKind

Methods

toMapping :: map -> Mapping (MappingFrom map) (MappingTo map)

Instances

ToMapping Value

ToMapping Obj

ToMapping (Expr (ValueType t))

(ToValue b, ~ * a (Expr (ValueType t))) => ToMapping (a -> b)

data Results a