295 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は、コレクションに対する読取り操作の結果によるカーソルです。

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

295.1 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は、コレクションに対する読取り操作の結果によるカーソルです。

参照:

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

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

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

  • タイプSODA_Collection_T

  • タイプSODA_Document_T

  • タイプSODA_Operation_T

  • タイプSODA_Cursor_T

295.3 SODAタイプの要約

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

表295-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タイプは、ドキュメントの結果セットを表します。このタイプは永続化できません。

295.3.1 SODA_COLLECTION_Tタイプ

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

表295-2 SODA_COLLECTION_Tタイプのサブプログラム

サブプログラム 説明

CREATE_INDEXファンクション

JSONで表現される索引指定を使用して索引を作成します。

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

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

DROP_INDEXファンクション

名前付き索引を削除します。

FINDファンクション

SODA_OPERATION_Tオブジェクトを返します。コンストラクタがないため、これ以外にSODA_Operation_Tの参照を取得する方法はありません。

FIND_ONEファンクション

キーと一致するドキュメントをフェッチします。

GET_DATA_GUIDEファンクション

CLOBとしてJSONデータ・ガイドを返します。

GET_METADATAファンクション

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

GET_NAMEファンクション

コレクションの名前を戻します。

INSERT_ONEファンクション

ドキュメントをコレクションに挿入します。

INSERT_ONE_AND_GETファンクション

ドキュメントをコレクションに挿入し、コンテンツを除くすべてのコンポーネントを含む結果ドキュメントを戻します。

REMOVE_ONEファンクション

キーと一致するドキュメントを削除します。

REPLACE_ONEファンクション

キーと一致するドキュメントのコンテンツおよび(オプションで)メディア・タイプを置換します。

REPLACE_ONE_AND_GETファンクション

キーと一致するドキュメントのコンテンツおよび(オプションで)メディア・タイプを置換し、すべてのコンポーネント(コンテンツを除く)を含む結果ドキュメントを戻します。

SAVEファンクション

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

SAVE_AND_GETファンクション

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

TRUNCATEファンクション

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

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

構文

CREATE_INDEX (
     specification VARCHAR2) 
  RETURN NUMBER;

パラメータ

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

パラメータ 説明

specification

索引の指定内容。

例295-1 戻り値

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

  • 1—索引が正常に作成された場合。

  • 0—索引が作成されなかった場合。

例外

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

参照:

SODA索引の指定内容の詳細は、次を参照してください。
295.3.1.2 CREATE_VIEW_FROM_DGファンクション

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

構文

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

CREATE_VIEW_FROM_DG (
   view_name                VARCHAR2,
   data_guide               CLOB) 
  RETURN NUMBER;

パラメータ

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

パラメータ 説明

view_name

作成するビューの名前。

data_guide

コレクションのデータ・ガイド。

戻り値

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

  • 1 - プロシージャが正常に完了した場合

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

例外

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

参照:

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

295.3.1.3 DROP_INDEXファンクション

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

構文

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

例295-2 パラメータ

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

パラメータ 説明

index_Name

索引の名前。

force

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

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

戻り値

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

  • 1—索引が正常に削除された場合。

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

例外

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

295.3.1.4 FINDファンクション

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

構文

FIND ()
 RETURN SODA_Operation_T;

戻り値

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

例外

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

295.3.1.5 FIND_ONEファンクション

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

構文

FIND_ONE (
     key         IN VARCHAR2)
 RETURN SODA_Document_T;

パラメータ

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

パラメータ 説明

key

フェッチするドキュメントのキー。

戻り値

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

例外

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

295.3.1.6 GET_DATA_GUIDEファンクション

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

構文

GET_DATA_GUIDE () 
 RETURN CLOB;

戻り値

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

参照:

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

例外

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

295.3.1.7 GET_METADATAファンクション

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

構文

GET_METADATA () 
  RETURN VARCHAR2;

戻り値

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

295.3.1.8 GET_NAMEファンクション

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

構文

GET_NAME ()
 RETURN NVARCHAR2;

戻り値

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

295.3.1.9 INSERT_ONEファンクション

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

構文

INSERT_ONE (
     document      IN SODA_Document_T)
 RETURN NUMBER;

パラメータ

表295-7 INSERT_ONEファンクションのパラメータ

パラメータ 説明

document

入力ドキュメント。

戻り値

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

例外

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

295.3.1.10 INSERT_ONE_AND_GETファンクション

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

構文

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

パラメータ

表295-8 INSERT_ONE_AND_GETファンクションのパラメータ

パラメータ 説明

document

入力ドキュメント。
hint

Oracle SQL形式のヒント文字列(囲んでいる/*+および*/を除く)。このパラメータは省略可能です。

戻り値

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

例外

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

295.3.1.11 REMOVE_ONEファンクション

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

構文

REMOVE_ONE (
     key       IN VARCHAR2)
 RETURN NUMBER;

パラメータ

表295-9 REMOVE_ONEファンクションのパラメータ

パラメータ 説明

key

ドキュメントのキー。

戻り値

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

  • 1 - ドキュメントが正常に削除された場合。

  • 0 - 指定されたキーを持つドキュメントが見つからなかった場合。

例外

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

295.3.1.12 REPLACE_ONEファンクション

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

構文

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

パラメータ

表295-10 REPLACE_ONEのパラメータ

パラメータ 説明

key

ドキュメントのキー。

document

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

戻り値

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

例外

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

295.3.1.13 REPLACE_ONE_AND_GETファンクション

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

構文

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

パラメータ

表295-11 REPLACE_ONE_AND_GETファンクションのパラメータ

パラメータ 説明

key

ドキュメントのキー。

document

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

戻り値

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

例外

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

295.3.1.14 SAVEファンクション

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

構文

SAVE (
     document IN  SODA_Document_T) 
  RETURN NUMBER;

パラメータ

表295-12 SAVEのパラメータ

パラメータ 説明

document

入力ドキュメント。nullを指定することはできません。

戻り値

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

例外

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

295.3.1.15 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;

パラメータ

表295-13 SAVE_AND_GETファンクションのパラメータ

パラメータ 説明

document

入力ドキュメント。nullを指定することはできません。

hint

Oracle SQL形式のヒント文字列(囲んでいる/*+および*/を除く)。このパラメータは省略可能です。

戻り値

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

例外

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

295.3.1.16 TRUNCATEファンクション

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

構文

TRUNCATE ( ) 
  RETURN Number;

戻り値

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

  • 1 - ファンクションが正常に完了した場合

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

例外

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

295.3.2 SODA_DOCUMENT_Tタイプ

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

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

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

  • key

  • コンテンツ

  • 作成日のタイムスタンプ

  • 最終変更のタイムスタンプ

  • バージョン

  • メディア・タイプ

表295-14 SODA_DOCUMENT_Tタイプのサブプログラム

サブプログラム 説明

GET_BLOBファンクション

BLOBベースのドキュメントのBLOBコンテンツをフェッチします。

GET_CLOBファンクション

CLOBベースのドキュメントのCLOBコンテンツをフェッチします。

GET_CREATED_ONファンクション

作成日のタイムスタンプをVARCHAR2でフェッチします。

GET_DATA_TYPEファンクション

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

GET_KEYファンクション

ドキュメント・キーをVARCHAR2でフェッチします。

GET_LAST_MODIFIEDファンクション

最終変更のタイムスタンプをVARCHAR2でフェッチします。

GET_MEDIA_TYPEファンクション

ドキュメント・コンテンツのメディア・タイプをVARCHAR2でフェッチします。

GET_VARCHAR2ファンクション

VARCHAR2ベースのドキュメントのVARCHAR2コンテンツをフェッチします。

GET_VERSIONファンクション

ドキュメントのバージョンをVARCHAR2でフェッチします。

295.3.2.1 GET_BLOBファンクション

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

構文

GET_BLOB () 
 RETURN BLOB;

戻り値

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

例外

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

295.3.2.2 GET_CLOBファンクション

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

構文

GET_CLOB () 
 RETURN CLOB;

戻り値

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

例外

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

295.3.2.3 GET_CREATED_ONファンクション

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

構文

GET_CREATED_ON () 
 RETURN VARCHAR2;

戻り値

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

295.3.2.4 GET_DATA_TYPEファンクション

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

構文

GET_DATA_TYPE () 
 RETURN PLS_INTEGER;

戻り値

表295-15 GET_DATA_TYPEの戻り値

定数 値 説明

DOC_VARCHAR2 CONSTANT PLS_INTEGER

1

VARCHAR2

DOC_BLOB CONSTANT PLS_INTEGER

2

BLOB

DOC_CLOB CONSTANT PLS_INTEGER

3

CLOB
295.3.2.5 GET_KEYファンクション

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

構文

GET_KEY () 
 RETURN VARCHAR2;

戻り値

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

295.3.2.6 GET_LAST_MODIFIEDファンクション

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

構文

GET_LAST_MODIFIED () 
 RETURN VARCHAR2;

戻り値

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

295.3.2.7 GET_MEDIA_TYPEファンクション

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

構文

GET_MEDIA_TYPE () 
 RETURN VARCHAR2;

戻り値

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

295.3.2.8 GET_VARCHAR2ファンクション

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

構文

GET_VARCHAR2 () 
 RETURN VARCHAR2;

戻り値

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

例外

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

295.3.2.9 GET_VERSIONファンクション

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

構文

GET_VERSION () 
 RETURN VARCHAR2;

戻り値

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

295.3.3 SODA_OPERATION_Tタイプ

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

表295-16 SODA_OPERATION_Tタイプのサブプログラム

サブプログラム 説明
ACQUIRE_LOCKファンクション

このファンクションでは、read操作の影響を受けるドキュメントが更新のためにロックされます(これはSQLのselect for updateと同等です)。

AS_OF_SCNファンクション

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

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

COUNTファンクション

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

FILTERファンクション

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

GET_CURSORファンクション

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

GET_DATA_GUIDEファンクション

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

GET_ONEファンクション

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

HINTファンクション

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

KEYファンクション

指定したキーのドキュメントを返すように指定します。このファンクションとKEYS(...)に対する以前のコールが同じチェーンに現れるときには、それらのコールが無視されます。

同じSODA_OPERATION_Tオブジェクトが返されるため、必要に応じてさらに基準を連結できます。

KEYSファンクション

このファンクションに指定したキーと一致するドキュメントを返すように指定します。このファンクションとKEY(...)に対する以前のコールが同じチェーンに現れるときには、それらのコールが無視されます。

同じSODA_OPERATION_Tオブジェクトが返されるため、必要に応じてさらに基準を連結できます。

LIMITファンクション

操作によって返されるドキュメントの数の制限を設定します。この設定は、GET_CURSORなどの読取り操作にのみ使用できます。書込み操作については、このメソッドを使用して設定した値は無視されます。

同じSODA_OPERATION_Tオブジェクトが返されるため、必要に応じてさらに基準を連結できます。

REMOVEファンクション

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

REPLACE_ONEファンクション

コレクション内の1つのドキュメントを指定されたドキュメントに置き換えます。ドキュメントが置換されたかどうかを示す数値を返します。

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

REPLACE_ONE_AND_GETファンクション

コレクション内の1つのドキュメントを指定されたドキュメントに置き換えます。ドキュメントが置換された場合は結果ドキュメントを返します。それ以外の場合はNULLを返します。

現時点では、このファンクションをコールする前に、置換対象のドキュメントを一意に識別するために、ファンクションKEY(...)をコールする必要があります。

このファンクションは、REPLACE_ONEと類似しています。唯一の違いは、REPLACE_ONE_AND_GETは、結果ドキュメントとともに更新されたコンポーネント(バージョンや最終変更のタイムスタンプなど)も返すことです。結果ドキュメントにはコンテンツ・コンポーネントが含まれません。

コンテンツとメディア・タイプを除き、入力ドキュメントで設定されたいずれのコンポーネントも置換中には使用されません。それらは無視されます。

SAMPLEファンクション

操作に使用するサンプリング・パラメータを設定します。

SKIPファンクション

操作基準に一致するドキュメントのうち、操作結果からスキップするドキュメントの数を設定します。この設定は、GET_CURSORなどの読取り操作にのみ使用できます。書込み操作については、このメソッドを使用して設定した値は無視されます。

同じSODA_OPERATION_Tオブジェクトが返されるため、必要に応じてさらに基準を連結できます。

VERSIONファンクション

指定したバージョンのドキュメントのみを返すように指定します。通常は、KEY(...)とともに連鎖させて、REMOVEやREPLACEなどの書込み操作のためのオプティミスティック・ロックを実施します。

同じSODA_OPERATION_Tオブジェクトが返されるため、必要に応じてさらに基準を連結できます。

295.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オブジェクトを返します。

295.3.3.2 AS_OF_SCNファンクション

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

構文

AS_OF_SCN (
     scn         IN NUMBER)
 RETURN SODA_Operation_T;

パラメータ

表295-17 AS_OF_SCNファンクションのパラメータ

パラメータ 説明

scn

SCNの入力値。NULLは指定できません。

戻り値

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

295.3.3.3 AS_OF_TIMESTAMPファンクション

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

構文

AS_OF_TIMESTAMP (
     timestamp         IN VARCHAR2)
 RETURN SODA_Operation_T;

パラメータ

表295-18 AS_OF_TIMESTAMPファンクションのパラメータ

パラメータ 説明

timestamp

入力タイムスタンプ。NULLは指定できません。

戻り値

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

295.3.3.4 COUNTファンクション

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

構文

COUNT ()
 RETURN NUMBER;

戻り値

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

例外

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

295.3.3.5 FILTERファンクション

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

構文

FILTER (
     qbe         IN VARCHAR2)
 RETURN SODA_Operation_T;

パラメータ

表295-19 FILTERファンクションのパラメータ

パラメータ 説明

qbe

例による問合せを表す文字列。

戻り値

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

参照:

295.3.3.6 GET_CURSORファンクション

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

構文

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

GET_CURSOR ()
 RETURN SODA_Cursor_T;

戻り値

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

例外

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

295.3.3.7 GET_DATA_GUIDEファンクション

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

構文

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

パラメータ

表295-20 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オブジェクトを返します。

295.3.3.8 GET_ONEファンクション

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

構文

GET_ONE ()
 RETURN SODA_Document_T;

戻り値

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

例外

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

295.3.3.9 HINTファンクション

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

構文

HINT (
     hint        IN VARCHAR2)
 RETURN SODA_Operation_T;

パラメータ

表295-21 HINTファンクションのパラメータ

パラメータ 説明

hint

Oracle SQL形式のヒント文字列(囲んでいる/*+および*/を除く)。

戻り値

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

295.3.3.10 KEYファンクション

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

構文

KEY (
     key         IN VARCHAR2)
 RETURN SODA_Operation_T;

パラメータ

表295-22 KEYファンクションのパラメータ

パラメータ 説明

key

操作に使用されるキー。

戻り値

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

295.3.3.11 KEYSファンクション

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

構文

KEYS (
     key_List  IN SODA_Key_List_T)
 RETURN SODA_Operation_T;

パラメータ

表295-23 KEYSファンクションのパラメータ

パラメータ 説明

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オブジェクトを返します。

295.3.3.12 LIMITファンクション

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

構文

LIMIT (
     limit         IN NUMBER)
 RETURN SODA_Operation_T;

パラメータ

表295-24 LIMITファンクションのパラメータ

パラメータ 説明

limit

読取り操作によって返される結果の数の制限。

戻り値

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

295.3.3.13 REMOVEファンクション

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

構文

REMOVE ()
 RETURN NUMBER;

戻り値

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

例外

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

295.3.3.14 REPLACE_ONEファンクション

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

構文

REPLACE_ONE (
      document IN SODA_Document_T)
 RETURN NUMBER;

パラメータ

表295-25 REPLACE_ONEファンクションのパラメータ

パラメータ 説明

document

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

戻り値

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

例外

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

295.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;

パラメータ

表295-26 REPLACE_ONE_AND_GETファンクションのパラメータ

パラメータ 説明

document

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

戻り値

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

例外

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

295.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;

パラメータ

表295-27 SAMPLEファンクションのパラメータ

パラメータ 説明
pct

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

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

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

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

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

戻り値

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

295.3.3.17 SKIPファンクション

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

構文

SKIP (
     offset         IN NUMBER)
 RETURN SODA_Operation_T;

パラメータ

表295-28 SKIPファンクションのパラメータ

パラメータ 説明

offset

スキップするドキュメントの数。

戻り値

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

295.3.3.18 VERSIONファンクション

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

構文

VERSION (
     version         IN VARCHAR2)
 RETURN SODA_Operation_T;

パラメータ

表295-29 VERSIONファンクションのパラメータ

パラメータ 説明

version

操作に使用するドキュメントのバージョン。

戻り値

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

295.3.4 SODA_CURSOR_Tタイプ

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

表295-30 SODA_CURSOR_Tタイプのサブプログラム

サブプログラム 説明

CLOSEファンクション

カーソルをクローズします。

HAS_NEXTファンクション

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

NEXTファンクション

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

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

構文

CLOSE ()
 RETURN BOOLEAN;

例295-3 戻り値

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

295.3.4.2 HAS_NEXTファンクション

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

構文

HAS_NEXT ()
 RETURN BOOLEAN;

戻り値

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

例外

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

295.3.4.3 NEXTファンクション

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

構文

NEXT ()
 RETURN SODA_Document_T;

戻り値

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

例外

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