Skip to main content

Defining Models

In CouchbaseOrm, models are defined as Ruby classes that inherit from CouchbaseOrm::Base. Each model represents a document type in Couchbase Server and encapsulates the data and behavior of the objects in your application.

3.1. Creating a Model

To create a model, define a new class that inherits from CouchbaseOrm::Base. For example, let's create a User model:

class User < CouchbaseOrm::Base
end

By convention, CouchbaseOrm uses the underscored, pluralized name of the class as the document type in Couchbase Server. In this case, the document type for the User model would be users.

3.2. Attribute Types

CouchbaseOrm supports various attribute types to define the structure and types of your model's data. You can specify the attributes of your model using the attribute method.

Here's an example of defining attributes in the User model:

class User < CouchbaseOrm::Base
attribute :email, :string
attribute :name, :string
attribute :age, :integer
attribute :height, :float
attribute :is_active, :boolean
attribute :birth_date, :date
attribute :created_at, :datetime
attribute :updated_at, :datetime
attribute :appointment_time, :time
attribute :hobbies, :array, type: :string
attribute :metadata, type: Hash
attribute :avatar, :binary

attribute :created_at, :datetime
attribute :updated_at, :datetime
end

In this example, we define several attributes for the User model, each with a specific type. The supported attribute types in CouchbaseOrm include:

  • :string: Represents a string value.

  • :integer: Represents an integer value.

  • :float: Represents a floating-point value.

  • :boolean: Represents a boolean value.

  • :date: Represents a date value.

  • :datetime: Represents a date and time value.

  • :time: Represents a time value.

  • :array: Represents an array of values.

  • :binary: Represents a binary data value.

  • Hash: Represents a hash (dictionary) of key-value pairs.

CouchbaseOrm automatically handles the serialization and deserialization of these attribute types when storing and retrieving documents from Couchbase Server.

3.3. Attribute Options

In addition to specifying the attribute type, you can also provide additional options to customize the behavior of the attributes. Some commonly used options include:

  • default: Specifies a default value for the attribute if no value is provided.

Here's an example of using attribute options:

class User < CouchbaseOrm::Base
attribute :name, :string, default: 'Unknown'
end

In this example, the name attribute has a default value of 'Unknown'.

3.4. Timestamps

CouchbaseOrm provides built-in support for timestamp attributes. By default, if you define attributes named created_at and updated_at with the :datetime type, CouchbaseOrm will automatically populate these attributes with the current date and time when a document is created or updated. To enable this feature, add the created_at and updated_at attributes to your model.The fields are automatically updated when the document is saved.document.save

class User < CouchbaseOrm::Base
attribute :created_at, :datetime
attribute :updated_at, :datetime
end

With these timestamp attributes defined, CouchbaseOrm will manage them automatically whenever a document is persisted or updated.

3.5. Callbacks

CouchbaseOrm supports lifecycle callbacks that allow you to execute code at certain points in a document's lifecycle. Callbacks can be used to perform actions before or after specific events, such as saving or updating a document.

Here are some commonly used callbacks:

  • before_create: Runs before a new document is created.
  • after_create: Runs after a new document is created.
  • before_save: Runs before a document is saved (either created or updated).
  • after_save: Runs after a document is saved (either created or updated).
  • before_update: Runs before an existing document is updated.
  • after_update: Runs after an existing document is updated.
  • before_destroy: Runs before a document is destroyed.
  • after_destroy: Runs after a document is destroyed.

To define a callback, use the corresponding callback method and provide a block or method name to be executed. For example:

class Document < CouchbaseOrm::Base
attribute :title, :string
attribute :content, :string

before_create :before_create_callback
after_create :after_create_callback
before_save :before_save_callback
after_save :after_save_callback
before_update :before_update_callback
after_update :after_update_callback
before_destroy :before_destroy_callback
after_destroy :after_destroy_callback

private

def before_create_callback
puts "Running before_create callback for #{title}"
end

def after_create_callback
puts "Running after_create callback for #{title}"
end

def before_save_callback
puts "Running before_save callback for #{title}"
end

def after_save_callback
puts "Running after_save callback for #{title}"
end

def before_update_callback
puts "Running before_update callback for #{title}"
end

def after_update_callback
puts "Running after_update callback for #{title}"
end

def before_destroy_callback
puts "Running before_destroy callback for #{title}"
end

def after_destroy_callback
puts "Running after_destroy callback for #{title}"
end
end

In this example, the Document model defines several callbacks that are triggered at different points in the document's lifecycle. The callback methods are implemented as private instance methods within the model class.

Callbacks allow you to encapsulate logic related to the document lifecycle and maintain a clean and organized codebase.

3.6. Validations

CouchbaseOrm includes built-in validation capabilities to ensure the integrity and validity of your data before persisting it to Couchbase Server. Validations help you enforce business rules and constraints on your models.

To define validations, use the validates method followed by the attribute name and the desired validation rules. For example:

class Book < CouchbaseOrm::Base
attribute :title, :string
attribute :author, :string
attribute :pages, :integer
attribute :genre, :string
attribute :email, :string

validates_presence_of :title
validates :author, presence: true
validates :pages, numericality: { greater_than: 0 }
validates :genre, inclusion: { in: %w[Fiction Non-Fiction] }
validates :author, format: { with: /\A[a-zA-Z]+\z/, message: 'only allows letters' }
validates :pages, length: { maximum: 500 }
validates :genre, exclusion: { in: %w[Science-Fiction] }
validates :email, format: { with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i }

validate :custom_validation

private

...
end

In this example, we define several validations for the User model:

  • The name attribute must be present.
  • The email attribute must match a specific format (a valid email address).
  • The age attribute must be a number greater than or equal to 18.

CouchbaseOrm provides a wide range of built-in validation helpers, such as:

  • presence: Ensures that the attribute is not blank.
  • validates_presence_of: An alias for presence.
  • format: Validates the attribute value against a regular expression.
  • length: Validates the length of the attribute value.
  • numericality: Validates that the attribute value is a valid number.
  • inclusion: Ensures that the attribute value is included in a given set.
  • exclusion: Ensures that the attribute value is not included in a given set.

You can also define custom validation methods by adding methods to your model class and using the validate method to trigger them. For example:

class Book < CouchbaseOrm::Base
attribute :title, :string
...

validate :custom_validation

private

def custom_validation
puts 'Running custom validation...'
if title&.include?('Funny')
errors.add(:title, 'should not contain the word "Funny"')
else
# print the title
puts "Title: #{title}"
puts 'Custom validation passed'
end
end
end

In this example, the custom_validation method is called during the validation process, and if some_condition is met, an error is added to the model's errors collection.

Validations are automatically run when saving a document. If any validations fail, the save operation will be aborted, and the model's errors collection will contain the validation error messages.

By leveraging validations, you can ensure the quality and consistency of your data before it is persisted to Couchbase Server.

With the model definition covered, including attributes, callbacks, and validations, you're ready to start querying and persisting data using CouchbaseOrm. In the next section, we'll explore the querying capabilities of CouchbaseOrm and how to retrieve data from Couchbase Server efficiently.