Safe Haskell	None

Database.Cassandra.Basic

Contents

Connection
MonadCassandra Typeclass
Cassandra Operations
Filtering
Exceptions
Utility
Basic Types
Helpers
Working with column types

Synopsis

Connection

type CPool = Pool Cassandra Source

A round-robin pool of cassandra connections

type Server = (HostName, Int)Source

A (ServerName, Port) tuple

defServer :: Server Source

A localhost server with default configuration

defServers :: [Server]Source

A single localhost server with default configuration

type KeySpace = String Source

createCassandraPool Source

Arguments

:: [Server]	List of servers to connect to
-> Int	Number of stripes to maintain
-> Int	Max connections per stripe
-> NominalDiffTime	Kill each connection after this many seconds
-> KeySpace	Each pool operates on a single KeySpace
-> IO CPool

Create a pool of connections to a cluster of Cassandra boxes

Each box in the cluster will get up to n connections. The pool will send queries in round-robin fashion to balance load on each box in the cluster.

MonadCassandra Typeclass

class MonadIO m => MonadCassandra m whereSource

All Cassy operations are designed to run inside MonadCassandra context.

We provide a default concrete Cas datatype, but you can simply make your own application monads an instance of MonadCassandra for conveniently using all operations of this package.

Please keep in mind that all Cassandra operations may raise CassandraExceptions at any point in time.

Methods

getCassandraPool :: m CPool Source

Instances

MonadIO m => MonadCassandra (ReaderT CPool m)

type Cas a = ReaderT CPool IO aSource

runCas :: CPool -> Cas a -> IO aSource

Main running function when using the ad-hoc Cas monad. Just write your cassandra actions within the Cas monad and supply them with a CPool to execute.

Cassandra Operations

getCol Source

Arguments

:: (MonadCassandra m, CasType k)
=> ColumnFamily
-> ByteString	Row key
-> k	Column/SuperColumn key; see `CasType` for what it can be. Use ByteString in the simple case.
-> ConsistencyLevel	Read quorum
-> m (Maybe Column)

Get a single key-column value.

get Source

Arguments

:: MonadCassandra m
=> ColumnFamily	in ColumnFamily
-> ByteString	Row key to get
-> Selector	Slice columns with selector
-> ConsistencyLevel
-> m [Column]

An arbitrary get operation - slice with Selector

getMulti Source

Arguments

:: MonadCassandra m
=> ColumnFamily
-> KeySelector	A selection of rows to fetch in one hit
-> Selector	Subject to column selector conditions
-> ConsistencyLevel
-> m (Map ByteString Row)	A Map from Row keys to `Row`s is returned

Do multiple gets in one DB hit

insert Source

Arguments

:: MonadCassandra m
=> ColumnFamily
-> ByteString	Row key
-> ConsistencyLevel
-> [Column]	best way to make these columns is through packCol
-> m ()

Insert an entire row into the db.

This will do as many round-trips as necessary to insert the full row. Please keep in mind that each column and each column of each super-column is sent to the server one by one.

 insert "testCF" "row1" ONE [packCol ("column key", "some column content")]

delete Source

Arguments

:: MonadCassandra m
=> ColumnFamily	In `ColumnFamily`
-> Key	Key to be deleted
-> Selector	Columns to be deleted
-> ConsistencyLevel
-> m ()

Delete an entire row, specific columns or a specific sub-set of columns within a SuperColumn.

Filtering

data Selector Source

A column selector/filter statement for queries.

Remember that SuperColumns are always fully deserialized, so we don't offer a way to filter columns within a SuperColumn.

Column names and ranges are specified by any type that can be packed into a Cassandra column using the CasType typeclass.

Constructors

All	Return everything in `Row`
forall a . CasType a => ColNames [a]	Return specific columns or super-columns depending on the `ColumnFamily`
forall a b . (CasType a, CasType b) => SupNames a [b]	When deleting specific columns in a super column
forall a b . (CasType a, CasType b) => Range	Return a range of columns or super-columns.
Fields rangeStart :: Maybe a rangeEnd :: Maybe b rangeOrder :: Order rangeLimit :: Int32

Instances

Show Selector
Default Selector

range :: Selector Source

A default starting point for range Selector. Use this so you don't run into ambiguous type variables when using Nothing.

 range = Range (Nothing :: Maybe ByteString) (Nothing :: Maybe ByteString) Regular 1024

data Order Source

Order in a range query

Constructors

Regular
Reversed

Instances

Show Order

reverseOrder :: Order -> Order Source

data KeySelector Source

A Key range selector to use with getMulti.

Constructors

Keys [Key]	Just a list of keys to get
KeyRange KeyRangeType Key Key Int32	A range of keys to get. Remember that RandomPartitioner ranges may not mean much as keys are randomly assigned to nodes.

Instances

Show KeySelector

data KeyRangeType Source

Encodes the Key vs. Token options in the thrift API.

InclusiveRange ranges are just plain intuitive range queries. WrapAround ranges are also inclusive, but they wrap around the ring.

Constructors

InclusiveRange
WrapAround

Instances

Show KeyRangeType

Exceptions

Utility

getTime :: IO Int64 Source

Cassandra is VERY sensitive to its timestamp values. As a convention, timestamps are always in microseconds

throwing :: IO (Either CassandraException a) -> IO aSource

Make exceptions implicit.

wrapException :: IO a -> IO aSource

Wrap exceptions of the underlying thrift library into the exception types defined here.

Basic Types

type ColumnFamily = String Source

type Key = ByteString Source

type ColumnName = ByteString Source

type Value = ByteString Source

data Column Source

A Column is either a single key-value pair or a SuperColumn with an arbitrary number of key-value pairs

Constructors

SuperColumn ColumnName [Column]
Column
Fields colKey :: ColumnName colVal :: Value colTS :: Maybe Int64 Last update timestamp; will be overridden during write/update ops colTTL :: Maybe Int32 A TTL after which Cassandra will erase the column

Instances

Eq Column
Ord Column
Read Column
Show Column

col :: ByteString -> ByteString -> Column Source

A short-hand for creating key-value Column values. This is pretty low level; you probably want to use packCol.

packCol :: CasType k => (k, ByteString) -> Column Source

Pack key-value pair into Column form ready to be written to Cassandra

unpackCol :: CasType k => Column -> (k, Value)Source

Unpack a Cassandra Column into a more convenient (k,v) form

packKey :: CasType a => a -> ByteString Source

Pack a column key into binary, ready for submission to Cassandra

type Row = [Column]Source

A full row is simply a sequence of columns

data ConsistencyLevel

Constructors

ONE
QUORUM
LOCAL_QUORUM
EACH_QUORUM
ALL
ANY
TWO
THREE

Instances

Enum ConsistencyLevel
Eq ConsistencyLevel
Ord ConsistencyLevel
Show ConsistencyLevel
Typeable ConsistencyLevel

Helpers

class CKey a whereSource

A typeclass to enable using any string-like type for row and column keys

Methods

toColKey :: a -> ByteString Source

fromColKey :: ByteString -> Either String aSource

Instances

CKey String
CKey ByteString
CKey Text
CKey ByteString
CKey Text
CKey [ByteString]	For easy composite keys, just serialize your data type to a list of bytestrings, we'll concat them and turn them into column keys.

fromColKey' :: CKey a => ByteString -> aSource

Raise an error if conversion fails

Working with column types

class CasType a whereSource

This typeclass defines and maps to haskell types that Cassandra natively knows about and uses in sorting and potentially validating column key values.

All column keys are eventually sent to and received from Cassandra in binary form. This typeclass allows us to map some Haskell type definitions to their binary representation. The correct binary serialization is handled for you behind the scenes.

For simplest cases, just use one of the string-like instances, e.g. ByteString, String or Text. Please keep in mind that these are just mapped to untyped BytesType.

Remember that for special column types, such as TLong, to have any effect, your ColumnFamily must have been created with that comparator or validator. Otherwise you're just encoding/decoding integer values without any Cassandra support for sorting or correctness.

The Python library pycassa has a pretty good tutorial to learn more.

Tuple instances support fixed ComponentType columns. Example:

 insert "testCF" "row1" [packCol ((TLong 124, TAscii "Hello"), "some content")]

Methods

encodeCas :: a -> ByteString Source

decodeCas :: ByteString -> aSource

Instances

CasType Int
CasType String
CasType ByteString
CasType Text
CasType ByteString
CasType Text
CasType TUtf8	Encode and decode as Utf8 `Text`
CasType TLong	Pack as an 8 byte unsigned number; negative signs are lost.
CasType TInt	Pack as an 8 byte number - same as `TLong`
CasType TInt32	Pack as a 4 byte number
CasType TCounter
CasType TBytes
CasType TAscii
CasType a => CasType (Single a)	Use the `Single` wrapper when querying only with the first of a two or more field CompositeType.
(CasType a, CasType b) => CasType (a, Exclusive b)
(CasType a, CasType b) => CasType (a, b)	Composite types - see Cassandra or pycassa docs to understand
(CasType a, CasType b, CasType c) => CasType (a, b, Exclusive c)
(CasType a, CasType b, CasType c) => CasType (a, b, c)
(CasType a, CasType b, CasType c, CasType d) => CasType (a, b, c, Exclusive d)
(CasType a, CasType b, CasType c, CasType d) => CasType (a, b, c, d)

newtype TAscii Source

Constructors

TAscii
Fields getAscii :: ByteString

Instances

Eq TAscii
Ord TAscii
Read TAscii
Show TAscii
CasType TAscii

newtype TBytes Source

Constructors

TBytes
Fields getTBytes :: ByteString

Instances

Eq TBytes
Ord TBytes
Read TBytes
Show TBytes
CasType TBytes

newtype TCounter Source

Constructors

TCounter
Fields getCounter :: ByteString

Instances

Eq TCounter
Ord TCounter
Read TCounter
Show TCounter
CasType TCounter

newtype TInt Source

Constructors

TInt
Fields getInt :: Integer

Instances

Eq TInt
Ord TInt
Read TInt
Show TInt
CasType TInt	Pack as an 8 byte number - same as `TLong`

newtype TInt32 Source

Constructors

TInt32
Fields getInt32 :: Int32

Instances

Eq TInt32
Ord TInt32
Read TInt32
Show TInt32
CasType TInt32	Pack as a 4 byte number

newtype TUtf8 Source

Constructors

TUtf8
Fields getUtf8 :: Text

Instances

Eq TUtf8
Ord TUtf8
Read TUtf8
Show TUtf8
CasType TUtf8	Encode and decode as Utf8 `Text`

newtype TUUID Source

Constructors

TUUID
Fields getUUID :: ByteString

Instances

Eq TUUID
Ord TUUID
Read TUUID
Show TUUID

newtype TLong Source

Constructors

TLong
Fields getLong :: Integer

Instances

Eq TLong
Ord TLong
Read TLong
Show TLong
CasType TLong	Pack as an 8 byte unsigned number; negative signs are lost.

newtype Exclusive a Source

Exclusive tag for composite column. You may tag the end of a composite range with this to make the range exclusive. See pycassa documentation for more information.

Constructors

Exclusive a

Instances

Eq a => Eq (Exclusive a)
Ord a => Ord (Exclusive a)
Read a => Read (Exclusive a)
Show a => Show (Exclusive a)
(CasType a, CasType b) => CasType (a, Exclusive b)
(CasType a, CasType b, CasType c) => CasType (a, b, Exclusive c)
(CasType a, CasType b, CasType c, CasType d) => CasType (a, b, c, Exclusive d)

NotFoundException
InvalidRequestException String
UnavailableException
TimedOutException
AuthenticationException String
AuthorizationException String
SchemaDisagreementException
ConversionException String
OperationNotSupported String

Eq CassandraException
Data CassandraException
Ord CassandraException
Read CassandraException
Show CassandraException
Typeable CassandraException
Exception CassandraException