ActiveRecord::Bitemporal

Installation

Add this line to your application's Gemfile:

gem 'activerecord-bitemporal'

And then execute:

$ bundle

Or install it yourself as:

$ gem install activerecord-bitemporal

概要

activerecord-bitemporal は Rails の ActiveRecord で Bitemporal Data Model を扱うためのライブラリになります。 activerecord-bitemporal では、モデルを生成すると

employee = nil
# MEMO: データをわかりやすくする為に時間を固定
#       2019/1/10 にレコードを生成する
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

以下のようなレコードが生成されます。

id	bitemporal_id	emp_code	name	valid_from	valid_to	transaction_from	transaction_to
1	1	001	Jane	2019-01-10	9999-12-31	2019-01-10	9999-12-31

そのモデルに対して更新を行うと

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/15") {
  # 更新する
  employee.update(name: "Tom")
}

次のような履歴レコードが暗黙的に生成されます。

id	bitemporal_id	emp_code	name	valid_from	valid_to	transaction_from	transaction_to
1	1	001	Jane	2019-01-10	9999-12-31	2019-01-10	2019-01-15
2	1	001	Jane	2019-01-10	2019-01-15	2019-01-15	9999-12-31
3	1	001	Tom	2019-01-15	9999-12-31	2019-01-15	9999-12-31

更に更新すると

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/15") {
  employee.update(name: "Tom")
}

Timecop.freeze("2019/1/20") {
  # 更に更新
  employee.update(name: "Kevin")
}

更新する度にどんどん履歴レコードが増えていきます。

id	bitemporal_id	emp_code	name	valid_from	valid_to	transaction_from	transaction_to
1	1	001	Jane	2019-01-10	9999-12-31	2019-01-10	2019-01-15
2	1	001	Jane	2019-01-10	2019-01-15	2019-01-15	9999-12-31
3	1	001	Tom	2019-01-15	9999-12-31	2019-01-15	2019-01-20
4	1	001	Tom	2019-01-15	2019-01-20	2019-01-20	9999-12-31
5	1	001	Kevin	2019-01-20	9999-12-31	2019-01-20	9999-12-31

また、レコードを読み込む場合は暗黙的に『一番最新のレコード』を参照します。

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/15") {
  employee.update(name: "Tom")
}

Timecop.freeze("2019/1/20") {
  employee.update(name: "Kevin")
}

Timecop.freeze("2019/1/25") {
  # 現時点で有効なレコードのみを参照する
  pp Employee.count
  # => 1

  # name = "Tom" は過去の履歴レコードとして扱われるので参照されない
  pp Employee.find_by(name: "Tom")
  # => nil

  # 最新のみ参照する
  pp Employee.all
  # [#<Employee:0x0000559b1b37eb08
  #   id: 1,
  #   bitemporal_id: 1,
  #   emp_code: "001",
  #   name: "Kevin",
  #   valid_from: 2019-01-20,
  #   valid_to: 9999-12-31,
  #   transaction_from: 2019-01-20,
  #   transaction_to: 9999-12-31>]
}

任意の時間の履歴レコードを参照したい場合は find_at_time(datetime, id) で時間指定して取得する事が出来ます。

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/15") {
  employee.update(name: "Tom")
}

Timecop.freeze("2019/1/20") {
  employee.update(name: "Kevin")
}

# 2019/1/25 に固定
Timecop.freeze("2019/1/25") {
  # 任意の時間の履歴レコードを取得する
  pp Employee.find_at_time("2019/1/13", employee.id).name
  # => "Jane"
  pp Employee.find_at_time("2019/1/18", employee.id).name
  # => "Tom"
  pp Employee.find_at_time("2019/1/23", employee.id).name
  # => "Kevin"
}

このように activerecord-bitemporal は、

保存時に履歴レコードを自動生成
.find_at_time 等で任意の時間のレコードを取得する

というような事を行うライブラリになります。

モデルを BiTemporal Data Model 化する

任意のモデルを BiTemporal Data Model(以下、BTDM)として扱う場合は、以下のカラムを DB に追加する必要があります。

ActiveRecord::Schema.define(version: 1) do
  create_table :employees, force: true do |t|
    t.string :emp_code
    t.string :name

    # BTDM に必要なカラムを追加する
    t.integer :bitemporal_id
    t.datetime :valid_from
    t.datetime :valid_to
    t.datetime :transaction_from
    t.datetime :transaction_to
  end
end

それぞれのカラムは以下のような意味を持ちます。

カラム名	型	値
`bitemporal_id`	`id` と同じ型	BTDM が共通で持つ `id`
`valid_from`	`datetime`	有効時間の開始時刻
`valid_to`	`datetime`	有効時間の終了時刻
`transaction_from`	`datetime`	システム時間の開始時刻
`transaction_to`	`datetime`	システム時間の終了時刻

また、モデルクラスでは ActiveRecord::Bitemporal を include をする必要があります。

class Employee < ActiveRecord::Base
  include ActiveRecord::Bitemporal
end

これで Employee モデルを BTDM として扱うことが出来ます。このドキュメントではこのモデルをサンプルとしてコードを書いていきます。

モデルインスタンスに対する操作について

ここではモデルの生成・更新・削除といったインスタンスに対する操作に関して解説します。

生成

以下のように BTDM を生成した場合、

# MEMO: Timecop を使って擬似的に 2019/1/10 の日付でレコードを生成
#       データをわかりやすくする為に使用しているだけで activerecord-bitemporal には Timecop は必要ありません
employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

以下のようなレコードが生成されます。

id	bitemporal_id	emp_code	name	valid_from	valid_to	transaction_from	transaction_to
1	1	001	Jane	2019-01-10	9999-12-31	2019-01-10	9999-12-31

この時に生成されるレコードのカラムには暗黙的に以下のような値が保存されます。

カラム	値
`bitemporal_id`	自身の `id`
`valid_from`	生成した時間
`valid_to`	擬似的な `INFINITY` 時間

これは『valid_from から valid_to までの期間で有効なデータ』という意味になります。また、 valid_from や valid_to を指定すれば『任意の時間』の履歴データも生成も出来ます。

Timecop.freeze("2019/1/10") {
  # 現時点よりも前からのデータを生成する
  Employee.create(emp_code: "001", name: "Jane", valid_from: "2019/1/1")
}

更新

#update 等でモデルを更新すると『更新時間』を基準とした履歴レコードが暗黙的に生成されます。

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/20") {
  # モデルを更新すると履歴レコードが生成される
  employee.update(name: "Tom")
  # これは #save でも同様に行われる
  # employee.name = "Tom"
  # employee.save
}

上記の操作を行うと以下のようなレコードが生成されます。

id	bitemporal_id	emp_code	name	valid_from	valid_to	transaction_from	transaction_to
1	1	001	Jane	2019-01-10	9999-12-31	2019-01-10	2019-01-20
2	1	001	Jane	2019-01-10	2019-01-20	2019-01-20	9999-12-31
3	1	001	Tom	2019-01-20	9999-12-31	2019-01-20	9999-12-31

更新時には以下のような処理を行っており、結果的に新しいレコードが2つ生成されることになります。また、この時に生成されるレコードは共通の bitemporal_id を保持します。

更新対象のレコード（id = 1）のシステム時間の終了時刻を更新する
更新を行った時間までのレコード（id = 2）を新しく生成する
更新を行った時間からのレコード（id = 3）を新しく生成する

activerecord-bitemporal ではレコードの内容を変更する際にレコードを直接変更するのではなくて『既存のレコードはシステム時間では参照しないような時刻』にして『変更後のレコードを新しく生成』していきます。ただし、#update_columns で更新を行うと強制的にレコードが上書きされるので注意してください。

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/20") {
  # #update_columns で更新するとレコードが直接変更される
  employee.update_columns(name: "Tom")
}

上記の場合は以下のようなレコードになります。 id = 1 のレコードが直接変更されるので注意してください。

id	bitemporal_id	emp_code	name	valid_from	valid_to	transaction_from	transaction_to
1	1	001	Tom	2019-01-10	9999-12-31	2019-01-10	9999-12-31

履歴を生成せずに上書きして更新したいのであれば activerecord-bitemporal 側で用意している #force_update を利用する事が出来ます。

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/20") {
  # #force_update のでは自身を受け取る
  # このブロック内であれば履歴を生成せずにレコードの変更が行われる
  employee.force_update { |employee|
    employee.update(name: "Tom")
  }
}

上記の場合は以下のレコードが生成されます。

id	bitemporal_id	emp_code	name	valid_from	valid_to	transaction_from	transaction_to
1	1	001	Jane	2019-01-10	9999-12-31	2019-01-10	2019-01-20
2	1	001	Tom	2019-01-10	9999-12-31	2019-01-20	9999-12-31

この場合は id = 1 はシステムの終了時刻が更新され、新しい id = 2 のレコードが生成されます。

更新時間を指定して更新

TODO:

削除

更新と同様にレコードのシステム時間の終了時刻を更新しつつ、新しいレコードが生成されます。

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/20") {
  employee.update(name: "Tom")
}

Timecop.freeze("2019/1/30") {
  # 削除を行うとその時間までの履歴が生成される
  employee.destroy
}

上記の場合では以下のようなレコードが生成されます。

id	bitemporal_id	emp_code	name	valid_from	valid_to	transaction_from	transaction_to
1	1	001	Jane	2019-01-10	9999-12-31	2019-01-10	2019-01-20
2	1	001	Jane	2019-01-10	2019-01-20	2019-01-20	9999-12-31
3	1	001	Tom	2019-01-20	9999-12-31	2019-01-20	2019-01-30
4	1	001	Tom	2019-01-20	2019-01-30	2019-01-30	9999-12-31

削除も更新と同様に

削除対象のレコード（id = 3）のシステム時間の終了時刻を更新する
削除を行った時間までの履歴レコード（id = 4）を新しく生成する

という風に『システム時間の終了時刻を更新してから新しいレコードを生成する』という処理を行っています。

ユニーク制約

BTDM では『履歴の時間が被っている場合』にユニーク制約のバリデーションを行います。

Employee.create!(name: "Jane", valid_from: "2019/1/1", valid_to: "2019/1/10")

# OK : 同じ時間帯で被っていない
Employee.create!(name: "Jane", valid_from: "2019/2/1", valid_to: "2019/2/10")

# NG : 同じ時間帯で被っている
Employee.create!(name: "Jane", valid_from: "2019/2/5", valid_to: "2019/2/15")

# OK : valid_from と valid_to は同じでも問題ない
Employee.create!(name: "Jane", valid_from: "2019/2/10", valid_to: "2019/2/20")

また、 BTDM の bitemporal_id もユニーク制約となっているので注意してください。

検索について

BTDM のレコードの検索について解説します。

検索時にデフォルトで追加されるクエリ

BTDM では DB からレコードを参照する場合、暗黙的に

現在の時間を指定する時間指定クエリ
論理削除を除くクエリ

が追加された状態で SQL 文が構築されます。

Timecop.freeze("2019/1/20") {
  # 現在の時間の履歴を返すために暗黙的に時間指定や論理削除されたレコードが除かれる
  puts Employee.all.to_sql
  # => SELECT "employees".* FROM "employees" WHERE "employees"."valid_from" <= '2019-01-20 00:00:00' AND "employees"."valid_to" > '2019-01-20 00:00:00' AND "employees"."transaction_to" = '9999-12-31 00:00:00'
}

これにより DB 上に複数の履歴レコードや論理削除されているレコードがあっても『現時点で有効な』レコードが参照されます。

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(name: "Jane")
}

Timecop.freeze("2019/1/15") {
  employee.update(name: "Tom")
}

Timecop.freeze("2019/1/20") {
  # DB 上では履歴レコードや論理削除済みレコードなどが複数存在するが、暗黙的にクエリが追加されているので
  # 通常の ActiveRecord のモデルを操作した時と同じレコードを返す
  pp Employee.count
  # => 1

  pp Employee.first
  # => #<Employee:0x000055efd894e9e0
  #     id: 1,
  #     bitemporal_id: 1,
  #     emp_code: nil,
  #     name: "Tom",
  #     valid_from: 2019-01-15,
  #     valid_to: 9999-12-31,
  #     transaction_from: 2019-01-15,
  #     transaction_to: 9999-12-31>

  # 更新前の名前で検索しても引っかからない
  pp Employee.where(name: "Jane").first
  # => nil

  # なぜなら暗黙的に時間指定のクエリが追加されている為
  puts Employee.where(name: "Jane").to_sql
  # => SELECT "employees".* FROM "employees" WHERE "employees"."valid_from" <= '2019-01-20 00:00:00' AND "employees"."valid_to" > '2019-01-20 00:00:00' AND "employees"."transaction_to" = '9999-12-31 00:00:00' AND "employees"."name" = 'Jane'
}

このように『現在の時間で有効なレコード』のみが検索の対象となります。また、これは default_scope ではなくて BTDM が独自にハックして暗黙的に追加する仕組みを実装しているので .unscoped で取り除く事は出来ないので注意してください。

# default_scope であれば unscoped で無効化することが出来るが、BTDM のデフォルトクエリはそのまま
puts Employee.unscoped { Employee.all.to_sql }
# => SELECT "employees".* FROM "employees" WHERE "employees"."valid_from" <= '2019-10-25 07:56:06.731259' AND "employees"."valid_to" > '2019-10-25 07:56:06.731259' AND "employees"."transaction_to" = '9999-12-31 00:00:00'

検索時にデフォルトクエリを取り除く

検索時にデフォルトクエリを取り除きたい場合、以下のスコープを使用します。

スコープ	動作
`.ignore_valid_datetime`	時間指定を無視する
`.within_deleted`	論理削除されているレコードを含める
`.without_deleted`	論理削除されているレコードを含めない

Timecop.freeze("2019/1/20") {
  # 時間指定をしているクエリを取り除く
  puts Employee.ignore_valid_datetime.to_sql
  # => SELECT "employees".* FROM "employees" WHERE "employees"."transaction_to" = '9999-12-31 00:00:00'

  # 論理削除しているレコードも含める
  puts Employee.within_deleted.to_sql
  # => SELECT "employees".* FROM "employees" WHERE "employees"."valid_from" <= '2019-01-20 00:00:00' AND "employees"."valid_to" > '2019-01-20 00:00:00'

  # 全てのレコードを対象とする
  puts Employee.ignore_valid_datetime.within_deleted.to_sql
  # => SELECT "employees".* FROM "employees"
}

『任意のレコードの履歴一覧を取得する』ようなことを行う場合は ignore_valid_datetime を使用して全レコードを参照するようにします。

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(name: "Jane")
}

Timecop.freeze("2019/1/15") {
  employee.update(name: "Tom")
}

Timecop.freeze("2019/1/20") {
  employee.update(name: "Kevin")

  # NOTE: bitemporal_id を参照することで同一の履歴を取得する事が出来る
  pp Employee.ignore_valid_datetime.where(bitemporal_id: employee.bitemporal_id).map(&:name)
  # => ["Jane", "Tom", "Kevin"]
}

時間を指定して検索する

任意の時間を指定して検索を行いたい場合、.valid_at(datetime) を利用する事が出来ます。

employee1 = nil
employee2 = nil
Timecop.freeze("2019/1/10") {
  employee1 = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/15") {
  employee1.update(name: "Tom")
  employee2 = Employee.create(emp_code: "002", name: "Homu")
}

Timecop.freeze("2019/1/20") {
  # valid_at で任意の時間を参照して検索する事が出来る
  puts Employee.valid_at("2019/1/10").to_sql
  # => SELECT "employees".* FROM "employees" WHERE "employees"."valid_from" <= '2019-01-10 00:00:00' AND "employees"."valid_to" > '2019-01-10 00:00:00' AND "employees"."transaction_to" = '9999-12-31 00:00:00'

  pp Employee.valid_at("2019/1/10").map(&:name)
  # => ["Jane"]
  pp Employee.valid_at("2019/1/17").map(&:name)
  # => ["Tom", "Homu"]

  # そのまま続けてリレーション出来る
  pp Employee.valid_at("2019/1/17").where(name: "Tom").first
  # => #<Employee:0x000055678afd1d20
  #     id: 1,
  #     bitemporal_id: 1,
  #     emp_code: "001",
  #     name: "Tom",
  #     valid_from: 2019-01-15,
  #     valid_to: 9999-12-31,
  #     transaction_from: 2019-01-15,
  #     transaction_to: 9999-12-31>
}

また、特定の id で検索するのであれば .find_at_time(datetime, id) も利用できます。

employee1 = nil
employee2 = nil
Timecop.freeze("2019/1/10") {
  employee1 = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/15") {
  employee1.update(name: "Tom")
  employee2 = Employee.create(emp_code: "002", name: "Homu")
}

Timecop.freeze("2019/1/20") {
  # 任意の時間の id のレコードを返す
  pp Employee.find_at_time("2019/1/12", employee1.id)
  # => #<Employee:0x000055b776d7ff18
  #     id: 1,
  #     bitemporal_id: 1,
  #     emp_code: "001",
  #     name: "Jane",
  #     valid_from: 2019-01-10,
  #     valid_to: 2019-01-15,
  #     transaction_from: 2019-01-15,
  #     transaction_to: 9999-12-31>

  # 見つからなければ nil を返す
  pp Employee.find_at_time("2019/1/12", employee2.id)
  # => nil

  # find_at_time の場合は例外を返す
  pp Employee.find_at_time!("2019/1/12", employee2.id)
  # => raise ActiveRecord::RecordNotFound (ActiveRecord::RecordNotFound)
}

`id` と `bitemporal_id` について

BTDM のインスタンスの id は特殊で『レコードの id』ではなくて『bitemporal_id の値』が割り当てられています。

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/15") {
  employee.update(name: "Tom")
}

Timecop.freeze("2019/1/20") {
  employee.update(name: "Kevin")

  # 現在のレコードの id は 1 を返す
  pp Employee.first.id
  # => 1

  # 別の履歴レコードを参照しても id は同じ
  pp Employee.find_at_time("2019/1/12", employee.id).id
  # => 1
}

インスタンスの id はレコードの読み込み時に自動的に設定されています。これは Employee.find(employee.id) で検索を行う際に id の値が レコードの id ではなくて bitemporal_id のほうが実装上都合がいい、という由来になっています。この影響により Employee.pluck(:id) や Employee.map(&:id)、 Employee.ids が返す結果が微妙に異なるので注意してください。

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/15") {
  employee.update(name: "Tom")
}

Timecop.freeze("2019/1/20") {
  employee.update(name: "Kevin")

  # DB の生 id が返ってくる
  pp Employee.ignore_valid_datetime.pluck(:id)

  # bitemporal_id が返ってくる
  pp Employee.ignore_valid_datetime.map(&:id)

  # bitemporal_id が返ってくる
  pp Employee.ignore_valid_datetime.ids
}

レコードの内容

id	bitemporal_id	emp_code	name	valid_from	valid_to	transaction_from	transaction_to
1	1	001	Jane	2019-01-10	9999-12-31	2019-01-10	2019-01-15
2	1	001	Jane	2019-01-10	2019-01-15	2019-01-15	9999-12-31
3	1	001	Tom	2019-01-15	9999-12-31	2019-01-15	2019-01-20
4	1	001	Tom	2019-01-15	2019-01-20	2019-01-20	9999-12-31
5	1	001	Kevin	2019-01-20	9999-12-31	2019-01-20	9999-12-31

また、元々の DB の id は #swapped_id で参照する事が出来ます。

employee = nil
Timecop.freeze("2019/1/10") {
  employee = Employee.create(emp_code: "001", name: "Jane")
}

Timecop.freeze("2019/1/15") {
  employee.update(name: "Tom")
}

Timecop.freeze("2019/1/20") {
  employee.update(name: "Kevin")

  pp Employee.first.swapped_id
  # => 5
  pp Employee.find_at_time("2019/1/12", employee.id).swapped_id
  # => 2
}

まとめると BTDM のインスタンスは以下のような値を保持しています。

id : bitemporal_id が暗黙的に設定される
bitemporal_id : BTDM 共通の id
swapped_id : DB の生 id

`id` 検索の注意点

BTDM では find_by(id: xxx) や where(id: xxx) を行う場合 id ではなくて bitemporal_id を参照する必要があります。

# NG : BTDM の場合は id 検索出来ない
Employee.find_by(id: employee.id)

# OK : bitemporal_id で検索を行う
# MEMO: id = bitemporal_id なの
#       find_by(bitemporal_id: employee.id)
#       でも動作するが employee.bitemporal_id と書いたほうが意図が伝わりやすい
Employee.find_by(bitemporal_id: employee.bitemporal_id)

# NG : BTDM の場合は id 検索出来ない
Employee.where(id: employee.id)

# OK : bitemporal_id で検索を行う
Employee.where(bitemporal_id: employee.bitemporal_id)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/kufu/activerecord-bitemporal.

Copyright

See ./LICENSE