データ・コマンドライン・インタフェース(CLI)は、KVStoreの単純なデータ・アクセス・ユーティリティです。ストアからのレコードの取得、ストアへのレコードの格納、ストアからのレコードの削除、スキーマの取得、およびストアについての一般的な情報の表示のために使用できます。特に適しているのは、Oracle NoSQL Databaseアプリケーションを作成している開発者、および開発のデータのために少量のレコードをストアに移入する必要がある開発者、または開発のデバッグ・アクティビティの一部としてストアの状態を調べる必要のある開発者です。CLIは、アプリケーションにおけるデータ・アクセスのプライマリ・インタフェースとして使用することは想定されていません。
CLIを起動するには、次のようにします。
java -jar KVHOME/lib/kvcli.jar -host <hostName>
-port <port> -store <storeName> [single command and arguments]
説明:
-host <hostName>は、ストアの一部として実行中のノードのホスト名を指定するために使用します。
-port <port>は、ホストがリスニングするポートを指定するために使用します。
-store <storeName>は、KVStoreの名前を指定するために使用します。
スクリプト・ファイルを実行する場合、"load"コマンドをコマンドラインで使用できます。
java -jar KVHOME/lib/kvcli.jar -host <hostname> -port <port> -store <storeName> load -file <path-to-script>
オプションの引数が何も渡されていない場合は、コマンドライン・インタフェースをインタラクティブに開始します。追加的な引数が渡される場合、それらは実行する単一のコマンドとして解釈され、それからインタフェースが返ります。CLIのインタラクティブなプロンプトは次のとおりです。
"kvshell-> "
aggregate [-count] [-sum <field[,field,..]>] [-avg <field[,field,..]>] [-key <key>] [-start <prefixString>] [-end <prefixString>]
aggregateコマンドは、一致するレコードに対して単純な集計操作を実行します。サポートされる操作は、count、sum、およびaverageです。count操作は、すべての一致キーに対して実行されます。
aggregateコマンドは、ストア内の一致キーを反復するため、特定のキーによっては、大きなストアに対して完了するのにとても長い時間がかかる場合があります。-startおよび-endは、反復に使用される範囲を制限します。これは特に、適切にフォーマットされた文字列などのキー・コンポネントに基づいたレコードの範囲を取得する場合に有効です。-startおよび-end引数は、両端を含みます。
たとえば、ストア内のすべてのレコードの単純なcountは次のとおりです。
kvshell-> aggregate -count count: 33508
Sumおよびaverageは、一致するレコードの特定のフィールド名を操作しますが、これは、その名前のフィールドを含むAvroレコードのみが使用されるということです。Sumおよびaverageは、AvroタイプがINT、LONG、FLOATおよびDOUBLEの数値フィールドのみを操作します。
たとえば、次のようなスキーマがあるとします。
{
"type" : "record",
"name" : "Cookie",
"fields" : [ {
"name" : "id",
"type" : "string",
"default" : ""
}, {
"name" : "frequency",
"type" : "int",
"default" : 0
}, {
"name" : "lastVisit",
"type" : "string",
"default" : ""
}, {
"name" : "segments",
"type" : {
"type" : "array",
"items" : "string"
},
"default" : [ ]
} ]
}
frequencyという名前のフィールドのsumの例:
kvshell-> aggregate -sum frequency -key /visits/charitable_donors/date sum(frequency): 2068
frequencyという名前のフィールドのaverageの例:
kvshell-> aggregate -avg frequency -key /visits/charitable_donors/date avg(frequency): 2.494571773220748
connect -host <hostname> -port <port> -store <storeName>
特定のホスト名、ポート情報およびストア名を使用して、既存のKVStoreに接続します。現行のストアがある場合は、別のストアに接続する前にクローズされます。特定のKVStoreのオープンに失敗した場合、次の警告が表示されます。"Warning: You are no longer connected to KVStore"
delete [-key <key>] [-start prefixString] [-end prefixString] [-all]
1つ以上のキーを削除します。-allが指定される場合、指定のキーで始まるすべてのキーを削除します。キーが指定されていない場合、ストア内のすべてのキーを削除します。-start および-endフラグは、削除に使用する範囲を制限します。
たとえば、rootで始まるストア内のすべのキーを削除するには、次のようにします。
kvshell-> delete -all 301 Keys deleted starting at root
get [-key <keyString>] [-json] [-file <output>] [-all] [-keyonly] [-valueonly] [-start <prefixString>] [-end <prefixString>]
指定されたキーを使用して単純なget操作を実行します。取得した値に表示可能な文字が含まれている場合はそれが出力され、そうでない場合は、そのバイト配列がBase64を使用して表示用にエンコーディングされます。この変換を示すために"[Base64]"が追加されます。getコマンドの引数は次のとおりです。
-key <keyString>
使用するフル・パスまたは接頭辞キー・パスを示します。<keyString>がフル・キー・パスの場合、1つの値の情報が返されます。このgetコマンドのフォーマットは、<keyString>です。<keyString>が接頭辞キー・パスである場合、複数のキー/値のペアが返されます。このgetコマンドのフォーマットは、get -key <keyString> -allです。キーは、メジャーおよびマイナー・キー・パスの両方、またはメジャー・キー・パスのみから構成されます。<keyString>フォーマットは、"major-key-path/-/minor-key-path"です。さらに、接頭辞キー・パスの場合、キーはメジャー・キー・パスの接頭辞部分から構成されます。
たとえば、KVStoreにある次のサンプル・キーを考えます。
/group/TC/-/user/bob /group/TC/-/user/john /group/TC/-/dep/IT /group/SZ/-/user/steve /group/SZ/-/user/diana
メジャー・キー・パスの接頭辞部分のみを含むキーを指定したgetコマンドは、次のようになります。
kvshell-> get -key /group -all -keyonly /group/TC/-/user/bob /group/TC/-/user/john /group/TC/-/dep/IT /group/SZ/-/user/steve /group/SZ/-/user/diana
メジャー・キー・パスを含むキーを指定したgetコマンドは、次のようになります。
kvshell-> get -key /group/TC -all -keyonly /group/TC/-/user/bob /group/TC/-/user/john /group/TC/-/dep/IT
メジャーおよびマイナー・キー・パスを含むキーを指定したgetコマンドは、次のようになります。
kvshell-> get -key /group/TC/-/user -all -keyonly /group/TC/-/user/bob /group/TC/-/user/john
kvshell-> get -key /group/TC/-/user/bob
{
"name" : "bob.smith",
"age" : 20,
"email" : "bob.smith@gmail.com",
"phone" : "408 555 5555"
}
-json
レコードがJSONの場合、指定する必要があります。
-file <output>
切り捨てられる出力ファイルを指定して、既存の内容をすべて、新しい内容で置き換えます。
次の例では、キー/Smith/Bobからのレコードが、ファイル"data.out"に書き込まれます。
kvshell-> get -key /Smith/Bob -all -file ./data.out
次の例では、ファイル"data.out"の内容が、キー/Wong/Billからのレコードで置き換えられます。
kvshell-> get -key /Wong/Bill -all -file ./data.out
-all
指定のキーで始まる反復に指定されます。キーの引数が指定されていない場合、ストア全体が反復されます。
-keyonly
-allとともに指定され、キーのみを返します。
-valueonly
-allとともに指定され、値のみを返します。
-start <prefixString>および-end <prefixString>
反復に使用される範囲を制限します。これは特に、適切にフォーマットされた文字列などのキー・コンポネントに基づいたレコードの範囲を取得する場合に有効です。-startおよび-end引数は、両端を含みます。
-startおよび-endは、-key <keyString>で指定されるキー・コンポーネントにのみ影響します。<keyString>の値は単純な文字列で構成する必要があり、複数のキー・コンポーネントは指定できません。
たとえば、キー構造が次のようになっているログを考えます。
/log/<year>/<month>/-/<day>/<time>
同じ日のすべてのログ・エントリは同じパーティションに入れられますが、日付によってシャード間での分割が行われます。timeフォーマットは、"hour.minute"です。
そのため、次のように指定して、2013年2月および3月のすべてのログ・エントリのgetができます。
kvshell-> get -all -keyonly -key /log/2013 -start 02 -end 03 /log/2013/02/-/01/1.45 /log/2013/02/-/05/3.15 /log/2013/02/-/15/10.15 /log/2013/02/-/20/6.30 /log/2013/02/-/28/8.10 /log/2013/03/-/01/11.13 /log/2013/03/-/15/2.28 /log/2013/03/-/22/4.52 /log/2013/03/-/31/11.55
より完全なキー・パスを指定すると、より明確なgetコマンドになります。たとえば、4月1日から4月4日までのすべてのログ・エントリを表示するには、次のようにします。
kvshell-> get -all -keyonly -key /log/2013/04 -start 01 -end 04 /log/2013/04/-/01/1.03 /log/2013/04/-/01/4.05 /log/2013/04/-/02/7.22 /log/2013/04/-/02/9.40 /log/2013/04/-/03/4.15 /log/2013/04/-/03/6.30 /log/2013/04/-/03/10.25 /log/2013/04/-/04/4.10 /log/2013/04/-/04/8.35
help [command [sub-command]]
ヘルプ・メッセージを出力します。引数がない場合は最上位のシェル・コマンドが一覧表示されます。追加的なコマンドおよびサブコマンドがある場合は、追加の詳細が示されます。
kvshell-> help load Usage: load -file <path to file> Loads the named file and interpret its contents as a script of commands to be executed. If any of the commands in the script fail, execution will stop at that point.
load -file <path to file>
指定したファイルをロードし、その内容を実行対象のコマンドのスクリプトとして解釈します。スクリプト内のいずれかのコマンドが失敗した場合、実行はその時点で停止します。
put -key <keyString> -value <valueString> [-file] [-hex | -json <schemaName>] [-if-absent] [-if-present]
指定のキー/値のペアをストアに格納します。次の引数が、putコマンドに適用されます。
-key<keyString>
ストアに格納するキーの名前を指定します。キーはメジャーおよびマイナー・キー・パスの両方、またはメジャー・キー・パスのみから構成されます。<keyString>フォーマットは、"major-key-path/-/minor-key-path"です。
たとえば、メジャーおよびマイナー・キー・パスを含むキーは、次のとおりです。
kvshell-> put -key /Smith/Bob/-/email -value
"{\"id\": 1,\"email\":\"bob.smith@gmail.com\"}" -json schema.EmailInfo
たとえば、メジャー・キー・パスのみを含むキーは、次のとおりです。
kvshell-> put -key /Smith/Bob -value"{\"name\":
\"bob.smith\", \"age\": 20, \"phone\":\"408 555 5555\", \"email\":
\"bob.smith@gmail.com\"}" -json schema.UserInfo
-value <valueString>
-jsonと-fileのどちらも指定しない場合、<valueString>は、RAWバイト配列して扱われます。
次に例を示します。
kvshell-> put -key /Smith/Bob/-/phonenumber -value "408 555 5555"
RAW配列とデータ構造とのマッピング(シリアライズおよびデシリアライズ)はすべて、アプリケーションで行う必要があります。これは推奨される方法ではありません。かわりに、非常に単純な値に対しても、Avroを使用してください。
-jsonでJSON文字列を指定する場合、valueStringは引用符でカプセル化する必要があり、その内部フィールド名および文字型の値も、文字列引用文字でカプセル化する必要があります。
次に例を示します。
kvshell-> put -key /Smith/John/-/email
"{\"id\": 1,\"email\":\"john.smith@gmail.com\"}" -json schema.EmailInfo
-file
値がファイルから取得されることを示します。使用するファイルは値パラメータで識別されます。
次に例を示します。
kvshell-> put -key /Smith/Bob -value ./smith-bob-info.txt -file -json schema.UserInfo
-hex
値が、BASE64エンコーディングによるBinHexエンコード・バイト値であることを示します。
-json<schemaName>
値がJSON文字列であることを示します。-fileとともに指定できます。
-if-absent
指定のキーに値が存在しない場合のみ、キー/値ペアがputであることを示します。
-if-present
指定のキーに値が存在する場合のみ、キー/値ペアがputであることを示します。
スキーマまたはストアについての基本情報を表示するコマンドをカプセル化します。サブコマンドは次のとおりです。
timeコマンドは、指定のコマンドを指定の引数とともに実行し、実行の経過時間を出力します。
たとえば、レコードの取得およびそれらのファイルへの書込みにかかった時間を表示するには、次のようにします。
kvshell-> time get -all -file ./data.out 209 Records returned. Wrote value to file ./data.out. Time: 265 ms.
たとえば、すべての既存のキーを削除するのにかかった時間を表示するには、次のようにします。
kvshell-> time delete -all 210 Keys deleted starting at root Time: 265 ms.