NoSQL な DBaaS である IBM Cloudant を使うようになり、単に「管理/環境構築の手間がない」とか「クラスタリングされてる」という以上に便利な機能がいくつもあることが分かってきました。そのいくつかを実際のサンプルを使って動かす形で紹介しようと思います。今回はいわゆる「バルクインサート」の API で、複数のドキュメントを1回の API でまとめて作成する方法です。
以下の内容を読み進めるにあたり、「実際に自分でも試してみたい」という人は是非 IBM Cloudant のアカウントを取得して、サービスインスタンスを作って動かしてみてください。まだ環境をお持ちでない場合、IBM Bluemix のアカウントを登録して、"Cloudant NoSQL DB" を選択してサービスを作成してください。加えて API の実行には curl コマンドを使うので、curl の実行環境を用意してください(Windows であればこちら、他はおそらく標準のはず):
サービス作成の際に利用プランを選択します。1GB かつ 30 日利用がないと削除されるという条件であれば無料の Lite プランを選択することも可能です。利用用途や目的に合わせて選択してください:
IBM Cloudant のサービスインスタンスを作成したら(或いは既にお持ちであれば)、作成済みのサービスインスタンスの「サービス接続情報」から「資格情報の表示」を選択して、IBM Cloudant に接続するための情報を確認します。具体的にはここで表示される username と password の値を後で利用することになるので、メモしておいてください:
また(今回はあまり使いませんが)IBM Cloudant はウェブのダッシュボード機能があり、データを確認したり、一部の操作をこのダッシュボードから行ったりすることができます。ダッシュボードにアクセスするにはサービスインスタンスの「管理」から「LAUNCH」ボタンをクリックすることで移行できます(或いは上記の「資格情報の表示」の中に表示されている "url" の値をウェブブラウザで指定して開きます。この場合はユーザー名とパスワードを聞かれるので、上記でメモした username と password を指定して開きます):
IBM Cloudant のダッシュボード画面です。左ペインの上から2つ目がデータベース一覧タブになっており、ここから現在作成済みのデータベースを一覧できます(下図ではまだ1つもありません)。この後の作業用に1つデータベースを作っておきます。画面右上の「Create Database」をクリックします:
適当な名前(以下例では "mydb")を入力して「Create」ボタンをクリックします:
指定した名前(mydb)のデータベースができました。この時点ではまだ1つもドキュメント(データ)が入っていないので空の状態です。再度画面左のデータベースアイコンをクリックして、データベース一覧に戻ります:
先程の画面に戻りました。mydb というデータベースが追加されて、現在のサイズやデータ数(# of Docs)などが確認できる状態になっています:
ではこのデータベースに対して、バルクインサート API を実行してみます。まずはインサートするドキュメントデータのサンプル(prefs.json)をここからダウンロードします:
https://raw.githubusercontent.com/dotnsf/samples/master/prefs.json
prefs.json の内容は以下のようになっています。"docs" 内に日本の47都道府県のコード(code)と名前(prefecture)、都道府県庁所在地名(capital)、そしてその緯度(lat)経度(lng)が JSON オブジェクトで定義されており、その配列を docs としています:
これが Cloudant のバルクインサート API で使う場合のデータフォーマットになります。挿入したい複数のドキュメントデータを { "docs": [ .. ] } という形式で、"docs" の配列として定義します。
ではこのドキュメントデータ(prefs.json)を上記で作成した mydb データベースにまとめて格納します。curl を使って以下のように実行します:
※↑青字の username と password の部分には IBM Cloudant の資格情報で確認した値をそのまま指定します。またデータファイル prefs.json はコマンド実行時のカレントディレクトリに存在しているものとします。
コマンド実行後にダッシュボード画面を(リロードして)確認すると、mydb データベースに 47 件の(47都道府県の)ドキュメントデータが格納されていることが分かります。詳しく見るために mydb を選択します:
先程は空だった mydb に 47 件のドキュメントデータが格納されていることが確認できます。個々のドキュメントデータの中身はこの(デフォルトの "Metadata" の)画面だとわかりにくいので、表示形式を "Table" か "JSON" に切り替えてみます(ここでは JSON を選択します):
ドキュメントデータが JSON フォーマットで、実際に格納した中身(doc)まで含めて表示されます。画面では北海道の1ドキュメントデータしか表示されていませんが、下にスクロールすると他のドキュメントデータも確認することができます:
なお、データベースのドキュメントデータ一覧は curl で以下のコマンドを実行した結果でも確認することができます:
↑include_docs=true のパラメータを付けて実行すると doc の中身まで、付けずに実行すると id と key の一覧のみ取得します。
今回は1回の API 実行で複数のドキュメントデータをまとめて Cloudant に格納するバルクインサート API を紹介しました。バルクインサート自体は必ずしも Cloudant の特徴というわけではなく、他のデータベースシステムにも存在している機能だと思いますが、今後 Cloudant の特徴でもある Design Document API を紹介していくつもりで、その時には今回作成した都道府県データを使ったサンプルを紹介する予定です。
なお、IBM Cloudant の REST API リフェレンスはこちらを参照ください:
https://console.bluemix.net/docs/services/Cloudant/api/http.html
以下の内容を読み進めるにあたり、「実際に自分でも試してみたい」という人は是非 IBM Cloudant のアカウントを取得して、サービスインスタンスを作って動かしてみてください。まだ環境をお持ちでない場合、IBM Bluemix のアカウントを登録して、"Cloudant NoSQL DB" を選択してサービスを作成してください。加えて API の実行には curl コマンドを使うので、curl の実行環境を用意してください(Windows であればこちら、他はおそらく標準のはず):
サービス作成の際に利用プランを選択します。1GB かつ 30 日利用がないと削除されるという条件であれば無料の Lite プランを選択することも可能です。利用用途や目的に合わせて選択してください:
IBM Cloudant のサービスインスタンスを作成したら(或いは既にお持ちであれば)、作成済みのサービスインスタンスの「サービス接続情報」から「資格情報の表示」を選択して、IBM Cloudant に接続するための情報を確認します。具体的にはここで表示される username と password の値を後で利用することになるので、メモしておいてください:
また(今回はあまり使いませんが)IBM Cloudant はウェブのダッシュボード機能があり、データを確認したり、一部の操作をこのダッシュボードから行ったりすることができます。ダッシュボードにアクセスするにはサービスインスタンスの「管理」から「LAUNCH」ボタンをクリックすることで移行できます(或いは上記の「資格情報の表示」の中に表示されている "url" の値をウェブブラウザで指定して開きます。この場合はユーザー名とパスワードを聞かれるので、上記でメモした username と password を指定して開きます):
IBM Cloudant のダッシュボード画面です。左ペインの上から2つ目がデータベース一覧タブになっており、ここから現在作成済みのデータベースを一覧できます(下図ではまだ1つもありません)。この後の作業用に1つデータベースを作っておきます。画面右上の「Create Database」をクリックします:
適当な名前(以下例では "mydb")を入力して「Create」ボタンをクリックします:
指定した名前(mydb)のデータベースができました。この時点ではまだ1つもドキュメント(データ)が入っていないので空の状態です。再度画面左のデータベースアイコンをクリックして、データベース一覧に戻ります:
先程の画面に戻りました。mydb というデータベースが追加されて、現在のサイズやデータ数(# of Docs)などが確認できる状態になっています:
ではこのデータベースに対して、バルクインサート API を実行してみます。まずはインサートするドキュメントデータのサンプル(prefs.json)をここからダウンロードします:
https://raw.githubusercontent.com/dotnsf/samples/master/prefs.json
prefs.json の内容は以下のようになっています。"docs" 内に日本の47都道府県のコード(code)と名前(prefecture)、都道府県庁所在地名(capital)、そしてその緯度(lat)経度(lng)が JSON オブジェクトで定義されており、その配列を docs としています:
{ "docs": [ { "code": 1, "prefecture": "北海道", "capital": "札幌市", "lat": 43.06417, "lng": 141.34694 }, { "code": 2, "prefecture": "青森県", "capital": "青森市", "lat": 40.82444, "lng": 140.74 }, { "code": 3, "prefecture": "岩手県", "capital": "盛岡市", "lat": 39.70361, "lng": 141.1525 }, : { "code": 46, "prefecture": "鹿児島県", "capital": "鹿児島市", "lat": 31.56028, "lng": 130.55806 }, { "code": 47, "prefecture": "沖縄県", "capital": "那覇市", "lat": 26.2125, "lng": 127.68111 } ] }
これが Cloudant のバルクインサート API で使う場合のデータフォーマットになります。挿入したい複数のドキュメントデータを { "docs": [ .. ] } という形式で、"docs" の配列として定義します。
ではこのドキュメントデータ(prefs.json)を上記で作成した mydb データベースにまとめて格納します。curl を使って以下のように実行します:
$ curl -u "username:password" -XPOST "https://username.cloudant.com/mydb/_bulk_docs" -H "Content-Type: application/json" -d @prefs.json
※↑青字の username と password の部分には IBM Cloudant の資格情報で確認した値をそのまま指定します。またデータファイル prefs.json はコマンド実行時のカレントディレクトリに存在しているものとします。
コマンド実行後にダッシュボード画面を(リロードして)確認すると、mydb データベースに 47 件の(47都道府県の)ドキュメントデータが格納されていることが分かります。詳しく見るために mydb を選択します:
先程は空だった mydb に 47 件のドキュメントデータが格納されていることが確認できます。個々のドキュメントデータの中身はこの(デフォルトの "Metadata" の)画面だとわかりにくいので、表示形式を "Table" か "JSON" に切り替えてみます(ここでは JSON を選択します):
ドキュメントデータが JSON フォーマットで、実際に格納した中身(doc)まで含めて表示されます。画面では北海道の1ドキュメントデータしか表示されていませんが、下にスクロールすると他のドキュメントデータも確認することができます:
なお、データベースのドキュメントデータ一覧は curl で以下のコマンドを実行した結果でも確認することができます:
$ curl -u "username:password" -XGET "https://username.cloudant.com/mydb/_all_docs?include_docs=true"
↑include_docs=true のパラメータを付けて実行すると doc の中身まで、付けずに実行すると id と key の一覧のみ取得します。
今回は1回の API 実行で複数のドキュメントデータをまとめて Cloudant に格納するバルクインサート API を紹介しました。バルクインサート自体は必ずしも Cloudant の特徴というわけではなく、他のデータベースシステムにも存在している機能だと思いますが、今後 Cloudant の特徴でもある Design Document API を紹介していくつもりで、その時には今回作成した都道府県データを使ったサンプルを紹介する予定です。
なお、IBM Cloudant の REST API リフェレンスはこちらを参照ください:
https://console.bluemix.net/docs/services/Cloudant/api/http.html
コメント
コメント一覧 (1)
最近から業務でIBM cloudのNode-REDとCloudantを使用しています。
なかなか日本語の参考ドキュメント等が見つからず苦労していましたが、貴サイトのすごく分かりやすい情報のおかげで少しづつ業務を進められるようになってきました。
ありがとうございます。