HomeAboutMeBlogGuest
© 2025 Sejin Cha. All rights reserved.
Built with Next.js, deployed on Vercel
📌
hkob's Notion/
NotionRubyMapping idea note
NotionRubyMapping idea note/
Notion Ruby Mapping Public API Reference
Notion Ruby Mapping Public API Reference/
🧱
DataSource 🆕 
🧱

DataSource 🆕 

1. Class methods

self.find(id, dry_run: false)

  • [PARAM] id data_source_id (String)
  • [PARAM(optional)] dry_run: true if you want to create a verification script (Boolean)
  • [EXCEPTION] StandardError throw StandardError when the data_source is not found.
DataSource.find(id) creates a DataSource object with retrieving data source API. The created object has data source information generated from the JSON response.
DataSource.find id, dry_run: true creates shell script using Retrieve a data source API for verification.

2. Instance methods

add_property(klass, title)

  • [PARAM] klass klass (child class of Property)
  • [PARAM] title property title (String)
add_property adds a data source property. After setting the property, please call ds.save to send data source information to Notion.
ds.save dry_run: true creates a shell script for verification (Update data source API using data_source_id as parent)

build_child_page(template_page: nil) { |p, pc| ... } →
🧱
Page

build_child_page creates a child page object of the data source. 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 data source. 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. By setting the template_page option, you can apply a template when creating a page. The value is either the string "default" or a Page object of the retrieved template page.
page.save dry_run: true creates a shell script for verification (Create a page API using data_source_id as parent)

create_child_page(template_page: nil, dry_run: false) { |p, pc| ... } →
🧱
Page

create_child_page creates a child page object of the data source and send to Notion. Properties of the created child page are automatically assigned using the parent data source. 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. By setting the template_page option, you can apply a template when creating a page. The value is either the string "default" or a Page object of the retrieved template page.
create_child_page dry_run: true creates a shell script for verification (Create a page API using data_source_id as parent)

created_time → CreatedTimeProperty

created_time returns the CreatedTimeProperty object for querying data source.

data_source_title → RichTextArray

data_source_title returns a RichTextArray object of the data source’s title.

description → RichTextArray

description returns a RichTextArray object of the data source’s description.

description=(text_info)

  • [PARAM] text_info
      • 📃
      The following objects are used for this argument.
      • 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)
description=(text_info) updates the data source description using a text_info.

is_inline → Boolean

is_inline returns the value true if the data source appears in the page as an inline block.

is_inline=(flag)

is_inline=(flag) updates the data source inline flag a flag value.

icon → Hash

icon returns JSON hash for the page icon.

last_edited_time → LastEditedTimeProperty

last_edited_time returns the LastEditedTimeProperty object for querying data source.

new_record? → Boolean, NilClass

new_record? returns true if the page is generated by create_child_data_source.

properties → PropertyCache

properties returns a PropertyCache object. Each DataSource property object can be obtained from PropertyCache object by [] method.

query_data_source(query = nil, dry_run: false) → List

  • [PARAM(optional)] query Query object including filter conditions 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

ds.query_data_source obtains a List object with Page objects contained in the data source. You can obtain filtered and ordered pages using Query object.
The query object can be generated from the Property objects included in the data source object. The Property object can be obtained from the retrieved or assigned data source 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.

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.
  1. query1: (A and B) filter
  1. query2: (A and B and C) filter
  1. query3: (A or B) filter
  1. query4: (A or B or C) filter
  1. query5: ((A and B) or C) filter
  1. query6: ((A or B) and C) filter
  1. query7: ((A and B) or (C and D)) filter

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.
  1. sort criteria only
  1. filter with sort

D: Dry run sample

This is a sample script for query data source. If dry_run flag is set, you can see the verification shell script.

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 ds.save to send data source information to Notion.
ds.save dry_run: true creates a shell script for verification (Update data source API)

rename_property(old_property_name, new_property_name) →
🧱
DataSource 🆕 

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 ds.save to send data source information to Notion.
  • result of dry run

save(dry_run: false) →
🧱
DataSource 🆕 

  • [PARAM(optional)] dry_run: true if you want to create a verification script
save method updates existing data source properties. The data source needs to be retrieved using find to prevent existing settings from disappearing.
ds.save dry_run: true creates a shell script for verification (Update data source API)

set_cover(url: nil, file_upload_object: nil)

  • [PARAM(optional)] a_url
    • external url (String)
  • [PARAM(optional)] a_fuo
    • file upload object (FileUploadObject)
set_cover can change the page cover using external url or file upload object.

set_icon(emoji: nil, url: nil, file_upload_object: nil)

  • [PARAM(optional)] an_emoji
    • emoji string (String)
  • [PARAM(optional)] a_url
    • external url (String)
  • [PARAM(optional)] a_fuo
    • file upload object (FileUploadObject)
set_icon can change the page icon using emoji, external url, or file upload object.
 
ds = DataSource.find "26cd8e4e98ab81d08983000b28d9e04d" # Notion API call
# => NotionRubyMapping::DataSource-26cd8e4e98ab81d08983000b28d9e04d # retrieved DataSource object
print DataSource.find "26cd8e4e98ab81d08983000b28d9e04d", dry_run: true
# #!/bin/sh
# curl -X GET 'https://api.notion.com/v1/data_sources/26cd8e4e98ab81d08983000b28d9e04d''' \
#   -H 'Notion-Version: 2025-09-03' \
#   -H 'Authorization: Bearer '"$NOTION_API_KEY"''
# => nil
ds = DataSource.find "26cd8e4e98ab81d08983000b28d9e04d" # Notion API call
ds.add_property NumberProperty, "added number property" do |np|
  np.format = "euro" # arrange option
end
ds.add_property UrlProperty, "added url property" # UrlProperty has no option
ds.save
# => NotionRubyMapping::DataSource-26cd8e4e98ab81d08983000b28d9e04d
ds = DataSource.find "26cd8e4e98ab81d08983000b28d9e04d" # Notion API call
ds.add_property NumberProperty, "added number property" do |np|
  np.format = "euro" # arrange option
end
ds.add_property UrlProperty, "added url property" # UrlProperty has no option
print ds.save dry_run: true
# #!/bin/sh
# curl -X PATCH 'https://api.notion.com/v1/data_sources/26cd8e4e98ab81d08983000b28d9e04d''' \
#   -H 'Notion-Version: 2025-09-03' \
#   -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
#   -H 'Content-Type: application/json' \
#   --data '{"properties":{"added number property":{"number":{"format":"euro"}},"added url property":{"url":{}}}}'
# => nil
page = ds.build_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 = ds.build_child_page(template_page: "default") 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)
template_page = Page.find "template_page_id"
page = ds.build_child_page(template_page: tempalte_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 = ds.build_child_page(dry_run: true) do |p, pc|
  p.set_icon emoji: "🎉"
  pc["Title"] << "New Page"
end
print page.save dry_run: true
# #!/bin/sh
# curl -X POST 'https://api.notion.com/v1/pages''' \
#   -H 'Notion-Version: 2025-09-03' \
#   -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
#   -H 'Content-Type: application/json' \
#   --data '{"parent":{"data_source_id":"26cd8e4e98ab81d08983000b28d9e04d"}}'
# => nil
page = ds.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)
page = ds.create_child_page(template_page: "default") 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)
template_page = Page.find "template_page_id"
page = ds.create_child_page(template_page: template_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)
print ds.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: 2025-09-03' \
#   -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
#   -H 'Content-Type: application/json' \
#   --data '{"parent":{"data_source_id":"26cd8e4e98ab81d08983000b28d9e04d"}}'
# => nil
ds.created_time
# => #<NotionRubyMapping::CreatedTimeProperty:...> # CreatedTimeProperty object
ds.data_source_title
# => #<NotionRubyMapping::RichTextArray:...>
ds.description
# => #<NotionRubyMapping::RichTextArray:...>
ds.description = "another description"
ds.update_property_schema_json
# => {"description"=>[{"type"=>"text", "text"=>{"content"=>"another description", "link"=>nil}, "plain_text"=>"another description", "href"=>nil}]}
ds.is_inline
# => true
ds.is_inline = true
ds.update_property_schema_json
# => {"is_inline"=>true}
ds.icon
# => {"type"=>"emoji", "emoji"=>"🎉"}
ds.last_edited_time
# => #<NotionRubyMapping::LastEditedTimeProperty:...> # LastEditedTimeProperty object
ds.new_record?
# => nil
ds.properties
# => #<NotionRubyMapping::PropertyCache:...>

ds.properties["Number"]
# => #<NotionRubyMapping::NumberProperty:...>
# query_data_source method calls Notion API
ds.query_data_source # retrieves all pages (no filter, no sort)
# => #<NotionRubyMapping::List:...>

ds.query_data_source query # retrieves using query
# => #<NotionRubyMapping::List:...>
tp = ds.properties["Title"]
query = tp.filter_starts_with("A").ascending(tp)
pages = ds.query_data_source query
# => #<NotionRubyMapping::List:...>
# Prepare some sample properties
ds = DataSource.new id: "sample data source id",
                  assign: [
                    TitleProperty, "tp",
                    NumberProperty, "np",
                    CheckboxProperty, "cp",
                    LastEditedTimeProperty, "letp",
                  ]
properties = ds.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 = 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 = 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 = 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 = 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 = 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 = 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 = 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}},
#   ]},
# ]}
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"},
# ]
query13 = tp.filter_starts_with("A").ascending(tp)

query13.filter
# => {"property" => "tp", "title" => {"starts_with" => "start"}}

query13.sort
# => [{"property" => "tp", "direction" => "ascending"}]
ds = DataSource.new id: "c37a2c66-e3aa-4a0d-a447-73de3b80c253", assign: [NumberProperty, "NumberTitle", UrlProperty, "UrlTitle"]
np, up = ds.properties.values_at "NumberTitle", "UrlTitle"
query = np.filter_greater_than(100).and(up.filter_starts_with("https")).ascending(np)
print ds.query_data_source 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}'
ds.remove_properties "Number"
print ds.save
# => #<NotionRubyMapping::DataSource:...> # DataSource object with NumberProperty removed.
ds.remove_properties "Number"
print ds.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}}'
ds.rename_property "added number property", "renamed number property"
ds.rename_property "added url property", "renamed url property"
ds.save
# => #<NotionRubyMapping::DataSource:...> # DataSource object with NumberProperty and UrlProperty renamed.
print ds.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":{"name":"renamed number property"},"added url property":{"name":"renamed url property"}}}'
ds = DataSource.find "c7697137d49f49c2bbcdd6a665c4f921"
fp, msp, np, rp, rup, sp = ds.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_data_source data_source_id: TestConnection::DATA_SOURCE_ID, synced_property_name: "Renamed table"
rup.function = "average"
sp.add_select_options name: "S3", color: "red"
ds.set_icon emoji: "🎉"
ds.data_source_title << "(Added)"
ds.save
# => #<NotionRubyMapping::DataSource:...> # updated DataSource object
ds = DataSource.find "c7697137d49f49c2bbcdd6a665c4f921"
np, rup = ds.properties.values_at "Number", "Rollup"
np.format = "percent"
rup.function = "average"
print ds.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"}}}}'
obj.set_cover url: "https://example.com/sample.png" # set external url
obj.save

fuo = FileUploadObject.new fname: "sample.png"
obj.set_cover file_upload_object: fuo
obj.save
obj.set_icon emoji: "💿" # set emoji
obj.save

obj.set_icon url: "https://example.com/icon.png" # set external url
obj.save

fuo = FileUploadObject.new fname: "sample.png"
obj.set_icon file_upload_object: fuo
obj.save