Changed sqlpp and views pages

teetangh · teetangh · commit adbb630b195a · 2024-06-03T14:43:55.000+05:30
diff --git a/docusaurus/docs/tutorial-ruby-couchbase-orm/07-sqlpp-queries.md b/docusaurus/docs/tutorial-ruby-couchbase-orm/07-sqlpp-queries.md
@@ -2,7 +2,7 @@
 
 CouchbaseOrm provides support for executing SQL++ queries directly from your Ruby code. SQL++ (or formerly N1QL,i.e. Non-First Normal Form Query Language) is a powerful query language that allows you to perform complex queries and aggregations on your Couchbase data.
 
-## Defining SQL++ Queries
+## 7.1 Defining SQL++ Queries
 
 To define an SQL++ query in your model, you can use the `n1ql` macro provided by CouchbaseOrm. Here are a few examples:
 
@@ -11,44 +11,62 @@ class N1QLTest < CouchbaseOrm::Base
   attribute :name, type: String
   attribute :lastname, type: String
   enum rating: %i[awesome good okay bad], default: :okay
+  attribute :country, type: String
 
+  # Example 1: Custom query with specific rating values
   n1ql :by_custom_rating, emit_key: [:rating], query_fn: proc { |bucket, _values, options|
     cluster.query("SELECT raw meta().id FROM `#{bucket.name}` WHERE type = 'n1_ql_test' AND rating IN [1, 2] ORDER BY name ASC", options)
   }
 
+  # Example 2: Simple query by name
   n1ql :by_name, emit_key: [:name]
 
+  # Example 3: Simple query by lastname
   n1ql :by_lastname, emit_key: [:lastname]
 
+  # Example 4: Custom query by country with parameter binding
+  n1ql :by_country, emit_key: [:country], query_fn: proc { |bucket, values, options|
+    cluster.query(
+      "SELECT raw meta().id FROM `#{bucket.name}` WHERE type = 'n1_ql_test' AND country = $country ORDER BY name ASC",
+      Couchbase::Options::Query(named_parameters: { country: values[0] })
+    )
+  }
+
+  # Example 5: Simple query by rating
   n1ql :by_rating_emit, emit_key: :rating
 
+  # Example 6: Custom query by rating with parameter binding
   n1ql :by_custom_rating_values, emit_key: [:rating], query_fn: proc { |bucket, values, options|
-  cluster.query("SELECT raw meta().id FROM `#{bucket.name}` where type = 'n1_ql_test' AND rating IN #{quote(values[0])} ORDER BY name ASC", options)
-}
+    cluster.query("SELECT raw meta().id FROM `#{bucket.name}` where type = 'n1_ql_test' AND rating IN #{quote(values[0])} ORDER BY name ASC", options)
+  }
+
+  # Example 7: Custom query by rating with custom ordering
   n1ql :by_rating_reverse, emit_key: :rating, custom_order: 'name DESC'
 
+  # Example 8: Simple query by rating without including documents
   n1ql :by_rating_without_docs, emit_key: :rating, include_docs: false
 
+  # Index definition for the rating attribute
   index_n1ql :rating
 end
 
 ```
 
 In these examples:
 
-- The `by_custom_rating` query selects the document IDs where the `type` is `'n1_ql_test'` and the `rating` is either 1 or 2, ordered by the `name` attribute in ascending order.
+- The `by_custom_rating` query selects the document IDs where the type is 'n1_ql_test' and the rating is either 1 or 2, ordered by the name attribute in ascending order.
 
-- The `by_name`, `by_lastname`, and `by_rating_emit` queries use the `emit_key` option to specify the attribute to be used as the key for the query.
+- The `by_name`, `by_lastname`, and `by_rating_emit` queries use the emit_key option to specify the attribute to be used as the key for the query.
 
-- The `by_custom_rating_values` query demonstrates passing values to the query using placeholders (`$1`, `$2`, etc.) and the `quote` method to properly escape the values.
+- The `by_custom_rating_values` query demonstrates passing values to the query using placeholders ($1, $2, etc.) and the quote method to properly escape the values.
 
-- The `by_rating_reverse` query uses the `custom_order` option to specify a custom ordering for the query results.
+- The `by_rating_reverse` query uses the custom_order option to specify a custom ordering for the query results.
 
-- The `by_rating_without_docs` query sets `include_docs` to `false` to retrieve only the document IDs without fetching the full documents.
+- The `by_rating_without_docs` query sets include_docs to false to retrieve only the document IDs without fetching the full documents.
 
-- The `index_n1ql` macro is used to define an index on the `rating` attribute and generate a corresponding query method.
+- The `index_n1ql` macro is used to define an index on the rating attribute and generate a corresponding query method. Note that the index_n1ql macro does not create the index in the Couchbase Dashboard directly; you would need to create the index separately using the Couchbase Dashboard or the Couchbase Query UI.
 
-## Query Parameters
+## 7.2 Query Parameters
 
 SQL++ queries often require parameters to be passed in order to filter or customize the results. CouchbaseOrm allows you to define queries with placeholders and provide the parameter values when executing the query.
 
@@ -60,7 +78,7 @@ n1ql :by_custom_rating_values, emit_key: [:rating], query_fn: proc { |bucket, va
 
 In this example, the `values` parameter represents an array of values passed to the query. The `quote` method is used to properly escape and format the values for use in the query.
 
-## Executing SQL++ Queries
+## 7.3 Executing SQL++ Queries
 
 To execute an SQL++ query, you simply call the defined query method on your model class.
 
@@ -70,7 +88,7 @@ docs = N1QLTest.by_custom_rating().collect { |ob| ob.name }
 
 CouchbaseOrm automatically executes the SQL++ query and returns the result set, which you can then process as needed.
 
-## Query Options
+## 7.4 Query Options
 
 CouchbaseOrm provides various options to customize the execution of SQL++ queries. These options can be passed as a hash parameter to the query method.
 
@@ -86,19 +104,24 @@ docs = N1QLTest.by_rating_reverse(key: 1)
 - `include_docs`: Specifies whether to include the full document content in the results.
 - `scan_consistency`: Specifies the consistency level for the query (`request_plus` by default). -->
 
-## Placeholder Values
+## 7.5 Placeholder Values
 
-In addition to using positional placeholders (`$1`, `$2`, etc.), CouchbaseOrm also supports named placeholders for better readability.
+You can use placeholder values in your SQL++ queries and pass the actual values when executing the query.
 
 ```ruby
-n1ql :by_name_and_rating, "SELECT * FROM `#{bucket.name}` WHERE name = $name AND rating = $rating"
+ n1ql :by_country, emit_key: [:country], query_fn: proc { |bucket, values, options|
+    cluster.query(
+      "SELECT raw meta().id FROM `#{bucket.name}` WHERE type = 'n1_ql_test' AND country = $country ORDER BY name ASC",
+      Couchbase::Options::Query(named_parameters: { country: values[0] })
+    )
+  }
 
-docs = N1QLTest.by_name_and_rating(name: 'John', rating: 'awesome')
+docs = N1QLTest.by_country(key: 'USA').collect { |ob| ob.name }
 ```
 
-In this example, the `$name` and `$rating` placeholders are used in the query, and the values are provided using a hash parameter with the corresponding keys.
+In this example, the `by_country` query uses a placeholder `$country` in the query string and passes the actual value `'USA'` as the parameter value when executing the query.
 
-## Query Result Processing
+## 7.6 Query Result Processing
 
 By default, CouchbaseOrm automatically maps the query result to instances of your model class. However, you can also process the query result manually if needed.
 
@@ -124,11 +147,19 @@ docs = N1QLTest.by_custom_rating_values(key: [[1, 2]]).collect { |ob| ob.name }
 
 In the above examples, the `collect` method is used to extract the `name` attribute from each document in the result set.
 
-## Indexing for SQL++
+## 7.7 Indexing for SQL++
 
 To optimize the performance of SQL++ queries, it's important to create appropriate indexes on the fields used in the query conditions. Couchbase Server provides a way to create indexes using the Index service.
 
 ```ruby
+
+class N1QLTest < CouchbaseOrm::Base
+  ... 
+
+  # Index definition for the rating attribute
+  index_n1ql :rating
+end
+
 # Query using index_n1ql
 docs = N1QLTest.find_by_rating(2).collect { |ob| ob.name }
 
diff --git a/docusaurus/docs/tutorial-ruby-couchbase-orm/08-views.md b/docusaurus/docs/tutorial-ruby-couchbase-orm/08-views.md
@@ -1,54 +1,158 @@
 # Views (aka Map/Reduce indexes)
 
-Views are defined in the model and typically just emit an attribute that
-can then be used for filtering results or ordering.
+Views are a powerful feature in Couchbase that allow you to define map functions to extract and emit specific data from your documents. The Ruby Couchbase ORM provides a convenient way to define and query views within your Ruby application.
+
+## 8.1 Defining Views
+
+To define a view in your Ruby Couchbase ORM model, you can use the `view` method followed by the view name and options. Here's an example:
+
+```ruby
+class Factory < CouchbaseOrm::Base
+  attribute :name, type: String
+  attribute :location, type: String
+  attribute :established_year, type: Integer
+  attribute :active, type: Boolean
+
+  view :by_name, emit_key: :name
+  view :by_location, emit_key: :location
+  view :by_established_year, emit_key: :established_year
+  view :by_active, emit_key: :active
+end
+```
+
+In this example, we define four views for the `Factory` model:
+- `by_name`: Emits the `name` attribute as the key.
+- `by_location`: Emits the `location` attribute as the key.
+- `by_established_year`: Emits the `established_year` attribute as the key.
+- `by_active`: Emits the `active` attribute as the key.
+
+The `emit_key` option specifies the attribute to use as the key for the view.
+
+## 8.2 Custom Map Functions
+
+You can also define custom map functions for your views using the `map` option. This allows you to emit custom keys and values based on your specific requirements. Here's an example:
 
 ```ruby
-    class Comment < CouchbaseOrm::Base
-      attribute :author :string
-      attribute :body, :string
-      view :all # => emits :id and will return all comments
-      view :by_author, emit_key: :author
-
-      # Generates two functions:
-      # * the by_author view above
-      # * def find_by_author(author); end
-      index_view :author
-
-      # You can make compound keys by passing an array to :emit_key
-      # this allow to query by read/unread comments
-      view :by_read, emit_key: [:user_id, :read]
-      # this allow to query by view_count
-      view :by_view_count, emit_key: [:user_id, :view_count]
-
-      validates_presence_of :author, :body
-    end
+view :by_name_and_location,
+  map: %{
+    function(doc) {
+      if (doc.type === "factory") {
+        emit([doc.name, doc.location], null);
+      }
+    }
+  }
 ```
 
-You can use `Comment.find_by_author('name')` to obtain all the comments by
-a particular author. The same thing, using the view directly would be:
-`Comment.by_author(key: 'name')`
+In this example, we define a view named `by_name_and_location` that emits a composite key consisting of the `name` and `location` attributes.
 
-When using a compound key, the usage is the same, you just give the full key :
+## 8.3 Querying Views
+
+Once you have defined your views, you can query them using the corresponding view methods. The view methods are automatically generated based on the view names. Here are some examples:
 
 ```ruby
-   Comment.by_read(key: '["'+user_id+'",false]') # gives all unread comments for one particular user
+# Query factories by name
+Factory.by_name(key: 'Factory A').each do |factory|
+  puts "- #{factory.name}"
+end
+
+# Query factories by location
+Factory.by_location(key: 'City X').each do |factory|
+  puts "- #{factory.name}"
+end
 
-   # or even a range !
+# Query factories by established year
+Factory.by_established_year(key: 2010).each do |factory|
+  puts "- #{factory.name}"
+end
 
-   Comment.by_view_count(startkey: '["'+user_id+'",10]', endkey: '["'+user_id+'",20]') 
-   
-   # gives all comments that have been seen more than 10 times but less than 20
+# Query active factories
+Factory.by_active(key: true).each do |factory|
+  puts "- #{factory.name}"
+end
 ```
 
-Ex : Compound keys allows to decide the order of the results, and you can reverse it by passing `descending: true`
+These examples demonstrate how to query views based on specific keys using the generated view methods.
+
+## Indexing Views
+
+In this section, let's explore the `index_view` function and the methods it generates for the `location` attribute.
+
+Here's an updated version of the `Factory` model using `index_view` for the `location` attribute:
 
 ```ruby
-    class Comment < CouchbaseOrm::Base19
-      self.ignored_properties = [:old_name] # ignore old_name property in the model
-      self.properties_always_exists_in_document = true # use is null for nil value instead of not valued for performance purpose, only possible if all properties always exists in document
-    end
-```      
-You can specify `properties_always_exists_in_document` to true if all properties always exists in document, this will allow to use `is null` instead of `not valued` for nil value, this will improve performance. 
-
-WARNING: If a document exists without a property, the query will failed! So you must be sure that all documents have all properties.
+class Factory < CouchbaseOrm::Base
+  attribute :name, type: String
+  attribute :location, type: String
+  attribute :established_year, type: Integer
+  attribute :active, type: Boolean
+
+  view :by_name, emit_key: :name
+  index_view :location
+  view :by_established_year, emit_key: :established_year
+  view :by_active, emit_key: :active
+
+  view :by_name_and_location,
+    map: %{
+      function(doc) {
+        if (doc.type === "factory") {
+          emit([doc.name, doc.location], null);
+        }
+      }
+    }
+
+  view :by_established_year_range,
+    map: %{
+      function(doc) {
+        if (doc.type === "factory" && doc.established_year) {
+          emit(doc.established_year, null);
+        }
+      }
+    }
+end
+```
+
+In this updated code, we replaced `view :by_location, emit_key: :location` with `index_view :location`. The `index_view` function generates two methods for querying based on the `location` attribute:
+
+1. `find_by_location(location)`: This method allows you to find factories by a specific location. It returns an array of factories that match the given location.
+
+2. `by_location(key: location)`: This method is similar to `find_by_location` but returns a `CouchbaseOrm::ResultsProxy` object, which provides an enumerable interface to access the view results.
+
+Now, let's see how we can use these generated methods to query factories by location:
+
+```ruby
+# Find factories by location using find_by_location
+factories = Factory.find_by_location('City X')
+factories.each do |factory|
+  puts "- #{factory.name} (#{factory.location})"
+end
+
+# Find factories by location using by_location
+Factory.by_location(key: 'City X').each do |factory|
+  puts "- #{factory.name} (#{factory.location})"
+end
+```
+
+Both `find_by_location` and `by_location` achieve the same result of finding factories by a specific location. The difference is that `find_by_location` returns an array of factories directly, while `by_location` returns a `CouchbaseOrm::ResultsProxy` object that you can further chain or iterate over.
+
+Using `index_view` provides a convenient way to generate commonly used query methods for a specific attribute. It simplifies the process of querying based on that attribute and enhances the readability of your code.
+
+<!-- ## 8.5 Range Queries (Experimental)
+
+You can perform range queries on views by specifying the `startkey` and `endkey` options. Here's an example:
+
+```ruby
+# Query factories established between 2005 and 2015
+Factory.by_established_year_range(startkey: 2005, endkey: 2015).each do |factory|
+  puts "- #{factory.name} (#{factory.established_year})"
+end
+```
+
+In this example, we query the `by_established_year_range` view to retrieve factories established between 2005 and 2015. -->
+
+## 8.5 Conclusion
+
+Views in the Ruby Couchbase ORM provide a powerful way to define and query data based on specific attributes and custom map functions. By defining views, you can easily retrieve subsets of your data and perform efficient queries based on your application's requirements.
+
+Remember to ensure that your design documents are up to date by calling `ensure_design_document!` on your models before running queries.
+
+With the flexibility and ease of use provided by the Ruby Couchbase ORM's view functionality, you can efficiently query and retrieve data from your Couchbase database.
