SODAタイプ

317 SODAタイプ

SODAタイプには、SODA_DOCUMENT_T、SODA_COLLECTION_T、SODA_OPERATION_TおよびSODA_CURSOR_Tという複数のタイプがあります。 SODA_DOCUMENT_TとSODA_COLLECTION_Tは、SODAが提供する2つの主要な抽象化(ドキュメントとコレクション)を表します。 SODA_OPERATION_Tは、コレクションに対する操作の条件を指定するために使用します。 SODA_CURSOR_Tは、コレクションに対する読取り操作の結果によるカーソルです。

この章のトピックは、次のとおりです:

317.1 SODAタイプの概要

参照:

317.2 SODAタイプのセキュリティ・モデル

SODAタイプは、SODA_APPロールを持つユーザーが使用できます。

SODAタイプはすべてSYSタイプです。 PUBLICには、この章で説明するSODAタイプのEXECUTE権限が付与されます。

タイプSODA_Collection_T
タイプSODA_Document_T
タイプSODA_Operation_T
タイプSODA_Cursor_T

317.3 SODAタイプの要約

この章では、SODAタイプをリストし、それらについて説明します。

表317-1 SODAタイプ

タイプ	説明
`SODA_Collection_T Type`	この`SODA`タイプは、`SODA`コレクションを表します。このタイプは永続化できません。
`SODA_Document_T Type`	この`SODA`タイプは、コンテンツを含むドキュメント(通常は`JSON`形式)を表します。このタイプは永続化できません。
`SODA_OPERATION_T Type`	この`SODA`タイプは、`SODA`コレクションに対するフィルタリングやページ区切りによるドキュメントの検索、削除と置換など読取り/書込み操作を実行します。このタイプは永続化できません。
`SODA_CURSOR_T Type`	この`SODA`タイプは、ドキュメントの結果セットを表します。このタイプは永続化できません。

317.3.1 SODA_Collection_Tタイプ

このSODAタイプは、SODAコレクションを表します。 SODAコレクションの参照は、DBMS_SODA.CREATE_COLLECTION()またはDBMS_SODA.OPEN_COLLECTION()をコールすることによってのみ取得できます。

表317-2 SODA_Collection_T型サブプログラム

サブプログラム	説明
`CREATE_INDEX Function`	JSONで表現される索引指定を使用して索引を作成します。サポートされている指定のタイプは3つあります。それぞれで、異なるタイプの索引(Bツリー索引、データ・ガイドによるJSON検索索引、空間索引)を指定します。
`CREATE_VIEW_FROM_DG Function`	データ・ガイドでの指定に従い、スカラー`JSON`フィールドを使用してリレーショナル列を含むビューを作成します。
`DROP_INDEX Function`	名前付き索引を削除します。
`FIND Function`	`SODA_OPERATION_T`オブジェクトを返します。コンストラクタがないため、これ以外に`SODA_Operation_T`の参照を取得する方法はありません。
`FIND_ONE Function`	キーと一致するドキュメントをフェッチします。
`GET_DATA_GUIDE Function`	CLOBとしてJSONデータ・ガイドを返します。
`GET_INDEX Function`	このファンクションは、コレクション上に作成された、提供された索引について指定内容を戻します。
`GET_METADATA Function`	コレクションのメタデータを`JSON`形式で戻します。
`GET_NAME Function`	コレクションの名前を戻します。
`INSERT_ONE Function`	ドキュメントをコレクションに挿入します。
`INSERT_ONE_AND_GET Function`	ドキュメントをコレクションに挿入し、コンテンツを除くすべてのコンポーネントを含む結果ドキュメントを戻します。
`LIST_INDEXES Function`	このファンクションは、コレクション上に作成されたすべての索引について指定内容を戻します。
`REMOVE_ONE Function`	キーと一致するドキュメントを削除します。
`REPLACE_ONE Function`	キーと一致するドキュメントのコンテンツおよび(オプションで)メディア・タイプを置換します。
`REPLACE_ONE_AND_GET Function`	キーと一致するドキュメントのコンテンツおよび(オプションで)メディア・タイプを置換し、すべてのコンポーネント(コンテンツを除く)を含む結果ドキュメントを戻します。
`SAVE Function`	ドキュメントをコレクションに保存します。
`SAVE_AND_GET Function`	ドキュメントをコレクションに保存します。
`TRUNCATE Function`	コレクション内のドキュメントをすべて削除します。

317.3.1.1 CREATE_INDEXファンクション

このファンクションでは、JSONで表現される索引指定を使用して索引を作成します。サポートされている指定のタイプは3つあります。それぞれで、異なるタイプの索引(Bツリー索引、データ・ガイドによるJSON検索索引、空間索引)を指定します。

構文

CREATE_INDEX (
     specification VARCHAR2) 
  RETURN NUMBER;

パラメータ

表317-3 CREATE_INDEXファンクションのパラメータ

パラメータ	説明
`specification`	索引の指定内容。

例317-1 戻り値

このファンクションは、次の値を戻します。

1-索引が正常に作成された場合。
0-索引が作成されなかった場合。

例外

Error-索引の作成中にエラーが発生した場合。

参照:

SODA索引の指定内容の詳細は、次を参照してください。

317.3.1.2 CREATE_VIEW_FROM_DGファンクション

このファンクションは、データ・ガイドでの指定に従い、スカラーJSONフィールドを使用してリレーショナル列を含むビューを作成します。このファンクションには、データ・ガイドが有効なJSON検索索引は必要ありません。データ・ガイドはファンクションに渡されます。ファンクションに渡されたデータ・ガイドが無効である場合は、エラーがスローされます。

構文

このプロシージャは、Autonomous Database 19cリリース以降でのみ使用可能です。

CREATE_VIEW_FROM_DG (
   data_guide               IN   CLOB,
   view_name                IN   VARCHAR2,   
   materialize              IN   BOOLEAN DEFAULT FALSE,
   mv_refresh_mode          IN   NUMBER DEFAULT 1,
   path                     IN   VARCHAR2 DEFAULT '$',
   resolve_name_conflicts   IN   BOOLEAN   DEFAULT FALSE,
   col_name_prefix          IN   VARCHAR2 DEFAULT NULL,
   mixed_case_columns       IN   BOOLEAN DEFAULT FALSE)
  RETURN NUMBER;

パラメータ

表317-4 CREATE_VIEW_FROM_DGファンクションのパラメータ

パラメータ	説明
`data_guide`	コレクションのデータ・ガイド。
`view_name`	作成するビューの名前。
`materialize`	ビューがマテリアライズドである必要があるかどうかを示すブール値。デフォルト値は`FALSE`です。
`mv_refresh_mode`	マテリアライズド・ビューのリフレッシュ・モード。使用可能な値は次のとおりです。 `DBMS_SODA.MV_REFRESH_ON_STATEMENT` (デフォルト) DBMS_SODA.MV_REFRESH_ON_COMMIT DBMS_SODA.MV_REFRESH_ON_DEMAND
`path`	展開するJSONフィールドのパス。 JSONパス式の構文が使用されます。たとえば: `$`を指定すると、JSONドキュメント・ルートから始まるビューが作成されます `$.purchaseOrder`を指定すると、purchaseOrderから始まるビューが作成されます。 `purchaseOrder`の下に子または子孫を展開し、すべてのスカラー値のビュー列を作成します。デフォルト値は`$`です。
`resolve_name_conflicts`	デフォルトでは、`o:preferred_column_name`間に競合があると、エラーが発生します。このパラメータを`TRUE`に設定すると、このプロシージャでは、順序番号を付加することでビュー列名の競合が自動的に解決されます。デフォルト値は`FALSE`です。
`col_name_prefix`	デフォルトでは、ビュー列名はJSONフィールド名と同じです。このパラメータを使用すると、ビュー列名に付加する接頭辞を指定できます。デフォルト値は`NULL`です。
`mixed_case_columns`	デフォルトでは、ビュー列名は大/小文字を区別します。このパラメータを使用すると、この動作を大/小文字の区別なしに変更できます。デフォルト値は`FALSE`です。

戻り値

このファンクションは、次の値を戻します。

1 - プロシージャが正常に完了した場合
0 - プロシージャが正常に完了できなかった場合

例外

Error - このファンクションでビューを作成できずエラーが発生した場合。

参照:

JSONデータ・ガイドの詳細は、「JSONデータ・ガイド」を参照してください。

317.3.1.3 DROP_INDEXファンクション

このファンクションでは、名前付き索引を削除します。

構文

DROP_INDEX (
     index_Name IN VARCHAR2,
     force      IN BOOLEAN DEFAULT FALSE) 
  RETURN NUMBER;

例317-2 パラメータ

表317-5 DROP_INDEXファンクションのパラメータ

パラメータ説明

パラメータ	説明
`index_Name`	索引の名前。
`force`	forceパラメータは、`TRUE`または`FALSE`のどちらかにします。 `JSON`検索索引または空間索引(Bツリー索引以外)を削除する場合は、`TRUE`に設定する必要があります。詳細は、DROP INDEXを参照してください。

index_Name

索引の名前。

force

forceパラメータは、TRUEまたはFALSEのどちらかにします。 JSON検索索引または空間索引(Bツリー索引以外)を削除する場合は、TRUEに設定する必要があります。

詳細は、DROP INDEXを参照してください。

戻り値

このファンクションは、次の値を戻します。

1-索引が正常に削除された場合。
0-索引が削除されなかった場合。たとえば、指定された名前の既存の索引が存在していなかった場合などです。

例外

Error-索引の削除中にエラーが発生した場合。

317.3.1.4 FINDファンクション

このファンクションでは、コレクションの操作タイプを返します。操作タイプを使用すると、各種の読取り/書込み操作を作成および実行できます。コンストラクタがないため、これ以外にSODA_Operation_Tの参照を取得する方法はありません。

構文

FIND ()
 RETURN SODA_Operation_T;

戻り値

このファンクションは、SODA_OPERATION_Tオブジェクトを戻します。

例外

このファンクションは、例外をスローしません。

317.3.1.5 FIND_ONEファンクション

このファンクションは、指定されたキーと一致するドキュメントをフェッチします。

構文

FIND_ONE (
     key         IN VARCHAR2)
 RETURN SODA_Document_T;

パラメータ

表317-6 FIND_ONEファンクションのパラメータ

パラメータ	説明
`key`	フェッチするドキュメントのキー。

戻り値

このファンクションは、キーと一致するドキュメントを戻します。一致するものが見つからない場合は、NULLを戻します。

例外

Error - ドキュメントの検索中にエラーが発生した場合。

317.3.1.6 GET_DATA_GUIDEファンクション

このファンクションでは、CLOBとしてJSONデータ・ガイドをフェッチします。 JSONデータ・ガイドは、本質的にはコレクション内のJSONドキュメントに対して推測されるスキーマです。 JSONデータ・ガイドを返すには、コレクションにJSON検索索引が定義されていて、データ・ガイドが有効にされている必要があります。

構文

GET_DATA_GUIDE () 
 RETURN CLOB;

戻り値

このファンクションは、CLOBとしてJSONデータ・ガイドを返します。

参照:

JSONデータ・ガイドの詳細は、「JSONデータ・ガイド」を参照してください。

例外

Error-データ・ガイドのフェッチ中にエラーが発生した場合。

317.3.1.7 GET_INDEXファンクション

このファンクションは、コレクション上に作成された、提供された索引について指定内容を戻します。

構文

GET_INDEX (
     index_name           IN VARCHAR2,
     schema_name          IN VARCHAR2 DEFAULT NULL) 
  RETURN VARCHAR2;

パラメータ

表317-7 GET_INDEXファンクションのパラメータ

パラメータ	説明
`index_name`	説明する索引の名前。
`schema_name`	索引が含まれているスキーマの名前。このパラメータは省略可能です。このパラメータを設定しなかった場合、このメソッドでは、このメソッドのコール元のスキーマ内で、指定された索引が検索されます。

戻り値

このファンクションは、JSON形式で索引の指定内容を戻します。

例外

Error-索引の指定内容を戻すときにエラーが発生した場合。

317.3.1.8 GET_METADATAファンクション

このファンクションは、コレクションのメタデータをJSON形式で戻します。

構文

GET_METADATA () 
  RETURN VARCHAR2;

戻り値

このファンクションは、コレクションのメタデータをJSON形式で戻します。

317.3.1.9 GET_NAMEファンクション

このファンクションは、コレクションの名前を戻します。

構文

GET_NAME ()
 RETURN NVARCHAR2;

戻り値

このファンクションは、コレクションの名前を戻します。

317.3.1.10 INSERT_ONEファンクション

このファンクションは、ドキュメントをコレクションに挿入します。

構文

INSERT_ONE (
     document      IN SODA_Document_T)
 RETURN NUMBER;

パラメータ

表317-8 INSERT_ONEファンクションのパラメータ

パラメータ	説明
`document`	入力ドキュメント。

戻り値

このファクションは数値を戻します。ドキュメントが正常に挿入された場合は 1、それ以外の場合は0です。

例外

Error - ドキュメントをコレクションに挿入しているときにエラーが発生した場合。

317.3.1.11 INSERT_ONE_AND_GETファンクション

このファンクションは、ドキュメントをコレクションに挿入します。

構文

INSERT_ONE_AND_GET (
     document      IN SODA_Document_T,
     hint          IN VARCHAR2 DEFAULT NULL)
 RETURN SODA_Document_T;

パラメータ

表317-9 INSERT_ONE_AND_GETファンクションのパラメータ

パラメータ	説明
`document`	入力ドキュメント。
`hint`	Oracle SQL形式のヒント文字列(囲んでいる`/+`および`/`を除く)。このパラメータは省略可能です。

戻り値

このファクションは、コンテンツを除き、指定されたコレクションでサポートされているすべてのドキュメント・コンポーネントを含む結果ドキュメントを戻します。

例外

Error - ドキュメントをコレクションに挿入しているときにエラーが発生した場合。

317.3.1.12 LIST_INDEXESファンクション

このファンクションは、コレクション上に作成されたすべての索引について指定内容を戻します。

構文

LIST_INDEXES ( ) 
  RETURN SODA_Index_List_T;

戻り値

このファンクションは、索引の指定内容をJSON形式でSODA_Index_List_Tのインスタンスとして戻します。

例外

Error-索引の指定内容を戻すときにエラーが発生した場合。

317.3.1.13 REMOVE_ONEファンクション

このファンクションは、指定されたキーと一致するドキュメントを削除します。

構文

REMOVE_ONE (
     key       IN VARCHAR2)
 RETURN NUMBER;

パラメータ

表317-10 REMOVE_ONEファンクションのパラメータ

パラメータ	説明
`key`	ドキュメントのキー。

戻り値

この関数は、次の値を返します。

1 - ドキュメントが正常に削除された場合。
0 - 指定されたキーを持つドキュメントが見つからなかった場合。

例外

Error - ドキュメントをコレクションから削除しているときにエラーが発生した場合。

317.3.1.14 REPLACE_ONEファンクション

このファンクションでは、キーを使用して、既存のドキュメントを新しいコンテンツとメディア・タイプで更新します。コンテンツおよびメディア・タイプを除き、documentに設定されているいずれのコンポーネントも置換中に使用されません。それらは無視されます。

構文

REPLACE_ONE (
     key            IN VARCHAR2,
     document       IN SODA_Document_T)
 RETURN NUMBER;

パラメータ

表317-11 REPLACE_ONEパラメータ

パラメータ	説明
`key`	ドキュメントのキー。
`document`	古いものを置換するための新しいコンテンツとメディア・タイプを含むドキュメント。

戻り値

このファクションは数値を返します。ドキュメントが置換された場合は1、それ以外の場合は0です。

例外

Error - コレクション内のドキュメントを置換しているときにエラーが発生した場合。

317.3.1.15 REPLACE_ONE_AND_GETファンクション

構文

REPLACE_ONE_AND_GET (
     key            IN VARCHAR2,
     document       IN SODA_Document_T)
 RETURN SODA_Document_T;

パラメータ

表317-12 REPLACE_ONE_AND_GETファンクションのパラメータ

パラメータ	説明
`key`	ドキュメントのキー。
`document`	古いものを置換するための新しいコンテンツとメディア・タイプを含むドキュメント。

戻り値

このファクションは、コンテンツを除き、指定されたコレクションでサポートされているすべてのドキュメント・コンポーネントを含む結果ドキュメントを戻します。指定されたコレクションでサポートされている場合、最終変更およびバージョン・コンポーネントが新しい値で更新されます。指定されたキーを持つドキュメントがコレクション内になかった場合は、結果ドキュメントのかわりにNULLが戻されます。

例外

Error - コレクション内のドキュメントを置換しているときにエラーが発生した場合。

317.3.1.16 SAVEファンクション

このファンクションは、ドキュメントをコレクションに保存します。このファンクションは、INSERT_ONE(document)ファンクションと同等ですが、クライアント割当てキーが使用され、指定されたキーを持つドキュメントがコレクションにすでに存在する場合、入力ドキュメントで置き換えられる点を除きます。このコレクションがクライアント割当てキーで構成され、キーが入力ドキュメントに指定されている場合を除き、キーは自動的に作成されます。

構文

SAVE (
     document IN  SODA_Document_T) 
  RETURN NUMBER;

パラメータ

表317-13 SAVEパラメータ

パラメータ	説明
`document`	入力ドキュメント。 nullを指定することはできません。

戻り値

このファンクションは、正常に完了した場合は番号1を戻し、それ以外の場合は0を戻します。

例外

Error - ドキュメントの保存中にエラーが発生した場合。

317.3.1.17 SAVE_AND_GETファンクション

このファンクションは、ドキュメントをコレクションに保存します。このメソッドは、INSERT_ONE_AND_GET(document)と同等ですが、クライアント割当てキーが使用され、指定したキーを持つドキュメントがコレクションにすでに存在する場合、入力ドキュメントで置き換えられる点を除きます。このコレクションがクライアント割当てキーで構成され、キーが入力ドキュメントに指定されていないかぎり、キーは自動的に作成されます。

構文

SAVE_AND_GET (
     document      IN SODA_Document_T,
     hint          IN VARCHAR2 DEFAULT NULL) 
  RETURN SODA_Document_T;

パラメータ

表317-14 SAVE_AND_GETファンクションのパラメータ

パラメータ	説明
`document`	入力ドキュメント。 nullを指定することはできません。
`hint`	Oracle SQL形式のヒント文字列(囲んでいる`/+`および`/`を除く)。このパラメータは省略可能です。

戻り値

例外

Error - ドキュメントの保存中または取得中にエラーが発生した場合。

317.3.1.18 TRUNCATEファンクション

このファンクションは、コレクション内のドキュメントをすべて削除します。

構文

TRUNCATE ( ) 
  RETURN Number;

戻り値

このファンクションは、次の値を戻します。

1 - ファンクションが正常に完了した場合
0 - ファンクションが正常に完了できなかった場合

例外

Error - コレクション内のドキュメントを削除しているときにエラーが発生した場合。

317.3.2 SODA_Document_Tタイプ

このSODAタイプは、コンテンツを含むドキュメント(通常はJSON形式)を表します。

このタイプは、永続化可能なpl/sqlタイプではありません。ただし、SODAは、基本的に永続性を提供するシステムであり、読取りおよび書込み操作があります。そのため、ドキュメント・コンテンツおよびその他のコンポーネントをデータベースに書き込むには、SODA_DOCUMENT_Tを直接永続化せずに、SODA_COLLECTION_Tで定義されている書込み操作(insertやreplaceなど)にこれを渡します。

ドキュメントには、次のコンポーネントがあります。

key
コンテンツ
作成日のタイムスタンプ
最終変更のタイムスタンプ
バージョン
メディア・タイプ

表317-15 SODA_Document_T型サブプログラム

サブプログラム	説明
`GET_BLOB Function`	`BLOB`ベースのドキュメントのBLOBコンテンツをフェッチします。
`GET_CLOB Function`	`CLOB`ベースのドキュメントの`CLOB`コンテンツをフェッチします。
`GET_CREATED_ON Function`	作成日のタイムスタンプを`VARCHAR2`でフェッチします。
`GET_DATA_TYPE Function`	ドキュメント・コンテンツの作成に使用されたSQLデータ・タイプをフェッチします。
`GET_JSON Function`	`JSON`ベースのドキュメントのJSONコンテンツをフェッチします。
`GET_KEY Function`	ドキュメント・キーを`VARCHAR2`でフェッチします。
`GET_LAST_MODIFIED Function`	最終変更のタイムスタンプを`VARCHAR2`でフェッチします。
`GET_MEDIA_TYPE Function`	ドキュメント・コンテンツのメディア・タイプを`VARCHAR2`でフェッチします。
`GET_VARCHAR2 Function`	`VARCHAR2`ベースのドキュメントの`VARCHAR2`コンテンツをフェッチします。
`GET_VERSION Function`	ドキュメントのバージョンを`VARCHAR2`でフェッチします。
`SODA_Document_T Function`	3つの異なる`SODA_DOCUMENT_T`コンストラクタ・ファンクションがあります。各コンストラクタ・ファンクションは、キー、コンテンツおよびメディア・タイプを使用して、ドキュメント・オブジェクトをインスタンス化します。

317.3.2.1 GET_BLOBファンクション

このファンクションは、ドキュメントのBLOBコンテンツをフェッチします。ドキュメントがBLOBコンテンツで構成されているか、BLOBコンテンツを含むコレクションから戻されたことを前提とします。それ以外の場合はエラーが戻されます。

構文

GET_BLOB () 
 RETURN BLOB;

戻り値

このファンクションは、ドキュメントのBLOBコンテンツを戻します。

例外

SODA Error: ドキュメントが最初にBLOBコンテンツで作成されていなかった場合。

317.3.2.2 GET_CLOBファンクション

このファンクションは、ドキュメントのCLOBコンテンツをフェッチします。ドキュメントがCLOBコンテンツで構成されているか、CLOBコンテンツを含むコレクションから戻されたことを前提とします。それ以外の場合はエラーが戻されます。

構文

GET_CLOB () 
 RETURN CLOB;

戻り値

このファンクションは、ドキュメントのCLOBコンテンツを戻します。

例外

SODA Error: ドキュメントが最初にCLOBコンテンツで作成されていなかった場合。

317.3.2.3 GET_CREATED_ONファンクション

このファンクションは、作成日のタイムスタンプをフェッチします。タイムスタンプ文字列は、ISO-8601形式、具体的にはYYYY-MM-DDThh:mm:ss.ssssssZという形式です。末尾のZが示すように、タイムスタンプはUTCで戻されます(Zは、ゼロのUTCオフセットを示します)。

構文

GET_CREATED_ON () 
 RETURN VARCHAR2;

戻り値

このファンクションは、作成日のタイムスタンプを戻します。

317.3.2.4 GET_DATA_TYPEファンクション

このファンクションは、ドキュメント・コンテンツの作成に使用されたSQLデータ・タイプをフェッチします。

構文

GET_DATA_TYPE () 
 RETURN PLS_INTEGER;

戻り値

表317-16 GET_DATA_TYPE戻り値

定数	値	説明
`DOC_VARCHAR2 CONSTANT PLS_INTEGER`	`1`	`VARCHAR2`
`DOC_BLOB CONSTANT PLS_INTEGER`	`2`	`BLOB`
`DOC_CLOB CONSTANT PLS_INTEGER`	`3`	`CLOB`
`DOC_JSON CONSTANT PLS_INTEGER`	`4`	`JSON`

317.3.2.5 GET_JSONファンクション

このファンクションは、ドキュメントのJSONコンテンツをフェッチします。ドキュメントがJSONタイプのコンテンツで構成されているか、JSONタイプのコンテンツを含むコレクションから戻されたことを前提とします。それ以外の場合はエラーが戻されます。

構文

GET_JSON () 
 RETURN JSON;

戻り値

このファンクションは、ドキュメントのJSONコンテンツを戻します。

例外

SODA Error: ドキュメントが最初にJSONコンテンツで作成されていなかった場合。

317.3.2.6 GET_KEYファンクション

このファンクションは、ドキュメント・キーをフェッチします。

構文

GET_KEY () 
 RETURN VARCHAR2;

戻り値

このファンクションは、ドキュメント・キーを戻します。

317.3.2.7 GET_LAST_MODIFIEDファンクション

このファンクションは、最終変更のタイムスタンプをフェッチします。タイムスタンプ文字列は、ISO-8601形式、具体的にはYYYY-MM-DDThh:mm:ss.ssssssZという形式です。末尾のZが示すように、タイムスタンプはUTCで戻されます(Zは、ゼロのUTCオフセットを示します)。

構文

GET_LAST_MODIFIED () 
 RETURN VARCHAR2;

戻り値

このファンクションは、最終変更のタイムスタンプを戻します。

317.3.2.8 GET_MEDIA_TYPEファンクション

このファンクションは、ドキュメント・コンテンツのメディア・タイプをフェッチします。

構文

GET_MEDIA_TYPE () 
 RETURN VARCHAR2;

戻り値

このファンクションは、ドキュメント・コンテンツのメディア・タイプを戻します。application/JSONがJSONドキュメントのメディア・タイプです(デフォルト)。

317.3.2.9 GET_VARCHAR2ファンクション

このファンクションは、ドキュメントのVARCHAR2コンテンツをフェッチします。ドキュメントがVARCHAR2コンテンツで構成されているか、VARCHAR2コンテンツを含むコレクションから戻されたことを前提とします。それ以外の場合はエラーが戻されます。

構文

GET_VARCHAR2 () 
 RETURN VARCHAR2;

戻り値

このファンクションは、ドキュメントのVARCHAR2コンテンツを戻します。

例外

SODA Error: ドキュメントが最初にVARCHAR2コンテンツで作成されていなかった場合。

317.3.2.10 GET_VERSIONファンクション

このファンクションは、ドキュメントのバージョンをフェッチします。

構文

GET_VERSION () 
 RETURN VARCHAR2;

戻り値

このファンクションは、ドキュメントのバージョンを戻します。

317.3.2.11 SODA_Document_Tファンクション

このファンクションは、キー、コンテンツおよびメディア・タイプを使用して、ドキュメント・オブジェクトをインスタンス化します。 3つの異なるSODA_DOCUMENT_Tコンストラクタ・ファンクションがあります。 2番目のパラメータ(<v|b|c>_Content)が各コンストラクタで異なります。最初のバリアントではVARCHAR2、2番目ではBLOB、3番目ではCLOBです。

構文

キーおよびメディア・タイプは、オプションのパラメータです(デフォルトはNULLです)。 3つのパラメータすべてをNULLに設定できます。 media_TypeがNULLに設定されている場合、デフォルトでapplication/jsonに設定されます。

keyおよびj_Contentをコンストラクタとともに使用し、キーとコンテンツを使用してドキュメント・オブジェクトをインスタンス化します。メディア・タイプ・パラメータは、データがJSONタイプであるため、このコンストラクタには存在しません。したがって、メディア・タイプはapplication/jsonであると認識されます。

SODA_DOCUMENT_T (
     key           IN VARCHAR2 DEFAULT NULL,
     v_Content     IN VARCHAR2,
     media_Type    IN VARCHAR2 DEFAULT NULL) 
 RETURN SODA_Document_T;

SODA_DOCUMENT_T (
     key           IN VARCHAR2 DEFAULT NULL,
     b_Content     IN BLOB,
     media_Type    IN VARCHAR2 DEFAULT NULL) 
 RETURN SODA_Document_T;

SODA_DOCUMENT_T (
     key           IN VARCHAR2 DEFAULT NULL,
     c_Content     IN CLOB,
     media_Type    IN VARCHAR2 DEFAULT NULL) 
 RETURN SODA_Document_T;

SODA_DOCUMENT_T (
     key           IN VARCHAR2 DEFAULT NULL,
     j_Content     IN JSON) 
 RETURN SODA_Document_T;

パラメータ

表317-17 SODA_Document_Tパラメータ

パラメータ	説明
`key`	ドキュメントのキー。
`v_Content`	`VARCHAR2`形式のドキュメントのコンテンツ。
`b_Content`	`BLOB`形式のドキュメントのコンテンツ。
`c_Content`	`CLOB`形式のドキュメントのコンテンツ。
`j_Content`	`JSON`タイプのインスタンスとしてのドキュメントのコンテンツ。
`media_Type`	ドキュメントのメディア・タイプ。 `JSON`ドキュメントの場合、メディア・タイプは`application`/`json`に設定できます。

ノート:

v_Content、b_Contentおよびc_Contentがすべて、1つのSODA_DOCUMENT_Tコンストラクタ・ファクションのパラメータであるわけではありません。 構文の項に示されているように、それぞれがコンストラクタ・ファンクションの特定のバリアントに対応します。

戻り値

このファクションは、SODA_Document_Tタイプのドキュメントを戻します。

317.3.3 SODA_OPERATION_Tタイプ

このSODAタイプは、SODAコレクションに対するフィルタリングやページ区切りによるドキュメントの検索、削除と置換など読取り/書込み操作の実行に使用します。

表317-18 SODA_OPERATION_T型サブプログラム

サブプログラム	説明
`ACQUIRE_LOCK Function`	このファンクションでは、`read`操作の影響を受けるドキュメントが更新のためにロックされます(これはSQLの`select for update`と同等です)。
`AS_OF_SCN Function`	このファンクションは、操作のSCN値を設定します。
`AS_OF_TIMESTAMP Function`	このファンクションは、操作のタイムスタンプ値を設定します。
`COUNT Function`	コレクション内で基準に一致するドキュメントの数を返します。このcount()とskip(...)またはlimit(...)が連鎖されていた場合は、例外が発生します。
`FILTER Function`	操作に対するフィルタ(例による問合せ(QBE)とも呼ばれます)の基準を設定します。同じ`SODA_OPERATION_T`オブジェクトが返されるため、必要に応じてさらに基準を連結できます。
`GET_CURSOR Function`	基準に一致するドキュメントの反復処理に使用できる`SODA_CURSOR_T`オブジェクトを返します。
`GET_DATA_GUIDE Function`	このファンクションは、データ・ガイドを取得します。
`GET_ONE Function`	基準に一致する1つの`SODA_DOCUMENT_T`オブジェクトを返します。複数のドキュメントが基準と一致する場合は、最初のドキュメントのみが返されます。
`HINT Function`	このファンクションは、操作のヒント属性を設定します。
`KEY Function`	指定したキーのドキュメントを返すように指定します。このファンクションと`KEYS`(...)に対する以前のコールが同じチェーンに現れるときには、それらのコールが無視されます。同じ`SODA_OPERATION_T`オブジェクトが返されるため、必要に応じてさらに基準を連結できます。
`KEYS Function`	このファンクションに指定したキーと一致するドキュメントを返すように指定します。このファンクションと`KEY`(...)に対する以前のコールが同じチェーンに現れるときには、それらのコールが無視されます。同じ`SODA_OPERATION_T`オブジェクトが返されるため、必要に応じてさらに基準を連結できます。
`LIMIT Function`	操作によって返されるドキュメントの数の制限を設定します。この設定は、`GET_CURSOR`などの読取り操作にのみ使用できます。書込み操作については、このメソッドを使用して設定した値は無視されます。同じ`SODA_OPERATION_T`オブジェクトが返されるため、必要に応じてさらに基準を連結できます。
`REMOVE Function`	コレクション内で基準に一致するすべてのドキュメントを削除します。削除されたドキュメントの数を返します。
`REPLACE_ONE Function`	コレクション内の1つのドキュメントを指定されたドキュメントに置き換えます。ドキュメントが置換されたかどうかを示す数値を返します。現時点では、このファンクションをコールする前に、置換対象のドキュメントを一意に識別するために、ファンクション`KEY`(...)をコールする必要があります。コンテンツとメディア・タイプを除き、入力ドキュメントで設定されたいずれのコンポーネントも置換中には使用されません。それらは無視されます。
`REPLACE_ONE_AND_GET Function`	コレクション内の1つのドキュメントを指定されたドキュメントに置き換えます。ドキュメントが置換された場合は結果ドキュメントを返します。それ以外の場合は`NULL`を返します。現時点では、このファンクションをコールする前に、置換対象のドキュメントを一意に識別するために、ファンクション`KEY`(...)をコールする必要があります。このファンクションは、`REPLACE_ONE`と類似しています。唯一の違いは、`REPLACE_ONE_AND_GET`は、結果ドキュメントとともに更新されたコンポーネント(バージョンや最終変更のタイムスタンプなど)も返すことです。結果ドキュメントにはコンテンツ・コンポーネントが含まれません。コンテンツとメディア・タイプを除き、入力ドキュメントで設定されたいずれのコンポーネントも置換中には使用されません。それらは無視されます。
`SAMPLE Function`	操作に使用するサンプリング・パラメータを設定します。
`SKIP Function`	操作基準に一致するドキュメントのうち、操作結果からスキップするドキュメントの数を設定します。この設定は、`GET_CURSOR`などの読取り操作にのみ使用できます。書込み操作については、このメソッドを使用して設定した値は無視されます。同じ`SODA_OPERATION_T`オブジェクトが返されるため、必要に応じてさらに基準を連結できます。
`VERSION Function`	指定したバージョンのドキュメントのみを返すように指定します。通常は、`KEY`(...)とともに連鎖させて、`REMOVE`や`REPLACE`などの書込み操作のためのオプティミスティック・ロックを実施します。同じ`SODA_OPERATION_T`オブジェクトが返されるため、必要に応じてさらに基準を連結できます。

317.3.3.1 ACQUIRE_LOCKファンクション

このファンクションでは、読取り操作の影響を受けるドキュメントが更新のためにロックされます(これはSQLのselect for update'と同等です)。 LOCK()を含む操作の後に、コレクション内のドキュメントを更新する別の操作が続きます。たとえば、REPLACEまたはREMOVEファンクションによるものです。ロックにより、その間は他のトランザクションがドキュメントを変更できなくなります。

このACQUIRE_LOCK()ファンクションを含む操作の後に実行されるコミットまたはロールバックにより、ドキュメントのロックが解除されます。つまり、このドキュメントのロックを保持しているトランザクションがコミットまたはロールバックされます。

このファンクションは、COUNT()ファンクションおよびGET_DATA_GUIDE()ファンクション以外のread操作とのみ使用してください。

SKIPおよびLIMITファンクションと組み合せて指定することもできません(エラーがスローされます)。

REPLACEやREMOVEなどのwrite操作とともに指定した場合、それは無視されるため影響はありません。

構文

ACQUIRE_LOCK ( )
 RETURN SODA_Operation_T;

戻り値

このファンクションは、起動時と同じSODA_OPERATION_Tオブジェクトを返します。

317.3.3.2 AS_OF_SCNファンクション

このファンクションは、操作のSCN値を設定します。

構文

AS_OF_SCN (
     scn         IN NUMBER)
 RETURN SODA_Operation_T;

パラメータ

表317-19 AS_OF_SCNファンクションのパラメータ

パラメータ	説明
`scn`	SCNの入力値。 `NULL`は指定できません。

戻り値

このファンクションは、起動時と同じSODA_OPERATION_Tオブジェクトを返します。

317.3.3.3 AS_OF_TIMESTAMPファンクション

このファンクションは、操作のタイムスタンプ値を設定します。

構文

AS_OF_TIMESTAMP (
     timestamp         IN VARCHAR2)
 RETURN SODA_Operation_T;

パラメータ

表317-20 AS_OF_TIMESTAMPファンクションのパラメータ

パラメータ	説明
`timestamp`	入力タイムスタンプ。 `NULL`は指定できません。

戻り値

このファンクションは、起動時と同じSODA_OPERATION_Tオブジェクトを返します。

317.3.3.4 COUNTファンクション

このファンクションは、コレクション内で基準に一致するドキュメントの数を返します。このcount()とskip(...)またはlimit(...)が連鎖されていた場合は、例外が発生します。

構文

COUNT ()
 RETURN NUMBER;

戻り値

このファンクションは、操作に指定した基準に一致するドキュメントの数を返します。

例外

Error-カウントの調査中にエラーが発生した場合。

317.3.3.5 FILTERファンクション

操作に対するフィルタ(例による問合せ(QBE)とも呼ばれます)の基準を設定します。同じSODA_OPERATION_Tオブジェクトが返されるため、必要に応じてさらに基準を付加できます。

構文

FILTER (
     qbe         IN VARCHAR2)
 RETURN SODA_Operation_T;

パラメータ

表317-21 FILTERファンクションのパラメータ

パラメータ	説明
`qbe`	例による問合せを表す文字列。

戻り値

このファンクションは、起動時と同じSODA_OPERATION_Tオブジェクトを返します。

参照:

317.3.3.6 GET_CURSORファンクション

基準に一致するドキュメントの反復処理に使用できるSODA_CURSOR_Tオブジェクトを返します。

構文

(オプション) ここに構文の情報を入力します。

GET_CURSOR ()
 RETURN SODA_Cursor_T;

戻り値

このファンクションは、読取り操作基準と一致するドキュメントの反復処理に使用できるSODA_CURSOR_Tオブジェクトを返します。

例外

SODA Error: カーソルのフェッチ中にエラーが発生した場合。

317.3.3.7 GET_DATA_GUIDEファンクション

このファンクションは、データ・ガイドを取得します。

構文

GET_DATA_GUIDE (
  format    IN PLS_INTEGER DEFAULT 1,  
  flag      IN PLS_INTEGER DEFAULT 0)
 RETURN CLOB;

パラメータ

表317-22 GET_DATA_GUIDEファンクションのパラメータ

パラメータ	説明
`format`	データ・ガイドのフォーマット。このパラメータには、次のいずれかの値を指定できます。 `DBMS_SODA.DATAGUIDE_FORMAT_HIERARCHICAL CONSTANT PLS_INTEGER` := 1; `DBMS_SODA.DATAGUIDE_FORMAT_FLAT CONSTANT PLS_INTEGER` := 2; デフォルト値は`1`です。
`flag`	このパラメータには、次のいずれかの値を指定できます。 `DBMS_SODA.DATAGUIDE_PRETTY CONSTANT PLS_INTEGER` := 1; `DBMS_SODA.DATAGUIDE_GEOJSON CONSTANT PLS_INTEGER` := 2; `DBMS_SODA.DATAGUIDE_GATHER_STATS CONSTANT PLS_INTEGER` := 4; デフォルト値は`0`です。

戻り値

このファンクションは、起動時と同じSODA_OPERATION_Tオブジェクトを返します。

317.3.3.8 GET_ONEファンクション

基準に一致する1つのSODA_DOCUMENT_Tオブジェクトを返します。複数のドキュメントが基準と一致する場合は、最初のドキュメントのみが返されます。

構文

GET_ONE ()
 RETURN SODA_Document_T;

戻り値

最初に一致するドキュメント。

例外

Error-ドキュメントのフェッチ中にエラーが発生した場合。

317.3.3.9 HINTファンクション

このファンクションは、操作のヒント属性を設定します。

構文

HINT (
     hint        IN VARCHAR2)
 RETURN SODA_Operation_T;

パラメータ

表317-23 HINTファンクションのパラメータ

パラメータ	説明
`hint`	Oracle SQL形式のヒント文字列(囲んでいる`/+`および`/`を除く)。

戻り値

このファンクションは、起動時と同じSODA_OPERATION_Tオブジェクトを返します。

317.3.3.10 KEYファンクション

指定したキーのドキュメントを返すように指定します。このファンクションとKEYS(...)に対する以前のコールが同じチェーンに現れるときには、それらのコールが無視されます。同じSODA_OPERATION_Tオブジェクトが返されるため、必要に応じてさらに基準を連結できます。

構文

KEY (
     key         IN VARCHAR2)
 RETURN SODA_Operation_T;

パラメータ

表317-24 KEYファンクションのパラメータ

パラメータ	説明
`key`	操作に使用されるキー。

戻り値

このファンクションは、起動時と同じSODA_OPERATION_Tオブジェクトを返します。

317.3.3.11 KEYSファンクション

このファンクションに指定したキーと一致するドキュメントを返すように指定します。このファンクションとkey(...)に対する以前のコールが同じチェーンに現れるときには、それらのコールが無視されます。同じSODA_OPERATION_Tオブジェクトが返されるため、必要に応じてさらに基準を連結できます。

構文

KEYS (
     key_List  IN SODA_Key_List_T)
 RETURN SODA_Operation_T;

パラメータ

表317-25 KEYSファンクションのパラメータ

パラメータ説明

パラメータ	説明
`key_List`	このパラメータは、キーを表す`VARCHAR2`のリストである`SODA_Key_List_T`です。 `key_list`がタイプ`SODA_Key_List_T`の変数の場合は、次のように初期化できます。 `key_list := SODA_Key_List_T('key1', 'key2', 'key3', etc);`

key_List

このパラメータは、キーを表すVARCHAR2のリストであるSODA_Key_List_Tです。

key_listがタイプSODA_Key_List_Tの変数の場合は、次のように初期化できます。

key_list := SODA_Key_List_T('key1', 'key2', 'key3', etc);

戻り値

このファンクションは、起動時と同じSODA_OPERATION_Tオブジェクトを返します。

317.3.3.12 LIMITファンクション

このファンクションでは、操作によって返されるドキュメントの数の制限を設定します。この設定は、GET_CURSORなどの読取り操作にのみ使用できます。書込み操作については、このメソッドを使用して設定した値は無視されます。同じSODA_OPERATION_Tオブジェクトが返されるため、必要に応じてさらに基準を連結できます。

構文

LIMIT (
     limit         IN NUMBER)
 RETURN SODA_Operation_T;

パラメータ

表317-26 LIMITファンクションのパラメータ

パラメータ	説明
`limit`	読取り操作によって返される結果の数の制限。

戻り値

このファンクションは、起動時と同じSODA_OPERATION_Tオブジェクトを返します。

317.3.3.13 REMOVEファンクション

このファンクションでは、コレクション内で基準に一致するすべてのドキュメントを削除します。削除されたドキュメントの数を返します。

構文

REMOVE ()
 RETURN NUMBER;

戻り値

このファンクションは、操作で削除された一致ドキュメントの数を返します。

例外

Error-ドキュメントの削除中にエラーが発生した場合。

317.3.3.14 REPLACE_ONEファンクション

このファンクションでは、コレクション内の1つのドキュメントを指定されたドキュメントに置き換えます。ドキュメントが置換されたかどうかを示す数値を返します。現時点では、このファンクションをコールする前に、置換対象のドキュメントを一意に識別するために、ファンクションKEY(...)をコールする必要があります。コンテンツとメディア・タイプを除き、入力ドキュメントで設定されたいずれのコンポーネントも置換中には使用されません。それらは無視されます。

構文

REPLACE_ONE (
      document IN SODA_Document_T)
 RETURN NUMBER;

パラメータ

表317-27 REPLACE_ONEファンクションのパラメータ

パラメータ	説明
`document`	置換に使用する新しいコンテンツとメディア・タイプが含まれているドキュメント・オブジェクト。

戻り値

このファクションは数値を返します。ドキュメントが置換された場合は1、それ以外の場合は0です。

例外

Error-コレクションの更新中にエラーが発生した場合。

317.3.3.15 REPLACE_ONE_AND_GETファンクション

コレクション内の1つのドキュメントを指定されたドキュメントに置き換えます。ドキュメントが置換された場合は結果ドキュメントを返します。それ以外の場合はNULLを返します。現時点では、このファンクションをコールする前に、置換対象のドキュメントを一意に識別するために、ファンクションKEY(...)をコールする必要があります。このファンクションは、REPLACE_ONEと類似しています。唯一の違いは、REPLACE_ONE_AND_GETは、結果ドキュメントとともに更新されたコンポーネント(バージョンや最終変更のタイムスタンプなど)も返すことです。結果ドキュメントにはコンテンツ・コンポーネントが含まれません。コンテンツとメディア・タイプを除き、入力ドキュメントで設定されたいずれのコンポーネントも置換中には使用されません。それらは無視されます。

構文

REPLACE_ONE_AND_GET (
     document         IN SODA_Document_T)
 RETURN SODA_Document_T;

パラメータ

表317-28 REPLACE_ONE_AND_GETファンクションのパラメータ

パラメータ	説明
`document`	置換に使用する新しいコンテンツとメディア・タイプが含まれているドキュメント・オブジェクト。

戻り値

例外

Error-コレクションの更新中にエラーが発生した場合

317.3.3.16 SAMPLEファンクション

このファンクションは、操作に使用するサンプリング・パラメータを設定します。

構文

SAMPLE (
     pct     IN   DOUBLE,
     seed    IN   NUMBER      DEFAULT NULL,
     method  IN   PLS_INTEFER DEFAULT DBMS_SODA.SAMPLE_ROW)
 RETURN SODA_Operation_T;

パラメータ

表317-29 SAMPLEファンクションのパラメータ

パラメータ説明

パラメータ	説明
`pct`	サンプルに含める文書またはブロック数の合計の割合。この値は`.000001`以上`100`未満の範囲で指定する必要があります。この割合は、各行(ブロック・サンプリングの場合は行の各クラスタ)が、サンプルの一部として選択される可能性を示します。これは、データベースによってコレクション内のドキュメントの割合が正確に取得されるということではありません。
`seed`	この属性を指定すると、実行ごとに同じサンプルを戻すことを試みるようにデータベースに指示できます。 seed値は、`0`から`4294967295`までの整数で指定する必要があります。この属性を省略した場合、戻されるサンプルは実行ごとに異なります。
`method`	使用するサンプリング方法のタイプ。有効な値は、次のとおりです。 `DBMS_SODA.SAMPLE_ROW` `DBMS_SODA.SAMPLE_BLOCK`

pct

サンプルに含める文書またはブロック数の合計の割合。この値は.000001以上100未満の範囲で指定する必要があります。

この割合は、各行(ブロック・サンプリングの場合は行の各クラスタ)が、サンプルの一部として選択される可能性を示します。これは、データベースによってコレクション内のドキュメントの割合が正確に取得されるということではありません。

seed

この属性を指定すると、実行ごとに同じサンプルを戻すことを試みるようにデータベースに指示できます。

seed値は、0から4294967295までの整数で指定する必要があります。この属性を省略した場合、戻されるサンプルは実行ごとに異なります。

method

使用するサンプリング方法のタイプ。有効な値は、次のとおりです。

DBMS_SODA.SAMPLE_ROW
DBMS_SODA.SAMPLE_BLOCK

戻り値

このファンクションは、SELF操作オブジェクトを戻します。

317.3.3.17 SKIPファンクション

このファンクションでは、操作基準に一致するドキュメントのうち、操作結果からスキップするドキュメントの数を設定します。この設定は、GET_CURSORなどの読取り操作にのみ使用できます。書込み操作については、このメソッドを使用して設定した値は無視されます。同じSODA_OPERATION_Tオブジェクトが返されるため、必要に応じてさらに基準を連結できます。

構文

SKIP (
     offset         IN NUMBER)
 RETURN SODA_Operation_T;

パラメータ

表317-30 SKIPファンクションのパラメータ

パラメータ	説明
`offset`	スキップするドキュメントの数。

戻り値

このファンクションは、起動時と同じSODA_OPERATION_Tオブジェクトを返します

317.3.3.18 VERSIONファンクション

このファンクションでは、指定したバージョンのドキュメントのみを返すように指定します。通常は、KEY(...)とともに連鎖させて、REMOVEやREPLACEなどの書込み操作のためのオプティミスティック・ロックを実施します。同じSODA_OPERATION_Tオブジェクトが返されるため、必要に応じてさらに基準を連結できます。

構文

VERSION (
     version         IN VARCHAR2)
 RETURN SODA_Operation_T;

パラメータ

表317-31 VERSIONファンクションのパラメータ

パラメータ	説明
`version`	操作に使用するドキュメントのバージョン。

戻り値

このファンクションは、起動時と同じSODA_OPERATION_Tオブジェクトを返します

317.3.4 SODA_CURSOR_Tタイプ

このSODAタイプは、ドキュメントの結果セットを表すために使用します。

表317-32 SODA_CURSOR_T型サブプログラム

サブプログラム	説明
`CLOSE Function`	カーソルをクローズします。
`HAS_NEXT Function`	次のドキュメントがカーソルに使用できる場合は、`TRUE`を返します。それ以外の場合は、`FALSE`を返します。
`NEXT Function`	カーソルが指している次のSODAドキュメントを返します。

317.3.4.1 CLOSEファンクション

このファンクションでは、カーソルをクローズします。

構文

CLOSE ()
 RETURN BOOLEAN;

例317-3 戻り値

このファンクションは、ブール値を返します。

317.3.4.2 HAS_NEXTファンクション

このファンクションは、次のドキュメントがカーソルに使用できる場合はTRUEを返します。それ以外の場合は、FALSEを返します。

構文

HAS_NEXT ()
 RETURN BOOLEAN;

戻り値

このファンクションは、ブール値を返します。次のドキュメントがカーソルに使用できる場合は、TRUE。それ以外の場合は、FALSEを返します。

例外

Error-次のドキュメントが使用できるかどうかのチェック中にエラーが発生した場合。

317.3.4.3 NEXTファンクション

このファンクションは、カーソルが指している次のSODAドキュメントを返します。

構文

NEXT ()
 RETURN SODA_Document_T;

戻り値

このファンクションは、カーソルが指している次のSODAドキュメントを返します。 HAS_NEXTファンクションがFALSEを返すときには、NULLを返します。

例外

Error-次のドキュメントの取得中にエラーが発生した場合。