JSONインスタンスの最大長

Teradata® Database JSONデータ型

brand
Software
prodname
Teradata Database
vrm_release
16.20
category
プログラミング リファレンス
featnum
B035-1150-162K-JPN

JSON型の最大長は可変です。つまり、JSON型にはいくつかのデフォルトの最大長がありますが、VARCHARデータ型と同様の方法で型が使用されている場所で長さを調整できます。したがって、長さが絶対最大長を超えることはできませんが、JSON型の特定のインスタンスに対して定義されている最大長は絶対最大長より短いことがあります。

絶対最大長はJSON型の最大長です。この制限は、16,776,192バイトです。

JSONテキスト データの絶対最大長

JSONテキストの最大長は、使用されている文字セットによって次のように異なります。
  • UNICODEの最大長は、8,388,096文字です。
  • LATINの最大長は、16,776,192文字です。

8,388,096のUNICODE文字または16,776,192のLATIN文字は、JSON型の絶対最大長である16,776,192バイトに相当します。

最大長を指定しないと、文字セットのデフォルトの最大長が選択されます。指定する場合、長さは最小2文字で文字セットの絶対最大長を超えることはできません。文字セットが指定されていない場合、ユーザーの文字セットが使用されます。

JSONバイナリ データの絶対最大長

バイナリ ストレージ形式を使用したJSON型の最大長は、16,776,192バイトです。

バイナリ データの長さが、同じデータのテキスト表現の長さ以下になるとは限りません。したがって、最大長xでテキストとして格納されているJSON列に収まるJSONデータが、 最大長xでバイナリ形式で格納されているJSON列に収まらない可能性があります(逆の場合も同様)。データが確実に収まるように、慎重に長さを選択する必要があります。

JSONバイナリ形式列の最大長の決定

バイナリ形式を使用するJSON列に指定する長さは、バイナリ形式のデータが収まる長さにする必要があります。ただし、データは取得するときに相当するテキストに変換されます。バイナリ形式の文字列がUTF8で格納されている場合、このデータは取得するときにUNICODEに変換されます。

テキスト表現で格納するには長さが十分でないデータは、バイナリ形式で格納できますが、テキスト形式で取得することはできません。大きいサイズにキャストせずにデータを選択するとエラーが報告されます。したがって、列の適切な長さを決定するには、いくつかの計画が必要です。次の例は、この長さを決定する方法を示します。

  1. サポートされているロード ユーティリティのいずれかを使用して、CLOB列を含む中間テーブルに複数のバイナリJSONデータをロードできます。
    CREATE TABLE clobTable(id INTEGER, c CLOB);
    
    /*load many rows of data*/
  2. 次のような問合わせで、バイナリ形式を使用するJSON列に必要な長さを決定します。
    SELECT MAX(NEW JSON(c).StorageSize('BSON')) FROM clobTable;

これは、JSON列の最小可能サイズを決定する方法の1つです。十分な領域があり、JSONを小さくしてパフォーマンス上の利点を享受する必要がない場合は、JSON列を最大可能サイズにすることを推奨します。

最大長の超過

最大長を超えると、次のエラーが返されます。
*** JSON value is too large to store in the defined JSON type.

例えば、JSON列に定義されている最大長より大きいデータを挿入するか、またはJSONパラメータがサポートするサイズより大きいデータを渡そうとすると、このエラーが返されます。

バイナリ形式を使用するJSON列の場合は、定義された列の長さに収まるバイナリ データをロードできますが、このデータは出力(テキスト)形式の最大許容サイズを超えることがあります。この場合、データは、バイナリ形式で格納できますが、テキスト形式で取得することはできません。テキストとしてこのデータにアクセスしようとすると、このエラーが表示されます。この問題が発生した場合は、次のいずれかを行ないます。
  • 最大長が大きいほうのJSON型にデータをキャストします。
  • 事前定義型(VARCHAR/VARBYTE/CLOB/ BLOB)にデータをキャストします。
  • AsJSONTextメソッドまたはAsBSONメソッドを使用してデータを選択します。

JSONデータの最大長と格納

JSONデータは、データのサイズに応じてインラインとLOBサブテーブルで格納されます。
  1. 指定される最大長が64,000バイト(64,000のLATIN文字または32,000のUNICODE文字)以下の場合、テーブルのすべての行のデータはインラインで格納されます。
  2. 指定される最大長が64,000バイトを超える場合、4Kバイト以下のデータを含む行はインラインで格納され、4Kバイトを超えるデータを含む行はLOBサブテーブルで格納されます。この方法で定義されたテーブルでは、データ サイズに応じて一部の行がインラインで格納され、一部の行がLOBサブテーブルで格納されます。

例: 最大長または文字セットを指定しているJSON列を含むテーブルの作成

次の例では、最大長と文字セットを指定する方法を示します。

例: JSON型の単一の列を使用し、最大長と文字セットを指定せずにテーブルを作成する
CREATE TABLE json_table(id INTEGER, json_j1 JSON);

結果: これにより、LATIN文字セットおよびその文字セットの最大長が16,776,192のLATIN文字の表が作成されます。JSON型に文字セットが指定されていない場合、ユーザーのデフォルト文字セットが使用されます。この例の結果では、ユーザーのデフォルト文字セットとしてLATINが指定されていることを想定しています。

例: JSON型の単一の列を使用し、最大長を指定せずにUNICODE文字セットを指定してテーブルを作成する
CREATE TABLE json_table(id INTEGER, json_j1 JSON CHARACTER SET UNICODE);

結果: これにより、UNICODE文字セットおよびその文字セットの最大長が8,388,096のUNICODE文字のテーブルが作成されます。

例: JSON型の単一の列を使用し、最大長を指定し、文字セットを指定せずにテーブルを作成する
CREATE TABLE json_table(id INTEGER, json_j1 JSON(100000));

結果: これにより、最大長が100000のLATIN文字のテーブルが作成されます。この例の結果は、ユーザーのデフォルト文字セットがLATINになっていることを想定しています。

例: JSON型の単一の列を使用し、最大長を指定し、UNICODE文字セットを指定してテーブルを作成する
CREATE TABLE json_table(id INTEGER, json_j1 JSON(100000) CHARACTER SET UNICODE);

結果: これにより、最大長が100000のUNICODE文字のテーブルが作成されます。

例: JSON型の複数の列を使用し、許容される長さを超える最大長を指定し、文字セットを指定せずにテーブルを作成する
CREATE TABLE json_table(id INTEGER, json_j1 JSON(64000), json_j2 JSON(12000));

結果: この事例は、行に格納される最大データ量が約76000バイトまで増大する可能性があるので失敗します。この事例は、前の項目1で説明したように、最大行サイズを超えます。

例: JSON型の複数の列を使用し、最大長を指定し、文字セットを指定せずにテーブルを作成する
CREATE TABLE json_table(id INTEGER, json_j1 JSON(64001), json_j2 JSON(12000));

結果: この事例は、行に格納される最大データ量が16000バイト以内で最大行サイズを超えないので成功します。この事例では、前の項目2で説明したストレージ スキーム(行に最大4Kバイトまで格納される)がjson_j1列に設定されているためです。

例: ストレージ形式を指定しているJSON列を含むテーブルの作成

次のテーブルでは、それぞれの最大長が異なるJSON型の5つの列を定義します。json2の列は、BSONストレージ形式を使用してJSONデータを格納します。json4の列は、UBJSONストレージ形式を使用してJSONデータを格納します。

CREATE TABLE employee (
    id    INTEGER, 
    json1 JSON(20), 
    json2 JSON(25) STORAGE FORMAT BSON, 
    json3 JSON(30) CHARACTER SET UNICODE, 
    json4 JSON(1000) STORAGE FORMAT UBJSON, 
    json5 JSON(5000));

例: JSON型のパラメータを含む関数の作成

次に、JSON型の入力または戻り値のパラメータを含む関数を示します。

CREATE FUNCTION json1 
    (p1 JSON(1000)) 
     RETURNS VARCHAR(100) 
     NO SQL 
     PARAMETER STYLE SQL 
     CALLED ON NULL INPUT 
     DETERMINISTIC 
     LANGUAGE C 
     EXTERNAL NAME 'CS!json1!json1.c!F!json1';
void json1 (	
     JSON_HANDLE    *json_handle, 
     VARCHAR_LATIN  *result,
     int            *indicator_ary,
     int            *indicator_result,
     char           sqlstate[6],
     SQL_TEXT       extname[129],
     SQL_TEXT       specific_name[129],
     SQL_TEXT       error_message[257])	
{
  /* body function */
}
CREATE FUNCTION json2 
    (p1 VARCHAR(100))  
    RETURNS JSON(100) NO SQL 
    PARAMETER STYLE SQL 
    CALLED ON NULL INPUT 
    DETERMINISTIC 
    LANGUAGE C 
    EXTERNAL NAME 'CS!json2!json2.c!F!json2';
void json2 (
     VARCHAR_LATIN  *result,	
     JSON_HANDLE    *json_handle, 
     int            *indicator_ary,
     int            *indicator_result,
     char           sqlstate[6],
     SQL_TEXT       extname[129],
     SQL_TEXT       specific_name[129],
     SQL_TEXT       error_message[257])	
{
  /* body function */
}

例: エラー: 定義されたJSON型を格納するには、JSON値が大きすぎる

この例では、JSON列に挿入されるデータが定義されている最大長より大きい場合はエラーが返されます。

この例のsmallJSONTableテーブルには、LATIN文字の最大長が10文字のJSON列があります。

CREATE TABLE smallJSONTable(id INTEGER, j JSON(10));

次のINSERT文は、JSON列に挿入されるデータが10文字未満なので成功します。

INSERT INTO smallJSONTable(1, '{"a":1}');
*** Insert completed. One row added.
*** Total elapsed time was 1 second.

次のINSERT文は、'{"a":12345}'が最大長の10文字を超えているので失敗します。

INSERT INTO smallJSONTable(1, '{"a":12345}');
*** Failure 7548 JSON value is too large to store in the defined JSON type.           

例: テキストのBSONデータにアクセス中のエラー

この例では、最大長が45バイトでストレージ形式がBSONに定義されているbsonCol列にJSONデータを挿入します。挿入するデータは、BSONで34バイトです。ただし、このデータは、UNICODEテキストでは94バイトです。したがって、問合わせでUNICODEテキストとしてデータにアクセスしようとすると、テキストが45バイトの最大長を超えているため、エラーが返されます。

CREATE TABLE bsonTable(id INTEGER, bsonCol JSON(45) STORAGE FORMAT BSON);

/* insert '{"username":null,"password":null,"member":true}' stored as BSON, 
which is 34 bytes in BSON and 94 bytes in UNICODE text */

INSERT INTO bsonTable(1, 
NEW JSON('220000000A757365726E616D65000A70617373776F726400086D656D626572000100'xb, 
BSON));

SELECT bsonCol FROM bsonTable;

結果:

*** Failure 7548 JSON value is too large to store in the defined JSON type.

この場合、AsJSONTextメソッドやAsBSONメソッドを使用して選択した事前定義型(VARCHAR/VARBYTE/CLOB/BLOB)か、または大きいバージョンのUNICODEテキスト形式のJSON型にキャストできます。

例: JSONバイナリ形式列の最大長の超過

この例では、ubjsonTableテーブルに、最大長が50バイトでストレージ形式がUBJSONに定義されているJSON列が含まれます。

CREATE TABLE ubjsonTable(id INTEGER, ubjsonCol JSON(50) STORAGE FORMAT UBJSON);

次のデータは、ubjsonTableに挿入されます。

INSERT ubjsonTable(1,'[100,100,100,100,100,100,100,100,100,100,100,100]');

次の問合わせでは、StorageSizeメソッドを使用して、UNICODEテキストで上記のデータを格納するために必要なバイトのサイズを取得します。

SELECT ubjsonCol.StorageSize('UNICODE_TEXT') FROM ubjsonTable;

結果:

ubjsonCol.STORAGESIZE('UNICODE_TEXT')
-------------------------------------
		                         98

次の問合わせでは、StorageSizeメソッドを使用して、UBJSON形式で上記のデータの格納に現在使用されているサイズをバイト単位で取得します。

SELECT ubjsonCol.StorageSize('UBJSON') FROM ubjsonTable;

結果:

ubjsonCol.STORAGESIZE('UBJSON')
-------------------------------
		                    40

UBJSON形式で挿入したデータは40バイトなので、このデータは最大長が50バイトに定義されているubjsonCol列に収まります。

次の問合わせは、UNICODEテキストとして挿入されたデータを取得しようとしたので失敗しました。挿入するデータは、前述の問合わせで示したように、UNICODEテキストで98バイトです。これは、ubjsonCol列の最大長である50バイトを超えています。

SELECT ubjsonCol FROM ubjsonTable;

結果:

*** Failure 7548 JSON value is too large to store in the defined JSON type.

UNICODEテキスト形式で挿入されたデータを取得するには、次の問合わせに示すように、データを大きいサイズにキャストする必要があります。

SELECT CAST(ubjsonCol as JSON(100) CHARACTER SET UNICODE) FROM ubjsonTable;

結果:

ubjsonCol
-------------------------------------------------
[100,100,100,100,100,100,100,100,100,100,100,100]