notion_ruby_mapping 0.1.4 → 0.2.2

data/README.md

@@ -1,44 +1,67 @@
-# NotionRubyMapping
+# notion_ruby_mapping
 
 Notion Ruby mapping is currently under development.
 
 Development note is here. → [Idea note of "notion_ruby_mapping"](https://www.notion.so/hkob/Idea-note-of-notion_ruby_mapping-3b0a3bb3c171438a830f9579d41df501)
 
 ## Table of Contents
-- [NotionRubyMapping](#notionrubymapping)
+
+
+<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->
+
+<!-- code_chunk_output -->
+
+- [notion\_ruby\_mapping](#notion_ruby_mapping)
   - [Table of Contents](#table-of-contents)
   - [1. Installation](#1-installation)
   - [2. Example code](#2-example-code)
-  - [3. Usage](#3-usage)
+    - [2.1 Set icon to all icon unsettled pages](#21-set-icon-to-all-icon-unsettled-pages)
+    - [2.2 Renumbering pages](#22-renumbering-pages)
+    - [2.3 Change title](#23-change-title)
+      - [Pattern 1 (replace existing text partially)](#pattern-1-replace-existing-text-partially)
+      - [Pattern 2 (replace all text)](#pattern-2-replace-all-text)
+  - [3. Preparation](#3-preparation)
     - [3.1 Create a New Integration](#31-create-a-new-integration)
     - [3.2 Create client](#32-create-client)
-    - [3.3 Retrieve a database](#33-retrieve-a-database)
-    - [3.4 Retrieve a page](#34-retrieve-a-page)
-    - [3.5 Query a database](#35-query-a-database)
-      - [3.5.1 A simple example](#351-a-simple-example)
-      - [3.5.2 Property classes](#352-property-classes)
-      - [3.5.3 Query object generator of property objects](#353-query-object-generator-of-property-objects)
-      - [3.5.4 Complex conditions](#354-complex-conditions)
-      - [3.5.5 Sort criteria](#355-sort-criteria)
-    - [3.6 Access the database or page values and properties](#36-access-the-database-or-page-values-and-properties)
-  - [3.7 Set icon (Database / Page)](#37-set-icon-database--page)
-  - [3.8 Update page property values](#38-update-page-property-values)
-    - [3.8.1 Assign property and update it (fastest: one API call only)](#381-assign-property-and-update-it-fastest-one-api-call-only)
-    - [3.8.2 Update the loaded page (easy but slow: two API calls)](#382-update-the-loaded-page-easy-but-slow-two-api-calls)
-    - [3.8.3 Update the unloaded page with auto-load (easy but slow: two API calls)](#383-update-the-unloaded-page-with-auto-load-easy-but-slow-two-api-calls)
-    - [3.8.4 Explanation of how to update each property](#384-explanation-of-how-to-update-each-property)
-      - [3.8.4.1 NumberProperty](#3841-numberproperty)
-      - [3.8.4.2 SelectProperty](#3842-selectproperty)
-      - [3.8.4.3 MultiSelectProperty](#3843-multiselectproperty)
-      - [3.8.4.4 DateProperty](#3844-dateproperty)
-    - [3.9 Iteration of list object](#39-iteration-of-list-object)
-  - [4. ChangeLog](#4-changelog)
-  - [5. Contributing](#5-contributing)
-  - [6. License](#6-license)
-  - [7. Code of Conduct](#7-code-of-conduct)
-  - [8. Acknowledgements](#8-acknowledgements)
-
-<!-- @import "[TOC]" {cmd="toc" depthFrom=2 depthTo=4 orderedList=false} -->
+  - [4. Usage](#4-usage)
+    - [4.1 Page](#41-page)
+      - [4.1.1 Retrieve a page](#411-retrieve-a-page)
+      - [4.1.2 Update page properties](#412-update-page-properties)
+      - [4.1.3 Update other page information](#413-update-other-page-information)
+      - [4.1.4 other methods](#414-other-methods)
+    - [4.2 Page](#42-page)
+      - [4.2.1 Retrieve a database](#421-retrieve-a-database)
+      - [4.2.2 Query a database](#422-query-a-database)
+        - [4.2.2.1 Complex conditions](#4221-complex-conditions)
+        - [4.2.2.2 Sort criteria](#4222-sort-criteria)
+      - [4.2.3 Update database](#423-update-database)
+    - [4.3 List class](#43-list-class)
+    - [4.4 Block class](#44-block-class)
+    - [4.5 Property classes](#45-property-classes)
+      - [4.5.1 How to obtain Property object](#451-how-to-obtain-property-object)
+      - [4.5.2 Query object generator of property objects](#452-query-object-generator-of-property-objects)
+      - [4.5.3 create or update values for Page properties](#453-create-or-update-values-for-page-properties)
+        - [4.5.3.1 NumberProperty](#4531-numberproperty)
+        - [4.5.3.2 SelectProperty](#4532-selectproperty)
+        - [4.5.3.3 MultiSelectProperty](#4533-multiselectproperty)
+        - [4.5.3.4 DateProperty](#4534-dateproperty)
+        - [4.5.3.4 UrlProperty](#4534-urlproperty)
+        - [4.5.3.5 EmailProperty](#4535-emailproperty)
+        - [4.5.3.6 PhoneNumberProperty](#4536-phonenumberproperty)
+        - [4.5.3.7 PeopleProperty](#4537-peopleproperty)
+        - [4.5.3.8 TitleProperty, RichTextProperty](#4538-titleproperty-richtextproperty)
+        - [4.5.3.9 CheckboxProperty](#4539-checkboxproperty)
+        - [4.5.3.10 EmailProperty](#45310-emailproperty)
+        - [4.5.3.11 FilesProperty](#45311-filesproperty)
+        - [4.5.3.12 RelationProperty](#45312-relationproperty)
+  - [6. ChangeLog](#6-changelog)
+  - [6. Contributing](#6-contributing)
+  - [7. License](#7-license)
+  - [8. Code of Conduct](#8-code-of-conduct)
+  - [9. Acknowledgements](#9-acknowledgements)
+
+<!-- /code_chunk_output -->
+
 
 ## 1. Installation
 
@@ -50,15 +73,22 @@ gem 'notion_ruby_mapping'
 
 And then execute:
 
-    $ bundle install
+```shell
+bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install notion_ruby_mapping
+```shell
+gem install notion_ruby_mapping
+```
 
 ## 2. Example code
 
+### 2.1 Set icon to all icon unsettled pages
+
 The following code sets a "💿" icon on all unset pages in the database.
+
 ```Ruby
 require "notion_ruby_mapping"
 
@@ -69,8 +99,13 @@ database_id = ENV["DATABASE_ID"]
 
 NotionCache.instance.create_client token
 
-Database.query(database_id).each do |page|
-  p page.set_icon(emoji: "💿").id unless page.icon
+db = Database.new id: database_id
+db.query_database.each do |page|
+  unless page.icon
+    page.set_icon(emoji: "💿")
+    page.save
+    p page.id
+  end
 end
 ```
 
@@ -78,19 +113,50 @@ end
 |---|---|
 |![Before execution](images/pre_set_icon.png)|![After execution](images/post_set_icon.png)|
 
+### 2.2 Renumbering pages
+
 The following code sets serial numbers to the pages whose title is not empty in ascending order of titles.
+
 ```Ruby
-tp = RichTextProperty.new("TextTitle")
-Database.query(database_id, tp.filter_is_not_empty.ascending(tp)).each.with_index(1) do |page, index|
+db = Database.new id: database_id, assign: [RichTextProperty, "TextTitle"]
+tp = db.properties["TextTitle"]
+query = tp.filter_is_not_empty.ascending(tp)
+db.query_database(tp.filter_is_not_empty.ascending(tp)).each.with_index(1) do |page, index|
   page.properties["NumberTitle"].number = index
-  page.update
+  page.save
 end
 ```
+
 | After execution                               |
 |-----------------------------------------------|
 | ![After exuecution](images/serial_number.png) |
 
-## 3. Usage
+### 2.3 Change title
+
+The following code update the page title.
+
+#### Pattern 1 (replace existing text partially)
+
+```Ruby
+page = Page.find page_id # API access
+print page.title # -> ABC\nDEF
+tp = page.properties["Title"]
+tp[1].text = "GHI"
+page.save # API access
+print page.title # -> ABC\nGHI
+```
+
+#### Pattern 2 (replace all text)
+
+```Ruby
+page = Page.new id: page_id, assign: [TitleProperty, "Title"]
+tp = page.properties["Title"]
+tp << TextObject.new("JKL")
+page.save # API access
+print page.title # -> JKL
+```
+
+## 3. Preparation
 
 ### 3.1 Create a New Integration
 
@@ -99,176 +165,152 @@ Please check [Notion documentation](https://developers.notion.com/docs#getting-s
 ### 3.2 Create client
 
 Please create a client (notion-ruby-client) before you use the following class.
+
 ```Ruby
 NotionCache.instance.create_client ENV["NOTION_API_TOKEN"]
 ```
 
-### 3.3 Retrieve a database
+## 4. Usage
+
+### 4.1 Page
+
+#### 4.1.1 Retrieve a page
 
-Database.find(id) creates a Database object from the results of Notion API.
+`Page.find(id)` creates a Page object with `retrieving page API`.
+The created object has page information generated from the JSON response.
 
 ```Ruby
-db = Database.find("c37a2c66-e3aa-4a0d-a447-73de3b80c253")
+page = Page.find "c01166c6-13ae-45cb-b968-18b4ef2f5a77" # Notion API call
 ```
 
-Database.new(id) creates a Database object without accessing to Notion.
-If you want to retrieve the contents after creation, please use a `reload` method.
+`Page.new(id)` creates a Page object without the Notion API.
+Since Page.new does not acquire property information, so you need to assign yourself.
 
 ```Ruby
-db = Database.new("c37a2c66-e3aa-4a0d-a447-73de3b80c253")
-db.reload
+# Assign some properties for update manually
+# The argument of assign keyword is Array with the multiple pairs of PropertyClass and Property name
+page = Page.new id: "c01166c6-13ae-45cb-b968-18b4ef2f5a77",
+                assign: [TitleProperty, "Title", NumberProperty, "NumberTitle"]
 ```
 
-### 3.4 Retrieve a page
+#### 4.1.2 Update page properties
 
-Page.find(id) creates a Page object from the results of Notion API.
+Page properties with values can be obtained from the retrieved page using `find`.
+On the other hand, Page properties without values can be obtained from the property assigned page.
 
 ```Ruby
-page = Page.find("c01166c6-13ae-45cb-b968-18b4ef2f5a77")
+tp = page.properties["Title"] # TitleProperty
+np = page.properties["Number"] # NumberProperty
 ```
 
-Page.new(id) creates a Page object without accessing to Notion.
-If you want to retrieve the contents after creation, please use a `reload` method.
+Each property object can change values using corresponded methods.
+After changing value, `will_update` flag of the property object also set to true.
+These methods are explained in the section of each property object class.
 
 ```Ruby
-page = Page.new("c01166c6-13ae-45cb-b968-18b4ef2f5a77")
-page.reload
+to = tp[1] # TitleProperty has Array of TextObject
+to.text = "ABC" # TextObject can set text by ".text="
+# or tp[1].text = "ABC"
+
+np.number = 3.14159
+page.save # Notion API call
 ```
 
-### 3.5 Query a database
+After update some properties, `page.save` method sends `Notion API` and replace the page information using the response of API.
 
-#### 3.5.1 A simple example
+```Ruby
+page.update # Notion API call
+```
+
+#### 4.1.3 Update other page information
+
+`page.set_icon` can change the page icon using emoji or external url.
+
+[Breaking change on v0.2.2] `page.set_icon` has no longer calling the Notion API.
+Please use `page.save` after `page.set_icon` if you want to update or create the page.
 
-Gets a List object of Page objects contained in the database.
-You can obtain filtered and ordered pages using Query object.
 ```Ruby
-Database.query("c37a2c66-e3aa-4a0d-a447-73de3b80c253") # retrieves all pages
-Database.query("c37a2c66-e3aa-4a0d-a447-73de3b80c253", query) # retrieves using query
+# both methods call Notion API
+obj.set_icon emoji: "💿" # set emoji
+obj.save
+
+obj.set_icon url: "https://cdn.profile-image.st-hatena.com/users/hkob/profile.png" # set external url
+obj.save
 ```
 
-Query object can be generated from the following Property objects.
-For example, in order to obtain the pages whose title starts with "A" and ordered by ascending,
-the following code can be used.
+#### 4.1.4 other methods
+
+- `page.save` call Notion API, and so on and replace object information.
+- `page.new_record?` returns true if the page was generated by `create_child_page`.
+- `page.title` returns plain_text string of `Title`.
+- `page.icon` returns JSON hash for the page icon.
+- `page[key]` returns a hash or an array object except "properties".
+
+### 4.2 Database
+
+#### 4.2.1 Retrieve a database
+
+`Database.find(id)` creates a Database object with `retrieving database API`.
+The created object has database information generated from the JSON response.
+
 ```Ruby
-tp = TitleProperty.new "Title"
-query = tp.filter_starts_with("A").ascending(tp)
-pages = Database.query database_id, query
+db = Database.find("c37a2c66-e3aa-4a0d-a447-73de3b80c253") # Notion API call
 ```
 
-#### 3.5.2 Property classes
+`Database.new(id)` creates a Database object without the Notion API.
+Since Database.new does not acquire property information, so you need to assign yourself.
 
-There are the following 17 XXXProperty classes corresponding to Notion databases.
-They are child classes of a `Property` class
-and these constructor method has a common form where the first argument is the property name.
 ```Ruby
-xp = XXXProperty.new "property name"
+# assign some properties for update manually
+db = Database.new id: "c37a2c66-e3aa-4a0d-a447-73de3b80c253",
+                assign: [TitleProperty, "Title", NumberProperty, "NumberTitle"]
 ```
 
-1. TitleProperty
-2. RichTextProperty
-3. UrlProperty
-4. EmailProperty
-5. PhoneNumberProperty
-6. NumberProperty
-7. CheckboxProperty
-8. SelectProperty
-9. MultiSelectProperty
-10. PeopleProperty
-11. CreatedByProperty
-12. LastEditedByProperty
-13. DateProperty
-14. CreatedTimeProperty
-15. LastEditedTimeProperty
-16. FilesProperty
-17. FormulaProperty
+#### 4.2.2 Query a database
 
-#### 3.5.3 Query object generator of property objects
+`db.query_database` obtains a List object with Page objects contained in the database.
+You can obtain filtered and ordered pages using Query object.
 
-The following methods for the Property objects generate a query object.
-- TitleProperty, RichTextProperty, UrlProperty, EmailProperty, PhoneNumberProperty
-  - filter_equals(value)
-  - filter_does_not_equal(value)
-  - filter_contains(value)
-  - filter_does_not_contain(value)
-  - filter_starts_with(value)
-  - filter_ends_with(value)
-  - filter_is_empty
-  - filter_is_not_empty
-- NumberProperty
-  - filter_equals(value)
-  - filter_does_not_equal(value)
-  - filter_greater_than(value)
-  - filter_less_than(value)
-  - filter_greater_than_or_equal_to(value)
-  - filter_less_than_or_equal_to(value)
-  - filter_is_empty
-  - filter_is_not_empty
-- CheckboxProperty
-  - filter_equals(value)
-  - filter_does_not_equal(value)
-- SelectProperty
-  - filter_equals(value)
-  - filter_does_not_equal(value)
-  - filter_is_empty
-  - filter_is_not_empty
-- MultiSelectProperty, PeopleProperty, CreatedByProperty, LastEditedByProperty
-  - filter_contains(value)
-  - filter_does_not_contain(value)
-  - filter_is_empty
-  - filter_is_not_empty
-- DateProperty, CreatedTimeProperty, LastEditedTimeProperty
-  - filter_equals(value(Date / Time / DateTime / String))
-  - filter_does_not_equal(value(Date / Time / DateTime / String))
-  - filter_before(value(Date / Time / DateTime / String))
-  - filter_after(value(Date / Time / DateTime / String))
-  - filter_on_or_before(value(Date / Time / DateTime / String))
-  - filter_on_or_after(value(Date / Time / DateTime / String))
-  - filter_past_week
-  - filter_past_month
-  - filter_past_year
-  - filter_next_week
-  - filter_next_month
-  - filter_next_year
-- FilesProperty
-  - filter_is_empty
-  - filter_is_not_empty
-- FormulaProperty
-  - filter_equals(value(Date / Time / DateTime / String))
-  - filter_does_not_equal(value(Date / Time / DateTime / String))
-  - filter_before(value(Date / Time / DateTime / String))
-  - filter_after(value(Date / Time / DateTime / String))
-  - filter_on_or_before(value(Date / Time / DateTime / String))
-  - filter_on_or_after(value(Date / Time / DateTime / String))
-  - filter_past_week
-  - filter_past_month
-  - filter_past_year
-  - filter_next_week
-  - filter_next_month
-  - filter_next_year
-  - filter_contains(value)
-  - filter_does_not_contain(value)
-  - filter_starts_with(value)
-  - filter_ends_with(value)
-  - filter_greater_than(value)
-  - filter_less_than(value)
-  - filter_greater_than_or_equal_to(value)
-  - filter_less_than_or_equal_to(value)
-  - filter_is_empty
-  - filter_is_not_empty
+```Ruby
+# query_database method calls Notion API
+db.query_database # retrieves all pages (no filter, no sort)
+db.query_database query # retrieves using query
+```
+
+The query object can be generated from the Property objects included in the database object.
+The Property object can be obtained from the retrieved or assigned database object like as the Page object.
+
+`filter_xxxx` methods of the property objects generates a query object.
+These methods are explained in the section of each property object class.
+
+```Ruby
+tp = db.properties["Title"]
+query = tp.filter_starts_with("A").ascending(tp)
+pages = db.query_database query
+```
 
-#### 3.5.4 Complex conditions
-Complex filters can be generated `and` / `or` methods.
+##### 4.2.2.1 Complex conditions
+
+Complex filters can be generated `and` / `or` methods of the Query object.
 Here are some sample scripts and the json parameters created from them.
 
 ```Ruby
 # Prepare some sample properties
-tp = TitleProperty.new "tp"
-np = NumberProperty.new "np"
-cp = CheckboxProperty.new "cp"
-letp = LastEditedTimeProperty.new "letp"
+db = Database.new id: "sample database id",
+                  assign: [
+                    TitleProperty, "tp",
+                    NumberProperty, "np",
+                    CheckboxProperty, "cp",
+                    LastEditedTimeProperty, "letp",
+                  ]
+properties = db.properties # PropertyCache object
+# PropertyCache object can receive [] or values_at methods.
+# `values_at` method is useful when retrieving multiple properties at once.
+(tp, np, cp, letp) = properties.values_at "tp", "np", "cp", "letp"
 ```
 
 - query1: (A and B) filter
+
 ```Ruby
 query1 = tp.filter_starts_with("start")
            .and(np.filter_greater_than(100))
@@ -289,6 +331,7 @@ query1 = tp.filter_starts_with("start")
 ```
 
 - query2: (A and B and C) filter
+
 ```Ruby
 query2 = tp.filter_starts_with("start")
   .and(np.filter_greater_than(100))
@@ -314,6 +357,7 @@ query2 = tp.filter_starts_with("start")
 ```
 
 - query3: (A or B) filter
+
 ```Ruby
 query3 = tp.filter_starts_with("start")
   .or(np.filter_greater_than(100))
@@ -334,6 +378,7 @@ query3 = tp.filter_starts_with("start")
 ```
 
 - query4: (A or B or C) filter
+
 ```Ruby
 query4 = tp.filter_starts_with("start")
       .or(np.filter_greater_than(100))
@@ -359,6 +404,7 @@ query4 = tp.filter_starts_with("start")
 ```
 
 - query5: ((A and B) or C) filter
+
 ```Ruby
 query5 = tp.filter_starts_with("start")
   .and(np.filter_greater_than(100))
@@ -388,6 +434,7 @@ query5 = tp.filter_starts_with("start")
 ```
 
 - query6: ((A or B) and C) filter
+
 ```Ruby
 query6 = tp.filter_starts_with("start")
   .or(np.filter_greater_than(100))
@@ -417,6 +464,7 @@ query6 = tp.filter_starts_with("start")
 ```
 
 - query7: ((A and B) or (C and D)) filter
+
 ```Ruby
 query7 = np.filter_greater_than(100).and(np.filter_less_than(200))
       .or(np.filter_greater_than(300).and(np.filter_less_than(400)))
@@ -452,11 +500,13 @@ query7 = np.filter_greater_than(100).and(np.filter_less_than(200))
 }
 ```
 
-#### 3.5.5 Sort criteria
+##### 4.2.2.2 Sort criteria
+
 Sort criteria can be appended to an existing query object.
 If you don't use the previous filters, you can generate by `Query.new`.
 
 - sort criteria only
+
 ```Ruby
 query8 = Query.new.ascending tp
 query9 = Query.new.ascending letp
@@ -484,6 +534,7 @@ query12 = Query.new.ascending(tp).descending letp
 ```
 
 - filter with sort
+
 ```Ruby
 query13 = tp.filter_starts_with("A").ascending(tp)
 
@@ -494,134 +545,195 @@ query13 = tp.filter_starts_with("A").ascending(tp)
 [{"property" => "tp", "direction" => "ascending"}]
 ```
 
-### 3.6 Access the database or page values and properties
+#### 4.2.3 Create child page
 
-Database or Page values can be accessed by [] access with keywords.
+`create_child_page` creates a child page object of the database.
 
 ```Ruby
-obj["icon"]
+page = db.create_child_page TitleProperty, "Name"
 ```
 
-Almost values returns a hash or an array object except "properties".
-`obj["properties"]` or `obj.properties` returns a PropertyCache object.
-The PropertyCache object is created from json information on the first access and is cached to the Page or Database object.
-If page or database object is generated by `.new` method, the object don't have json information.
-In this case, the `.properties` method calls `reload` method automatically, then it creates the PropertyCache object from the loaded json information (called auto-load function).
+#### 4.2.4 Update database
 
-```Ruby
-obj["properties"]
-# or
-obj.properties
-```
+=== under construction ===
 
-Each Property object is obtained by [] access with the property name.
-The Property object is also created on the first access and is cached to the PropertyCache object.
+### 4.3 List class
+
+`db.query_database` and other API list results returns a List object.
+The list object is an Enumerable object, so usually combines with `.each` method.
 
 ```Ruby
-np = obj.properties["NumberTitle"]
+db.query_database(query).each do |page|
+  # exec some methods for a page object
+end
 ```
 
-## 3.7 Set icon (Database / Page)
+Notion API returns only the first page-size objects.
+The default page-size of this library is 100.
+Since the above `.each` method is supported for paging, it will automatically execute API call that obtain the following 100 objects when you used the first 100 objects.
+Users do not have to worry about paging.
 
-Database or Page icon can update by `obj.set_icon` method.
-You can set icon as emoji or external url.
+### 4.4 Block class
 
-```Ruby
-obj.set_icon emoji: "💿" # set emoji
-obj.set_icon url: "https://cdn.profile-image.st-hatena.com/users/hkob/profile.png" # set external url
-```
+=== under construction ===
 
-## 3.8 Update page property values
+### 4.5 Property classes
 
-Page properties can update in the following three ways.
+#### 4.5.1 How to obtain Property object
 
-### 3.8.1 Assign property and update it (fastest: one API call only)
+There are the following 17 XXXProperty classes corresponding to Notion databases.
 
-This is the fastest way using an empty Page object.
-`page.assign_property` generates an empty PropertyCache and an empty XXXProperty.
-After updating the property value, please call `page.update`.
-Notion API will be called using a JSON payload generated from the PropertyCache object.
+1. TitleProperty
+2. RichTextProperty
+3. UrlProperty
+4. EmailProperty
+5. PhoneNumberProperty
+6. NumberProperty
+7. CheckboxProperty
+8. SelectProperty
+9. MultiSelectProperty
+10. PeopleProperty
+11. CreatedByProperty
+12. LastEditedByProperty
+13. DateProperty
+14. CreatedTimeProperty
+15. LastEditedTimeProperty
+16. FilesProperty
+17. FormulaProperty
+
+They are child classes of a `Property` class and generated from Page or Database objects.
 
 ```Ruby
-page = Page.new id: page_id
-property = page.assign_property NumberProperty, "NumberTitle"
-property.number = 2022
-page.update # update page API call
-print page
-```
+page = Page.new page_id, assign: [XXXProperty, "property_name"]
+# or
+page = Page.find page_id
 
-### 3.8.2 Update the loaded page (easy but slow: two API calls)
+xp = page.properties["property_name"]
+# or
+xp, yp = page.properties.values_at "xp_name", "yp_name"
+```
 
-This is an easiest way using a loaded Page object.
-A PropertyCache object is automatically generated by `page.properties`.
-After updating the property value, please call `page.update`.
-Notion API will be called using a JSON payload generated from the PropertyCache object.
-There are two API calls (find and update).
+#### 4.5.2 Query object generator of property objects
 
-```Ruby
-page = Page.find first_page_id # retrieve page API call
-property = page.properties["NumberTitle"]
-property.number = 2022
-page.update # update page API call
-print page
-```
+The following methods for the Property objects generate a query object.
 
-### 3.8.3 Update the unloaded page with auto-load (easy but slow: two API calls)
+- TitleProperty, RichTextProperty, UrlProperty, EmailProperty, PhoneNumberProperty
+  - filter_equals(value)
+  - filter_does_not_equal(value)
+  - filter_contains(value)
+  - filter_does_not_contain(value)
+  - filter_starts_with(value)
+  - filter_ends_with(value)
+  - filter_is_empty
+  - filter_is_not_empty
+- NumberProperty
+  - filter_equals(value)
+  - filter_does_not_equal(value)
+  - filter_greater_than(value)
+  - filter_less_than(value)
+  - filter_greater_than_or_equal_to(value)
+  - filter_less_than_or_equal_to(value)
+  - filter_is_empty
+  - filter_is_not_empty
+- CheckboxProperty
+  - filter_equals(value)
+  - filter_does_not_equal(value)
+- SelectProperty
+  - filter_equals(value)
+  - filter_does_not_equal(value)
+  - filter_is_empty
+  - filter_is_not_empty
+- MultiSelectProperty, PeopleProperty, CreatedByProperty, LastEditedByProperty
+  - filter_contains(value)
+  - filter_does_not_contain(value)
+  - filter_is_empty
+  - filter_is_not_empty
+- DateProperty, CreatedTimeProperty, LastEditedTimeProperty
+  - filter_equals(value(Date / Time / DateTime / String))
+  - filter_does_not_equal(value(Date / Time / DateTime / String))
+  - filter_before(value(Date / Time / DateTime / String))
+  - filter_after(value(Date / Time / DateTime / String))
+  - filter_on_or_before(value(Date / Time / DateTime / String))
+  - filter_on_or_after(value(Date / Time / DateTime / String))
+  - filter_past_week
+  - filter_past_month
+  - filter_past_year
+  - filter_next_week
+  - filter_next_month
+  - filter_next_year
+- FilesProperty
+  - filter_is_empty
+  - filter_is_not_empty
+- FormulaProperty
+  - filter_equals(value(Date / Time / DateTime / String))
+  - filter_does_not_equal(value(Date / Time / DateTime / String))
+  - filter_before(value(Date / Time / DateTime / String))
+  - filter_after(value(Date / Time / DateTime / String))
+  - filter_on_or_before(value(Date / Time / DateTime / String))
+  - filter_on_or_after(value(Date / Time / DateTime / String))
+  - filter_past_week
+  - filter_past_month
+  - filter_past_year
+  - filter_next_week
+  - filter_next_month
+  - filter_next_year
+  - filter_contains(value)
+  - filter_does_not_contain(value)
+  - filter_starts_with(value)
+  - filter_ends_with(value)
+  - filter_greater_than(value)
+  - filter_less_than(value)
+  - filter_greater_than_or_equal_to(value)
+  - filter_less_than_or_equal_to(value)
+  - filter_is_empty
+  - filter_is_not_empty
 
-This is also an easiest way using an auto-load function of the Page object.
-A PropertyCache object is automatically generated by `page.properties` using the auto-load function of page objects.
-After updating the property value, please call `page.update`.
-Notion API will be called using a JSON payload generated from the PropertyCache object.
-There are also two API calls (find and update).
+#### 4.5.3 create or update values for Page properties
 
-```Ruby
-page = Page.new id: first_page_id
-property = page.properties["NumberTitle"] # retrieve page API call (auto-load)
-property.number = 12345
-page.update # update page API call
-print page
-```
+Retrieving Page object has XXXProperties with values.
+On the other hand, Assigned Page object has also XXXProperties, but they don't have any information for pages.
 
-### 3.8.4 Explanation of how to update each property
+XXXProperties can change property values by setter methods.
+Since the setter method is different for each class, it will be explained separately.
 
-#### 3.8.4.1 NumberProperty
+##### 4.5.3.1 NumberProperty
 
 NumberProperty can set a number by `.number=`.
 
 ```Ruby
 np = page.properties["NumberTitle"]
-np.number = 456
-p np.create_json
-# Result => {"number" => 456}
+np.number = 3.14
+p np.property_values_json
+# Result => => {"np"=>{"number"=>3.14, "type"=>"number"}}
 ```
 
-#### 3.8.4.2 SelectProperty
+##### 4.5.3.2 SelectProperty
 
 NumberProperty can set a select name by `.select=`.
 
 ```Ruby
 sp = page.properties["SelectTitle"]
 sp.select = "Select 2"
-p sp.create_json
-# Result => {"select" => {"name" => "Select 2"}}
+p sp.property_values_json
+# Result => {"sp"=>{"type"=>"select", "select"=>{"name"=>"Select 2"}}}
 ```
 
-#### 3.8.4.3 MultiSelectProperty
+##### 4.5.3.3 MultiSelectProperty
 
 MultiSelectProperty can set a select value or Array of select values by `.multi_select=`.
 
 ```Ruby
 msp = page.properties["MultiSelectTitle"]
-msp.select = "MS2"
-p msp.create_json
-# Result => {"multi_select" => [{"name" => "MS2"}]}
+msp.multi_select = "MS2"
+p msp.property_values_json
+# Result => {"msp"=>{"type"=>"multi_select", "multi_select"=>[{"name"=>"MS2"}]}}
 
 msp.multi_select = %w[MS2 MS1]
-p msp.create_json
-# Result => {"multi_select" => [{"name" => "MS2"}, {"name" => "MS1"}]}
+p msp.property_values_json
+# Result => {"msp"=>{"type"=>"multi_select", "multi_select"=>[{"name"=>"MS2"}, {"name"=>"MS1"}]}}
 ```
 
-#### 3.8.4.4 DateProperty
+##### 4.5.3.4 DateProperty
 
 DateProperty can set a start_date or end_date by `.start_date=` or `end_date=`.
 Date, Time, DateTime or String object can be used to the argument.
@@ -629,48 +741,183 @@ Date, Time, DateTime or String object can be used to the argument.
 ```Ruby
 dp = page.properties["DateTitle"]
 dp.start_date = Date.new(2022, 2, 22)
-p dp.create_json
-# Result => {"start" => "2022-02-22"}
+p dp.property_values_json
+# Result => {"dp"=>{"type"=>"date", "date"=>{"start"=>"2022-02-22", "end"=>nil, "time_zone"=>nil}}}
 
 dp.start_date = Time.new(2022, 2, 22, 1, 23, 45, "+09:00")
-p dp.create_json
-# Result => {"start" => "2022-02-22T01:23:45+09:00"}
+p dp.property_values_json
+# Result =>{"dp"=>{"type"=>"date", "date"=>{"start"=>"2022-02-22T01:23:45+09:00", "end"=>nil, "time_zone"=>nil}}}
 
 dp.start_date = DateTime.new(2022, 2, 23, 1, 23, 45, "+09:00")
-p dp.create_json
-# Result => {"start" => "2022-02-23T01:23:45+09:00"}
+p dp.property_values_json
+# Result => {"dp"=>{"type"=>"date", "date"=>{"start"=>"2022-02-23T01:23:45+09:00", "end"=>nil, "time_zone"=>nil}}}
 
 dp.start_date = Date.new(2022, 2, 20)
 dp.end_date = Date.new(2022, 2, 22)
-p dp.create_json
-# Result => {"start" => "2022-02-20", "end" => "2022-02-22"}
+p dp.property_values_json
+# Result => => {"dp"=>{"type"=>"date", "date"=>{"start"=>"2022-02-20", "end"=>"2022-02-22", "time_zone"=>nil}}}
 
 dp.start_date = Time.new(2022, 2, 21, 1, 23, 45, "+09:00")
 dp.end_date = Time.new(2022, 2, 22, 1, 23, 45, "+09:00")
-p dp.create_json
+p dp.property_values_json
 # Result => {"start" => "2022-02-21T01:23:45+09:00", "end" => "2022-02-22T01:23:45+09:00"}
 
 dp.start_date = DateTime.new(2022, 2, 21, 1, 23, 45, "+09:00")
 dp.end_date = DateTime.new(2022, 2, 22, 1, 23, 45, "+09:00")
-p dp.create_json
-# result => {"start" => "2022-02-21T01:23:45+09:00", "end" => "2022-02-22T01:23:45+09:00"}
+p dp.property_values_json
+# result => {"dp"=>{"type"=>"date", "date"=>{"start"=>"2022-02-21T01:23:45+09:00", "end"=>nil, "time_zone"=>nil}}}
 ```
 
-### 3.9 Iteration of list object
+##### 4.5.3.4 UrlProperty
 
-Some methods like as `Database.query` return a list object.
-Since the list object also has a json array object, `Enumerable` module is implemented.
-Each iteration creates a Page or Block object and calls the block with it as an argument.
+UrlProperty can set a url by `.url=`.
 
 ```Ruby
-pages = Database.query("c37a2c66-e3aa-4a0d-a447-73de3b80c253") # retrieves all pages
-pages.each do |page| # obj's class is Page or Block
-  page.set_icon(emoji: "💿") unless page["icon"]
-end
+up = page.properties["UrlTitle"]
+up.url = "https://www.google.com/"
+p up.property_values_json
+# result => {"up"=>{"url"=>"https://www.google.com/", "type"=>"url"}}
+```
+
+##### 4.5.3.5 EmailProperty
+
+EmailProperty can set an email by `.email=`.
+
+```Ruby
+ep = page.properties["MailTitle"]
+ep.email = "https://www.google.com/"
+p ep.property_values_json
+# result => {"ep"=>{"email"=>"hkobhkob@gmail.com", "type"=>"email"}}
 ```
 
-## 4. ChangeLog
+##### 4.5.3.6 PhoneNumberProperty
+
+PhoneNumberProperty can set an phone number by `.phone_number=`.
+
+```Ruby
+pp = page.properties["TelTitle"]
+pp.phone_number = "xx-xxxx-xxxx"
+p pp.property_values_json
+# result => {"pp"=>{"phone_number"=>"xx-xxxx-xxxx", "type"=>"phone_number"}}
+```
+
+##### 4.5.3.7 PeopleProperty
+
+PeopleProperty can set an people by `.people=`.
+PeopleProperty can set a user_id/UserObject value or Array of user_id/UserObject values by `.people=`.
+
+```Ruby
+pp = page.properties["UserTitle"]
+pp.people = "user_id1"
+p pp.property_values_json
+# result => {"pp"=>{"type"=>"people", "people"=>[{"object"=>"user", "id"=>"user_id1"}]}}
+
+pp.people = UserObject.new json: user1_json
+p pp.property_values_json
+# result => {"pp"=>{"type"=>"people", "people"=>[{"object"=>"user", "id"=>"user_id1_from_json"}]}}
+```
+
+```Ruby
+pp.people = %w[user_id2 user_id3]
+p pp.property_values_json
+# result => {"pp"=>{"type"=>"people", "people"=>[{"object"=>"user", "id"=>"user_id2"}, {"object"=>"user", "id"=>"user_id3"}]}}
+
+u2 = UserObject.new(json: user2_json)
+u3 = UserObject.new(json: user3_json)
+pp.people = [u2, u3]
+p pp.property_values_json
+# result => {"pp"=>{"type"=>"people", "people"=>[{"object"=>"user", "id"=>"user_id2_from_json"}, {"object"=>"user", "id"=>"user_id3_from_json"}]}}
+```
+
+##### 4.5.3.8 TitleProperty, RichTextProperty
+
+TextProperty's subclasses (TitleProperty, RichTextProperty) have an array of TextObject objects.
+`[]` method returns an existing TextObject.
+The obtained TextObject can be set text by `.text=`.
+
+```Ruby
+pp = page.properties["Title"]
+tp[0].text = "ABC\n"
+p tp.property_values_json
+# result => {"tp"=>{"type"=>"title", "title"=>[{"type"=>"text", "text"=>{"content"=>"ABC\n", "link"=>nil}, "plain_text"=>"ABC\n", "href"=>nil}]}}
+```
+
+`<<` method appends a new TextObject or a String.
+```Ruby
+to = TextObject.new "DEF"
+to.bold = true
+to.italic = true
+to.strikethrough = true
+to.underline = true
+to.code = true
+to.color = "default"
+tp << to
+p tp.property_values_json
+# result => {"tp"=>{"type"=>"title","title"=>[{"type"=>"text","text"=>{"content"=>"ABC\n","link"=>nil},"plain_text"=>"ABC\n","href"=>nil},{"type"=>"text","text"=>{"content"=>"DEF","link"=>nil},"plain_text"=>"DEF","href"=>nil,"annotations"=>{"bold"=>true,"italic"=>true,"strikethrough"=>true,"underline"=>true,"code"=>true,"color"=>"default"}}]}}
+```
+
+`delete_at(index)` method remove a TextObject at index.
+```Ruby
+tp.delete_at 1
+tp << "GHI"
+p tp.property_values_json
+# result => {"tp"=>{"type"=>"title", "title"=>[{"type"=>"text", "text"=>{"content"=>"ABC\n", "link"=>nil}, "plain_text"=>"ABC\n", "href"=>nil}, {"type"=>"text", "text"=>{"content"=>"DEF", "link"=>nil}, "plain_text"=>"DEF", "href"=>nil, "annotations"=>{"bold"=>true, "italic"=>true, "strikethrough"=>true, "underline"=>true, "code"=>true, "color"=>"default"}}, {"type"=>"text", "text"=>{"content"=>"GHI", "link"=>nil}, "plain_text"=>"GHI", "href"=>nil}]}}
+```
+
+##### 4.5.3.9 CheckboxProperty
+
+PeopleProperty can set a boolean value by `.checkbox=`.
+```Ruby
+cp = page.properties["CheckboxTitle"]
+cp.checkbox = true
+p cp.property_values_json
+# result => {"cp"=>{"checkbox"=>true, "type"=>"checkbox"}}
+```
+
+##### 4.5.3.10 EmailProperty
+
+EmailProperty can set an email address by `.email=`.
+```Ruby
+ep = page.properties["MailTitle"]
+ep.email = "hkobhkob@gmail.com"
+p ep.property_values_json
+# result => {"ep"=>{"email"=>"hkobhkob@gmail.com", "type"=>"email"}}
+```
+
+##### 4.5.3.11 FilesProperty
+
+FilesProperty can set an external url or Array of external urls by `.files=`.
+
+```Ruby
+fp = page.properties["FilesTitle"]
+fp.files = "F1"
+p fp.property_values_json
+# Result => {"fp"=>{"files"=>[{"name"=>"F1", "type"=>"external", "external"=>{"url"=>"F1"}}], "type"=>"files"}}
+
+fp.files = %w[F2 F3]
+p fp.property_values_json
+# Result => {"fp"=>{"files"=>[{"name"=>"F2", "type"=>"external", "external"=>{"url"=>"F2"}}, {"name"=>"F3", "type"=>"external", "external"=>{"url"=>"F3"}}], "type"=>"files"}}
+```
+
+##### 4.5.3.12 RelationProperty
+
+RelationProperty can set an relation's page_id or Array of relation's page_ids by `.relation=`.
+
+```Ruby
+rp = page.properties["RelationTitle"]
+rp.relation = "R1"
+p rp.property_values_json
+# Result => {"rp"=>{"type"=>"relation", "relation"=>[{"id"=>"R1"}]}}
+
+rp.relation = %w[R2 R3]
+p rp.property_values_json
+# Result => {"rp"=>{"type"=>"relation", "relation"=>[{"id"=>"R2"}, {"id"=>"R3"}]}}
+```
+
+
+## 6. ChangeLog
 
+- 2022/3/14 Exclude notion-ruby-client, update Property values, update for Notion-Version 2022-02-22
 - 2022/2/25 add_property_for_update -> assign_property, update README.md
 - 2022/2/20 add support for MultiSelectProperty
 - 2022/2/19 add support for SelectProperty
@@ -681,18 +928,18 @@ end
 - 2022/2/13 added Page#set_icon
 - 2022/2/13 First commit
 
-## 5. Contributing
+## 6. Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/hkob/notion_ruby_mapping. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/notion_ruby_mapping/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at <https://github.com/hkob/notion_ruby_mapping>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/notion_ruby_mapping/blob/main/CODE_OF_CONDUCT.md).
 
-## 6. License
+## 7. License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## 7. Code of Conduct
+## 8. Code of Conduct
 
 Everyone interacting in the NotionRubyMapping project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/notion_ruby_mapping/blob/main/CODE_OF_CONDUCT.md).
 
-## 8. Acknowledgements
+## 9. Acknowledgements
 
 The code depends on [notion-ruby-client](https://github.com/orbit-love/notion-ruby-client).