Class: Ashikawa::Core::Collection

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/ashikawa-core/collection.rb

Overview

A certain Collection within the Database

Direct Known Subclasses

EdgeCollection, VertexCollection

Constant Summary collapse

CONTENT_TYPES =

ArangoDB’s collections contain either only documents or only edges

{
  2 => :document,
  3 => :edge
}
CONTENT_CLASS =

Map the content types to the classes from Ashikawa

{
  document: Document,
  edge: Edge
}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(database, raw_collection) ⇒ Collection

Create a new Collection object with a name and an optional ID

Examples:

Create a Collection object from scratch

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)

Parameters:

  • database (Database) —

    The database the connection belongs to

  • raw_collection (Hash) —

    The raw collection returned from the server



145
146
147
148
149
 
# File 'lib/ashikawa-core/collection.rb', line 145

def initialize(database, raw_collection)
  @database = database
  parse_raw_collection(raw_collection)
  @content_class = CONTENT_CLASS[@content_type]
end

Instance Attribute Details

#content_type ⇒ :document, :edge (readonly)

The kind of content in the collection: Documents or Edges

Examples:

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.content_type #=> :document

Returns:

  • (:document, :edge) 


124
125
126
 
# File 'lib/ashikawa-core/collection.rb', line 124

def content_type
  @content_type
end

#database ⇒ Database (readonly)

The database the collection belongs to

Examples:

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.database #=> #<Database: ...>

Returns:



106
107
108
 
# File 'lib/ashikawa-core/collection.rb', line 106

def database
  @database
end

#id ⇒ Fixnum (readonly)

The ID of the collection. Is set by the database and unique

Examples:

Get the id of the collection

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.id #=> 4588

Returns:

  • (Fixnum) 


69
70
71
 
# File 'lib/ashikawa-core/collection.rb', line 69

def id
  @id
end

#name ⇒ String

The name of the collection, must be unique

Examples:

Change the name of a collection

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.name # => 'example_1'
collection.name = 'example_2'
collection.name # => 'example_2'

Returns:

  • (String) 


51
52
53
 
# File 'lib/ashikawa-core/collection.rb', line 51

def name
  @name
end

#status ⇒ Status (readonly)

A wrapper around the status of the collection

Examples:

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.status.loaded? #=> true
collection.status.new_born? #=> false

Returns:



88
89
90
 
# File 'lib/ashikawa-core/collection.rb', line 88

def status
  @status
end

Instance Method Details

#[](document_key) ⇒ Object

Fetch a certain document by its key, return nil if the document does not exist

Examples:

Fetch the document with the key 12345

document = collection[12345]

Parameters:

  • document_key (Fixnum) —

    the id of the document

Returns:

  • Document



367
368
369
370
371
 
# File 'lib/ashikawa-core/collection.rb', line 367

def [](document_key)
  fetch(document_key)
rescue DocumentNotFoundException
  nil
end

#add_index(type, options) ⇒ Object

Add an index to the collection

Examples:

Add a hash-index to the fields :name and :profession of a collection

people = database['people']
people.add_index(:hash, :on => [:name, :profession])

Add a hash-index to the field :email of a collection

user = database['user']
user.add_index(:hash, :on => :email)

Parameters:

  • type (Symbol) —

    specify the type of the index, for example ‘:hash`

  • options (Hash) —

    a customizable set of options

Options Hash (options):

  • on (Array<Symbol>) —

    fields on which to apply the index

  • unique (Boolean) —

    Should the index be unique? Default is false

Returns:

  • Index



430
431
432
433
434
435
436
437
438
439
440
 
# File 'lib/ashikawa-core/collection.rb', line 430

def add_index(type, options)
  options[:on] = [options[:on]].flatten
  unique = options.fetch(:unique, false)
  response = send_request("index?collection=#{@id}", post: {
    'type' => type.to_s,
    'fields' => options.fetch(:on).map { |field| field.to_s },
    'unique' => unique
  })

  Index.new(self, response)
end

#build_content_class(data, additional_attributes = {}) ⇒ Document

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds an instance for the content class

Parameters:

  • data (Hash) —

    The raw data to be used to instatiate the class

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

    Initial attributes to be passed to the underlying content class

Returns:

  • (Document) —

    The instatiated document



498
499
500
 
# File 'lib/ashikawa-core/collection.rb', line 498

def build_content_class(data, additional_attributes = {})
  @content_class.new(@database, data, additional_attributes)
end

#create_document(attributes) ⇒ Document

Create a new document with given attributes

Examples:

Create a new document from raw data

collection.create_document(attributes)

Parameters:

  • attributes (Hash)

Returns:



392
393
394
395
396
 
# File 'lib/ashikawa-core/collection.rb', line 392

def create_document(attributes)
  raise "Can't create a document in an edge collection" if @content_type == :edge
  response = send_request_for_content(post: attributes)
  build_content_class(response, attributes)
end

#create_edge(from, to, attributes) ⇒ Edge

Deprecated.

Since we introduced the dedicated Graph module (‘gharial’) all operations regarding edges and vertices should be done through that module. Due to this please use EdgeCollection#add instead.

Create a new edge between two documents with certain attributes

Examples:

Create a new document from raw data

collection.create_edge(node_a, node_b, {'name' => 'incredible edge'})

Parameters:

Returns:

  • (Edge) —

    The created edge



410
411
412
413
414
415
 
# File 'lib/ashikawa-core/collection.rb', line 410

def create_edge(from, to, attributes)
  warn '[DEPRECATION] `create_edge` is deprecated.  Please use `EdgeCollection#add` instead.'
  raise "Can't create an edge in a document collection" if @content_type == :document
  response = send_request("edge?collection=#{@id}&from=#{from.id}&to=#{to.id}", post: attributes)
  Edge.new(@database, response, attributes)
end

#delete ⇒ String

Deletes the collection

Examples:

Delete a collection

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.delete

Returns:

  • (String) —

    Response from the server



283
284
285
 
# File 'lib/ashikawa-core/collection.rb', line 283

def delete
  send_request_for_this_collection('', delete: {})
end

#fetch(document_key) ⇒ Object

Fetch a certain document by its key

Examples:

Fetch the document with the key 12345

document = collection.fetch(12345)

Parameters:

  • document_key (Fixnum) —

    the key of the document

Returns:

  • Document

Raises:



355
356
357
358
 
# File 'lib/ashikawa-core/collection.rb', line 355

def fetch(document_key)
  response = send_request_for_content_key(document_key)
  build_content_class(response)
end

#figure ⇒ Figure

Return a Figure initialized with current data for the collection

Examples:

Get the datafile count for a collection

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.figure.datafiles_count #=> 0

Returns:



262
263
264
265
 
# File 'lib/ashikawa-core/collection.rb', line 262

def figure
  raw_figure = get_information_from_server(:figures, :figures)
  Figure.new(raw_figure)
end

#index(id) ⇒ Object

Get an index by ID

Examples:

Get an Index by its ID

people = database['people']
people.index(1244) #=> #<Index: id=1244...>

Parameters:

  • id (Fixnum)

Returns:

  • Index



450
451
452
453
 
# File 'lib/ashikawa-core/collection.rb', line 450

def index(id)
  response = send_request("index/#{@name}/#{id}")
  Index.new(self, response)
end

#indices ⇒ Array<Index>

Get all indices

Examples:

Get all indices

people = database['people']
people.indices #=> [#<Index: id=1244...>, ...]

Returns:



462
463
464
465
466
467
468
 
# File 'lib/ashikawa-core/collection.rb', line 462

def indices
  response = send_request("index?collection=#{@id}")

  response['indexes'].map do |raw_index|
    Index.new(self, raw_index)
  end
end

#key_options ⇒ KeyOptions

Get information about the type of keys of this collection

Examples:

Check if this collection has autoincrementing keys

collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.key_options.type # => 'autoincrement'

Returns:



222
223
224
 
# File 'lib/ashikawa-core/collection.rb', line 222

def key_options
  KeyOptions.new(get_information_from_server(:properties, :keyOptions))
end

#length ⇒ Fixnum

Returns the number of documents in the collection

Examples:

How many documents are in the collection?

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.length # => 0

Returns:

  • (Fixnum) —

    Number of documents



242
243
244
 
# File 'lib/ashikawa-core/collection.rb', line 242

def length
  get_information_from_server(:count, :count)
end

#load ⇒ String

Load the collection into memory

Examples:

Load a collection into memory

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.load

Returns:

  • (String) —

    Response from the server



303
304
305
 
# File 'lib/ashikawa-core/collection.rb', line 303

def load
  send_command_to_server(:load)
end

#query ⇒ Query

Return a Query initialized with this collection

Examples:

Get all documents in this collection

people = database['people']
people.query.all #=> #<Cursor: id=1244...>

Returns:



477
478
479
 
# File 'lib/ashikawa-core/collection.rb', line 477

def query
  Query.new(self)
end

#replace(document_key, raw_document) ⇒ Hash

Replace a document by its key

Examples:

Replace the document with the key 12345

collection.replace(12345, document)

Parameters:

  • document_key (Fixnum) —

    the key of the document

  • raw_document (Hash) —

    the data you want to replace it with

Returns:

  • (Hash) —

    parsed JSON response from the server



381
382
383
 
# File 'lib/ashikawa-core/collection.rb', line 381

def replace(document_key, raw_document)
  send_request_for_content_key(document_key, put: raw_document)
end

#truncate ⇒ String

Delete all documents from the collection

Examples:

Remove all documents from a collection

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.truncate

Returns:

  • (String) —

    Response from the server



343
344
345
 
# File 'lib/ashikawa-core/collection.rb', line 343

def truncate
  send_command_to_server(:truncate)
end

#unload ⇒ String

Load the collection into memory

Examples:

Unload a collection into memory

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.unload

Returns:

  • (String) —

    Response from the server



323
324
325
 
# File 'lib/ashikawa-core/collection.rb', line 323

def unload
  send_command_to_server(:unload)
end

#volatile? ⇒ Boolean

Check if the collection is volatile

Examples:

Is the people collection volatile?

people = database['people']
people.volatile? #=> false

Returns:

  • (Boolean) 


488
489
490
 
# File 'lib/ashikawa-core/collection.rb', line 488

def volatile?
  get_information_from_server(:properties, :isVolatile)
end

#wait_for_sync=(new_value) ⇒ String

Change if the document will wait until the data has been synchronised to disk

Examples:

Tell the collection to wait for file synchronization

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.wait_for_sync = true

Returns:

  • (String) —

    Response from the server



211
212
213
 
# File 'lib/ashikawa-core/collection.rb', line 211

def wait_for_sync=(new_value)
  send_information_to_server(:properties, :waitForSync, new_value)
end

#wait_for_sync? ⇒ Boolean

Does the document wait until the data has been synchronised to disk?

Examples:

Does the collection wait for file synchronization?

database = Ashikawa::Core::Database.new('http://localhost:8529')
raw_collection = {
  'name' => 'example_1',
  'waitForSync' => true,
  'id' => 4588,
  'status' => 3,
  'error' => false,
  'code' => 200
}
collection = Ashikawa::Core::Collection.new(database, raw_collection)
collection.wait_for_sync? #=> false

Returns:

  • (Boolean) 


191
192
193
 
# File 'lib/ashikawa-core/collection.rb', line 191

def wait_for_sync?
  get_information_from_server(:properties, :waitForSync)
end