データ・コマンドライン・インタフェース(CLI)は、KVStoreの単純なデータ・アクセス・ユーティリティです。ストアからのレコードの取得、ストアへのレコードの格納、ストアからのレコードの削除、スキーマの取得、およびストアについての一般的な情報の表示のために使用できます。特に適しているのは、Oracle NoSQL Databaseアプリケーションを作成している開発者、および開発のデータのために少量のレコードをストアに移入する必要がある開発者、または開発のデバッグ・アクティビティの一部としてストアの状態を調べる必要のある開発者です。CLIは、アプリケーションにおけるデータ・アクセスのプライマリ・インタフェースとして使用することは想定されていません。
CLIを起動するには、次のようにします。
java -Xmx256m -Xms256m \ -jar KVHOME/lib/kvcli.jar -host <hostName> \ -port <port> -store <storeName> [single command and arguments]
説明:
-host <hostName>
は、ストアの一部として実行中のノードのホスト名を指定するために使用します。
-port <port>
は、ホストがリスニングするポートを指定するために使用します。
-store <storeName>
は、KVStoreの名前を指定するために使用します。
スクリプト・ファイルを実行する場合、"load"コマンドをコマンドラインで使用できます。
java -Xmx256m -Xms256m \ -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>
指定したファイルをロードし、その内容を実行対象のコマンドのスクリプトとして解釈します。スクリプト内のいずれかのコマンドが失敗した場合、実行はその時点で停止します。
たとえば、スクリプト・ファイルload-contacts-5.txt
に次のコマンドが収集されているとします。
### Begin Script ### put -key /contact/Bob/Walker -value "{\"phone\":\"857-431-9361\", \ \"email\":\"Nunc@Quisque.com\",\"city\":\"Turriff\"}" \ -json example.ContactInfo put -key /contact/Craig/Cohen -value "{\"phone\":\"657-486-0535\", \ \"email\":\"sagittis@metalcorp.net\",\"city\":\"Hamoir\"}" \ -json example.ContactInfo put -key /contact/Lacey/Benjamin -value "{\"phone\":\"556-975-3364\", \ \"email\":\"Duis@laceyassociates.ca\",\"city\":\"Wasseiges\"}" \ -json example.ContactInfo put -key /contact/Preston/Church -value "{\"phone\":\"436-396-9213\", \ \"email\":\"preston@mauris.ca\",\"city\":\"Helmsdale\"}" \ -json example.ContactInfo put -key /contact/Evan/Houston -value "{\"phone\":\"028-781-1457\", \ \"email\":\"evan@texfoundation.org\",\"city\":\"Geest-G\"}" \ -json example.ContactInfo exit ### End Script ###
スクリプトを実行するには、データ・コマンドライン・インタフェースでload
コマンドを使用します。
スクリプトを実行する前に、ストアにスキーマをロードしておく必要があります。スキーマの追加の詳細は、「スキーマの追加」を参照してください。
> java -Xmx256m -Xms256m \ -jar KVHOME/lib/kvcli.jar -host node01 -port 5000 -store mystore load -file ./load-contacts-5.txt Operation successful, record inserted. Operation successful, record inserted. Operation successful, record inserted. Operation successful, record inserted. Operation successful, record inserted.
ストアには次のスキーマが事前にロードされていました。
{ "type": "record", "name": "ContactInfo", "namespace": "example", "fields": [ {"name": "phone", "type": "string", "default": ""}, {"name": "email", "type": "string", "default": ""}, {"name": "city", "type": "string", "default": ""} ] }
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.