本文へジャンプ

GridDB Web APIリファレンス

Revision: 5.7.0-932

1 Web API

1.1 概要

GridDBクラスタに対して、ロウの登録や取得、TQLやSQL文実行などの操作を行うことができるWeb APIを提供します。 Web APIはWebアプリケーションとして構成されます。

Web API
Web API

Web APIを用いて次のことができます。

  • ロウ取得
    • コンテナからロウを取得
    • コンテナから複数のロウを取得
  • ロウ登録
    • コンテナに対してロウを登録
    • 複数のコンテナに対してロウを登録
  • データベース接続確認
    • データベースに対して接続を確認
  • コンテナ一覧取得
    • データベースに対してコンテナ一覧を取得
  • コンテナ情報取得
    • コンテナに対してコンテナ情報(カラムに関してなど)を取得
  • TQL文実行
    • 複数のTQL文を実行し結果を取得
  • ロウ削除
    • コンテナに対してロウを削除
  • コンテナ作成
    • データベースに対して新規コンテナを作成
  • コンテナ削除
    • データベースに対してコンテナを削除
  • SQL DDL文実行
    • 指定したデータベースでSQL DDL文を実行
  • SQL DML SELECT文実行
    • 指定したデータベースでSQL SELECT文を実行
  • SQL DML UPDATE文実行
    • 指定したデータベースでSQL UPDATE文を実行
  • SQL DCL文実行
    • 指定したデータベースでSQL DCL文を実行
  • SQL SELECT文実行
    • 指定したデータベースでSQL SELECT文を実行
  • SQL UPDATE文実行
    • 指定したデータベースでSQL UPDATE文を実行

1.2 Web APIを利用するには

Web APIを利用するには、事前にJavaをインストールする必要があります。対応するバージョンは以下のとおりです。

  • Oracle Java 8
  • Oracle Java 11
  • OpenJDK 8
  • OpenJDK 11

Web APIのインストールと設定の手順は、以下のとおりです。

  1. ライブラリパッケージをインストールする
  2. Web APIパッケージをインストールする
  3. 接続先のクラスタを設定する
  4. Web APIの動作を設定する(任意)
  5. ログ出力先を設定する(任意)

1.2.1 ライブラリパッケージをインストールする

以下のパッケージをインストールします。

  • Javaライブラリのパッケージ(griddb-ee-java-lib-X.X.X-linux.x86_64.rpm)

Web APIアプリケーションを配置するマシンにrootユーザでログインし、以下のコマンドでパッケージをインストールします。

# rpm -Uvh griddb-ee-java-lib-X.X.X-linux.x86_64.rpm

※X.X.XはGridDBのバージョン

1.2.2 Web APIパッケージをインストールする

Web APIのパッケージ(griddb-ee-webapi-X.X.X-linux.x86_64.rpm)をインストールします。

Web APIアプリケーションを配置するマシンにrootユーザでログインし、以下のコマンドでパッケージをインストールします。

# rpm -Uvh griddb-ee-webapi-X.X.X-linux.x86_64.rpm

※X.X.XはGridDBのバージョン

インストール後、Web APIのjarファイルや設定ファイルは下記のように配置されます。

/usr/griddb-ee-webapi-X.X.X/                             : Web APIインストールディレクトリ
                     conf/
                     etc/
                     griddb-webapi-ee-X.X.X.jar          : Web API jarファイル

/usr/girddb-webapi/griddb-webapi.jar -> /usr/griddb-ee-webapi-X.X.X/griddb-webapi-ee-X.X.X.jar

/var/lib/gridstore/webapi/conf/griddb_webapi.properties  : 設定ファイル
                              /repository.json           : クラスタ情報定義ファイル
                         /log                            : ログ出力ディレクトリ

1.2.3 接続先のクラスタを設定する

Web APIから接続するクラスタの情報を、クラスタ情報定義ファイル( /var/lib/gridstore/webapi/conf/repository.json )に設定します。

接続するクラスタのクラスタ定義ファイル(gs_cluster.json)の値を基に、modeにクラスタ構成の接続方式を指定し、方式に対応するアドレス情報の項目を記載してください。

パラメータ JSONデータ型 説明
clusters 配列 クラスタ情報の配列
name 文字列 クラスタ名
mode 文字列 接続方式(MULTICAST/FIXED_LIST/PROVIDER )
(mode=MULTICAST)
address 文字列 ロウ登録/取得用マルチキャストアドレス
port 整数 ロウ登録/取得用ポート
jdbcAddress 文字列 SQL実行用マルチキャストアドレス
jdbcPort 整数 SQL実行用ポート番号
(mode=FIXED_LIST)
transactionMember 文字列 ロウ登録/取得用アドレスとポート
sqlMember 文字列 SQL実行用アドレスとポート
(mode=PROVIDER)
providerUrl 文字列 全機能共通のプロバイダURL

例)マルチキャスト方式の場合

{
  "clusters" : [
    {
      "name" : "myCluster",
      "mode" : "MULTICAST",
      "address" : "239.0.0.111",
      "port" : 31999
    }
  ]
}

【メモ】

  • repository.jsonの内容が不正である場合(書式誤り、必須パラメータ未定義など)、Web APIの起動がエラーになります。

1.2.4 Web APIの動作を設定する(任意)

Web APIの動作を設定ファイル(/var/lib/gridstore/webapi/conf/griddb_webapi.properties)に設定します。

この設定の変更を行わずに、すべてデフォルト値のままでもWeb APIは動作します。システムの必要に応じて、値の変更を行ってください。

1.2.4.1 GridDBに関する設定

項目 説明 デフォルト値
failoverTimeout WebAPIからGridDBへのアクセスでノード障害を検知してからリトライを繰り返すフェイルオーバー時間(秒) 5
transactionTimeout トランザクション開始から終了までの最大時間(秒) 30
containerCacheSize コンテナ情報をキャッシュする最大数 100

1.2.4.2 Web APIの動作設定

項目 説明 デフォルト値
maxResponseSize ロウ取得、SQL実行結果、TQL実行結果の上限のサイズ(MB) (1~2048までの整数) 20
maxRequestSize ロウ登録の上限のサイズ(MB) (1~2048までの整数) 20
loginTimeout SQL実行時の接続タイムアウト(秒)
(値は整数を指定します。0以下のときはSQL実行はできません。)
5
maxQueryNum 一回のリクエストに含められる最大のSELECT文のクエリ数(0~100までの整数) 10
maxLimit SQL, TQL実行時に一度に取得する上限のロウ数(1以上の整数) 10000
timeZone SQL、TQLで時刻情報を取得する際のオフセット計算に利用するタイムゾーンとして、時刻(±hh:mm または ±hhmm), タイムゾーンID(「Z」のみサポート), AUTO(JavaVMの環境引継ぎ)のいずれかを指定 Z
authenticationMethod 認証方式として、INTERNAL(内部認証) / LDAP(LDAP認証)のいずれかを指定 GridDBクラスタ設定に依存
notificationInterfaceAddress 複数のネットワークインターフェースがあるときにクラスタのネットワーク構成をマルチキャスト方式にする場合、マルチキャストパケットを受信するインターフェースのIPアドレスを指定 OSに依存
sslMode SSL接続設定として、DISABLED(SSL無効)、PREFERRED(SSL有効、ただし非SSL接続も許容),VERIFY(SSL有効かつサーバ証明書検証実施)のいずれかを指定 PREFERRED
blobPath BLOBデータをzipファイルとして処理する際、一時データを保管するために用いられるディレクトリ -

【メモ】

  • 環境設定を反映させるにはWeb APIを再起動する必要があります。
  • LDAP認証、SSL接続の詳細は『GridDB 機能リファレンス』(GridDB_FeaturesReference.html)を参照してください。
  • GridDBクラスタでSSL接続設定が無効の場合、本ツールの設定に依らず、SSL通信は行うことができません。
  • SSL通信設定(sslMode)をVERIFYに設定する場合、信頼する認証局の証明書が必要です。keytoolコマンドを使ってインポートしてください。また、java起動時の引数でトラストストア(-Djavax.net.ssl.trustStore)やパスワード((-Djavax.net.ssl.trustStorePassword)を指定したい場合は、環境変数GS_COMMON_JVM_ARGSに指定してください。信頼する認証局の証明書の有効期限切れ確認は未サポートです。
  • 環境変数GS_COMMON_JVM_ARGSは、以下を参考に/etc/environmentへ設定してください。設定を反映させるにはWeb APIを再起動する必要があります。

例)

GS_COMMON_JVM_ARGS="-Djavax.net.ssl.trustStore=/var/lib/gridstore/admin/keystore.jks -Djavax.net.ssl.trustStorePassword=changeit"
  • クライアントとWEB API間でSSL通信を行う場合、以下を参考に/usr/griddb-webapi/application.propertiesへ設定してください。

例)

server.ssl.enabled=true
server.port=8443
server.ssl.key-store-type=JKS
server.ssl.key-store=/var/lib/gridstore/admin/keystore.jks
server.ssl.key-store-password=changeit
server.ssl.key-alias=tomcat
  • Web APIの使用するポート番号を変更する場合は、以下の/usr/griddb-webapi/application.propertiesの設定を変更してください。設定可能な値は1~65535までの整数です。
#HTTP/HTTPS port
server.port=8081

1.2.5 ログ出力先を設定する(任意)

Web APIのログは、デフォルトでは下記のディレクトリに出力されます。

/var/lib/gridstore/webapi/log

出力先を変更する場合は、下記のファイルを変更してください。

/var/lib/gridstore/webapi/conf/logback.xml

1.2.6 起動と停止

Web APIアプリケーションはserviceコマンドで起動、停止を行うことができます。

# service griddb-webapi [start|stop|status|restart]

1.3 共通機能(HTTPリクエスト/レスポンス)

各機能において共通のHTTPリクエスト/レスポンス部分について説明します。

1.3.1 URI

Web APIを利用する場合にアクセスするURIです。

http://(Web APIサーバのIP):(port)/griddb/v2/(コマンドパス)

【メモ】

  • (コマンドパス)は、各機能の節をご参照ください。
  • 名前に記号('-' '.' '/' '=')を含むクラスタ、データベース、コンテナに対して、Web APIで操作を行うことはできません。

1.3.2 リクエストヘッダ

ヘッダには下記の値を指定してください。(全APIで共通)

項目 説明 必須
Content-Type "application/json; charset=UTF-8"
Authorization GridDBへアクセスするユーザとパスワードをuser:password形式で指定します(Basic認証)

1.3.3 リクエストボディ

リクエストボディで値を送信する場合、JSON形式で記述してください。JSON形式のフォーマットは、各機能の節をご参照ください。

【メモ】

  • JSON形式のデータの文字コードはUTF-8で記述してください。

  • 日時を記述する場合は、UTCで下記の形式で記述してください。

    • YYYY-MM-DDThh:mm:ss.SSSZ
  • 日付型の値で上記以外の形式を指定した場合は、エラーになります。

    • 例)
      • 2016/01/17T14:32:33.888Z ・・・年月日の区切り文字誤りでエラー
      • 2016-01-18 ・・・時間の指定がないのでエラー
  • リクエストボディのJSONデータの最大値(単位:MB)は、下のように griddb_webapi.propertiesで設定できます。

    maxRequestSize=20
    

1.3.4 レスポンスコード

レスポンスコードは各機能の節をご参照ください。

1.3.5 レスポンスボディ

処理が成功した場合のレスポンスボディは、各機能の節をご参照ください。

処理が失敗した場合は、下記の形式でエラーメッセージが返ります。

{
  "version":"v2",
  "errorCode":"エラーコード",
  "errorMessage":"エラーメッセージ"
}

【メモ】

  • リクエストボディのJSONデータの最大値(単位:MB)は、下のように griddb_webapi.propertiesで設定できます。

    maxResponseSize=20
    

1.4 ロウ取得

1.4.1 単一のコンテナからのロウ取得

コンテナやテーブルのロウを取得します。条件を指定して、取得するロウを絞込むこともできます。

コマンドパス

/:cluster/dbs/:database/containers/:container/rows

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)
:container コンテナ(テーブル)名

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

項目 説明 JSONデータ型 必須
/offset 取得開始位置 数値(0からの整数) -
/limit 取得数 数値(1からの整数)
/condition 条件式(詳細は『GridDB TQLリファレンス』(GridDB_TQL_Reference.html)参照) 文字列 -
/sort ソート条件(指定したカラムの値の昇順(asc)・降順(desc)。「カラム名 asc」または「カラム名 desc」と記述する。) 文字列 -

【メモ】

  • limitで指定した値が設定ファイルのmaxLimitの値よりも大きい場合、maxLimitの値をlimit句に使用します。

例)カラムidの値が50以上のロウデータを、idの値で降順ソートし、11番目から100個取得する

{
  "offset" : 10,
  "limit"  : 100,
  "condition" : "id >= 50",
  "sort" : "id desc"
}

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

取得したロウは、下記の形式のJSONデータで返ります。

項目 説明 JSONデータ型
/columns カラム情報の配列 配列
/columns/name カラム名 文字列
/columns/type データ型 文字列
/rows ロウの配列 配列
/total offset, limitを無視した場合の取得ロウ数 数値
/offset 取得開始位置 数値
/limit 適用された取得数 数値

例)

{
  "columns" : [
    {"name": "date", "type": "TIMESTAMP" },
    {"name": "value", "type": "DOUBLE" },
    {"name": "str", "type": "STRING" }
  ],
  "rows" : [
    ["2016-01-16T10:25:00.253Z", 100.5, "normal" ],
    ["2016-01-16T10:35:00.691Z", 173.9, "normal" ],
    ["2016-01-16T10:45:00.032Z", 173.9, null ]
  ],
  "total" : 100000,
  "offset" : 0,
  "limit" : 3
}

ロウのカラム値はカラムのデータ型に応じて、下記のJSONデータ型で出力されます。

分類 データ型 JSONデータ型
基本型 ブール型 BOOL 真偽値 (true または false) true
文字列型 STRING 文字列 "GridDB"
整数型 BYTE/SHORT/INTEGER/LONG 数値 512
浮動小数点数型 FLOAT/DOUBLE 数値 593.5
時刻型 TIMESTAMP 文字列
・UTC
・フォーマット
YYYY-MM-DDThh:mm:ss.SSSZ
"2016-01-16T10:25:00.253Z"
空間型 GEOMETRY 文字列 (WKT表現) "POLYGON((0 0,10 0,10 10,0 10,0 0))"
BLOB型 BLOB 文字列 "UEsDBAoAAAgAADS4PFIAAAAAAAAAAAA..."
配列型 ブール型 BOOL 真偽値の配列 [true, false, true]
文字列型 STRING 文字列の配列 ["A","B","C"]
整数型 BYTE/SHORT/INTEGER/LONG 数値の配列 [100, 39, 535]
浮動小数点数型 FLOAT/DOUBLE 数値の配列 [3.52, 6.94, 1.83]
時刻型 TIMESTAMP 文字列の配列
(書式は基本型の時刻型と同じ)
["2016-01-16T10:25:00.253Z", "2016-01-17T01:42:53.038Z"]

【メモ】

  • BLOBデータはbase64形式で返ります。そのため、BLOBデータの取得後にbase64のデータをデコードする必要があります。
  • カラム値がNULLの場合、JSONデータのカラムにはnullが返ります。

1.4.2 単一のコンテナからのロウ取得(zipファイル形式のBLOBデータ)

本機能はコンテナ (テーブル)からロウを取得します。コンテナにBLOBカラムがある場合、BLOBデータはzipファイルとして返ります。条件を指定して、取得するロウを絞り込むこともできます。

コマンドパス

/:cluster/dbs/:database/containers/:container/rows/blob

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースには"public"を指定してください)
:container コンテナ (テーブル) 名

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

項目名 説明 JSONデータ型 必須
/offset 取得開始位置 0からの整数 -
/limit 取得するロウ数 1からの整数
/condition 条件式(詳細は『GridDB TQLリファレンス』(GridDB_TQL_Reference.html)参照) 文字列 -
/sort ソート条件 (指定したカラムの値の昇順(asc)・降順(desc)。「カラム名 asc」または「カラム名 desc」と記述する。) string -
/fileNameCol 値をBLOBデータファイル名に用いるコンテナ内のカラム名 文字列 -

【メモ】

  • limitで指定される値が設定ファイルのmaxLimitの値よりも大きい場合、limit句ではmaxLimitの値が用いられます。
  • デフォルトでは各ロウのBLOBデータはランダムな名前でファイル拡張子なしで保存されます。 Web APIにはBLOBデータファイル名を別のカラムの値に設定するオプションがあります。例えば、BLOBデータのファイル名を保管する文字列型カラム file_nameを有するテーブルの場合、オプションによりこのカラムの値を使って各ロウのBLOBデータファイル名を設定することができます。: {"fileNameCol": "<column_name>"}

次の例ではカラム"id" の値が50以上のロウデータを取得し、取得したデータを"id"の値の降順にソートし、10番目のロウから100の値を取得し、カラムfile_name の値をBLOBデータファイル名に用います。

{ 
  "offset" : 10, 
  "limit" : 100, 
  "condition" : "id >= 50", 
  "sort" : "id desc",
  "fileNameCol": "file_name"
}

レスポンスコード

コード  説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

レスポンスボディは次のフォームデータとして返ります。

キー 説明 コンテンツタイプ
file zipファイルは全BLOBデータファイルを含みます。
このzipファイルの名前としてランダムな名前が生成され、レスポンスに付加されます。
application/zip
rows 非BLOBのカラムデータ application/json

rows の値は次のJSONデータとして返ります。

項目 説明 JSONデータ型
/columns カラム情報の配列 配列
/columns/name カラム名 文字列
/columns/type カラムデータ型 文字列
/rows ロウの配列 配列
/total offsetとlimitを無視した場合に取得するロウ数 数値
/offset 取得開始位置 数値
/limit 適用する取得数 数値

【メモ】

  • コンテナにBLOBカラムがない場合またはクエリ結果にBLOBデータがない場合、Web APIは中にファイルを含まないzipファイルを返します。
  • コンテナに2つ以上のBLOBカラムがある場合、BLOBデータファイル名は同じ名前の前に番号を付けたものになります。 例:1_picture.jpg、2_picture.jpg.
  • fileNameColのロウ値が無効なファイル名を有する場合、APIサーバはランダムな名前を生成します。
  • zipファイル中のBLOBファイル名はJSONデータ中のBLOBカラムの値と同一であり、双方とも(BLOB)という接頭辞で始まります。
  • レスポンスデータには、JSONデータとフォームデータの2つのデータ型があります。この両者の間は -- で始まる文字列で区切られます。最初のデータがJSONデータで次に来るのがフォームデータです。全BLOBデータファイルを含むzipファイルを取得するには、バイナリの中身をコピーして(PKという接頭辞を最初につけます)、.zip拡張子のファイルに保存します。

例:

  • 次はレスポンスボディの一例です。
--zO7yOzRXhcrXUbD7heAB9rGzewWDfUt
Content-Disposition: form-data; name="rows"
Content-Type: application/json;charset=UTF-8

{"columns":[{"name":"key","type":"INTEGER"},{"name":"data","type":"BLOB"},{"name":"des","type":"STRING"}],"rows":[[1000,"(BLOB)d0f925b9-884a-420a-a7a8-91c53ed7b126","lombok"],[200,"(BLOB)dee59ebc-2bf9-4f36-9b86-0bf72ff16e29","anh2.png"]],"offset":0,"limit":2,"total":3}
--zO7yOzRXhcrXUbD7heAB9rGzewWDfUt
Content-Disposition: form-data; name="file"; filename="e17bba76-4315-4c32-9384-81fff84abc84.zip"
Content-Type: application/zip
Content-Length: 1780817

PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

カラム値はカラムのデータ型に応じて、下記のJSONデータ型を戻します。

分類 データ型 JSONデータ型
基本型 ブール型 BOOL 真偽値 (true または false) true
文字列型 STRING 文字列 "GridDB"
整数型 BYTE/SHORT/INTEGER/LONG 数値 512
浮動小数点数型 FLOAT/DOUBLE 数値 593.5
日付時刻型 TIMESTAMP テキスト文字列
・UTC
・書式
YYYY-MM-DDThh:mm:ss.SSSZ
"2016-01-16T10:25:00.253Z"
空間型 GEOMETRY テキスト文字列(WKT表現) POLYGON((0 0,10 0,10 10,0 10,0 0))
配列型 ブール型 BOOL 真偽値の配列 [true, false, true]\
文字列型 STRING テキスト文字列値の配列 ["A","B","C"]
整数型 BYTE/SHORT/INTEGER/LONG 数値の配列 [100, 39, 535]
浮動小数点数型 FLOAT/DOUBLE 数値の配列 [3.52, 6.94, 1.83]
日付時刻型 TIMESTAMP テキスト文字列値の配列
(書式はと基本型の日付時刻型と同一)
["2016-01-16T10:25:00.253Z", "2016-01-17T01:42:53.038Z"]

【メモ】

  • カラム値がNULLの場合、JSONデータのカラムにはnullが返ります。

1.4.3 複数のコンテナからのロウ取得

本機能は複数のコンテナ(テーブル)からロウを取得します。条件を指定して取得するロウを絞り込むこともできます。本機能はロウキーを有するコンテナにのみサポートされています。

コマンドパス

/:cluster/dbs/:database/containers/rows

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

項目 説明 JSONデータ型 必須 デフォルト値
/name コンテナ名 文字列 -
/startKeyValue - ロウデータを取得する開始位置を指定するためのロウキー値。
- startKeyValueはデータ型がLONG、INTEGER、TIMESTAMPのいずれかであるひとつのロウキーを有するコンテナに対してのみ適用されます。
- ロウキーがTIMESTAMP型の場合、開始のキー値は次の形式になっている必要があります。 yyyy-MM-ddTHH:mm:ss.SSSZ
文字列または数値 - -
/finishKeyValue - ロウデータを取得する終了位置を指定するためのロウキー値。
- finishKeyValueはデータ型がLONG、INTEGER、TIMESTAMPのいずれかであるひとつのロウキーを有するコンテナに対してのみ適用されます。
- ロウキーがTIMESTAMP型の場合、終了のキー値は次の形式になっている必要があります。 yyyy-MM-ddTHH:mm:ss.SSSZ
文字列または数値 - -
/keyValues - ロウデータ取得の検索条件として使われるロウキー値の一覧。この一覧中の値と一致するロウキーを有するロウデータが返ります。
- keyValuesはデータ型がSTRING、LONG、 INTEGER、TIMESTAMPのいずれかであるひとつのロウキーを有するコンテナに対してのみ適用されます。
- startKeyValuefinishKeyValuekeyValuesを同時に指定した場合、Web APIはkeyValuesの条件を使ってロウを取得し、startKeyValuefinishKeyValueは無視します。
- ロウキーがTIMESTAMP型の場合、キー値は次の形式になっている必要があります。yyyy-MM-ddTHH:mm:ss.SSSZ
文字列/数値の配列 - -
/offset 取得開始位置。offsetは各コンテナに対し設定されます。 0からの整数 - 0
/limit 取得するロウ数。limitは各コンテナに対し設定されます。 1からの整数 - 10000

【メモ】

  • limitに指定された値が設定ファイルのmaxLimitの値よりも大きい場合、maxLimitの値をlimit句に使用します。
  • BLOBデータはbase64形式で返ります。そのため、BLOBデータの取得後にbase64のデータをデコードする必要があります。
  • startKeyValuefinishKeyValuekeyValuesの条件はひとつのロウキーを有するコンテナにのみサポートされています。

次の例は2つのコンテナからロウデータを取得します。最初のコンテナはキー値が0から100であるロウデータを取得し、その中の2番目のロウから10個の値を取得します。2番目のコンテナはキー値が1、3、5のいずれかであるロウデータを取得します。

[
  {
    "name":"container1",
    "startKeyValue":0,
    "finishKeyValue":100,
    "limit":10,
    "offset":2
  },
  {
    "name":"container2",
    "keyValues":[1, 3, 5]
  }
]

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

取得したロウは次のJSONデータとして返ります。

項目 説明 JSONデータ型
/container コンテナ名 文字列
/columns カラム情報の配列 配列
/columns/name カラム名 文字列
/columns/type JSONデータ型 文字列
/results ロウの配列 Array
/total offset, limitを無視した場合のロウの取得数 数値
/offset 取得開始位置 数値
/limit 適用された取得数 数値

例)

[
  {
    "container":"container1",
    "columns": [
      { "name":"date", "type":"TIMESTAMP" },
      { "name":"value", "type":"DOUBLE" },
      { "name":"str", "type":"STRING" }
    ],
    "results": [
      ["2016-01-16T10:25:00.253Z", 100.5, "normal"],
      ["2016-01-16T10:35:00.691Z", 173.9, "normal"],
      ["2016-01-16T10:45:00.032Z", 173.9, null]
    ],
    "total":100,
    "offset":0,
    "limit":3
  },
  {
    "container":"container2",
    "columns": [
      { "name":"date", "type":"STRING" },
      { "name":"value", "type":"LONG" }
    ],
    "results": [
      ["string1", 100],
      ["string2", 173],
      ["string3", 200]
    ],
    "total":10000,
    "offset":0,
    "limit":10000
  }
]

カラムのデータ型に応じて、次のJSONタイプのカラム値が戻ります。本セクションを参照してください。

【メモ】

  • カラム値がNULLの場合、JSONデータのカラムにはnullが返ります。

1.5 ロウ登録

1.5.1 単一のコンテナへのロウ登録

ひとつのコンテナにロウを登録します。

登録するロウは、JSON形式で指定します。ひとつのコンテナに複数のロウを登録することもできます。

【メモ】

  • ひとつのコンテナに1ロウ/複数ロウのデータを指定して登録することができます。
  • 登録先のコンテナは存在している必要があります。
  • ロウキーが指定されているコンテナの場合、既にコンテナに存在するロウキーと同一のロウキーを指定するとロウが更新されます。ロウキーが異なる場合は、ロウが新規に登録されます。
  • ロウキーが指定されていないコンテナの場合、すべてのロウが新規に登録されます。
  • Web APIはbase64形式のBLOBデータをサポートしています。そのため、このデータをリクエストボディに指定する前にbase64のBLOBデータはエンコードする必要があります。
  • ロウ登録処理の途中で例外が発生した場合、一部のロウに対する登録のみが反映されたままとなる場合があります。そのため、例外発生時にHTTPクライアントでリトライする場合、ロウキーが指定されていないコンテナの場合は同じデータが重複して登録される場合があります。

コマンドパス

/:cluster/dbs/:database/containers/:container/rows

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)
:container コンテナ(テーブル)名

HTTPメソッド

PUT

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

ロウを下記のJSON形式で指定してください。

項目 説明 JSONデータ型 必須
/(row) ロウ(カラム値の配列) 配列

例)

[
  ["2016-01-16T10:25:00.253Z", 100.5, "normal"],
  ["2016-01-16T10:35:00.691Z", 173.9, "normal"],
  ["2016-01-16T10:45:00.032Z", 173.9, null]
]

ロウのカラム値はカラムのデータ型に応じて、下記のJSONデータ型で記述してください。

分類 データ型 JSONデータ型
基本型 ブール型 BOOL 真偽値 (true または false)
または 文字列 ("true" または "false")
true
文字列型 STRING 文字列 "GridDB"
整数型 BYTE/SHORT/INTEGER/LONG 数値 または 文字列 512
浮動小数点数型 FLOAT/DOUBLE 数値 または 文字列 593.5
時刻型 TIMESTAMP 文字列
・UTC
・フォーマット
YYYY-MM-DDThh:mm:ss.SSSZ
"2016-01-16T10:25:00.253Z"
空間型 GEOMETRY 文字列 (WKT表現) "POLYGON((0 0,10 0,10 10,0 10,0 0))"
BLOB型 BLOB 文字列 "UEsDBAoAAAgAADS4PFIAAAAAAAAAAAA..."
配列型 ブール型 BOOL 真偽値の配列 または 文字列の配列 [true, false, true]
文字列型 STRING 文字列の配列 ["A","B","C"]
整数型 BYTE/SHORT/INTEGER/LONG 数値の配列 または 文字列の配列 [100, 39, 535]
浮動小数点数型 FLOAT/DOUBLE 数値の配列 または 文字列の配列 [3.52, 6.94, 1.83]
時刻型 TIMESTAMP 文字列の配列
(書式は基本型の時刻型と同じ)
["2016-01-16T10:25:00.253Z", "2016-01-17T01:42:53.038Z"]

【メモ】

  • カラムのデータにNULL値(JSONデータ型のnull)を指定した場合、Web APIは以下のように動作します。
    • 対応するカラムにNOT NULL制約が設定されている場合:登録エラー
    • 対応するカラムにNOT NULL制約が設定されていない場合:NULL値が登録される

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

レスポンスボディはJSONデータとして返ります。

項目 説明 JSONデータ型
/count 更新/挿入されたロウ数 数値

例)

{
  "count" : 2
}

1.5.2 単一のコンテナへのロウ登録(zipファイル形式のBLOBデータ)

本機能は指定したBLOBデータを有するコンテナにロウを登録します。

登録するロウをフォームデータの形式で指定します。ひとつのコンテナに複数のロウを登録することができます。

【メモ】

  • ひとつのコンテナに1ロウ/複数ロウのデータを指定して登録することができます。
  • 登録先のコンテナは存在している必要があります。
  • ロウキーが指定されているコンテナの場合、既にコンテナに存在するロウキーと同一のロウキーを指定するとロウが更新されます。ロウキーが異なる場合は、ロウが新規に登録されます。
  • ロウキーが指定されていないコンテナの場合、ロウが新規に登録されます。
  • ロウ登録処理の途中で例外が発生した場合、一部のロウに対する登録のみが反映されたままとなる場合があります。そのため、例外発生時にHTTPクライアントでリトライする場合、ロウキーが指定されていないコンテナの場合は同じデータが重複して登録される場合があります。

コマンドパス

/:cluster/dbs/:database/containers/:container/rows/blob

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)
:container コンテナ(テーブル)名

HTTPメソッド

PUT

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

リクエストボディを次のフォームデータとして指定します。

キー 説明 コンテンツタイプ
file zipファイルはすべてのBLOBデータファイルを含みます。 application/zip
rows JSON形式でコンテナに追加する必要のあるロウの一覧(各ロウはオブジェクトの一覧) application/json

rows を下記のJSON形式で指定してください。

項目 説明 JSONデータ型 必須
/(row) ロウ(カラム値の配列) 配列

【メモ】

  • BLOBカラムの値は文字列型である必要があります。これはzipファイル中のファイル名(大文字/小文字を区別) についても同じです。

  • BLOBカラムの値がzipファイル中にない場合、エラーが返ります。

  • zipファイルにサブディレクトリがある場合、BLOBカラム値にそのサブディレクトリを指定してください。

  • アップロードファイルの最大サイズは次のようにapplication.propertiesファイルで設定できます。

    # アップロードされるファイルの上限サイズを指定します。デフォルトは1MB
    spring.servlet.multipart.max-file-size=500MB
    
    # multipart/form-data形式のリクエストの上限サイズを指定します。デフォルトは10MB
    spring.servlet.multipart.max-request-size=500MB

例)

  • zipファイルが以下のファイル構造である場合、

    file.zip
        |----image1.png
        |----picture
                |----image2.png
    

    リクエストボディのrows のデータ型は以下のようになっている必要があります。

    [
       ["5","image1.png"],   
       ["6","picture/image2.png"]
    ] 
    

カラム値はカラムのデータ型に応じて、下記のJSONデータ型で記述してください。

分類 データ型 JSONデータ型
基本型 ブール型 BOOL 真偽値(true または false)
または文字列("true"または"false")
true
文字列型 STRING 文字列 "GridDB"
整数型 BYTE/SHORT/INTEGER/LONG 数値またはテキスト文字列 512
浮動小数点数型 FLOAT/DOUBLE 数値またはテキスト文字列 593.5
日付時刻型 TIMESTAMP テキスト文字列
・UTC
・書式
YYYY-MM-DDThh:mm:ss.SSSZ
"2016-01-16T10:25:00.253Z"
空間型 GEOMETRY テキスト文字列 (WKT表現) POLYGON((0 0,10 0,10 10,0 10,0 0))
配列型 ブール型 BOOL 真偽値の配列または文字列の配列 [true, false, true]
文字列型 STRING テキスト文字列値の配列 ["A","B","C"]
整数型 BYTE/SHORT/INTEGER/LONG 数値の配列または文字列の配列 [100, 39, 535]
浮動小数点数型 FLOAT/DOUBLE 数値の配列または文字列の配列 [3.52, 6.94, 1.83]
日付時刻型 TIMESTAMP テキスト文字列値の配列
(書式はと基本型の日付時刻型と同一)
["2016-01-16T10:25:00.253Z", "2016-01-17T01:42:53.038Z"]

【メモ】

  • カラムのデータにNULL値(JSONデータ型のnull)を指定した場合、Web APIは以下のように動作します。
    • 対応するカラムにNOT NULL制約が設定されている場合:登録エラーが発生
    • 対応するカラムにNOT NULL制約が設定されていない場合:NULL値が登録される

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

処理に成功した場合は、何も返りません。

失敗した場合のレスポンスボディは、レスポンスボディ を参照してください。

1.5.3 複数のコンテナへのロウ登録

本機能は複数のコンテナにロウを登録します。

登録するロウは、JSON形式で指定します。ひとつのコンテナに複数のロウを登録することもできます。

【メモ】

  • ひとつのコンテナにひとつまたは複数ロウのデータを指定して登録することができます。
  • 登録先のコンテナは存在している必要があります。
  • ロウキーが指定されているコンテナの場合、既にコンテナに存在するロウキーと同一のロウキーを指定するとロウが更新されます。ロウキーが異なる場合は、ロウが新規に登録されます。
  • ロウキーが指定されていないコンテナの場合、すべてのロウが新規に登録されます。
  • ひとつのロウの中の値の数は、ひとつのコンテナの中のカラム数と等しい必要があります。カラムがnullableの場合、そのカラムの値は省略できません。 nullまたは空の値として指定する必要があります。
  • Web APIはbase64形式のBLOBデータをサポートしています。そのため、このデータをリクエストボディに指定する前にbase64のBLOBデータはエンコードする必要があります。
  • ロウ登録処理の途中で例外が発生した場合、一部のロウに対する登録のみが反映されたままとなる場合があります。そのため、例外発生時にHTTPクライアントでリトライする場合、ロウキーが指定されていないコンテナの場合は同じデータが重複して登録される場合があります。

コマンドパス

/:cluster/dbs/:database/containers/rows

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

PUT

リクエストヘッダ

リクエストヘッダ を参照してください。

リクエストボディ

ロウを下記のJSON形式で指定してください。

項目 説明 JSONデータ型 必須
/containerName コンテナ名 文字列
/rows ロウ(カラム値の配列) 配列

【メモ】

  • ロウキーがTIMESTAMP型の場合、ロウの値は次の形式である必要があります。 yyyy-MM-ddTHH:mm:ss.SSSZ

例)

[
  {
    "containerName":"container2",
    "rows":[
      ["a3", "a4"],
      ["b3", "b4"]
    ]
  },
  {
    "containerName":"container4",
    "rows":[
      [3000, 4000],
      [5000, 6000]
    ]
  }
]

カラム値はカラムのデータ型に応じて、下記のJSONデータ型で記述してください。

本セクション を参照してください。

【メモ】

  • カラム値にNULL値(JSONデータ型のnull)を指定した場合、Web APIは以下のように動作します。
    • 対応するカラムにNOT NULL制約が設定されている場合:登録エラーが発生
    • 対応するカラムにNOT NULL制約が設定されていない場合:NULL値が登録される

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

レスポンスボディは下記のJSONデータで返ります。

項目 説明 JSONデータ型
/containerName コンテナ名 文字列
/updatedRows 更新/挿入されたロウ数 数値

例)

[
  {
    "containerName":"container2",
    "updatedRows" : 2
  },
  {
    "containerName":"container4",
    "updatedRows" : 2
  }
]

1.6 データベース接続確認

指定したデータベースへの接続を確認します。

コマンドパス

/:cluster/dbs/:database/checkConnection

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

GET

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストパラメータ

項目 説明 データ型 必須
/timeout Web API専用のタイムアウト値(秒) 数値(0からの整数) -

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
500 Web API/GridDBでエラーが発生

レスポンスボディ

処理に成功した場合は、何も返りません。

失敗した場合のレスポンスボディは、レスポンスボディを参照してください。

1.7 コンテナ一覧取得

コンテナやテーブルの一覧を取得します。条件を指定して、取得するコンテナを絞込むこともできます。

コマンドパス

/:cluster/dbs/:database/containers

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

GET

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストパラメータ

項目 説明 JSONデータ型 必須
/type 取得コンテナ種別 文字列(COLLECTION または TIME_SERIES) -
/limit 取得数 数値(0からの整数)
/offset 取得開始位置 数値(0からの整数) -
/sort ソート 文字列 -

【メモ】

  • offsetは、必ずlimitと同時に使用する必要があります。

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
500 Web API/GridDBでエラーが発生

レスポンスボディ

取得したロウは、下記の形式のJSONデータで返ります。

項目 説明 JSONデータ型
/names コンテナ名の配列 配列
/total offset, limitを無視した場合の取得数 数値
/offset 取得開始位置 数値
/limit 適用された取得数 数値

例)

{
  "names" : [
    "container1",
    "container2",
    "timeseries1"
  ],
  "total" : 100000,
  "offset" : 0,
  "limit" : 3
}

1.8 コンテナ情報取得

コンテナやテーブルの情報を取得します。

コマンドパス

/:cluster/dbs/:database/containers/:container/info

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)
:container コンテナ(テーブル)名

HTTPメソッド

GET

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

なし

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

項目 説明 JSONデータ型
/container_name コンテナ名 文字列
/container_type コンテナ種別 文字列(COLLECTION または TIME_SERIES)
/rowkey ロウキー有無 真偽値(true または false)
/columns カラム情報の配列 配列
/columns/name カラム名 文字列
/columns/type カラムのデータ型 文字列
/columns/index インデックス 文字列の配列(TREE または SPATIAL)

例)

{
  "container_name" : "container1",
  "container_type" : "COLLECTION",
  "rowkey" : true,
  "columns" : [
    {"name": "date", "type": "TIMESTAMP", "index": ["TREE"]},
    {"name": "value", "type": "DOUBLE", "index": []},
    {"name": "str", "type": "STRING", "index": []}
  ]
}

【メモ】

  • 複合ロウキー、複合索引が設定されているコンテナは非対応です。実行するとIllegalStateExceptionが発生します。

1.9 TQL実行

TQL文を実行します。複数のTQL文を一度に送信することができます。また、実行結果で特定のカラムの値だけを取得することができます。

コマンドパス

/:cluster/dbs/:database/tql

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

項目 説明 JSONデータ型 必須
/name 対象コンテナ名 文字列
/stmt TQL文 文字列
/columns 取得カラム名の配列 配列 -
/hasPartialExecution 部分実行モードの設定有無。デフォルト値は設定無し 真偽値(true または false) -

【メモ】

  • TQL文中のlimitで指定した値が設定ファイルのmaxLimitの値よりも大きい場合、maxLimitの値をlimit句に使用します。

例)

[
  {"name" : "container1", "stmt" : "select * limit 100", "columns" : null, "hasPartialExecution" : true},
  {"name" : "myTable", "stmt" : "select * limit 100", "columns" : ["value1"]} 
]

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

項目 説明 JSONデータ型
/columns カラム情報の配列 配列
/columns/name カラム名 文字列
/columns/type データ型 文字列
/results TQL実行結果 配列
/total offset, limitを無視した場合の取得数 数値
/offset 取得開始位置 数値
/limit 適用された取得数 数値
/responseSizeByte レスポンスサイズ 数値

【メモ】

  • TQL文が集約演算の場合、total, offset, limitは含まれません。

例)

[
  {
    "columns":[
      {"name":"date","type":"TIMESTAMP","timePrecision":"MILLISECOND"},
      {"name":"value","type":"DOUBLE"},{"name":"str","type":"STRING"}
    ],
    "results":[
      ["2016-01-16T10:25:00.253Z",20.02,"row_example_1"],
      ["2016-01-16T10:25:00.254Z",20.03,"row_example_2"],
      ["2016-01-16T10:25:00.255Z",20.04,"row_example_3"],
      ["2016-01-16T10:25:00.256Z",20.05,"row_example_4"]
    ],
    "offset":0,
    "limit":100,
    "total":4,
    "responseSizeByte":116
  },
  {
    "columns":[
      {"name":"value1","type":"DOUBLE"}
  ],
    "results":[
      [1.0]
    ],
    "offset":0,
    "limit":100,
    "total":1,
    "responseSizeByte":8
  }
]

1.10 ロウ削除

コンテナやテーブルのロウを削除します。

コマンドパス

/:cluster/dbs/:database/containers/:container/rows

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)
:container コンテナ(テーブル)名

HTTPメソッド

DELETE

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

項目 説明 JSONデータ型 必須
/(key) ロウキー 配列

例)

[
  "key1",
  "key2",
  "key3"
]

レスポンスコード

コード 説明
204 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

処理に成功した場合は、何も返りません。

失敗した場合のレスポンスボディは、レスポンスボディを参照してください。

【メモ】

  • 複合ロウキーが設定されているコンテナは非対応です。実行するとIllegalStateExceptionが発生します。

1.11 コンテナ作成

コンテナを作成します。

コマンドパス

/:cluster/dbs/:database/containers

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

項目 説明 JSONデータ型 必須
/container_name コンテナ名 文字列
/container_type コンテナ種別 文字列(COLLECTION または TIME_SERIES)
/rowkey ロウキー有無 真偽値(true または false)
/columns カラム情報の配列 配列
/columns/name カラム名 文字列
/columns/type カラムのデータ型 文字列
/columns/index インデックス 文字列の配列(TREE または SPATIAL) -

例)

{
  "container_name" : "container1",
  "container_type" : "COLLECTION",
  "rowkey" : true,
  "columns" : [
    {"name": "date", "type": "TIMESTAMP", "index": ["TREE"]},
    {"name": "value", "type": "DOUBLE", "index": []},
    {"name": "str", "type": "STRING", "index": []}
  ]
}

レスポンスコード

コード 説明
201 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
409 指定したコンテナがすでに存在する
500 Web API/GridDBでエラーが発生

レスポンスボディ

処理に成功した場合は、何も返りません。

失敗した場合のレスポンスボディは、レスポンスボディを参照してください。

【メモ】

  • 複合ロウキー、複合索引は非対応です。

1.12 コンテナ削除

コンテナを削除します。

コマンドパス

/:cluster/dbs/:database/containers

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

DELETE

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

項目 説明 JSONデータ型 必須
/(name) コンテナ名 配列

例)

[
  "container1",
  "container2",
  "timeseries1"
]

レスポンスコード

コード 説明
204 成功、削除対象のコンテナが存在しない
400 リクエストデータの誤り
401 認証エラー、接続エラー
500 Web API/GridDBでエラーが発生

レスポンスボディ

処理に成功した場合は、何も返りません。

失敗した場合のレスポンスボディは、レスポンスボディを参照してください。

1.13 SQL DDL文実行

本機能はGridDBのデータベースでひとつまたは複数のSQL DDL文(CREATE TABLE, DROP TABLE, ALTER TABLE)を実行します。

コマンドパス

/:cluster/dbs/:database/sql/ddl

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダ参照してください。

リクエストボディ

ひとつまたは複数のSQL DDL文を下記のJSON形式で指定してください。

項目 説明 JSONデータ型 必須
/stmt SQL DDL文 string

例)

[ 
 {"stmt" : "CREATE TABLE myTable (key INTEGER PRIMARY KEY, value1 DOUBLE NOT NULL, value2 DOUBLE NOT NULL)"}
]

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
500 Web API/GridDBでエラーが発生

レスポンスボディ

項目 説明 JSONデータ型
/status SQL DDL文のステータス。 10 はそれぞれ成功と失敗を指します。0が含まれる場合も、HTTPのステータスコードは200(OK)が返ります。 数値
/stmt SQL DDL文 文字列
/message クエリ実行時に表示されるエラーメッセージ 文字列

例)

[ 
 {
  "status" : 1,
  "stmt" : "CREATE TABLE myTable (key INTEGER PRIMARY KEY, value1 DOUBLE NOT NULL, value2 DOUBLE NOT NULL)",
  "message": null 
 }
]

1.14 SQL DML SELECT文実行

指定したデータベースでひとつまたは複数のSQL SELECT文を実行します。

コマンドパス

/:cluster/dbs/:database/sql/dml/query

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

ひとつまたは複数のSQL SELECT文を下記のJSON形式で指定してください。

項目 説明 JSONデータ型 必須
/stmt SQL SELECT文 文字列

例)

[
  {"stmt" : "select * from container1"},
  {"stmt" : "select * from myTable"}
]

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

項目 説明 JSONデータ型
/columns カラム情報の配列 配列
/columns/name カラム名 文字列
/columns/type データ型 文字列
/results SQL SELECT実行結果 配列
/responseSizeByte レスポンスサイズ 数値

例)

[
  {
    "columns":[
      {"name":"date","type":"TIMESTAMP","timePrecision":"MILLISECOND"},
      {"name":"value","type":"DOUBLE"},
      {"name":"str","type":"STRING"}
    ],
    "results":[
      ["2016-01-16T10:25:00.253Z",20.02,"row_example_1"],
      ["2016-01-16T10:25:00.254Z",20.03,"row_example_2"],
      ["2016-01-16T10:25:00.255Z",20.04,"row_example_3"],
      ["2016-01-16T10:25:00.256Z",20.05,"row_example_4"]
    ],
    "responseSizeByte":180
  },
  {
    "columns":[
      {"name":"key","type":"INTEGER"},
      {"name":"value1","type":"DOUBLE"},
      {"name":"value2","type":"DOUBLE"}
    ],
    "results":[
      [1,1.0,2.0]
    ],
    "responseSizeByte":20
  }
]

ロウのカラム値はカラムのデータ型に応じて、下記のJSONデータ型で出力されます。

分類 データ型 JSONデータ型
基本型 ブール型 BOOL 真偽値 (true または false) true
文字列型 STRING 文字列 "GridDB"
整数型 BYTE/SHORT/INTEGER/LONG 数値 512
浮動小数点数型 FLOAT/DOUBLE 数値 593.5
時刻型 TIMESTAMP 文字列
・UTC
・フォーマット
YYYY-MM-DDThh:mm:ss.SSSZ
"2016-01-16T10:25:00.253Z"

【メモ】

  • カラムのデータがNULL値の場合は、JSONデータ型のnullが返ります。
  • GEOMETRY型、配列型は未サポートです。
  • GEOMETRY型と配列型カラムのデータ型は”UNKNOWN”となり、カラムのデータとしてはnullが返ります。
  • 複数のSQLを指定する際、どれかひとつでも実行に失敗した場合、HTTPレスポンスのステータスコードとして400が返ります。この際、失敗したSQL以降のSQLは実行されません。

1.15 SQL DML UPDATE文実行

本機能はGridDBのデータベースでひとつまたは複数のSQL UPDATE文(UPDATE, INSERT, DELETE, REPLACE)を実行します。

コマンドパス

/:cluster/dbs/:database/sql/dml/update

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダ参照してください。

リクエストボディ

ひとつまたは複数のSQL UPDATE文を下記のJSON形式で指定してください。

項目 説明 JSONデータ型 必須
/stmt SQL UPDATE文 string

例)

[ 
  {"stmt" : "update container1 set col2 = 333 where col1 = 't3'"}
]

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
500 Web API/GridDBでエラーが発生

レスポンスボディ

項目 説明 JSONデータ型
/status SQL UPDATE文のステータス。 10 はそれぞれ成功と失敗を指します。0が含まれる場合も、HTTPのステータスコードは200(OK)が返ります。 数値
/message クエリ実行時に表示されるエラーメッセージ 文字列
/updatedRows 更新または挿入されたロウ数 数値
/stmt SQL UPDATE文 文字列

例)

[ 
  {
    "status" : 1,
    "updatedRows" : 2,
    "stmt" : "update container1 set col2 = 333 where col1 = 't3'",
    "message": null 
  }
]

1.16 SQL DCL文実行

本機能はGridDBのデータベースでひとつまたは複数のSQL DCL文(GRANT, REVOKE, SET PASSWORD)を実行します。

コマンドパス

/:cluster/dbs/:database/sql/dcl

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダ参照してください。

リクエストボディ

ひとつまたは複数のSQL DCL文を下記のJSON形式で指定してください。

項目 説明 JSONデータ型 必須
/stmt SQL DCL文 string

例)

[ 
 {"stmt" : "grant all on database1 to user1"}
]

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
500 Web API/GridDBでエラーが発生

レスポンスボディ

項目 説明 JSONデータ型
/status SQL DLC文のステータス。 10 はそれぞれ成功と失敗を指します。0が含まれる場合も、HTTPのステータスコードは200(OK)が返ります。 数値
/message クエリ実行時に表示されるエラーメッセージ 文字列
/stmt SQL DCL文 文字列

Example:

[ 
 {
  "status" : 1,
  "stmt" : "grant all on database1 to user1",
  "message": null 
 }
]

1.17 【非推奨】SQL SELECT文実行

指定したデータベースでひとつまたは複数のSQL SELECT文を実行します。

コマンドパス

/:cluster/dbs/:database/sql/select

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダを参照してください。

リクエストボディ

ひとつまたは複数のSQL SELECT文を下記のJSON形式で指定してください。

項目 説明 JSONデータ型 必須
/stmt SQL SELECT文 文字列

例)

[
  {"stmt" : "select * from container1"},
  {"stmt" : "select * from myTable"}
]

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

項目 説明 JSONデータ型
/columns カラム情報の配列 配列
/columns/name カラム名 文字列
/columns/type データ型 文字列
/results SQL SELECT実行結果 配列
/responseSizeByte レスポンスサイズ 数値

例)

[
  {
    "columns":[
      {"name":"date","type":"TIMESTAMP","timePrecision":"MILLISECOND"},
      {"name":"value","type":"DOUBLE"},
      {"name":"str","type":"STRING"}
    ],
    "results":[
      ["2016-01-16T10:25:00.253Z",20.02,"row_example_1"],
      ["2016-01-16T10:25:00.254Z",20.03,"row_example_2"],
      ["2016-01-16T10:25:00.255Z",20.04,"row_example_3"],
      ["2016-01-16T10:25:00.256Z",20.05,"row_example_4"]
    ],
    "responseSizeByte":180
  },
  {
    "columns":[
      {"name":"key","type":"INTEGER"},
      {"name":"value1","type":"DOUBLE"},
      {"name":"value2","type":"DOUBLE"}
    ],
    "results":[
      [1,1.0,2.0]
    ],
    "responseSizeByte":20
  }
]

ロウのカラム値はカラムのデータ型に応じて、下記のJSONデータ型で出力されます。

分類 データ型 JSONデータ型
基本型 ブール型 BOOL 真偽値 (true または false) true
文字列型 STRING 文字列 "GridDB"
整数型 BYTE/SHORT/INTEGER/LONG 数値 512
浮動小数点数型 FLOAT/DOUBLE 数値 593.5
時刻型 TIMESTAMP 文字列
・UTC
・フォーマット
YYYY-MM-DDThh:mm:ss.SSSZ
"2016-01-16T10:25:00.253Z"

【メモ】

  • カラムのデータがNULL値の場合は、JSONデータ型のnullが返ります。
  • GEOMETRY型、配列型は未サポートです。
  • GEOMETRY型と配列型カラムのデータ型は”UNKNOWN”となり、カラムのデータとしてはnullが返ります。
  • 複数のSQLを指定する際、どれかひとつでも実行に失敗した場合、HTTPレスポンスのステータスコードとして400が返ります。この際、失敗したSQL以降のSQLは実行されません。

1.18 【非推奨】SQL UPDATE文実行

本機能はGridDBのデータベースでひとつまたは複数のSQL UPDATE文を実行します。

コマンドパス

/:cluster/dbs/:database/sql/update

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダ参照してください。

リクエストボディ

ひとつまたは複数のSQL UPDATE文を下記のJSON形式で指定してください。

項目 説明 JSONデータ型 必須
/stmt SQL UPDATE文 string

【メモ】

  • Web APIではSQL文中のSELECT、EXPLAIN、ANALYZEはサポートされていません。

例)

[ 
  {"stmt" : "update container1 set col2 = 333 where col1 = 't3'"}
]

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
500 Web API/GridDBでエラーが発生

レスポンスボディ

項目 説明 JSONデータ型
/status SQL UPDATE文のステータス。 10 はそれぞれ成功と失敗を指します。0が含まれる場合も、HTTPのステータスコードは200(OK)が返ります。 数値
/message クエリ実行時に表示されるエラーメッセージ 文字列
/updatedRows 更新または挿入されたロウ数 数値
/stmt SQL UPDATE文 文字列

Example:

[ 
  {
    "status" : 1,
    "updatedRows" : 2,
    "stmt" : "update container1 set col2 = 333 where col1 = 't3'",
    "message": null 
  }
]

1.19 動作確認

Web APIの動作確認は、Linuxのcurlコマンド等で行ってください。

  • 例)データベース接続確認

    curl -f -X GET -u "user:password" \
    http://host:port/griddb/v2/cluster/dbs/public/checkConnection
    
  • 例)コンテナ一覧取得

    curl -f -X GET -u "user:password" \
    http://host:port/griddb/v2/cluster/dbs/public/containers?limit=100
    
  • 例)ロウ取得

    curl -f -X POST -u "user:password" \
    -H "Content-type:application/json; charset=UTF-8" -d '{"limit":5,"sort":"id asc"}' \
    http://host:port/griddb/v2/cluster/dbs/public/containers/test/rows
    
  • 例)ロウ登録

    curl -f -X PUT -u "user:password" \
    -H "Content-type:application/json; charset=UTF-8" -d '[[1,"value"],[2,"value"]]' \
    http://host:port/griddb/v2/cluster/dbs/public/containers/test/rows
    
  • 例)SQL SELECT文実行

    curl -f -X POST -u "user:password" \
    -H "Content-type:application/json; charset=UTF-8" -d '[{"stmt":"select * from test"}]' \
    http://host:port/griddb/v2/cluster/dbs/public/sql/select
    

1.20 アンインストール

Web APIを停止したあと、以下の手順でディレクトリおよび配置したファイルを削除してください。

# rpm -e griddb-ee-webapi