1. Simple Oracle Document Access (SODA)の概要
  2. SODAの概要

1 SODAの概要

Simple Oracle Document Access (SODA)はNoSQL形式のAPIセットであり、これを使用すると、Oracle Databaseのドキュメント(特にJSON)のコレクションを作成および格納でき、Structured Query Language (SQL)や、ドキュメントがどのようにデータベースに格納されているかを理解していなくても、そのコレクションの取得や問合せを行うことができます。

様々な言語とRepresentational State Transfer (REST)アーキテクチャ・スタイルで使用するための別々のSODA実装があります。SODA for REST自体は、ほとんどすべてのプログラミング言語からアクセスできます。これは、SODA操作をUniform Resource Locator (URL)パターンにマップします。

注意:

このマニュアルでは、様々なSODA実装に存在する機能について説明します。ここで説明されている機能の中には、一部の実装で使用できないものがある可能性があります。さらに、異なる実装では、機能の一部で提供方法が異なる可能性があります。詳細は、特定の実装のドキュメントを参照してください。

SODA APIはドキュメント中心です。任意のSODA実装を使用して、ほぼあらゆる種類のドキュメント(ビデオ、イメージ、サウンド、およびその他のバイナリ・コンテンツを含む)について、作成、読取り、更新、削除(CRUD)操作を実行できます。また、任意のSODA実装を使用し、パターン一致: 例による問合せ(QBE)を使用してJavaScript Object Notation (JSON)ドキュメントのコンテンツを問い合せることができます。CRUD操作はドキュメント・キーまたはQBEによって決定できます。

Oracle Databaseでは、JSONデータの格納および問合せをネイティブにサポートしています。SODAドキュメント・コレクションは、通常のデータベース表とビューによってバックアップされます。このため、データベース機能をSODAドキュメントのコンテンツで使用できます。

ただし、SODAアプリケーションを開発またはデプロイするためにSQLに関する知識や、データベース管理者(DBA)の支援は必要ありません。SODA CRUDおよび問合せ操作は、基礎となるデータベース表またはビューに対するSQL操作に自動的にマップされ、これらの操作は最適化されています。

SQL標準では、JSONデータの直接問合せが可能なSQL/JSON演算子のセットが定義されています。これらの演算子に基づくデータベース・ビューでは、ドキュメントの構造の変化に影響されないスキーマの読込み動作を提供します。必要であれば、SQL知識を持つ開発者がSQL/JSONを使用して、データベースを最大限に活用するSODAデータの高度な操作を実行できます。たとえば、SQL開発者は、データベース分析とJSONデータのレポート作成を適用して、他のデータを含む集計や結合操作に組み込むことができます。さらに、SODAアプリケーションはデータベース・トランザクションを使用できます。

次のSODA抽象化により、SQLとクライアント・プログラミングの複雑さが隠されます。

  • コレクション

  • ドキュメント

ドキュメント・コレクションにはドキュメントが含まれています。コレクションはOracle Databaseスキーマ(データベース・ユーザーとも呼ばれます)に永続化されます。一部のSODA実装では、SODAデータベースと呼ばれます。

SODAコレクションは、Oracle Databaseの表またはビューに似ています。

SODAは主にJSONドキュメントを扱うように設計されていますが、ドキュメントはMultipurpose Internet Mail Extensions (MIME)タイプでもかまいません。

そのコンテンツに加えて、ドキュメントには、そのキー、バージョン、メディア・タイプ(コンテンツのタイプ)および作成された日時と最後に変更された日時と呼ばれる一意の識別子を含む他のドキュメント・コンポーネントがあります。一般に、キーはドキュメントの作成時にSODAによって割り当てられますが、クライアントが割り当てたキーも使用できます。コンテンツおよびキー(クライアントによって割り当てられる場合)の他に、ドキュメントのメディア・タイプを設定できます。他のコンポーネントはSODAによって生成および維持されます。コンテンツおよびキー以外のコンポーネントはすべて省略可能です。

SODAドキュメントは、データベース表またはビューの行に類似しており、実際にその行によってバックアップされています。行には、各ドキュメント・コンポーネント(キー、コンテンツ、バージョンなど)ごとに1つの列があります。

含まれているドキュメントに加えて、コレクションには、コレクション・メタデータも関連付けられています。これは、コレクションに関して、その記憶域、バージョンおよびタイムスタンプのドキュメント・コンポーネントを追跡するかどうか、そのようなコンポーネントがどのように生成されるか、コレクションがJSONドキュメントのみを含めることができるかどうかなど、様々な詳細情報を指定します。

一部のコンテキストで、コレクション・メタデータはJSONドキュメントとして表されます。このメタデータ・ドキュメントは、コレクション仕様と呼ばれることがあります。コレクションを作成するときにカスタム・コレクション仕様を指定して、デフォルトで提供されるものとは異なるメタデータを提供できます。

SODAではドキュメントに対するCRUD操作を提供しています。JSONドキュメントはさらに、フィルタ仕様とも呼ばれる例による問合せ(QBE)パターンを使用して、問い合せることができます。フィルタ仕様自体はJSONオブジェクトです。

SODA APIは、コレクション管理(作成、ドロップ、リスト)およびドキュメント管理(CRUD)の操作を提供します。

SODAを使用して実行できるアクションは次のとおりです。

  • コレクションを作成する

  • 既存のコレクションを開く

  • コレクションをドロップする

  • 既存のコレクションをすべてリストする

  • ドキュメントを作成する

  • ドキュメントをコレクションに挿入する

  • コレクション内のドキュメントをキー、またはキーとバージョンで検索する

  • コレクション内のすべてのドキュメントを検索する

  • コレクション内のドキュメントをキーまたはQBEで検索する

  • コレクション内のドキュメントをキー、またはキーとバージョンで置換(更新)する(オプティミスティック・ロック)

  • コレクションから、キー、またはキーとバージョンでドキュメントを削除する(オプティミスティック・ロック)

  • コレクションから、キーまたはQBEでドキュメントを削除する

  • コレクション内のドキュメントを索引付けする(問合せのパフォーマンス向上のため)

  • ドキュメントの構造および型の情報を集計するコレクション用のJSONデータ・ガイドを作成する

アプリケーションは、このようなアクションを1つ以上実行するときに、データベース・トランザクションを使用します。脚注1

関連項目:

  • SODAドキュメントの概要
    SODAは、主にJavaScript Object Notation (JSON)ドキュメント、つまりコンテンツがJSONデータであるドキュメントを操作するように設計されていますが、他の種類のドキュメントも使用できます。ドキュメントには、コンテンツ以外に、他のコンポーネントがあります。
  • SODAドキュメント・コレクションの概要
    SODAコレクションは、Oracle Databaseの表またはビューによってバックアップされる一連のドキュメントです。
  • コレクション表のデフォルトの命名規則
    デフォルトでは、ドキュメント・コレクションの基礎となるデータベースへ表の名前はコレクション名から派生します。

1.1 SODAドキュメントの概要

SODAは、主にJavaScript Object Notation (JSON)ドキュメント、つまりコンテンツがJSONデータであるドキュメントを操作するように設計されていますが、他の種類のドキュメントも使用できます。ドキュメントには、コンテンツ以外に、他のコンポーネントがあります。

次に、単純なJSONドキュメントのコンテンツのテキスト表現を示します。

{ "name"    : "Alexander",
  "address" : "1234 Main Street",
  "city"    : "Anytown",
  "state"   : "CA",
  "zip"     : "12345" }

次のドキュメント・コンポーネントを(たとえばアプリケーション・クライアントなどで)設定できます。

  • キー

  • コンテンツ

  • メディア・タイプ

コレクションでは、各ドキュメントにコレクション固有のドキュメント・キーが必要です。デフォルトでは、コレクションは、挿入されたドキュメントのドキュメント・キーを自動的に生成するように構成されています。コレクション用に独自のカスタム・キーをかわりに使用する場合は、作成時にドキュメントのキーを指定する必要があります。

メディア・タイプは、ドキュメントのコンテンツのタイプを指定します。JSONドキュメントの場合、メディア・タイプは"application/json"です。

次のドキュメント・コンポーネントは、SODA自体によって自動的に設定および管理されます。

  • バージョン

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

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

SODAドキュメントは、コンテンツを含むそのコンポーネントをカプセル化する抽象オブジェクトで、コンテンツのキャリヤです。SODAのドキュメント作成操作でそのようなプログラム・ドキュメント・オブジェクトが作成され、ドキュメント・オブジェクトが検索操作などのなんらかのSODA操作によって返されます。脚注2

ドキュメントは表またはビューの行としてOracle Databaseに格納され、各コンポーネントはそれぞれの列に格納されます。

クライアント・アプリケーションでは、SODAドキュメントは使用される特定のSODA実装に適した方法で表されます。次に例を示します。

  • SODA for Javaでは、ドキュメントはJavaインタフェースとして表されます。

  • SODA for PL/SQLでは、ドキュメンはPL/SQLオブジェクト型として表されます。

  • SODA for Cでは、ドキュメントはOracle Call Interface (OCI)ハンドルとして表されます。

すべての場合で、ドキュメントを作成してそのコンポーネントにアクセスするメソッドまたは関数があります。

これらのSODAコレクションにコンテンツを書き込み、読み取るには、ドキュメントの作成、書込みおよび読取り操作を使用します。

  • SODAのドキュメント作成操作は、指定したコンテンツを含むドキュメント・オブジェクトを作成する場合に使用します。(コンテンツは、JSONデータなどが可能です。)

  • SODAの書込み操作(挿入など)は、Oracle Databaseでドキュメントを永続的に格納する場合に使用します。(ドキュメント・コンテンツはデータベース表に書き込まれます。)

  • SODAの読取り操作(検索など)は、Oracle Databaseからドキュメントをフェッチする場合に使用します。特定のゲッター操作は、特定のドキュメント・コンポーネント(キーやコンテンツなど)を読み取る場合に使用します。

関連項目:

JSONに関する一般的な情報は、JSONの概要を参照

親トピック: SODAの概要

1.2 SODAドキュメント・コレクションの概要

SODAコレクションは、Oracle Databaseの表またはビューによってバックアップされる一連のドキュメントです。

デフォルトでは、SODAドキュメント・コレクションを作成するとOracle Databaseに次のものが作成されます。

  • 永続的なデフォルトのコレクション・メタデータ。

  • SODAクライアントが接続されているデータベース・スキーマ内の、コレクションを保管するための表。

すべてのSODA実装に、JSONで表されるコレクションのメタデータを返すメタデータ取得操作が提供されています。デフォルトのコレクション用に返されるデフォルトのコレクション・メタデータを例1-1に示します。

デフォルトのメタデータには、各ドキュメントの5つのコンポーネント(キー、コンテンツ、バージョン、最終変更のタイムスタンプ、作成時のタイムスタンプ)を追跡するコレクションを指定します。これらは、それぞれkeyColumn、contentcolumn、versionColumn、lastModifiedColumn、creationTimeColumnフィールドでJSONに指定されています。これらの各コンポーネントは、Oracle Databaseでコレクションをバックアップする表またはビューの別の列に格納されます。メタデータは、さらにこれらのコンポーネントに関する様々な詳細およびそれらをバックアップするデータベース列を指定します。

例1-1では、キー・コンポーネント: 列名が"ID"、列タイプが"VARCHAR2"、最大キー長が255、使用されるキー生成メソッドが"UUID"です。

クライアント・アプリケーションでは、ドキュメント・コレクションは使用される特定のSODA実装に適した方法で表されます。次に例を示します。

  • SODA for Javaでは、コレクションはJavaインタフェースとして表されます。

  • SODA for PL/SQLでは、コレクションはPL/SQLオブジェクト型として表されます。

  • SODA for Cでは、コレクションはOracle Call Interface (OCI)ハンドルとして表されます。

コレクションが作成されると、コレクションの作成操作はJavaまたはPL/SQLオブジェクトまたはOCIハンドルを返します。これらのハンドルを使用して、様々なコレクションの読込みおよび書込み操作を実行できます。脚注3

注意:

SODA for REST URI構文では、バージョン・コンポーネントの後に、custom-actions、metadata-catalog、または特定のコレクション名を使用できます。custom-actionsまたはmetadata-catalogを使用する場合、URI内の次のセグメント(存在する場合)はコレクション名です。

構文の柔軟性のため、custom-actionsまたはmetadata-catalogという名前のコレクションを持つことはできません。SODA for RESTを使用して、いずれかの名前のコレクションを作成しようとすると、エラーが発生します。

SODA for REST以外のSODA実装では、custom-actionsまたはmetadata-catalogという名前のコレクションの作成および使用について何ら制約はありません。ただし、相互運用の可能性を考慮して、コレクションにこれらの名前は使用しないことをお薦めします。

コレクションを作成する場合、次のような項目を指定できます。

  • 記憶域の詳細。たとえば、コレクションを格納する表の名前、列の名前とデータ型など。

  • 作成時のタイムスタンプ、最終変更のタイムスタンプおよびバージョン用の列の有無。

  • コレクションがJSONドキュメントのみを格納できるかどうか。

  • ドキュメント・キーの生成方式、およびドキュメント・キーをクライアントで割り当てるかまたは自動的に生成するか。

  • バージョンの生成方式。

この構成可能性により、新しいコレクションを既存のデータベースの表またはビューにマップすることもできます。

デフォルト以外の方法でコレクションを構成するには、カスタム・コレクションメタデータを定義して、コレクションの作成操作に渡す必要があります。このメタデータは、JSONデータとして表されます。

注意:

コレクション・メタデータをカスタマイズして、デフォルトで提供されている動作とは異なる動作を取得できます。ただし、一部のコンポーネントを変更するには、SQLデータ型などのOracle Databaseの概念をよく理解している必要があります。やむを得ない理由のないかぎり、そのようなコンポーネントは変更しないことをお薦めします。SODAコレクションはOracle Database表(またはビュー)の上に実装されるため、多くのコレクション構成要素は基礎となる表構成に関連しています。

たとえば、コンテンツ列の型をBLOB (デフォルト値)からVARCHAR2に変更する場合、その影響(VARCHAR2のコンテンツ・サイズが32Kバイトに制限されること、キャラクタ・セットの変換が発生する場合があることなど)を理解する必要があります。

カスタム・メタデータを使用する理由は次のとおりです。

  • SecureFiles LOB記憶域を構成するため。

  • JSON (異種コレクション)以外のドキュメントを格納するようにコレクションを構成するため。

  • 既存のOracle Databaseの表またはビューを新しいコレクションにマップする。

  • 既存の表へのコレクションのマッピングが読取り専用であることを指定するため。

  • VARCHAR2列をJSONコンテンツに使用するため、および列に許可されているデータのデフォルトの最大長を増やすため。

    データベースが拡張データ型で構成されていて、これらのデータ型の最大長が32767バイトに拡張されている場合に、許可されている最大データ長を増やす必要があります。拡張データ型の詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

関連項目:

SODAコレクション・メタデータ・コンポーネントの詳細は、SODAコレクション・メタデータ・コンポーネント(参考)を参照

コレクションに対する読取りと書込みの操作は、開いている場合にのみ実行できます。コレクションを開くと、コレクションを表すオブジェクト(JavaおよびPL/SQLの場合)またはハンドル(Cの場合)が取得されます。コレクションを作成すると、自動的に開かれます。コレクション作成操作は、コレクション・オブジェクトまたはハンドルを返します。既存のコレクションを開くためのオープン操作もあります。この場合もコレクション・オブジェクトまたはハンドルを返します。 コレクションを作成しようとすると、同じ名前のコレクションがすでに存在する場合は、その既存のコレクションが単に開かれます。

注意:

デフォルトではコレクションの表名はコレクション名から派生しますが、コレクションの作成操作に渡すカスタム・コレクション・メタデータで明示的に指定することもできます。この表名(導出または明示的に指定された)が、現在接続されているデータベース・スキーマ(ユーザー)内の既存の表と一致する場合、create-collection操作はその既存の表を使用してコレクションをバックアップしようとします。脚注4

したがって、既存の表がコレクション・メタデータと一致することを確認する必要があります。たとえば、コレクション・メタデータでコレクションにkey、contentおよびversionの3つの列があることが指定されている場合、基礎となる表にこれらの列が存在し、列の型はコレクション・メタデータで指定されたものと一致する必要があります。コレクション作成操作は、コレクション・メタデータと一致するかどうかを確認するために、既存の表の最小限の検証を実行します。表とメタデータが一致しないと判断された場合、コレクション作成操作でエラーが発生します。

注意:

SQLを使用して、コレクションの基礎となるデータベース表をドロップしないでください。コレクションのドロップには、単なるデータベース表のドロップよりも多くのことが含まれます。表に格納されているドキュメントに加えて、コレクションにはメタデータがあり、これはOracle Databaseにも保持されています。コレクションの基礎となる表をドロップしても、同様にコレクション・メタデータがドロップされることはありません。

例1-1 デフォルトのコレクション・メタデータ

{
   "schemaName" : "mySchemaName",
   "tableName" : "myTableName",
   "keyColumn" :
   {
      "name" : "ID",
      "sqlType" : "VARCHAR2",
      "maxLength" : 255,
      "assignmentMethod" : "UUID"
   },
   "contentColumn" :
   {
      "name" : "JSON_DOCUMENT",
      "sqlType" : "BLOB",
      "compress" : "NONE",
      "cache" : true,
      "encrypt" : "NONE",
      "validation" : "STANDARD"
   },
   "versionColumn" :
   {
     "name" : "VERSION",
     "method" : "SHA256"
   },
   "lastModifiedColumn" :
   {
     "name" : "LAST_MODIFIED"
   },
   "creationTimeColumn" :
   {
      "name" : "CREATED_ON"
   },
   "readOnly" : false
}

関連トピック

親トピック: SODAの概要

1.3 コレクション表のデフォルトの命名規則

デフォルトでは、ドキュメント・コレクションの基礎となるデータベース表の名前はコレクション名から派生します。

デフォルトで提供されているものと異なる表名が必要な場合、カスタム・コレクション・メタデータを使用して明示的に名前を指定します。

デフォルトの表名は、指定したコレクション名から次のように派生します。

  1. コレクション名の各ASCII制御文字および二重引用符(")はアンダースコア(_)に置き換わります。

  2. 次の条件のすべてが適用される場合、名前のすべての文字は大文字に変換され、表名を示します。この場合、SQLコードで表名を引用符で囲む必要はありません。これ以外の場合、表名を引用符で囲む必要があります。

    • 名前内の文字がすべて小文字か、すべて大文字である。

    • 名前がASCII文字で始まる。

    • 名前内の各文字がASCIIの英数字、アンダースコア(_)、ドル記号($)または番号記号(#)である。

      注意:

      Oracleの識別子名には、ドル記号文字($)または数字記号文字(#)を使用しないことをお薦めします。

次に例を示します。

  • コレクション名"col"と"COL"は、両方とも"COL"という名前になります。SQLで使用すると、表名は大/小文字の区別なく解釈されるため、二重引用符(")で囲む必要はありません。

  • コレクション名"myCol"は"myCol"という表名になります。SQLで使用されると、表名は大/小文字を区別して解釈されるため、二重引用符(")で囲む必要があります。

関連トピック

親トピック: SODAの概要


脚注凡例

脚注1: SODA for RESTはこの点に関して例外です。そのアクションにデータベース・トランザクションは使用できません。
脚注2: RESTはプログラミング言語ではないため、SODA for RESTにはドキュメントを示すプログラム的な「オブジェクト」はありません。ただし、SODA for RESTには、同じ概念のドキュメントが含まれています。たとえば、ドキュメントを読むときは、コンポーネントのすべて(キー、コンテンツ、バージョンなど)を含むJSON表現を取得します。
脚注3: これは、言語ベースのSODA実装の場合のみです。SODA for RESTでは、コレクションは、基本的に単なるURLで表されます。
脚注4: SODA for RESTは、ここでは例外です。セキュリティ上の理由から、このコンテキストではSODA for RESTでエラーが発生し、REST操作を使用して既存の表にアクセスすることを禁止します。