1. SQLリファレンス・ガイド
  2. 組込み関数
  3. 行の関数

行の関数

表管理の項で説明しているように、表の行は表スキーマに準拠するレコード値ですが、表スキーマに含まれない追加のプロパティが含まれています。このようなプロパティの値を抽出するには、この項にリストされた関数を使用する必要があります。

これらの関数のシグネチャでは、入力パラメータの型としてAnyRecordを指定していますが、関数では実際には入力として行が必要です。行を返す唯一の式は、行変数、つまり、名前が$で始まる表の別名です。「例: TTLの更新」の項に、remaining_hours() 関数(行が使用可能な関数の1つ)の使用例を示します。

modification_time関数

modification_time関数を使用すると、行の最新の変更時間(UTC)を表示できます。この時間は、精度3 (ミリ秒)のタイムスタンプ値として返されます。行が挿入後に変更されていない場合は、挿入時間を返します。これは、表が複数のリージョンにまたがり、Oracle NoSQL Databaseクロスリージョン・エージェントがリモート・リージョンからデータをレプリケートして表を更新しているデプロイメントで役立つ場合があります。

構文:
timestamp(3) modification_time (AnyRecord)

セマンティクス:

  • AnyRecord: この関数は、入力値として行を想定します。
  • 戻り型: timestamp(3)

例:

航空会社アプリケーションでは、最終変更時間に基づいて、乗客旅行レコードの定期バックアップをスケジュールできます。次回の反復で考慮できるのは、最後にスケジュールされたバックアップの後に変更されたレコードのみです。 
SELECT modification_time($u) 
FROM BaggageInfo $u 
WHERE ticketNo = 1762344493810

説明:

modification_time関数を使用して、BaggageInfo表から乗客レコードの最終変更時間の詳細を取得できます。

出力:

 +--------------------------+
 |         Column_1         |
 +--------------------------+
 | 2023-01-18T07:53:02.048Z |
 +--------------------------+

この問合せは、BaggageInfo表からticketNoが1762344493810の乗客の最新の変更時間に関する情報を返します。

remaining_hours関数

行の有効期限が切れるまでの満で数えた時間数を返します。行に有効期限がない場合は、負数を返します。

構文:
integer remaining_hours(AnyRecord)

セマンティクス:

  • AnyRecord: この関数は、入力値として行を想定します。
  • 戻り型: integer

remaining_days関数

行の有効期限が切れるまでの満で数えた日数を返します。行に有効期限がない場合は、負数を返します。

構文:
integer remaining_days(AnyRecord)

セマンティクス:

  • AnyRecord: この関数は、入力値として行を想定します。
  • 戻り型: integer

expiration_time関数

行の有効期限を精度ゼロのタイムスタンプ値として返します。行に有効期限がない場合は、UTC 1970年1月1日に設定されたタイムスタンプを返します。

構文:
timestamp(0) expiration_time(AnyRecord)

セマンティクス:

  • AnyRecord: この関数は、入力値として行を想定します。
  • 戻り型: timestamp(0)

expiration_time_millis関数

行の有効期限をUTC 1970年1月1日以降のミリ秒数で返します。行に有効期限がない場合は、ゼロを返します。

構文:
long expiration_time_millis(AnyRecord)

セマンティクス:

  • AnyRecord: この関数は、入力値として行を想定します。
  • 戻り型: long

例: TTL関連関数

航空会社アプリケーションでは、データの有効期限より前に乗客レコードをバックアップしたり、有効期限を延長して、表内の情報をより長い期間保持できるようにする場合があります。 
SELECT
remaining_hours($u) AS hours,
remaining_days($u) AS days,
expiration_time($u) AS expirytime,
expiration_time_millis($u) AS expirytime_ms
FROM BaggageInfo $u
WHERE ticketNo = 1762344493810

説明:

TTL失効関数を使用して、BaggageInfo表の乗客レコードを含む行の有効期限の詳細(ある場合)を確認できます。

出力:
{"hours":376,"days":15,"expirytime":"2023-02-04T00:00:00.000Z","expirytime_ms":1675468800000}

問合せは、BaggageInfo表のticketNoが1762344493810の乗客データを含む行のTTL情報を返します。

この場合、行は15日後に失効します。前述の行関数を使用して、時間数、タイムスタンプ値、およびUTC 1970年1月1日以降のミリ秒数で同じ情報が表示されます。

UPDATE文を使用して、行の有効期限日時を次のように更新できます:
UPDATE BaggageInfo $u
SET TTL remaining_days($u) + 15 days
WHERE ticketNo = 1762344493810

上の文は、行の存続期間を15日間延長します。この例では、行の失効までの残りの日数は15日で、前述の文ではさらに15日追加され、30日後に失効するように行が効率的にレンダリングされます。remaining_hours関数を使用し、時間数を追加して、行の有効期限を時間単位で延長できます。

TTL値の更新の詳細は、「例: TTLの更新」を参照してください。

次の関数を使用すると、データがストア全体にどのように分散されているかを確認し、統計を収集できます。

versionまたはrow_version関数

versionまたはrow_version関数を使用すると、特定の行のバージョンを表示できます。行が挿入または変更されるたびに、行バージョン値が自動的に計算され、前の行バージョン値が新しい値に置き換えられます。行バージョン値は、表内のすべての行で一意であり、手動で変更することはできません。version関数とrow_version関数の両方が同じ結果をフェッチし、問合せ内で区別なく使用できます。「例」の項に示すように、SELECT句とWHERE句の両方でversion関数とrow_version関数を使用できます。

構文:
binary version(AnyRecord)
binary row_version(AnyRecord)

セマンティクス:

  • AnyRecord: versionまたはrow_version関数は、入力値として行を想定します。
  • 戻り型: versionまたはrow_version関数は、バイナリ値を返します。バージョンを問合せの文字列として使用するには、CAST式を使用して値を文字列にキャストする必要があります。

例:

航空手荷物追跡アプリケーション表から、乗客チケット番号が1762344493810である行のバージョンをフェッチします。 

SELECT row_version($t) from Baggageinfo $t WHERE ticketNo =
    1762344493810

説明:

この問合せでは、チケット番号が1762344493810の乗客データを含む行のバージョンをフェッチします。この行をrow_version関数の入力引数として指定します。かわりにversion関数を使用しても、同じ結果が返されます。

出力:
{"Column_1":"rO0ABXcsACEZ1TNcQVVExr5UlPEJixAJAAAAAAAAKDIBAwAAAAEAAAABAAAAAAAO1xE="}

次の例では、UPDATE文を使用して、乗客のデータのconfNoフィールドを変更し、更新された行バージョンをフェッチします。 

UPDATE baggageinfo $t
SET confNo = "LE6J6Z"
WHERE ticketNo = 1762344493810
RETURNING row_version($t) as rowVersion
出力:
{"rowVersion":"rO0ABXcsACEZ1TNcQVVExr5UlPEJixAJAAAAAAAATP8BAwAAAAEAAAABAAAAAAAaylA="}

行が更新された後、対応する行のバージョンは、Oracle NoSQL Databaseサーバーによって新しい値に自動的に置き換えられます。

次の例では、WHERE句でrow_version関数を使用して、行バージョンに関連付けられた乗客データをフェッチします。 

SELECT ticketNo AS TICKET, fullName AS NAME 
FROM baggageinfo $t 
WHERE cast(row_version($t) as String) ="rO0ABXcsACEZ1TNcQVVExr5UlPEJixAJAAAAAAAAKDIBAwAAAAEAAAABAAAAAAAO1xE="

バージョンを比較するためにCAST式を使用してrow_version関数の結果を文字列にキャストすることに注意してください。この例では、乗客データをフェッチするために前の行バージョンが使用されます。データの更新時に前の行バージョンが存在しなくなったため、それに関連付けられた乗客データはありません。 

0 row returned

row_version関数は、その他のNoSQL式でも使用できます。次の例では、CASE式でrow_version関数を使用して乗客データが変更されているかどうかを確認します: 

SELECT ticketNo AS TICKET, modification_time($t) AS TIME,
CASE
WHEN CAST(row_version($t) as String) = "rO0ABXcsACEZ1TNcQVVExr5UlPEJixAJAAAAAAAAKDIBAwAAAAEAAAABAAAAAAAO1xE="
        THEN "row is not modified"
        ELSE "row is modified"
END AS REPORT
FROM baggageinfo $t
WHERE ticketNo = 1762344493810;

まず、CAST式を使用してrow_version関数の結果を文字列にキャストし、その値を以前に格納したバージョンと比較します。文字列比較操作の結果に応じて、対応するメッセージが表示されます。この問合せでは、modification_time関数を使用して、乗客データの最新の変更時間も確認します。

出力:
{"TICKET":1762344493810,"TIME":"2024-04-04T09:42:52.128Z","REPORT":"row is
      modified"}

integer shard (AnyRecord)

shard関数を使用すると、特定のデータ行が格納されているシャードIDを取得できます。整数値を返します。シャードIDの詳細は、管理者ガイドのキー配布統計の表示に関する項を参照してください。

構文:
integer shard (AnyRecord)

セマンティクス:

  • AnyRecord: この関数は、入力値として行を想定します。
  • 戻り型: integer

例:

この関数を使用して、Oracle NoSQL Databaseクラスタ内の潜在的なストレージ・ホットスポットまたは不均衡を識別できます。たとえば、特定のシャードが他のシャードより多くの記憶域を消費しているように見える場合があります。 

SELECT shard($u) AS Shard 
FROM BaggageInfo $u 
WHERE ticketNo = 1762344493810

説明:

航空会社アプリケーションでは、shard関数を使用して、乗客レコードが格納されるシャード詳細を決定します。

出力:
{"Shard":1}

問合せは、ticketNoが1762344493810の行がBaggageInfo表に格納されるシャードを返します。

次のコマンドを発行して、そのシャード内のレコード数をストア内の他のシャードと比較できます。
SELECT count(ticketNo) AS Shard_count 
FROM BaggageInfo $u 
WHERE shard($u) =1
出力:
{"Shard_count":2}

partition関数

KVStore内のすべてのデータは1つ以上のキーによってアクセスされます。キーは表内の1つの列である場合と、キー/値ペアのキー部分である場合があります。キーはパーティションと呼ばれる論理コンテナに配置され、各シャードには1つ以上のパーティションが含まれています。詳細は、概要ガイドのパーティションを参照してください。

partition関数を使用すると、特定のデータ行が格納されているパーティションIDを表示できます。

構文:
integer partition (AnyRecord)

セマンティクス:

  • AnyRecord: この関数は、入力値として行を想定します。
  • 戻り型: integer

例:

partition関数を使用して、行がOracle NoSQL Databaseクラスタに格納されるパーティションを決定します。 

SELECT partition($u) AS partition 
FROM BaggageInfo $u 
WHERE ticketNo = 1762344493810

説明:

この例では、partition関数は、乗客レコードが格納されている場所のパーティション詳細を返します。問合せは、ticketNoが1762344493810の行がBaggageInfo表に格納されるパーティションを返します。

出力:
{"partition":80}

次の問合せは、id 1のシャード内のパーティションのリストを返します。 

SELECT partition ($u) AS partition_count 
FROM BaggageInfo $u 
WHERE shard($u)=1
出力:
{"partition_count":80}
{"partition_count":131}

row_storage_size関数

row_storage_size関数を使用すると、特定のデータ行で使用される永続記憶域サイズ(バイト単位)を確認できます。整数値を返します。

構文:
integer row_storage_size (AnyRecord)

セマンティクス:

  • AnyRecord: この関数は、入力値として行を想定します。
  • 戻り型: integer

例:

row_storage_size関数を使用して、特定の行のレコード・サイズを取得できます。 

SELECT row_storage_size($u) AS storage_size 
FROM BaggageInfo $u 
WHERE ticketNo = 1762344493810

説明:

航空会社アプリケーションでは、row_storage_size関数を使用して個々の乗客レコードの記憶域サイズを決定できます。

出力:
{"storage_size":1123}

問合せは、BaggageInfo表のticketNoが1762344493810の乗客レコードを含む行の記憶域サイズを返します。記憶域サイズはバイト単位で表示されます。

index_storage_size関数

index_storage_size関数を使用すると、指定したデータ行の索引で使用される永続記憶域サイズ(バイト単位)を確認できます。整数値を返します。この関数では2つの引数を指定します。最初の引数は、索引が作成される表参照です。2番目の引数は、記憶域サイズが必要な索引名です。索引名では、大文字と小文字は区別されません。

構文:
integer index_storage_size (AnyRecord, String)

セマンティクス:

  • AnyRecord: 索引が最初の引数として作成される表参照。
  • string: 索引の名前。
  • 戻り型: integer

例:

index_storage_size関数を使用して、表の個々の索引の記憶域サイズを決定できます。各索引の記憶域サイズは、個別に問い合せる必要があります。表のすべての索引の合計記憶域サイズを決定するには、各索引に対して関数をコールする必要があります。
SELECT index_storage_size($u,"idx_contact") 
FROM baggageInfo $u 
WHERE ticketNo = 1762344493810

説明:

航空会社アプリケーションでは、Oracle NoSQL Database表の必須フィールドの索引を作成できます。index_storage_size関数を使用して、各索引の記憶域サイズを取得します。

この例では、表のcontactPhoneフィールドに索引が作成されます。表名BaggageInfo表および索引名idx_contactは、関数の引数として指定されます。

索引の詳細は、「索引について」を参照してください。

出力:

 +----------+
 | Column_1 |
 +----------+
 |       40 |
 +----------+

問合せは、BaggageInfo表のticketNoが1762344493810の乗客レコードを含む行の記憶域サイズを返します。記憶域サイズはバイト単位で表示されます。

例:

航空会社アプリケーションで、次の問合せを使用すると、クラスタ内のパーティション間で表の記憶域がどのように分散されているかを詳細に表示できます。パーティションごとに、そのパーティションに含まれる表のすべての行を格納するために使用される合計バイト数が取得されます。 
SELECT
partition($u) AS partition,
sum(row_storage_size($u)) AS sum
FROM BaggageInfo $u
GROUP BY partition($u)

説明:

この例では、partition関数によって、乗客レコードがBaggageInfo表に格納されるパーティションが決定されます。sum関数は、各行の記憶域サイズを計算し、結果を合計します。

出力:

 +----------+----------+
 | partition|     sum  |
 +----------+----------+
 |        80|      1123|
 |       131|      1115|
 +----------+----------+

出力の最初の列はパーティション番号のリストで、2番目の列はそれらのパーティションの現在のサイズです。