Safe Haskell | Safe-Infered |
---|
A higher level module for working with Cassandra.
All row and column keys are standardized to be of strict types. Row keys are Text, while Column keys are ByteString. This might change in the future and we may revert to entirely ByteString keys.
Serialization and de-serialization of Column values are taken care of automatically using the ToJSON and FromJSON typeclasses.
- type CPool = Pool Cassandra
- type Server = (HostName, Int)
- defServer :: Server
- defServers :: [Server]
- type KeySpace = String
- createCassandraPool :: [Server] -> Int -> Int -> NominalDiffTime -> KeySpace -> IO CPool
- class MonadIO m => MonadCassandra m where
- getCassandraPool :: m CPool
- type Cas a = ReaderT CPool IO a
- runCas :: CPool -> Cas a -> IO a
- get :: (MonadCassandra m, FromJSON a, CasType k) => ColumnFamily -> RowKey -> Selector -> ConsistencyLevel -> m [(k, a)]
- get_ :: (MonadCassandra m, FromJSON a) => ColumnFamily -> RowKey -> Selector -> ConsistencyLevel -> m [a]
- getCol :: (MonadCassandra m, FromJSON a, CasType k) => ColumnFamily -> RowKey -> k -> ConsistencyLevel -> m (Maybe a)
- getMulti :: (MonadCassandra m, FromJSON a) => ColumnFamily -> KeySelector -> Selector -> ConsistencyLevel -> m (Map RowKey [(ColumnName, a)])
- insertCol :: (MonadCassandra m, ToJSON a, CasType k) => ColumnFamily -> RowKey -> k -> ConsistencyLevel -> a -> m ()
- modify :: (MonadCassandra m, ToJSON a, FromJSON a, CasType k) => ColumnFamily -> RowKey -> k -> ConsistencyLevel -> ConsistencyLevel -> (Maybe a -> m (ModifyOperation a, b)) -> m b
- modify_ :: (MonadCassandra m, ToJSON a, FromJSON a, CasType k) => ColumnFamily -> RowKey -> k -> ConsistencyLevel -> ConsistencyLevel -> (Maybe a -> m (ModifyOperation a)) -> m ()
- delete :: MonadCassandra m => ColumnFamily -> RowKey -> Selector -> ConsistencyLevel -> m ()
- type RowKey = ByteString
- type ColumnName = ByteString
- data ModifyOperation a
- type ColumnFamily = String
- data ConsistencyLevel
- = ONE
- | QUORUM
- | LOCAL_QUORUM
- | EACH_QUORUM
- | ALL
- | ANY
- | TWO
- | THREE
- data CassandraException
- data Selector
- range :: Selector
- data Order
- reverseOrder :: Order -> Order
- data KeySelector
- data KeyRangeType
- class CKey a where
- toColKey :: a -> ByteString
- fromColKey :: ByteString -> Either String a
- fromColKey' :: CKey a => ByteString -> a
- class CasType a where
- encodeCas :: a -> ByteString
- decodeCas :: ByteString -> a
- newtype TAscii = TAscii {}
- newtype TBytes = TBytes {}
- newtype TCounter = TCounter {}
- newtype TInt = TInt {}
- newtype TInt32 = TInt32 {}
- newtype TUtf8 = TUtf8 {}
- newtype TUUID = TUUID {}
- newtype TLong = TLong {}
- newtype Exclusive a = Exclusive a
Connection
defServers :: [Server]Source
A single localhost server with default configuration
:: [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
CassandraException
s at any point in time.
MonadIO m => MonadCassandra (ReaderT CPool m) |
Cassandra Operations
:: (MonadCassandra m, FromJSON a, CasType k) | |
=> ColumnFamily | |
-> RowKey | |
-> Selector | A slice selector |
-> ConsistencyLevel | |
-> m [(k, a)] | List of key-value pairs. See |
An arbitrary get operation - slice with Selector
.
Internally based on Basic.get. Table is assumed to be a regular ColumnFamily and contents of returned columns are cast into the target type.
:: (MonadCassandra m, FromJSON a) | |
=> ColumnFamily | |
-> RowKey | |
-> Selector | A slice selector |
-> ConsistencyLevel | |
-> m [a] |
:: (MonadCassandra m, FromJSON a, CasType k) | |
=> ColumnFamily | |
-> RowKey | |
-> k | Column name; anything in |
-> ConsistencyLevel | |
-> m (Maybe a) |
Get a single column from a single row
getMulti :: (MonadCassandra m, FromJSON a) => ColumnFamily -> KeySelector -> Selector -> ConsistencyLevel -> m (Map RowKey [(ColumnName, a)])Source
Get a slice of columns from multiple rows at once. Note that since we are auto-serializing from JSON, all the columns must be of the same data type.
:: (MonadCassandra m, ToJSON a, CasType k) | |
=> ColumnFamily | |
-> RowKey | |
-> k | Column name. See |
-> ConsistencyLevel | |
-> a | Content |
-> m () |
:: (MonadCassandra m, ToJSON a, FromJSON a, CasType k) | |
=> ColumnFamily | |
-> RowKey | |
-> k | Column name; anything in CasType |
-> ConsistencyLevel | Read quorum |
-> ConsistencyLevel | Write quorum |
-> (Maybe a -> m (ModifyOperation a, b)) | Modification function. Called with |
-> m b | Return the decided |
A modify function that will fetch a specific column, apply modification function on it and save results back to Cassandra.
A b
side value is returned for computational convenience.
This is intended to be a workhorse function, in that you should be able to do all kinds of relatively straightforward operations just using this function.
This method may throw a CassandraException
for all exceptions other than
NotFoundException
.
:: (MonadCassandra m, ToJSON a, FromJSON a, CasType k) | |
=> ColumnFamily | |
-> RowKey | |
-> k | Column name; anything in CasType |
-> ConsistencyLevel | Read quorum |
-> ConsistencyLevel | Write quorum |
-> (Maybe a -> m (ModifyOperation a)) | Modification function. Called with |
-> m () |
Same as modify
but does not offer a side value.
This method may throw a CassandraException
for all exceptions other than
NotFoundException
.
:: MonadCassandra m | |
=> ColumnFamily | In |
-> RowKey | Key to be deleted |
-> Selector | Columns to be deleted |
-> ConsistencyLevel | |
-> m () |
Necessary Types
type RowKey = ByteStringSource
type ColumnName = ByteStringSource
data ModifyOperation a Source
Possible outcomes of a modify operation
Eq a => Eq (ModifyOperation a) | |
Ord a => Ord (ModifyOperation a) | |
Read a => Read (ModifyOperation a) | |
Show a => Show (ModifyOperation a) |
type ColumnFamily = StringSource
data ConsistencyLevel
data CassandraException Source
Filtering
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.
All | Return everything in |
forall a . CasType a => ColNames [a] | Return specific columns or super-columns depending on the |
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. |
|
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
reverseOrder :: Order -> OrderSource
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.
Helpers
A typeclass to enable using any string-like type for row and column keys
toColKey :: a -> ByteStringSource
fromColKey :: ByteString -> Either String aSource
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
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")]
encodeCas :: a -> ByteStringSource
decodeCas :: ByteString -> aSource
CasType Int | |
CasType String | |
CasType ByteString | |
CasType Text | |
CasType ByteString | |
CasType Text | |
CasType TUtf8 | Encode and decode as Utf8 |
CasType TLong | Pack as an 8 byte unsigned number; negative signs are lost. |
CasType TInt | Pack as an 8 byte number - same as |
CasType TInt32 | Pack as a 4 byte number |
CasType TCounter | |
CasType TBytes | |
CasType TAscii | |
CasType a => CasType (Single a) | Use the |
(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) |
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.
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) |