Links (Block base class)
PageBookmarkBlockCodeBlockEmbedBlockHeading2BlockLinkToPageBlockQuoteBlockToDoBlockToggleHeading3Block
DatabaseBreadcrumbBlockColumnBlockEquationBlockHeading3BlockNumberedListItemBlockSyncedBlockToggleBlockVideoBlock
↑ Table of Contents
1. Singleton methodsself.find(id, dry_run: false)2. Instance methodsadd_property(klass, title)build_child_page { |p, pc| ... } → create_child_page(dry_run: false) { |p, pc| ... } → created_time → CreatedTimePropertydatabase_title → RichTextArraydescription → RichTextArraydescription=(text_info)is_inline → Booleanis_inline=(flag)icon → Hashlast_edited_time → LastEditedTimePropertynew_record? → Boolean, NilClassproperties → PropertyCachequery_database(query = nil, dry_run: false) → ListA: overviewB: complex conditionsC: Sort criteriaD: Dry run sampleremove_properties(*property_names) → Arrayrename_property(old_property_name, new_property_name) → save(dry_run: false) → set_icon(emoji: nil, url: nil)
1. Singleton methods
self.find(id, dry_run: false)
- [PARAM] id database_id (String)
- [PARAM(optional)] dry_run: true if you want to create a verification script (Boolean)
- [EXCEPTION] StandardError throw StandardError when the database is not found.
Database.find(id) creates a Database object with retrieving database API. The created object has database information generated from the JSON response.Database.find "c37a2c66-e3aa-4a0d-a447-73de3b80c253" # Notion API call # => #<NotionRubyMapping::Database:...> # retrieved Database object
Database.find id, dry_run: true creates shell script using Retrieve a database API for verification.Database.find "c37a2c66-e3aa-4a0d-a447-73de3b80c253", dry_run: true # => # #!/bin/sh # curl '<https://api.notion.com/v1/databases/c37a2c66-e3aa-4a0d-a447-73de3b80c253>'\\ # -H 'Notion-Version: 2022-02-22'\\ # -H 'Authorization: Bearer '"$NOTION_API_KEY"''\\ # -H 'Content-Type: application/json'
2. Instance methods
add_property(klass, title)
- [PARAM] klass klass (child class of Property)
- [PARAM] title property title (String)
add_property adds a database property. After setting the property, please call db.save to send database information to Notion.db = Database.find "c7697137d49f49c2bbcdd6a665c4f921" db.add_property NumberProperty, "added number property" do |np| np.format = "euro" # arrange option end db.add_property UrlProperty, "added url property" # UrlProperty has no option db.save # => #<NotionRubyMapping::Database:...> # updated Database object
db.save dry_run: true creates a shell script for verification (Update database API using database_id as parent)db = Database.find "c7697137d49f49c2bbcdd6a665c4f921" db.add_property NumberProperty, "added number property" do |np| np.format = "euro" # arrange option end db.add_property UrlProperty, "added url property" # UrlProperty has no option db.save dry_run: true # => # #!/bin/sh # curl -X PATCH '<https://api.notion.com/v1/databases/c7697137d49f49c2bbcdd6a665c4f921>'\\ # -H 'Notion-Version: 2022-02-22'\\ # -H 'Authorization: Bearer '"$NOTION_API_KEY"''\\ # -H 'Content-Type: application/json'\\ # --data '{"properties":{"added number property":{"number":{"format":"euro"}},"added url property":{"url":{}}}}'
build_child_page { |p, pc| ... } → Page
[Breaking change on v0.4.0]
For compatibility with Rails,
create_child_page is renamed to build_child_page. create_child_page calls build_child_page and save.build_child_page creates a child page object of the database. After setting some properties, please call page.save to send page information to Notion. Properties of the created child page are automatically assigned using the parent database. if a block is provided, the method will yield the new Page object(p) and the properties (PropertyCache object pc) to that block for initialization.page = db.create_child_page do |p, pc| # p is the new Page object # pc is the properties of the new Page object (PropertyCache Object) p.set_icon emoji: "🎉" pc["Title"] << "New Page" end page.save # => #<NotionRubyMapping::Page:...> # Page object generated from response from Notion (created Page)
page.save dry_run: true creates a shell script for verification (Create a page API using database_id as parent)page = db.create_child_page do |p, pc| p.set_icon emoji: "🎉" pc["Title"] << "New Page" end page.save dry_run: true # => # #!/bin/sh # curl -X POST 'https://api.notion.com/v1/pages' \ # -H 'Notion-Version: 2022-02-22' \ # -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ # -H 'Content-Type: application/json' \ # --data '{"properties":{"Title":{"type":"title","title":[{"type":"text","text":{"content":"New Page","link":null},"plain_text":"New Page","href":null}]}},"parent":{"database_id":"c37a2c66e3aa4a0da44773de3b80c253"},"icon":{"type":"emoji","emoji":"🎉"}}'
create_child_page(dry_run: false) { |p, pc| ... } → Page
[Breaking change on v0.4.0]
For compatibility with Rails,
create_child_page is renamed to build_child_page. create_child_page calls build_child_page and save.create_child_page creates a child page object of the database and send to Notion. Properties of the created child page are automatically assigned using the parent database. if a block is provided, the method will yield the new Page object (p) and the properties (PropertyCache object pc) to that block for initialization.page = db.create_child_page do |p, pc| # p is the new Page object # pc is the properties of the new Page object (PropertyCache Object) p.set_icon emoji: "🎉" pc["Title"] << "New Page" end # => #<NotionRubyMapping::Page:...> # Page object generated from response from Notion (created Page)
create_child_page dry_run: true creates a shell script for verification (Create a page API using database_id as parent)spage = db.create_child_page dry_run: true do |p, pc| p.set_icon emoji: "🎉" pc["Title"] << "New Page" end # => # #!/bin/sh # curl -X POST 'https://api.notion.com/v1/pages' \ # -H 'Notion-Version: 2022-02-22' \ # -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ # -H 'Content-Type: application/json' \ # --data '{"properties":{"Title":{"type":"title","title":[{"type":"text","text":{"content":"New Page","link":null},"plain_text":"New Page","href":null}]}},"parent":{"database_id":"c37a2c66e3aa4a0da44773de3b80c253"},"icon":{"type":"emoji","emoji":"🎉"}}'
created_time → CreatedTimeProperty
created_time returns the CreatedTimeProperty object for querying database. db.created_time # => #<NotionRubyMapping::CreatedTimeProperty:...> # CreatedTimeProperty object
database_title → RichTextArray
database_title returns a RichTextArray object of the database’s title.db.database_title # => #<NotionRubyMapping::RichTextArray:0x0000000108d7d468>
description → RichTextArray
description returns a RichTextArray object of the database’s description.db.description # => #<NotionRubyMapping::RichTextArray:0x0000000108bb0130>
description=(text_info)
- [PARAM] text_info
- a String like as “text” (String)
- an Array of Strings (Array of Strings)
- a RichTextObject (RichTextObject)
- an Array of RichTextObjects (Array of RichTextObjects)
- a RichTextArray (RichTextArray)
The following objects are used for this argument.
description=(text_info) updates the database description using a text_info.db.description = "another description" db.update_property_schema_json # => {"description"=>[{"type"=>"text", "text"=>{"content"=>"another description", "link"=>nil}, "plain_text"=>"another description", "href"=>nil}]}
is_inline → Boolean
is_inline returns the value true if the database appears in the page as an inline block.db.is_inline # => true
is_inline=(flag)
is_inline=(flag) updates the database inline flag a flag value.db.is_inline = true db.update_property_schema_json # => {"is_inline"=>true}
icon → Hash
icon returns JSON hash for the page icon.db.icon # => {"type"=>"emoji", "emoji"=>"🎉"}
last_edited_time → LastEditedTimeProperty
last_edited_time returns theLastEditedTimeProperty object for querying database. db.last_edited_time # => #<NotionRubyMapping::LastEditedTimeProperty:...> # LastEditedTimeProperty object
new_record? → Boolean, NilClass
new_record? returns true if the page is generated by create_child_database.db.new_record? # => nil
properties → PropertyCache
properties returns a PropertyCache object. Eacg Database property object can be obtained from PropertyCache object by [] method.db.properties db.properties # => #<NotionRubyMapping::PropertyCache:...> db.properties["Number"] # => #<NotionRubyMapping::NumberProperty:...>
query_database(query = nil, dry_run: false) → List
- [PARAM(optional)] query Query object including filter condtions and sort criteria. If no query is given, all pages are retrieved. (Query)
- [PARAM(optional)] dry_run: true if you want to create a verification script (Boolean)
A: overview
db.query_database obtains a List object with Page objects contained in the database. You can obtain filtered and ordered pages using Query object.# query_database method calls Notion API db.query_database # retrieves all pages (no filter, no sort) # => #<NotionRubyMapping::List:...> db.query_database query # retrieves using query # => #<NotionRubyMapping::List:...>
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.tp = db.properties["Title"] query = tp.filter_starts_with("A").ascending(tp) pages = db.query_database query # => #<NotionRubyMapping::List:...>
B: 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.# Prepare some sample properties 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
query1 = tp.filter_starts_with("start") .and(np.filter_greater_than(100)) query1.filter # => # { # "and" => [ # { # "property" => "tp", # "title" => {"starts_with" => "start"}, # }, # { # "property" => "np", # "number" => {"greater_than" => 100}, # }, # ], # }
- query2: (A and B and C) filter
query2 = tp.filter_starts_with("start") .and(np.filter_greater_than(100)) .and(cp.filter_equals(true)) query2.filter # => # { # "and" => [ # { # "property" => "tp", # "title" => {"starts_with" => "start"}, # }, # { # "property" => "np", # "number" => {"greater_than" => 100}, # }, # { # "property" => "cp", # "checkbox" => {"equals" => true}, # }, # ], # }
- query3: (A or B) filter
query3 = tp.filter_starts_with("start") .or(np.filter_greater_than(100)) query3.filter # => # { # "or" => [ # { # "property" => "tp", # "title" => {"starts_with" => "start"}, # }, # { # "property" => "np", # "number" => {"greater_than" => 100}, # }, # ], # }
- query4: (A or B or C) filter
query4 = tp.filter_starts_with("start") .or(np.filter_greater_than(100)) .or(cp.filter_equals(true)) query4.filter # => # { # "or" => [ # { # "property" => "tp", # "title" => {"starts_with" => "start"}, # }, # { # "property" => "np", # "number" => {"greater_than" => 100}, # }, # { # "property" => "cp", # "checkbox" => {"equals" => true}, # }, # ], # }
- query5: ((A and B) or C) filter
query5 = tp.filter_starts_with("start") .and(np.filter_greater_than(100)) .or(cp.filter_equals(true)) query5.filter # => # { # "or" => [ # { # "and" => [ # { # "property" => "tp", # "title" => {"starts_with" => "start"}, # }, # { # "property" => "np", # "number" => {"greater_than" => 100}, # }, # ], # }, # { # "property" => "cp", # "checkbox" => {"equals" => true}, # }, # ], # }
- query6: ((A or B) and C) filter
query6 = tp.filter_starts_with("start") .or(np.filter_greater_than(100)) .and(cp.filter_equals(true)) query6.filter # => # { # "and" => [ # { # "or" => [ # { # "property" => "tp", # "title" => {"starts_with" => "start"}, # }, # { # "property" => "np", # "number" => {"greater_than" => 100}, # }, # ], # }, # { # "property" => "cp", # "checkbox" => {"equals" => true}, # }, # ], # }
- query7: ((A and B) or (C and D)) filter
query7 = np.filter_greater_than(100).and(np.filter_less_than(200)) .or(np.filter_greater_than(300).and(np.filter_less_than(400))) query7.filter # => # { # "or" => [ # { # "and" => [ # { # "property" => "np", # "number" => {"greater_than" => 100}, # }, # { # "property" => "np", # "number" => {"less_than" => 200}, # }, # ], # }, # { # "and" => [ # { # "property" => "np", # "number" => {"greater_than" => 300}, # }, # { # "property" => "np", # "number" => {"less_than" => 400}, # }, # ], # }, # ], # }
C: 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
query8 = Query.new.ascending tp query9 = Query.new.ascending letp query10 = Query.new.descending tp query11 = Query.new.descending letp query12 = Query.new.ascending(tp).descending letp query8.sort # => [{"property" => "tp", "direction" => "ascending"}] query9.sort # => [{"timestamp" => "letp", "direction" => "ascending"}] query10.sort # => [{"property" => "tp", "direction" => "descending"}] query11.sort # => [{"timestamp" => "letp", "direction" => "descending"}] query12.sort # => # [ # {"property" => "tp", "direction" => "ascending"}, # {"timestamp" => "letp", "direction" => "descending"}, # ]
- filter with sort
query13 = tp.filter_starts_with("A").ascending(tp) query13.filter # => {"property" => "tp", "title" => {"starts_with" => "start"}} query13.sort # => [{"property" => "tp", "direction" => "ascending"}]
D: Dry run sample
This is a sample script for query database. If dry_run flag is set, you can see the verification shell script.
db = Database.new id: "c37a2c66-e3aa-4a0d-a447-73de3b80c253", assign: [NumberProperty, "NumberTitle", UrlProperty, "UrlTitle"] np, up = db.properties.values_at "NumberTitle", "UrlTitle" query = np.filter_greater_than(100).and(up.filter_starts_with("https")).ascending(np) print db.query_database query, dry_run: true # => # #!/bin/sh # curl -X POST 'https://api.notion.com/v1/databases/c37a2c66e3aa4a0da44773de3b80c253/query' \ # -H 'Notion-Version: 2022-02-22' \ # -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ # -H 'Content-Type: application/json' \ # --data '{"filter":{"and":[{"property":"NumberTitle","number":{"greater_than":100}},{"property":"UrlTitle","url":{"starts_with":"https"}}]},"sorts":[{"property":"NumberTitle","direction":"ascending"}],"page_size":100}'
remove_properties(*property_names) → Array
- [PARAM] property_names: property names that you want to remove
remove_properties sets a remove flag for the property objects corresponding to the specified names. After setting the remove flags of some properties, please call page.save to send page information to Notion. db.remove_properties "Number", "Formula" print db.save # => #<NotionRubyMapping::Database:...> # Database object with NumberProperty and FormulaProperty removed.
db.save dry_run: true creates a shell script for verification (Update database API)db.remove_properties "Number" print db.save dry_run: true # => # #!/bin/sh # curl -X PATCH 'https://api.notion.com/v1/databases/c7697137d49f49c2bbcdd6a665c4f921' \ # -H 'Notion-Version: 2022-02-22' \ # -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ # -H 'Content-Type: application/json' \ # --data '{"properties":{"Number":null}}'
rename_property(old_property_name, new_property_name) → Database
rename_property sets a rename flag for the property objects corresponding to the specified old name. After setting the rename flags of some properties, please call page.save to send page information to Notion.db.rename_property "added number property", "renamed number property" db.rename_property "added url property", "renamed url property" db.save # => #<NotionRubyMapping::Database:...> # Database object with NumberProperty and UrlProperty renamed.
- result of dry run
db.rename_property "added number property", "renamed number property" db.rename_property "added url property", "renamed url property" db.save # => # #!/bin/sh # curl -X PATCH '<https://api.notion.com/v1/databases/c7697137d49f49c2bbcdd6a665c4f921>'\\ # -H 'Notion-Version: 2022-02-22'\\ # -H 'Authorization: Bearer '"$NOTION_API_KEY"''\\ # -H 'Content-Type: application/json'\\ # --data '{"properties":{"added number property":{"name":"renamed number property"},"added url property":{"name":"renamed url property"}}}'
save(dry_run: false) → Database
- [PARAM(optional)] dry_run: true if you want to create a verification script
save method updates existing database properties. The database needs to be retrieved using find to prevent existing settings from disappearing.db = Database.find "c7697137d49f49c2bbcdd6a665c4f921" fp, msp, np, rp, rup, sp = db.properties.values_at "Formula", "MultiSelect", "Number", "Relation", "Rollup", "Select" fp.formula_expression = "pi" msp.add_multi_select_options name: "MS3", color: "blue" np.format = "percent" rp.replace_relation_database database_id: TestConnection::DATABASE_ID, synced_property_name: "Renamed table" rup.function = "average" sp.add_select_options name: "S3", color: "red" db.set_icon emoji: "🎉" db.database_title << "(Added)" db.save # => #<NotionRubyMapping::Database:...> # updated Database object
db.save dry_run: true creates a shell script for verification (Update database API)db = Database.find "c7697137d49f49c2bbcdd6a665c4f921" np, rup = db.properties.values_at "Number", "Rollup" np.format = "percent" rup.function = "average" print db.save dry_run: true # => #!/bin/sh # curl -X PATCH 'https://api.notion.com/v1/databases/c7697137d49f49c2bbcdd6a665c4f921' \ # -H 'Notion-Version: 2022-02-22' \ # -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ # -H 'Content-Type: application/json' \ # --data '{"properties":{"Rollup":{"rollup":{"function":"average","relation_property_name":"Relation","rollup_property_name":"NumberTitle"}},"Number":{"number":{"format":"percent"}}}}'
set_icon(emoji: nil, url: nil)
- [PARAM(optional)] emoji
- emoji string (String)
- [PARAM(optional)] url
- external url (String)
set_icon can change the page icon using emoji or external url.# 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