SQL 命令行終端 (CLI)
IOTDB 為用戶提供 cli/Shell 工具用于啟動客戶端和服務(wù)端程序。下面介紹每個 cli/Shell 工具的運行方式和相關(guān)參數(shù)。
$IOTDB_HOME 表示 IoTDB 的安裝目錄所在路徑。
安裝
在 iotdb 的根目錄下執(zhí)行
> mvn clean package -pl cli -am -DskipTests在生成完畢之后，IoTDB 的 cli 工具位于文件夾"cli/target/iotdb-cli-{project.version}"中。
運行
Cli 運行方式
安裝后的 IoTDB 中有一個默認用戶：root，默認密碼為root。用戶可以使用該用戶嘗試運行 IoTDB 客戶端以測試服務(wù)器是否正常啟動?？蛻舳藛幽_本為$IOTDB_HOME/sbin 文件夾下的start-cli腳本。啟動腳本時需要指定運行 IP 和 RPC PORT。以下為服務(wù)器在本機啟動，且用戶未更改運行端口號的示例，默認端口為 6667。若用戶嘗試連接遠程服務(wù)器或更改了服務(wù)器運行的端口號，請在-h 和-p 項處使用服務(wù)器的 IP 和 RPC PORT。
用戶也可以在啟動腳本的最前方設(shè)置自己的環(huán)境變量，如 JAVA_HOME 等 （對于 linux 用戶，腳本路徑為："/sbin/start-cli.sh"； 對于 windows 用戶，腳本路徑為："/sbin/start-cli.bat")
Linux 系統(tǒng)與 MacOS 系統(tǒng)啟動命令如下：
Shell > sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw rootWindows 系統(tǒng)啟動命令如下：
Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root回車后即可成功啟動客戶端。啟動后出現(xiàn)如圖提示即為啟動成功。
_____ _________ ______ ______
|_ _| | _ _ ||_ _ `.|_ _ \
| | .--.|_/ | | \_| | | `. \ | |_) |
| | / .'`\ \ | | | | | | | __'.
_| |_| \__. | _| |_ _| |_.' /_| |__) |
|_____|'.__.' |_____| |______.'|_______/ version <version>
IoTDB> login successfully輸入quit或exit可退出 cli 結(jié)束本次會話，cli 輸出quit normally表示退出成功。
Cli 運行參數(shù)
| 參數(shù)名 | 參數(shù)類型 | 是否為必需參數(shù) | 說明 | 例子 |
|---|---|---|---|---|
| -disableISO8601 | 沒有參數(shù) | 否 | 如果設(shè)置了這個參數(shù)，IoTDB 將以數(shù)字的形式打印時間戳 (timestamp)。 | -disableISO8601 |
-h <host> | string 類型，不需要引號 | 是 | IoTDB 客戶端連接 IoTDB 服務(wù)器的 IP 地址。 | -h 10.129.187.21 |
| -help | 沒有參數(shù) | 否 | 打印 IoTDB 的幫助信息 | -help |
-p <rpcPort> | int 類型 | 是 | IoTDB 連接服務(wù)器的端口號，IoTDB 默認運行在 6667 端口。 | -p 6667 |
-pw <password> | string 類型，不需要引號 | 否 | IoTDB 連接服務(wù)器所使用的密碼。如果沒有輸入密碼 IoTDB 會在 Cli 端提示輸入密碼。 | -pw root |
-u <username> | string 類型，不需要引號 | 是 | IoTDB 連接服務(wù)器鎖使用的用戶名。 | -u root |
-maxPRC <maxPrintRowCount> | int 類型 | 否 | 設(shè)置 IoTDB 返回客戶端命令行中所顯示的最大行數(shù)。 | -maxPRC 10 |
-e <execute> | string 類型 | 否 | 在不進入客戶端輸入模式的情況下，批量操作 IoTDB | -e "show storage group" |
| -c | 空 | 否 | 如果服務(wù)器設(shè)置了 rpc_thrift_compression_enable=true, 則 CLI 必須使用 -c | -c |
下面展示一條客戶端命令，功能是連接 IP 為 10.129.187.21 的主機，端口為 6667 ，用戶名為 root，密碼為 root，以數(shù)字的形式打印時間戳，IoTDB 命令行顯示的最大行數(shù)為 10。
Linux 系統(tǒng)與 MacOS 系統(tǒng)啟動命令如下：
Shell > sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10Windows 系統(tǒng)啟動命令如下：
Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10使用 OpenID 作為用戶名認證登錄
OpenID Connect (OIDC) 使用 keycloack 作為 OIDC 服務(wù)權(quán)限認證服務(wù)。
配置
配置位于 iotdb-engines.properties，設(shè)定 authorizer_provider_class 為 org.apache.iotdb.db.auth.authorizer.OpenIdAuthorizer 則開啟了 openID 服務(wù)，默認情況下值為 org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer 表示沒有開啟 openID 服務(wù)。
authorizer_provider_class=org.apache.iotdb.db.auth.authorizer.OpenIdAuthorizer如果開啟了 openID 服務(wù)則 openID_url 為必填項，openID_url 值為 http://ip:port/auth/realms/{realmsName}
openID_url=http://127.0.0.1:8080/auth/realms/iotdb/keycloack 配置
1、下載 keycloack 程序，在 keycloack/bin 中啟動 keycloack
Shell >cd bin
Shell >./standalone.sh2、使用 https://ip:port/auth 登陸 keycloack, 首次登陸需要創(chuàng)建用戶
3、點擊 Administration Console 進入管理端
4、在左側(cè)的 Master 菜單點擊 add Realm, 輸入 Name 創(chuàng)建一個新的 Realm
5、點擊左側(cè)菜單 Clients，創(chuàng)建 client
6、點擊左側(cè)菜單 User，創(chuàng)建 user
7、點擊新創(chuàng)建的用戶 id，點擊 Credentials 導(dǎo)航輸入密碼和關(guān)閉 Temporary 選項，至此 keyclork 配置完成
8、創(chuàng)建角色，點擊左側(cè)菜單的 Roles然后點擊Add Role 按鈕添加角色
9、在Role Name 中輸入iotdb_admin，點擊save 按鈕。提示：這里的iotdb_admin不能為其他名稱否則即使登陸成功后也將無權(quán)限使用iotdb的查詢、插入、創(chuàng)建存儲組、添加用戶、角色等功能
10、點擊左側(cè)的User 菜單然后點擊用戶列表中的Edit的按鈕為該用戶添加我們剛創(chuàng)建的iotdb_admin角色
11、選擇Role Mappings ，在Available Role選擇iotdb_admin角色然后點Add selected 按鈕添加角色
12、如果iotdb_admin角色在Assigned Roles中并且出現(xiàn)Success Role mappings updated提示，證明角色添加成功
提示：如果用戶角色有調(diào)整需要重新生成token并且重新登陸iotdb才會生效
以上步驟提供了一種 keycloak 登陸 iotdb 方式，更多方式請參考 keycloak 配置
若對應(yīng)的 IoTDB 服務(wù)器開啟了使用 OpenID Connect (OIDC) 作為權(quán)限認證服務(wù)，那么就不再需要使用用戶名密碼進行登錄。
替而代之的是使用 Token，以及空密碼。
此時，登錄命令如下：
Shell > sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw ""其中，需要將{my-access-token} （注意，包括{}）替換成你的 token，即 access_token 對應(yīng)的值。
如何獲取 token 取決于你的 OIDC 設(shè)置。 最簡單的一種情況是使用password-grant。例如，假設(shè)你在用 keycloack 作為你的 OIDC 服務(wù)，
并且你在 keycloack 中有一個被定義成 public 的iotdb客戶的 realm，那么你可以使用如下curl命令獲得 token。
（注意例子中的{}和里面的內(nèi)容需要替換成具體的服務(wù)器地址和 realm 名字）：
curl -X POST "http://{your-keycloack-server}/auth/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \
-d "username={username}" \
-d "password={password}" \
-d 'grant_type=password' \
-d "client_id=iotdb-client"示例結(jié)果如下：
{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"}Cli 的批量操作
當您想要通過腳本的方式通過 Cli / Shell 對 IoTDB 進行批量操作時，可以使用-e 參數(shù)。通過使用該參數(shù)，您可以在不進入客戶端輸入模式的情況下操作 IoTDB。
為了避免 SQL 語句和其他參數(shù)混淆，現(xiàn)在只支持-e 參數(shù)作為最后的參數(shù)使用。
針對 cli/Shell 工具的-e 參數(shù)用法如下：
Linux 系統(tǒng)與 MacOS 指令：
Shell > sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb}Windows 系統(tǒng)指令
Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb}在 Windows 環(huán)境下，-e 參數(shù)的 SQL 語句需要使用``對于" "進行替換
為了更好的解釋-e 參數(shù)的使用，可以參考下面在 Linux 上執(zhí)行的例子。
假設(shè)用戶希望對一個新啟動的 IoTDB 進行如下操作：
創(chuàng)建名為 root.demo 的存儲組
創(chuàng)建名為 root.demo.s1 的時間序列
向創(chuàng)建的時間序列中插入三個數(shù)據(jù)點
查詢驗證數(shù)據(jù)是否插入成功
那么通過使用 cli/Shell 工具的 -e 參數(shù)，可以采用如下的腳本：
# !/bin/bash
host=127.0.0.1
rpcPort=6667
user=root
pass=root
./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "set storage group to root.demo"
./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE"
./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)"
./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)"
./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)"
./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo"打印出來的結(jié)果顯示如下，通過這種方式進行的操作與客戶端的輸入模式以及通過 JDBC 進行操作結(jié)果是一致的。
Shell > ./shell.sh
+-----------------------------+------------+
| Time|root.demo.s1|
+-----------------------------+------------+
|1970-01-01T08:00:00.001+08:00| 10|
|1970-01-01T08:00:00.002+08:00| 11|
|1970-01-01T08:00:00.003+08:00| 12|
+-----------------------------+------------+
Total line number = 3
It costs 0.267s需要特別注意的是，在腳本中使用 -e 參數(shù)時要對特殊字符進行轉(zhuǎn)義。