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の更新」を参照してください。

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

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番目の列はそれらのパーティションの現在のサイズです。