Module: Dynamoid::Indexes::ClassMethods

Defined in:
lib/dynamoid/indexes.rb

Instance Method Summary collapse

Instance Method Details

#find_index(hash, range = nil) ⇒ Dynamoid::Indexes::Index?

Returns an index by its hash key and optional range key.

It works only for indexes without explicit name declared.

Parameters:

  • hash (scalar) —

    the hash key used to declare an index

  • range (scalar) (defaults to: nil) —

    the range key used to declare an index (optional)

Returns:



161
162
163
 
# File 'lib/dynamoid/indexes.rb', line 161

def find_index(hash, range = nil)
  indexes[index_key(hash, range)]
end

#find_index_by_name(name) ⇒ Dynamoid::Indexes::Index?

Returns an index by its name

Parameters:

  • name (string, symbol) —

    the name of the index to lookup

Returns:



169
170
171
172
 
# File 'lib/dynamoid/indexes.rb', line 169

def find_index_by_name(name)
  string_name = name.to_s
  indexes.each_value.detect { |i| i.name.to_s == string_name }
end

#global_secondary_index(options = {}) ⇒ Object

Defines a Global Secondary index on a table. Keys can be specified as hash-only, or hash & range.

class Post
  include Dynamoid::Document

  field :category

  global_secondary_index hash_key: :category
end

The full example with all the options being specified:

global_secondary_index hash_key: :category,
                       range_key: :created_at,
                       name: 'posts_category_created_at_index',
                       projected_attributes: :all,
                       read_capacity: 100,
                       write_capacity: 20

Global secondary index should be declared after fields for mentioned hash key and optional range key are declared (with method field)

The only mandatory option is hash_key. Raises Dynamoid::Errors::InvalidIndex exception if passed incorrect options.

Parameters:

  • options (Hash) (defaults to: {}) —

    the options to pass for this table

Options Hash (options):

  • name (Symbol) —

    the name for the index; this still gets namespaced. If not specified, will use a default name.

  • hash_key (Symbol) —

    the index hash key column.

  • range_key (Symbol) —

    the index range key column (if applicable).

  • projected_attributes (Symbol, Array<Symbol>) —

    table attributes to project for this index. Can be :keys_only, :all or an array of included fields. If not specified, defaults to :keys_only.

  • read_capacity (Integer) —

    set the read capacity for the index; does not work on existing indexes.

  • write_capacity (Integer) —

    set the write capacity for the index; does not work on existing indexes.



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/dynamoid/indexes.rb', line 65

def global_secondary_index(options = {})
  unless options.present?
    raise Dynamoid::Errors::InvalidIndex, 'empty index definition'
  end

  unless options[:hash_key].present?
    raise Dynamoid::Errors::InvalidIndex, 'A global secondary index requires a :hash_key to be specified'
  end

  index_opts = {
    read_capacity: Dynamoid::Config.read_capacity,
    write_capacity: Dynamoid::Config.write_capacity
  }.merge(options)

  index_opts[:dynamoid_class] = self
  index_opts[:type] = :global_secondary

  index = Dynamoid::Indexes::Index.new(index_opts)
  gsi_key = index_key(options[:hash_key], options[:range_key])
  global_secondary_indexes[gsi_key] = index
  self
end

#index_key(hash, range = nil) ⇒ String

Generates a convenient lookup key name for a hash/range index. Should normally not be used directly.

Parameters:

  • hash (Symbol) —

    hash key name.

  • range (Symbol) (defaults to: nil) —

    range key name.

Returns:

  • (String) —

    returns “hash” if hash only, “hash_range” otherwise.



202
203
204
205
206
 
# File 'lib/dynamoid/indexes.rb', line 202

def index_key(hash, range = nil)
  name = hash.to_s
  name += "_#{range}" if range.present?
  name
end

#index_name(hash, range = nil) ⇒ String

Generates a default index name.

Parameters:

  • hash (Symbol) —

    hash key name.

  • range (Symbol) (defaults to: nil) —

    range key name.

Returns:

  • (String) —

    index name of the form “table_name_index_index_key”.



213
214
215
 
# File 'lib/dynamoid/indexes.rb', line 213

def index_name(hash, range = nil)
  "#{table_name}_index_#{index_key(hash, range)}"
end

#indexed_hash_keys ⇒ Array[String]

Returns an array of hash keys for all the declared Glocal Secondary Indexes.

Returns:

  • (Array[String]) —

    array of hash keys



229
230
231
232
233
 
# File 'lib/dynamoid/indexes.rb', line 229

def indexed_hash_keys
  global_secondary_indexes.map do |_name, index|
    index.hash_key.to_s
  end
end

#indexes ⇒ Hash<String, Object>

Convenience method to return all indexes on the table.

Returns:

  • (Hash<String, Object>) —

    the combined hash of global and local secondary indexes.



221
222
223
 
# File 'lib/dynamoid/indexes.rb', line 221

def indexes
  local_secondary_indexes.merge(global_secondary_indexes)
end

#is_global_secondary_index?(hash, range = nil) ⇒ Boolean

Returns true iff the provided hash key combo is a global secondary index.

Parameters:

  • hash (Symbol) —

    hash key name.

  • range (Symbol) (defaults to: nil) —

    range key name.

Returns:

  • (Boolean) —

    true iff provided keys correspond to a global secondary index.



192
193
194
 
# File 'lib/dynamoid/indexes.rb', line 192

def is_global_secondary_index?(hash, range = nil)
  global_secondary_indexes[index_key(hash, range)].present?
end

#is_local_secondary_index?(hash, range = nil) ⇒ Boolean

Returns true iff the provided hash key combo is a local secondary index.

Parameters:

  • hash (Symbol) —

    hash key name.

  • range (Symbol) (defaults to: nil) —

    range key name.

Returns:

  • (Boolean) —

    true iff provided keys correspond to a local secondary index.



181
182
183
 
# File 'lib/dynamoid/indexes.rb', line 181

def is_local_secondary_index?(hash, range = nil)
  local_secondary_indexes[index_key(hash, range)].present?
end

#local_secondary_index(options = {}) ⇒ Object

Defines a local secondary index on a table. Will use the same primary hash key as the table.

class Comment
  include Dynamoid::Document

  table hash_key: :post_id
  range :created_at, :datetime
  field :author_id

  local_secondary_index range_key: :author_id
end

The full example with all the options being specified:

local_secondary_index range_key: :created_at,
                      name: 'posts_created_at_index',
                      projected_attributes: :all

Local secondary index should be declared after fields for mentioned hash key and optional range key are declared (with method field) as well as after table method call.

The only mandatory option is range_key. Raises Dynamoid::Errors::InvalidIndex exception if passed incorrect options.

Parameters:

  • options (Hash) (defaults to: {}) —

    options to pass for this index.

Options Hash (options):

  • name (Symbol) —

    the name for the index; this still gets namespaced. If not specified, a name is automatically generated.

  • range_key (Symbol) —

    the range key column for the index.

  • projected_attributes (Symbol, Array<Symbol>) —

    table attributes to project for this index. Can be :keys_only, :all or an array of included fields. If not specified, defaults to :keys_only.



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/dynamoid/indexes.rb', line 123

def local_secondary_index(options = {})
  unless options.present?
    raise Dynamoid::Errors::InvalidIndex, 'empty index definition'
  end

  primary_hash_key = hash_key
  primary_range_key = range_key
  index_range_key = options[:range_key]

  unless index_range_key.present?
    raise Dynamoid::Errors::InvalidIndex, 'A local secondary index ' \
                                          'requires a :range_key to be specified'
  end

  if primary_range_key.present? && index_range_key == primary_range_key
    raise Dynamoid::Errors::InvalidIndex, 'A local secondary index ' \
                                          'must use a different :range_key than the primary key'
  end

  index_opts = options.merge(
    dynamoid_class: self,
    type: :local_secondary,
    hash_key: primary_hash_key
  )

  index = Dynamoid::Indexes::Index.new(index_opts)
  key = index_key(primary_hash_key, index_range_key)
  local_secondary_indexes[key] = index
  self
end