JSON入力パラメータの検証

オプションで、DBMS_VECTOR.UTL関数およびDBMS_VECTOR_CHAIN.UTL関数へのJSON入力の構造を検証できます。この関数は、JSONを使用して入力パラメータを定義します。

JSONデータはスキーマレスであるため、ベクトル・ユーティリティ・パッケージAPIが実行時に行う検証量は最小限で、パフォーマンスが向上します。APIでは、必須のJSONパラメータ(APIを実行するために指定したパラメータ)のみが検証されますが、オプションのJSONパラメータおよび属性は検証されません。

APIをコールする前に、DBMS_JSON_SCHEMAパッケージのサブプログラムを使用して、PARAMS句で指定する入力データが特定のJSONスキーマに対して有効かどうかをテストできます。これにより、柔軟性が向上し、スキーマが有効なデータのみがJSON列に挿入されるようになります。

次のスキーマに対して、DBMS_VECTOR.UTLおよびDBMS_VECTOR_CHAIN.UTLファンクションのJSON入力パラメータを検証します。

データベース・プロバイダの場合:

SCHEMA_CHUNK

{ "title" : "utl_to_chunks", 
  "description" : "Chunk parameters",
  "type" : "object",
  "properties" : { 
    "by"           : {"type" : "string", "enum" : [ "chars", "characters", "words", "vocabulary" ]   }, 
    "max"          : {"type" : "string", "pattern" : "^[1-9][0-9]*$" }, 
    "overlap"      : {"type" : "string", "pattern" : "^[0-9]+$" }, 
    "split"        : {"type" : "string", "enum" : [ "none", "newline", "blankline", "space", "recursively", "custom" ]  }, 
    "vocabulary"   : {"type" : "string"  }, 
    "language"     : {"type" : "string"  }, 
    "normalize"    : {"type" : "string", "enum" : [ "all", "none", "options" ]  }, 
      "norm_options" : {"type" : "array",  "items": {  { "type": "string", "enum": ["widechar", "whitespace", "punctuation"] }  },
    "custom_list"  : {"type" : "array",  "items": { "type": "string" }  }, 
    "extended"     : {"type" : "boolean" } },
  "additionalProperties" : false 
}

SCHEMA_VOCAB

{ "title" : "create_vocabulary", 
  "description" : "Create vocabulary parameters",
  "type" : "object",
  "properties" : { 
    "table_name"      : {"type" : "string" }, 
    "column_name"     : {"type" : "string" }, 
    "vocabulary_name" : {"type" : "string" }, 
    "format"          : {"type" : "string", "enum" : [ "BERT", "GPT2", "XLM" ]  }, 
    "cased"           : {"type" : "boolean" } },
  "additionalProperties" : false, 
  "required" : [ "table_name", "column_name", "vocabulary_name" ]
}

SCHEMA_LANG

{ "title" : "create_lang_data", 
  "description" : "Create language data parameters",
  "type" : "object",
  "properties" : { 
    "table_name"      : {"type" : "string" }, 
    "column_name"     : {"type" : "string" }, 
    "preference_name" : {"type" : "string" }, 
    "language"        : {"type" : "string" } }, 
  "additionalProperties" : false, 
  "required" : [ "table_name", "column_name", "preference_name", "language" ]
}

SCHEMA_TEXT

{ "title": "utl_to_text", 
  "description": "To text parameters",
  "type" : "object",
  "properties" : { 
    "plaintext"       : {"type" : "boolean" }, 
    "charset"         : {"type" : "string", "enum" : [ "UTF8" ] } }, 
  "additionalProperties": false 
}

SCHEMA_DBEMB

{ "title" : "utl_to_embedding", 
  "description" : "To DB embeddings parameters",
  "type" : "object",
  "properties" : { 
    "provider"  : {"type" : "string" }, 
    "model"     : {"type" : "string" } }, 
  "additionalProperties": true, 
  "required" : [ "provider", "model" ]
}

SCHEMA_SUM

{ "title" : "utl_to_summary", 
  "description" : "To summary parameters",
  "type" : "object",
  "properties" : { 
    "provider"       : {"type" : "string" }, 
    "numParagraphs"  : {"type" : "number" }, 
    "language"       : {"type" : "string" }, 
    "glevel"         : {"type" : "string" }  
   }, 
  "additionalProperties" : true, 
  "required" : [ "provider" ]
}

For REST Providers:

SCHEMA_REST


{  "title" : "REST parameters",
   "description" : "REST versions of utl_to_embedding, utl_to_summary, utl_to_generate_text",
   "type" : "object",
   "properties" : {
     "provider"         : {"type" : "string" },
     "credential_name"  : {"type" : "string" },
     "url"              : {"type" : "string" },
     "model"            : {"type" : "string" }
    },
   "additionalProperties" : true,
   "required" : [ "provider", "credential_name", "url", "model" ] }

サードパーティ・サービス・プロバイダに対するすべてのRESTコールは、それぞれの埋込み、要約およびテキスト生成操作に対して同じスキーマを共有します。

例:

JSONスキーマに対してJSONデータを検証するには、PL/SQLファンクションまたはプロシージャのDBMS_JSON_SCHEMA.is_valid()を使用します。

このファンクションは、有効な場合は1を返し、無効な場合は0を返します(無効なデータはオプションでエラーを発生させる可能性があります)。このプロシージャでは、有効な場合はTRUE、OUTパラメータの値として無効な場合はFALSEが返されます。
```
l_valid := sys.DBMS_JSON_SCHEMA.is_valid(params, json(SCHEMA), dbms_json_schema.RAISE_ERROR);
```
プロシージャ(関数ではない)is_validを使用する場合、OUTパラメータとして検証エラー・レポートにアクセスできます。プロシージャをこのように使用すると、スキーマに対してデータがチェックされ、妥当性(BOOLEAN)およびエラー(JSON)のパラメータに出力されます。
```
sys.DBMS_JSON_SCHEMA.is_valid(params, json(SCHEMA), l_valid, l_errors);
```
エラーの詳細な検証レポートを読み取るには、PL/SQLプロシージャDBMS_JSON_SCHEMA.validate_reportを使用します。

(プロシージャではなく)ファンクションis_validを使用する場合、このようなレポートにアクセスできません。関数is_validのかわりに、SQL問合せでPL/SQLファンクションDBMS_JSON_SCHEMA.validate_reportを使用して検証し、プロシージャis_validのOUTパラメータで提供されるものと同じ完全な検証情報をJSON型のインスタンスとして返すことができます。
```
SELECT JSON_SERIALIZE(DBMS_JSON_SCHEMA.validate_report('json',SCHEMA) returning varchar2 PRETTY);
```

関連トピック

親トピック: 埋込みを生成するためのPL/SQLパッケージについて