Module: CouchbaseOrm::N1ql::ClassMethods

Defined in:
lib/couchbase-orm/n1ql.rb

Constant Summary collapse

N1QL_DEFAULTS = 
{ include_docs: true }.freeze

Instance Method Summary collapse

Instance Method Details

#index_n1ql(attr, validate: true, find_method: nil, n1ql_method: nil) ⇒ void

This method returns an undefined value.

Sets up a Couchbase N1QL query and a corresponding finder method for the given attribute.

N1QL (Non-first Normal Form Query Language) is a powerful query language for Couchbase that allows you to perform complex queries on your data. For more details, see the [Couchbase N1QL Documentation](docs.couchbase.com/server/current/n1ql/n1ql-intro/index.html).

Examples:

Define an index N1QL query for the `email` attribute

class User
  include CouchbaseOrm::Model
  index_n1ql :email
end

# This creates a N1QL query method `by_email` and a finder method `find_by_email`
users = User.by_email(key: ['user@example.com'])
user = User.find_by_email('user@example.com')

Define an index N1QL query for the `username` attribute with custom method names

class User
  include CouchbaseOrm::Model
  index_n1ql :username, find_method: :find_user_by_username, n1ql_method: :by_username_n1ql
end

# This creates a N1QL query method `by_username_n1ql` and a finder method `find_user_by_username`
users = User.by_username_n1ql(key: ['john_doe'])
user = User.find_user_by_username('john_doe')

Parameters:

  • attr (Symbol) —

    The attribute to create the N1QL query and finder method for.

  • validate (Boolean) (defaults to: true) —

    Whether to validate the presence of the attribute (default: true).

  • find_method (Symbol, String, nil) (defaults to: nil) —

    The name of the finder method to be created (optional).

  • n1ql_method (Symbol, String, nil) (defaults to: nil) —

    The name of the N1QL query method to be created (optional).

Raises:

  • (ArgumentError) —

    if the class already responds to the given name.



126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/couchbase-orm/n1ql.rb', line 126

def index_n1ql(attr, validate: true, find_method: nil, n1ql_method: nil)
  n1ql_method ||= "by_#{attr}"
  find_method ||= "find_#{n1ql_method}"

  validates(attr, presence: true) if validate
  n1ql n1ql_method, emit_key: attr

  define_singleton_method find_method do |value|
    send n1ql_method, key: [value]
  end
end

#n1ql(name, query_fn: nil, emit_key: [], custom_order: nil, **options) ⇒ void

This method returns an undefined value.

Defines a N1QL query method with dynamic method creation.

N1QL (Non-first Normal Form Query Language) is a powerful query language for Couchbase that allows you to perform complex queries on your data. For more details, see the [Couchbase N1QL Documentation](docs.couchbase.com/server/current/n1ql/n1ql-intro/index.html).

Examples:

Define a N1QL query to find documents by `email`

class User
  include CouchbaseOrm::Model
  n1ql :find_by_email, emit_key: :email
end

# This creates a query method `find_by_email`
users = User.find_by_email(key: 'user@example.com')

Define a N1QL query with custom ordering

class User
  include CouchbaseOrm::Model
  n1ql :ordered_by_creation, emit_key: :created_at, custom_order: 'ORDER BY created_at DESC'
end

# This creates a query method `ordered_by_creation`
users = User.ordered_by_creation

Define a N1QL query with a custom query function

class User
  include CouchbaseOrm::Model
  n1ql :custom_query, query_fn: ->(keys) { "SELECT * FROM `bucket` WHERE #{keys.map { |k| "`#{k}` = ?" }.join(' AND ')}" }, emit_key: [:email, :username]
end

# This creates a query method `custom_query`
users = User.custom_query(key: { email: 'user@example.com', username: 'johndoe' })

Parameters:

  • name (Symbol, String) —

    The name of the N1QL query method.

  • query_fn (Proc, nil) (defaults to: nil) —

    An optional function to customize the query.

  • emit_key (Symbol, Array<Symbol>) (defaults to: []) —

    The key(s) to emit from the query (optional, defaults to an empty array).

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

    An optional parameter to define custom ordering for the query.

  • options (Hash) —

    Additional options for the N1QL query.

Raises:

  • (ArgumentError) —

    if the class already responds to the given name.



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/couchbase-orm/n1ql.rb', line 63

def n1ql(name, query_fn: nil, emit_key: [], custom_order: nil, **options)
  raise ArgumentError.new("#{self} already respond_to? #{name}") if self.respond_to?(name)

  emit_key = Array.wrap(emit_key)
  emit_key.each do |key|
    raise "unknown emit_key attribute for n1ql :#{name}, emit_key: :#{key}" if key && !attribute_names.include?(key.to_s)
  end
  options = N1QL_DEFAULTS.merge(options)
  method_opts = {}
  method_opts[:emit_key] = emit_key

  @indexes ||= {}
  @indexes[name] = method_opts

  singleton_class.__send__(:define_method, name) do |key: NO_VALUE, **opts, &result_modifier|
    opts = options.merge(opts).reverse_merge(scan_consistency: :request_plus)
    values = key == NO_VALUE ? NO_VALUE : convert_values(method_opts[:emit_key], key)
    current_query = run_query(method_opts[:emit_key], values, query_fn, custom_order: custom_order,
                                                                        **opts.except(:include_docs, :key))
    if result_modifier
      opts[:include_docs] = true
      current_query.results(&result_modifier)
    elsif opts[:include_docs]
      current_query.results { |res| find(res) }
    else
      current_query.results
    end
  end
end