Class: Familia::UnsortedSet

Inherits:
DataType show all
Includes:
DataType::CollectionBase
Defined in:
lib/familia/data_type/types/unsorted_set.rb

Overview

Familia::UnsortedSet

Instance Attribute Summary collapse

Attributes included from Settings

#current_key_version, #default_expiration, #delim, #encryption_hkdf_salt, #encryption_hkdf_salt_history, #encryption_keys, #encryption_personalization, #encryption_personalization_history, #logical_database, #prefix, #raise_on_unsaved_parent_write, #schema_path, #schema_validator, #schemas, #strict_write_order, #suffix, #transaction_mode

Instance Method Summary collapse

Methods included from DataType::CollectionBase

#collection_type?, #each_record

Methods included from Features::Autoloader

autoload_files, included, normalize_to_config_name

Methods included from DataType::Serialization

#deserialize_value, #deserialize_values, #deserialize_values_with_nil, #serialize_value, #strip_legacy_json_encoding

Methods included from DataType::DatabaseCommands

#current_expiration, #delete!, #echo, #exists?, #expire, #expireat, #persist, #rename, #renamenx, #type

Methods included from DataType::Connection

#dbclient, #dbkey, #uri

Methods included from Connection::Behavior

#connect, #create_dbclient, #multi, #normalize_uri, #pipeline, #pipelined, #transaction, #uri=, #url, #url=, #with_connection_scope

Methods included from Settings

#configure, #default_suffix, #dirty_write_warnings, #dirty_write_warnings=, #pipelined_mode, #pipelined_mode=

Methods included from Base

add_feature, #as_json, #expired?, #expires?, find_feature, #generate_id, #to_json, #to_s, #ttl, #update_expiration, #uuid

Constructor Details

This class inherits a constructor from Familia::DataType

Instance Attribute Details

#features_enabled ⇒ Object (readonly) Originally defined in module Features

Returns the value of attribute features_enabled.

#logical_database(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

#parent ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute parent.

#prefix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute prefix.

#suffix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute suffix.

#uri(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute uri.

Instance Method Details

#<<(v) ⇒ Object



39
40
41
# File 'lib/familia/data_type/types/unsorted_set.rb', line 39

def <<(v)
  add v
end

#add(*values) ⇒ Object Also known as: add_element

Note:

This method executes a Redis SADD immediately, unlike scalar field setters which are deferred until save. If the parent object has unsaved scalar field changes, consider calling save first to avoid split-brain state.



30
31
32
33
34
35
36
# File 'lib/familia/data_type/types/unsorted_set.rb', line 30

def add *values
  warn_if_dirty!
  serialized = values.flatten.compact.map { |v| serialize_value(v) }
  dbclient.sadd?(dbkey, serialized) unless serialized.empty?
  update_expiration
  self
end

#collectraw ⇒ Object



119
120
121
122
# File 'lib/familia/data_type/types/unsorted_set.rb', line 119

def collectraw(&)
  Familia.assert_replies_available!('UnsortedSet#collectraw')
  membersraw.collect(&)
end

#difference(*other_sets) ⇒ Array, Redis::Future Also known as: diff

Returns the difference of this set minus one or more other sets.

Parameters:

  • other_sets (Array<UnsortedSet, String>) —

    Other sets (as UnsortedSet instances or raw keys)

Returns:

  • (Array, Redis::Future) —

    Deserialized members present in this set but not in any other sets. Inside a transaction or pipeline, the SDIFF Future (resolves to the raw members).



174
175
176
177
# File 'lib/familia/data_type/types/unsorted_set.rb', line 174

def difference(*other_sets)
  keys = extract_keys(other_sets)
  Familia.transform_reply(dbclient.sdiff(dbkey, *keys)) { |elements| deserialize_values(*elements) }
end

#diffstore(destination, *other_sets) ⇒ Integer Also known as: difference_store

Stores the difference of this set minus other sets into a destination key.

Parameters:

  • destination (UnsortedSet, String) —

    Destination set (as UnsortedSet instance or raw key)

  • other_sets (Array<UnsortedSet, String>) —

    Other sets to subtract

Returns:

  • (Integer) —

    Number of elements in the resulting set



251
252
253
254
255
256
257
# File 'lib/familia/data_type/types/unsorted_set.rb', line 251

def diffstore(destination, *other_sets)
  dest_key = extract_key(destination)
  keys = extract_keys(other_sets)
  result = dbclient.sdiffstore(dest_key, dbkey, *keys)
  update_expiration
  result
end

#each(matching: nil, batch_size: 100) {|member| ... } ⇒ Enumerator, self

Note:

Pattern matches raw Redis storage (JSON-encoded). To filter on deserialized values, use Enumerable#select instead.

Iterates over members of the set.

Uses SSCAN for memory-efficient iteration. Optionally filters by member pattern using Redis MATCH.

Examples:

Iterate all members

tags.each { |tag| puts tag }

Filter by pattern (matches JSON-encoded storage)

tags.each(matching: "*category*") { |tag| process(tag) }

Parameters:

  • matching (String, nil) (defaults to: nil) —

    Optional glob-style pattern to filter members (e.g., "user:", "_active"). Pattern is passed to Redis SSCAN MATCH and matches against raw storage format (JSON-encoded strings). For a string "admin", match with "\"admin\"" or use "*admin*" for substring match.

  • batch_size (Integer) (defaults to: 100) —

    Number of elements to fetch per SSCAN iteration

Yields:

  • (member) —

    Each deserialized member (optionally filtered)

Returns:

  • (Enumerator, self) —

    Returns Enumerator if no block given, self otherwise



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
# File 'lib/familia/data_type/types/unsorted_set.rb', line 91

def each(matching: nil, batch_size: 100, &block)
  return to_enum(:each, matching: matching, batch_size: batch_size) unless block

  Familia.assert_replies_available!('UnsortedSet#each')

  cursor = 0
  loop do
    new_cursor, elements = scan(cursor, match: matching, count: batch_size)
    elements.each(&block)
    cursor = new_cursor
    break if cursor.zero?
  end

  self
end

#eachraw ⇒ Object

The raw iterators need the SMEMBERS reply to iterate over, so they raise Familia::OperationModeError inside a transaction or pipeline.



109
110
111
112
# File 'lib/familia/data_type/types/unsorted_set.rb', line 109

def eachraw(&)
  Familia.assert_replies_available!('UnsortedSet#eachraw')
  membersraw.each(&)
end

#eachraw_with_index ⇒ Object



114
115
116
117
# File 'lib/familia/data_type/types/unsorted_set.rb', line 114

def eachraw_with_index(&)
  Familia.assert_replies_available!('UnsortedSet#eachraw_with_index')
  membersraw.each_with_index(&)
end

#element_count ⇒ Integer Also known as: size, length, count

Returns the number of elements in the unsorted set

Returns:

  • (Integer) —

    number of elements



13
14
15
# File 'lib/familia/data_type/types/unsorted_set.rb', line 13

def element_count
  dbclient.scard dbkey
end

#empty? ⇒ Boolean, Redis::Future

Returns whether the set has no members. Inside a transaction or pipeline, the SCARD Future (resolves to the count).

Returns:

  • (Boolean, Redis::Future) —

    whether the set has no members. Inside a transaction or pipeline, the SCARD Future (resolves to the count).



23
24
25
# File 'lib/familia/data_type/types/unsorted_set.rb', line 23

def empty?
  Familia.transform_reply(element_count, &:zero?)
end

#intercard(*other_sets, limit: 0) ⇒ Integer Also known as: intersection_cardinality

Returns the cardinality of the intersection without retrieving members. More memory-efficient than intersection when only the count is needed.

Parameters:

  • other_sets (Array<UnsortedSet, String>) —

    Other sets (as UnsortedSet instances or raw keys)

  • limit (Integer) (defaults to: 0) —

    Stop counting after reaching this limit (0 = no limit)

Returns:

  • (Integer) —

    Number of elements in the intersection



212
213
214
215
216
217
218
# File 'lib/familia/data_type/types/unsorted_set.rb', line 212

def intercard(*other_sets, limit: 0)
  keys = extract_keys(other_sets)
  all_keys = [dbkey, *keys]
  args = [:sintercard, all_keys.size, *all_keys]
  args.push('LIMIT', limit) if limit.positive?
  dbclient.call(*args)
end

#intersection(*other_sets) ⇒ Array, Redis::Future Also known as: inter

Returns the intersection of this set with one or more other sets.

Parameters:

  • other_sets (Array<UnsortedSet, String>) —

    Other sets (as UnsortedSet instances or raw keys)

Returns:

  • (Array, Redis::Future) —

    Deserialized members present in all sets. Inside a transaction or pipeline, the SINTER Future (resolves to the raw members).



153
154
155
156
# File 'lib/familia/data_type/types/unsorted_set.rb', line 153

def intersection(*other_sets)
  keys = extract_keys(other_sets)
  Familia.transform_reply(dbclient.sinter(dbkey, *keys)) { |elements| deserialize_values(*elements) }
end

#interstore(destination, *other_sets) ⇒ Integer Also known as: intersection_store

Stores the intersection of this set with other sets into a destination key.

Parameters:

  • destination (UnsortedSet, String) —

    Destination set (as UnsortedSet instance or raw key)

  • other_sets (Array<UnsortedSet, String>) —

    Other sets to intersect with

Returns:

  • (Integer) —

    Number of elements in the resulting set



225
226
227
228
229
230
231
# File 'lib/familia/data_type/types/unsorted_set.rb', line 225

def interstore(destination, *other_sets)
  dest_key = extract_key(destination)
  keys = extract_keys(other_sets)
  result = dbclient.sinterstore(dest_key, dbkey, *keys)
  update_expiration
  result
end

#member?(val) ⇒ Boolean, Redis::Future Also known as: include?

Returns whether +val+ is a member. Inside a transaction or pipeline, the SISMEMBER Future (resolves to true or false; the Future itself is always truthy).

Returns:

  • (Boolean, Redis::Future) —

    whether +val+ is a member. Inside a transaction or pipeline, the SISMEMBER Future (resolves to true or false; the Future itself is always truthy).



132
133
134
# File 'lib/familia/data_type/types/unsorted_set.rb', line 132

def member?(val)
  dbclient.sismember dbkey, serialize_value(val)
end

#member_any?(*values) ⇒ Array<Boolean> Also known as: members?

Checks membership for multiple values at once.

Parameters:

  • values (Array) —

    Values to check for membership

Returns:

  • (Array<Boolean>) —

    Array of booleans indicating membership for each value



183
184
185
186
187
# File 'lib/familia/data_type/types/unsorted_set.rb', line 183

def member_any?(*values)
  values = values.flatten
  serialized = values.map { |v| serialize_value(v) }
  dbclient.smismember(dbkey, serialized)
end

#members ⇒ Array, Redis::Future Also known as: all

Returns Deserialized members. Inside a transaction or pipeline, the SMEMBERS Future (resolves to the raw members).

Returns:

  • (Array, Redis::Future) —

    Deserialized members. Inside a transaction or pipeline, the SMEMBERS Future (resolves to the raw members).



46
47
48
49
# File 'lib/familia/data_type/types/unsorted_set.rb', line 46

def members
  echo :members, Familia.pretty_stack(limit: 1) if Familia.debug
  Familia.transform_reply(membersraw) { |elements| deserialize_values(*elements) }
end

#membersraw ⇒ Object



65
66
67
# File 'lib/familia/data_type/types/unsorted_set.rb', line 65

def membersraw
  dbclient.smembers(dbkey)
end

#move(dstkey, val) ⇒ Object



267
268
269
270
271
272
# File 'lib/familia/data_type/types/unsorted_set.rb', line 267

def move(dstkey, val)
  warn_if_dirty!
  ret = dbclient.smove dbkey, dstkey, serialize_value(val)
  update_expiration
  ret
end

#pop ⇒ Object



260
261
262
263
264
265
# File 'lib/familia/data_type/types/unsorted_set.rb', line 260

def pop
  warn_if_dirty!
  ret = deserialize_value(dbclient.spop(dbkey))
  update_expiration
  ret
end

#remove_element(value) ⇒ Integer Also known as: remove

Removes a member from the set

Parameters:

  • value —

    The value to remove from the set

Returns:

  • (Integer) —

    The number of members that were removed (0 or 1)



140
141
142
143
144
145
# File 'lib/familia/data_type/types/unsorted_set.rb', line 140

def remove_element(value)
  warn_if_dirty!
  ret = dbclient.srem dbkey, serialize_value(value)
  update_expiration
  ret
end

#sample(count = 1) ⇒ Array, Redis::Future Also known as: random

Get one or more random members from the set

Parameters:

  • count (Integer) (defaults to: 1) —

    Number of random members to return (default: 1)

Returns:

  • (Array, Redis::Future) —

    Array of deserialized random members. Inside a transaction or pipeline, the SRANDMEMBER Future (resolves to the raw members).



279
280
281
# File 'lib/familia/data_type/types/unsorted_set.rb', line 279

def sample(count = 1)
  Familia.transform_reply(sampleraw(count)) { |elements| deserialize_values(*elements) }
end

#sampleraw(count = 1) ⇒ Array Also known as: randomraw

Get one or more random members from the set without deserialization

Parameters:

  • count (Integer) (defaults to: 1) —

    Number of random members to return (default: 1)

Returns:

  • (Array) —

    Array of raw random members



287
288
289
# File 'lib/familia/data_type/types/unsorted_set.rb', line 287

def sampleraw(count = 1)
  dbclient.srandmember(dbkey, count) || []
end

#scan(cursor = 0, match: nil, count: nil) ⇒ Array<Integer, Array>, Redis::Future

Iterates over set members using cursor-based iteration.

Parameters:

  • cursor (Integer) (defaults to: 0) —

    Starting cursor position (default: 0)

  • match (String, nil) (defaults to: nil) —

    Optional pattern to filter members

  • count (Integer, nil) (defaults to: nil) —

    Optional hint for number of elements to return per call

Returns:

  • (Array<Integer, Array>, Redis::Future) —

    Two-element array: [new_cursor, deserialized_members]. Inside a transaction or pipeline, the SSCAN Future (resolves to the raw cursor and members).



197
198
199
200
201
202
203
204
205
# File 'lib/familia/data_type/types/unsorted_set.rb', line 197

def scan(cursor = 0, match: nil, count: nil)
  opts = {}
  opts[:match] = match if match
  opts[:count] = count if count

  Familia.transform_reply(dbclient.sscan(dbkey, cursor, **opts)) do |(new_cursor, elements)|
    [new_cursor.to_i, deserialize_values(*elements)]
  end
end

#selectraw ⇒ Object



124
125
126
127
# File 'lib/familia/data_type/types/unsorted_set.rb', line 124

def selectraw(&)
  Familia.assert_replies_available!('UnsortedSet#selectraw')
  membersraw.select(&)
end

#to_a ⇒ Array

Ruby's conversion to an Array, used by splat and Array(). A conversion method must return its type, so inside a block to_a refuses instead of returning a Redis::Future; #members passes the Future through.

Returns:

  • (Array) —

    the deserialized members

Raises:



59
60
61
62
63
# File 'lib/familia/data_type/types/unsorted_set.rb', line 59

def to_a
  Familia.assert_replies_available!('UnsortedSet#to_a')

  members
end

#union(*other_sets) ⇒ Array, Redis::Future

Returns the union of this set with one or more other sets.

Parameters:

  • other_sets (Array<UnsortedSet, String>) —

    Other sets (as UnsortedSet instances or raw keys)

Returns:

  • (Array, Redis::Future) —

    Deserialized members present in any of the sets. Inside a transaction or pipeline, the SUNION Future (resolves to the raw members).



164
165
166
167
# File 'lib/familia/data_type/types/unsorted_set.rb', line 164

def union(*other_sets)
  keys = extract_keys(other_sets)
  Familia.transform_reply(dbclient.sunion(dbkey, *keys)) { |elements| deserialize_values(*elements) }
end

#unionstore(destination, *other_sets) ⇒ Integer Also known as: union_store

Stores the union of this set with other sets into a destination key.

Parameters:

  • destination (UnsortedSet, String) —

    Destination set (as UnsortedSet instance or raw key)

  • other_sets (Array<UnsortedSet, String>) —

    Other sets to union with

Returns:

  • (Integer) —

    Number of elements in the resulting set



238
239
240
241
242
243
244
# File 'lib/familia/data_type/types/unsorted_set.rb', line 238

def unionstore(destination, *other_sets)
  dest_key = extract_key(destination)
  keys = extract_keys(other_sets)
  result = dbclient.sunionstore(dest_key, dbkey, *keys)
  update_expiration
  result
end