redis 0.5 · OCaml Package

Redis cluster client

Parameters

module IO : S.IO

Signature

module IO = IO

module StringBound : sig ... end

module FloatBound : sig ... end

Types and exceptions

type redirection = {

slot : int;
host : string;
port : int;

}

type reply = [

| `Status of string
| `Error of string
| `Int of int
| `Int64 of Stdlib.Int64.t
| `Bulk of string option
| `Multibulk of reply list
| `Ask of redirection
| `Moved of redirection

]

val string_of_reply : reply -> string

For debugging purpose

type connection_spec = {

host : string;
port : int;

}

Server connection info

val connection_spec : ?port:int -> string -> connection_spec

Create a connection spec with the given host.

parameter port
port to connect to (default 6379)

since 0.5

module SlotMap : Stdlib.Map.S with type key = int

module ConnectionSpecMap : Stdlib.Map.S with type key = connection_spec

type cluster_connections = private {

mutable connections_spec : connection_spec SlotMap.t;
mutable connections : connection ConnectionSpecMap.t;

}

and connection = private {

fd : IO.fd;
in_ch : IO.in_channel;
out_ch : IO.out_channel;
stream : reply list IO.stream;
cluster : cluster_connections;

}

exception Redis_error of string

Error responses from server

exception Unexpected of reply

Protocol errors

exception Unrecognized of string * string

type bit_operation =

| AND
| OR
| XOR
| NOT

Possible BITOP operations

Connection handling

val connect : connection_spec -> connection IO.t

val disconnect : connection -> unit IO.t

val with_connection : connection_spec -> (connection -> 'a IO.t) -> 'a IO.t

val stream : connection -> reply list IO.stream

Connection commands

val auth : connection -> string -> unit IO.t

Authenticate to server.

val auth_acl : connection -> string -> string -> unit IO.t

Authenticate to server with username and password.

val echo : connection -> string -> string option IO.t

Echo given string.

val ping : connection -> bool IO.t

Ping connection; returns true if ping was successfull.

val quit : connection -> unit IO.t

Close connection.

val select : connection -> int -> unit IO.t

Switch to a different db; raises Error if index is invalid.

val sentinel_masters : connection -> (string * string) list list IO.t

SENTINEL commands

val sentinel_get_master_addr_by_name : 
  connection ->
  string ->
  (string * string) option IO.t

Keys commands

val del : connection -> string list -> int IO.t

Delete a key; returns the number of keys removed.

val exists : connection -> string -> bool IO.t

Determine if a key exists.

val expire : connection -> string -> int -> bool IO.t

Set a key's time to live in seconds; returns true if timeout was set, false otherwise.

val pexpire : connection -> string -> int -> bool IO.t

Set a key's time to live in milliseconds; returns true if timeout was set, false otherwise.

val expireat : connection -> string -> float -> bool IO.t

Set the expiration for a key as a UNIX timestamp, the time is truncated to the nearest second; returns true if timeout was set, false otherwise.

val pexpireat : connection -> string -> int -> bool IO.t

Set the expiration for a key as a UNIX timestamp in milliseconds; returns true if timeout was set, false otherwise.

val keys : connection -> string -> string list IO.t

Find all keys matching the given pattern.

val scan : 
  ?pattern:string ->
  ?count:int ->
  connection ->
  int ->
  (int * string list) IO.t

Incrementally iterate the keys space; see tests for usage example.

val move : connection -> string -> int -> bool IO.t

Move key to a different db; returns true if key was moved, false otherwise.

val persist : connection -> string -> bool IO.t

Remove timeout on key; returns true if timeout was removed, false otherwise.

val randomkey : connection -> string option IO.t

Return a random key from the keyspace; returns None if db is empty.

val rename : connection -> string -> string -> unit IO.t

Rename a key; raises Error if key doesn't exist.

val renamenx : connection -> string -> string -> bool IO.t

Rename a key, only if the new key does not exist; returns true if key was renamed, false if newkey already exists.

val sort : 
  connection ->
  ?by:string ->
  ?limit:(int * int) ->
  ?get:'a list ->
  ?order:[< `Asc | `Desc ] ->
  ?alpha:bool ->
  string ->
  string list IO.t

Sort elements in a list, set or sorted set; return sorted list of items.

val sort_and_store : 
  connection ->
  ?by:string ->
  ?limit:(int * int) ->
  ?get:'a list ->
  ?order:[< `Asc | `Desc ] ->
  ?alpha:bool ->
  string ->
  string ->
  int IO.t

Sort and store elements in a list, set or sorted set; returns length of sorted items list which was stored.

val ttl : connection -> string -> int option IO.t

Time to live for a key in seconds; returns None if key doesn't exist or doesn't have a timeout.

val pttl : connection -> string -> int option IO.t

Time to live for a key in milliseconds; returns None if key doesn't exist or doesn't have a timeout.

val type_of : 
  connection ->
  string ->
  [> `Hash | `List | `None | `String | `Zset ] IO.t

Determine the type stored as key.

val dump : connection -> string -> string option IO.t

Return a serialized version of the value stored at the specified key; returns None if key doesn't exist.

val restore : connection -> string -> int -> string -> unit IO.t

Create a key with serialized value (obtained via DUMP).

val migrate : 
  connection ->
  ?copy:bool ->
  ?replace:bool ->
  string ->
  int ->
  string ->
  int ->
  int ->
  unit IO.t

Atomically transfer a key from a source Redis instance to a destination Redis instance.

val object_refcount : connection -> string -> int option IO.t

Inspect the internals of Redis objects; returns the number of references of the value associated with the specified key.

val object_encoding : connection -> string -> string option IO.t

Inspect the internals of Redis objects; returns the kind of internal representation used in order to store the value associated with a key.

val object_idletime : connection -> string -> int option IO.t

Inspect the internals of Redis objects; returns the number of seconds since the object stored at the specified key is idle.

String commands

val append : connection -> string -> string -> int IO.t

Append a value to a key; returns length of string after append.

val setbit : connection -> string -> int -> int -> int IO.t

Sets or clears the bit at offset in the string value stored at key.

val getbit : connection -> string -> int -> int IO.t

Returns the bit value at offset in the string value stored at key.

val bitop : connection -> bit_operation -> string -> string list -> int IO.t

Perform a bitwise operation between multiple keys (containing string values) and store the result in the destination key. See bit_operation type for available operations.

val bitcount : ?first:int -> ?last:int -> connection -> string -> int IO.t

Count the number of set bits (population counting) in a string.

val bitpos : ?first:int -> ?last:int -> connection -> string -> int -> int IO.t

Return the position of the first bit set to 1 or 0 in a string.

val decr : connection -> string -> int IO.t

Decrements the number stored at key by one. If the key does not exist, it is set to 0 before performing the operation.

val decrby : connection -> string -> int -> int IO.t

Decrements the number stored at key by decrement. If the key does not exist, it is set to 0 before performing the operation.

val get : connection -> string -> string option IO.t

Get the value of key.

val getrange : connection -> string -> int -> int -> string option IO.t

Returns the substring of the string value stored at key, determined by the offsets start and end (both are inclusive).

val getset : connection -> string -> string -> string option IO.t

Atomically sets key to value and returns the old value stored at key. Returns None when key exists but does not hold a string value.

val incr : connection -> string -> int IO.t

Increments the number stored at key by one. If the key does not exist, it is set to 0 before performing the operation.

val incrby : connection -> string -> int -> int IO.t

Increments the number stored at key by increment. If the key does not exist, it is set to 0 before performing the operation.

val incrbyfloat : connection -> string -> float -> float IO.t

Increment the string representing a floating point number stored at key by the specified increment. If the key does not exist, it is set to 0 before performing the operation.

val mget : connection -> string list -> string option list IO.t

Returns the values of all specified keys.

val mset : connection -> (string * string) list -> unit IO.t

Sets the given keys to their respective values.

val msetnx : connection -> (string * string) list -> bool IO.t

Sets the given keys to their respective values. MSETNX will not perform any operation at all even if just a single key already exists.

val set : 
  connection ->
  ?ex:int ->
  ?px:int ->
  ?nx:bool ->
  ?xx:bool ->
  string ->
  string ->
  bool IO.t

Set key to hold the string value.

val setex : connection -> string -> int -> string -> unit IO.t

Set key to hold the string value and set key to timeout after a given number of seconds.

val psetex : connection -> string -> int -> string -> unit IO.t

PSETEX works exactly like SETEX with the sole difference that the expire time is specified in milliseconds instead of seconds.

val setnx : connection -> string -> string -> bool IO.t

Set key to hold string value if key does not exist.

val setrange : connection -> string -> int -> string -> int IO.t

Overwrites part of the string stored at key, starting at the specified offset, for the entire length of value.

val strlen : connection -> string -> int IO.t

Returns the length of the string value stored at key. An error is returned when key holds a non-string value.

Hash commands

val hdel : connection -> string -> string -> bool IO.t

Removes the specified fields from the hash stored at key. Specified fields that do not exist within this hash are ignored.

val hexists : connection -> string -> string -> bool IO.t

Returns if field is an existing field in the hash stored at key.

val hget : connection -> string -> string -> string option IO.t

Returns the value associated with field in the hash stored at key.

val hgetall : connection -> string -> (string * string) list IO.t

Returns all fields and values of the hash stored at key.

val hincrby : connection -> string -> string -> int -> int IO.t

Increments the number stored at field in the hash stored at key by increment.

val hincrbyfloat : connection -> string -> string -> float -> float IO.t

Increments the number stored at field in the hash stored at key by increment.

val hkeys : connection -> string -> string list IO.t

Returns all field names in the hash stored at key.

val hlen : connection -> string -> int IO.t

Returns the number of fields contained in the hash stored at key.

val hmget : connection -> string -> string list -> string option list IO.t

Returns the values associated with the specified fields in the hash stored at key.

val hmset : connection -> string -> (string * string) list -> unit IO.t

Sets the specified fields to their respective values in the hash stored at key.

val hset : connection -> string -> string -> string -> bool IO.t

Sets field in the hash stored at key to value.

val hsetnx : connection -> string -> string -> string -> bool IO.t

Sets field in the hash stored at key to value, only if field does not yet exist.

val hstrlen : connection -> string -> string -> int IO.t

Get the length of the value of a hash field

val hscan : 
  ?pattern:string ->
  ?count:int ->
  connection ->
  string ->
  int ->
  (int * (string * string) list) IO.t

Incrementally iterate hash fields and associated values

val hvals : connection -> string -> string list IO.t

Returns all values in the hash stored at key.

List commands

val blpop : connection -> string list -> int -> (string * string) option IO.t

Remove and get the first element in a list, or block until one is available

val brpop : connection -> string list -> int -> (string * string) option IO.t

Remove and get the last element in a list, or block until one is available

val brpoplpush : connection -> string -> string -> int -> string option IO.t

Pop a value from a list, push it to another list and return it; or block until one is available

val lindex : connection -> string -> int -> string option IO.t

Get an element from a list by its index

val linsert : 
  connection ->
  string ->
  [< `After | `Before ] ->
  string ->
  string ->
  int option IO.t

Insert an element before or after another element in a list

val llen : connection -> string -> int IO.t

Get the length of a list

val lpop : connection -> string -> string option IO.t

Remove and get the first element in a list

val lpush : connection -> string -> string list -> int IO.t

Prepend one or multiple values to a list

val lpushx : connection -> string -> string list -> int IO.t

Prepend a value to a list, only if the list exists

val lrange : connection -> string -> int -> int -> string list IO.t

Get a range of elements from a list

val lrem : connection -> string -> int -> string -> int IO.t

Remove elements from a list

val lset : connection -> string -> int -> string -> unit IO.t

Set the value of an element in a list by its index

val ltrim : connection -> string -> int -> int -> unit IO.t

Trim a list to the specified range

val rpop : connection -> string -> string option IO.t

Remove and get the last element in a list

val rpoplpush : connection -> string -> string -> string option IO.t

Remove the last element in a list, prepend it to another list and return it

val rpush : connection -> string -> string list -> int IO.t

Append one or multiple values to a list

val rpushx : connection -> string -> string list -> int IO.t

Append a value to a list, only if the list exists

HyperLogLog commands

val pfadd : connection -> string -> string list -> bool IO.t

Adds values to the HyperLogLog data structure.

val pfcount : connection -> string list -> int IO.t

Returns the approximated cardinality of the union of the HyperLogLogs passed.

val pfmerge : connection -> string list -> unit IO.t

Merge multiple HyperLogLog values into an unique value that will approximate the cardinality of the union of the observed Sets of the source HyperLogLog structures.

Set commands

val sadd : connection -> string -> string -> bool IO.t

Returns true if member was added, false otherwise.

val scard : connection -> string -> int IO.t

val sdiff : connection -> string list -> string list IO.t

Difference between first and all successive sets.

val sdiffstore : connection -> string -> string list -> int IO.t

like sdiff, but store result in destination. returns size of result.

val sinter : connection -> string list -> string list IO.t

val sinterstore : connection -> string -> string list -> int IO.t

Like SINTER, but store result in destination. Returns size of result.

val sismember : connection -> string -> string -> bool IO.t

val smembers : connection -> string -> string list IO.t

val smove : connection -> string -> string -> string -> bool IO.t

Returns true if an element was moved, false otherwise.

val spop : connection -> string -> string option IO.t

Remove random element from set.

val srandmember : connection -> string -> string option IO.t

Like SPOP, but doesn't remove chosen element.

val srem : connection -> string -> string -> bool IO.t

Returns true if element was removed.

val sunion : connection -> string list -> string list IO.t

val sunionstore : connection -> string -> string list -> int IO.t

Like SUNION, but store result in destination. Returns size of result.

Pub/sub commands

val publish : connection -> string -> string -> int IO.t

Post a message to a channel. Returns number of clients that received the message.

val pubsub_channels : connection -> string option -> reply list IO.t

Lists the currently active channels. If no pattern is specified, all channels are listed.

val pubsub_numsub : connection -> string list -> reply list IO.t

Returns the number of subscribers (not counting clients subscribed to patterns) for the specified channels.

val subscribe : connection -> string list -> unit IO.t

Subscribes the client to the specified channels.

val unsubscribe : connection -> string list -> unit IO.t

Unsubscribes the client from the given channels, or from all of them if an empty list is given

val psubscribe : connection -> string list -> unit IO.t

Subscribes the client to the given patterns.

val punsubscribe : connection -> string list -> unit IO.t

Unsubscribes the client from the given patterns.

Sorted set commands

val zadd : 
  connection ->
  ?x:[< `NX | `XX ] ->
  ?ch:bool ->
  string ->
  (float * string) list ->
  int IO.t

Add one or more members to a sorted set, or update its score if it already exists.

val zrange : 
  connection ->
  ?withscores:bool ->
  string ->
  int ->
  int ->
  reply list IO.t

Return a range of members in a sorted set, by index.

val zrevrange : 
  connection ->
  ?withscores:bool ->
  string ->
  int ->
  int ->
  reply list IO.t

Return a reversed range of members in a sorted set, by index.

val zrangebyscore : 
  connection ->
  ?withscores:bool ->
  ?limit:(int * int) ->
  string ->
  FloatBound.t ->
  FloatBound.t ->
  reply list IO.t

Return a range of members in a sorted set, by score.

val zrangebylex : 
  connection ->
  ?limit:(int * int) ->
  string ->
  StringBound.t ->
  StringBound.t ->
  reply list IO.t

Return a range of members in a sorted set, by lexicographical range.

val zrevrangebyscore : 
  connection ->
  ?withscores:bool ->
  ?limit:(int * int) ->
  string ->
  FloatBound.t ->
  FloatBound.t ->
  reply list IO.t

Return a range of members in a sorted set, by score.

val zrevrangebylex : 
  connection ->
  ?limit:(int * int) ->
  string ->
  StringBound.t ->
  StringBound.t ->
  reply list IO.t

Return a range of members in a sorted set, by lexicographical range.

val zrem : connection -> string -> string list -> int IO.t

Remove one or more members from a sorted set.

val zremrangebylex : 
  connection ->
  string ->
  StringBound.t ->
  StringBound.t ->
  int IO.t

Remove all members in a sorted set between the given lexicographical range.

val zremrangebyscore : 
  connection ->
  string ->
  FloatBound.t ->
  FloatBound.t ->
  int IO.t

Remove all members in a sorted set between the given score range.

val zremrangebyrank : connection -> string -> int -> int -> int IO.t

Remove all members in a sorted set between the given rank range.

val zcard : connection -> string -> int IO.t

Returns the sorted set cardinality (number of elements) of the sorted set stored at key.

val zincrby : connection -> string -> float -> string -> float IO.t

Increment the score of a member in the sorted set

val zscore : connection -> string -> string -> float option IO.t

Returns the score of a member in the sorted set.

val zcount : connection -> string -> FloatBound.t -> FloatBound.t -> int IO.t

Returns the number of elements in the sorted set at key with a score between min and max.

val zlexcount : 
  connection ->
  string ->
  StringBound.t ->
  StringBound.t ->
  int IO.t

Returns the number of members in a sorted set between a given lexicographical range.

val zrank : connection -> string -> string -> int option IO.t

Returns the rank of member in the sorted set stored at key.

val zrevrank : connection -> string -> string -> int option IO.t

Returns the reversed rank of member in the sorted set stored at key.

Stream commands

For redis >= 5. We only support a subset of the commands for now.

val xadd : 
  connection ->
  string ->
  ?maxlen:[ `Exact of int | `Approximate of int ] ->
  ?id:string ->
  (string * string) list ->
  string IO.t

Add a stream event, as a list of key-value pairs, to the given stream.

returns
the ID of the new event

parameter maxlen
can be used to trim the stream.

parameter id
specify a custom ID. Most of the of time you don't want to set this.
@see the official doc

since 0.5

val xdel : connection -> string -> string list -> int IO.t

Delete specific stream events. Should be rarely useful.

returns
the number of deleted events.
@see the official doc

since 0.5

val xlen : connection -> string -> int IO.t

Length of a stream. @see https://redis.io/commands/xlen .

since 0.5

val xtrim : 
  connection ->
  string ->
  maxlen:[ `Exact of int | `Approximate of int ] ->
  unit ->
  int IO.t

Trim stream to the given maximum length.

parameter maxlen
the maximum number of entries to preserve, prioritizing the most recent ones. `Approximate n is faster, and should be preferred.

returns
number of deleted entries
@see the official doc

since 0.5

type stream_event = string * (string * string) list

A stream event as returned by Redis. It is composed of a stream ID (timestamp + counter), and a list of key/value pairs.

since 0.5

val xrange : 
  connection ->
  string ->
  start:StringBound.t ->
  end_:StringBound.t ->
  ?count:int ->
  unit ->
  stream_event list IO.t

xrange connection stream ~start ~end_ () returns a range of events in the stream.

parameter start
beginning of the range. It can be one of:
- StringBound.NegInfinity ("-" in the doc) to indicate the earliest possible time
- StringBound.Inclusive "timestamp" or StringBound.Inclusive "timestamp-number" for a left-inclusive bound
- StringBound.Exclusive "timestamp" or StringBound.Exclusive "timestamp-number" for a left-exclusive bound ("(" in the doc) only since Redis 6.2

parameter end_
same as start but for the right bound

parameter count
maximum number of events returned

returns
a lits of events (at most count if specified). Each event is a pair (id, pairs) where id is the unique ID of the event, of the form "<timestamp>-<counter>", and pairs is a list of key-value pairs associated with the event.
@see the official doc

since 0.5

val xrevrange : 
  connection ->
  string ->
  start:StringBound.t ->
  end_:StringBound.t ->
  ?count:int ->
  unit ->
  stream_event list IO.t

Like xrange but in reverse order. @see the official doc

since 0.5

val xread : 
  connection ->
  ?count:int ->
  ?block_ms:int ->
  (string * [ `Last | `After of string ]) list ->
  (string * stream_event list) list IO.t

xread connection pairs reads data from the multiple streams specified in pairs.

Each item of pairs is a pair ("stream-name", <after>) where <after> is either:

`Last ("$" in the doc) to get events coming after the last current event (so, new events);
or `After i to get events coming after the given ID i, excluding i itself.

returns
a list of ("stream-name", <events>). Each pair contains the name of a stream (that was among the input pairs), along with events of that stream coming after the corresponding position.

parameter count
max number of events returned per stream

parameter block_ms
if provided, xread blocks at most block_ms milliseconds for new events. Otherwise xread is synchronous and returns immediately.
@see the official doc

since 0.5

Transaction commands

val multi : connection -> unit IO.t

Marks the start of a transaction block. Subsequent commands will be queued for atomic execution using EXEC.

val exec : connection -> reply list IO.t

Executes all previously queued commands in a transaction and restores the connection state to normal.

val discard : connection -> unit IO.t

Flushes all previously queued commands in a transaction and restores the connection state to normal.

val watch : connection -> string list -> unit IO.t

Marks the given keys to be watched for conditional execution of a transaction.

val unwatch : connection -> unit IO.t

Flushes all the previously watched keys for a transaction.

val queue : (unit -> 'a IO.t) -> unit IO.t

Scripting commands

val script_load : connection -> string -> string IO.t

Load the specified Lua script into the script cache. Returns the SHA1 digest of the script for use with EVALSHA.

val eval : connection -> string -> string list -> string list -> reply IO.t

Evaluates a script using the built-in Lua interpreter.

val evalsha : connection -> string -> string list -> string list -> reply IO.t

Evaluates a script cached on the server side by its SHA1 digest.

Server

val bgrewriteaof : connection -> unit IO.t

val bgsave : connection -> unit IO.t

val config_resetstat : connection -> unit IO.t

val dbsize : connection -> int IO.t

val flushall : connection -> unit IO.t

clear all databases

val flushdb : connection -> unit IO.t

clear current database

val info : connection -> (string * string) list IO.t

val lastsave : connection -> float IO.t

last successful save as Unix timestamp

val role : connection -> reply list IO.t

role in context of replication

val save : connection -> unit IO.t

synchronous save

val shutdown : connection -> unit IO.t

save and shutdown server

module MassInsert : sig ... end

Batch commands for mass insertion

package redis