Currently, when using the vector-store database for development, debugging, and problem locating, developers are unable to view the content information in the database files, such as metadata and user data.
To improve developers' work efficiency, the database debugging tool allows developers to view the vector-store database on devices.
The vector-store database debugging tool is available since HarmonyOS 6.0.0.
Environment requirements
- Before using this tool, you need to obtain the HDC tool, enable the Developer Options, and run the hdc shell command.
- This debugging tool can be used only for debugging applications. For details about how to configure a debugged application, see Running/Debugging Configuration.
- Connect the devices properly.
Preparations
Before using the vector-store debugging tool, switch to the target application path and then run the arkdata command to access the vector-store debugging tool. (You need to use ArkData to configure relevant parameters to open the vector-store database, and only after the database is successfully opened can you use the vector-store tool to add, delete, modify, and query data.)
The following table describes the parameters supported by the arkdata command.
Parameter Value Type Description -t String Database type, which is used to access the corresponding database debugging tool. Value range: {preference_kv, preference_xml, vector} -f String Full path of the database file, which includes the file name. The path cannot end with a slash (/). -h N/A Help information about the program. 
For the vector-store database debugging tool, the -p and -c parameters are not involved.
C:\Users\*****>hdc shell $ cd /data/app/el1/100/base/com.test.myapplication // Go to the target app path. (The current path is an example. Go to the path based on your actual needs.) $ arkdata -t vector // -f is not specified, indicating that no database file is specified. By default, a database named arkdata is created in the data/vector directory of the current working directory. Enter ".help" for usage hints. vector>>> .q
When opening the database in the path of a non-target application, if the -f parameter is missing (which would trigger the default folder creation), the process of creating the data/vector folder hierarchy in the current directory fails. The error information is as follows:
C:\Users\*****>hdc shell $ arkdata -t vector [unsucc]Failed to create directory ./data/vector : Permission denied
When opening the database in the path of a non-target application, the .db file fails to be created in the specified path. The error information is as follows:
C:\Users\*****>hdc shell $ arkdata -t vector -f ./vector [GMDB SERVER] [GMERR-1013000] multi-process init init unsucc! [ERROR] open db fail, ret = -5000.
Run the arkdata --help command to view the parameters related to the entire graph store.
C:\Users\*****>hdc shell $ arkdata --help USAGE arkdata [option] OPTION -t|--type <preference_kv | preference_xml | vector>, it is mandatory -f|--file <database file path> -p|--pageSize <database pageSize> -c|--cacheSize <database cacheSize> -h|--help
Command Reference
The following table lists the commands supported by the vector-store debugging tool.
| Command Format | Description |
|---|---|
| .help | Displays the help information. |
| .q | .quit | Exits the database interaction mode. |
| .mode <table|print> | Sets the output format. The default value is table. |
| .table | Lists all table names. |
| .index | Lists all index names. |
| .schema | Lists the schemas of tables. |
| .count | Lists the total number of records in all tables. |
The following table lists the common operation cases of the vector-store debugging tool.
| Shortcut | Command |
|---|---|
| Creating a Table | create table |
| Querying a Table | .table or .schema |
| Renaming a Table | alter table t1 rename to new_t1; |
| Adding a Table Field | alter table t1 add column c text; |
| Renaming a Table Field | alter table t1 rename b to new_b; |
| Deleting a Table Field | alter table t1 drop column c; |
| Deleting a Table | drop table t1; |
| Adding a Table Index | create index idx_1 on t3(a); |
| Inserting Data | insert into t2 values(1,'xx'),(2,'yy'); |
| Querying Data | select * from t1; |
| Updating Data | update t1 set b = 'z' where a =3; |
| Deleting Data | delete from t1 where b = 'z'; |
Constraints
For the vector-store database debugging tool, the maximum length of a command statement is 1024 × 1024-1.
Since hdc displays garbled characters when Chinese is used, the database debugging tool does not support Chinese.
Mobile phones and PCs/2-in-1 devices are supported.
[h2]Help Command (.help)
After the vector-store database is opened, you can run the help command to view the supported commands.
vector>>> .help
[h2]Creating or Opening an Existing Graph Store
Run the hdc shell command to enter the shell interaction mode.
You must switch to the target application path, go to the path where the db file exists, and run the arkdata -t vector command to create a database.
C:\Users\*****>hdc shell $ cd /data/app/el1/100/database/com.test.myapplication // Go to the target application path. (The current path is an example. Go to the path based on your actual needs.) $ cd entry/rdb/ // Go to the path where the .db file exists. You need to have the read and write permissions on the .db file to create a new database. $ arkdata -t vector Enter ".help" for usage hints. vector>>>
Wait for the system to automatically generate the following files. The tag debug_hap_data_file indicates that the file is the target app file.
$ ls -lZ ./data/vector/ total 176 -rw------- 1 shell shell u:object_r:debug_hap_data_file:s0 77824 2025-08-12 20:12 arkdata -rw------- 1 shell shell u:object_r:debug_hap_data_file:s0 8208 2025-08-12 20:13 arkdata.ctrl -rw------- 1 shell shell u:object_r:debug_hap_data_file:s0 24592 2025-08-12 20:13 arkdata.ctrl.dwr -rw------- 1 shell shell u:object_r:debug_hap_data_file:s0 512 2025-08-12 20:13 arkdata.redo -rw------- 1 shell shell u:object_r:debug_hap_data_file:s0 8 2025-08-12 20:13 arkdata.safe -rw------- 1 shell shell u:object_r:debug_hap_data_file:s0 28672 2025-08-12 20:12 arkdata.undo
Open an existing graph store.
$ arkdata -t vector -f ./data/vector/arkdata Enter ".help" for usage hints. vector>>>
[h2]Creating a Table
At the vector>>> prompt, run the create table command to create a table.
// Create a table via a single-line command. vector>>> create table t1(a int unique, b text); vector>>> .schema +-------+------+----------+----------------------------------------+ | type | name | tbl_name | sql | +-------+------+----------+----------------------------------------+ | TABLE | T1 | T1 | create table t1(a int unique, b text); | +-------+------+----------+----------------------------------------+ // Create a table via a single multi-line command. vector>>> create table t7( a int unique, b text); vector>>> .schema +-------+------+----------+---------------------------------------+ | type | name | tbl_name | sql | +-------+------+----------+---------------------------------------+ | TABLE | t7 | t7 | create table t7(a int unique,b text); | +-------+------+----------+---------------------------------------+
At the vector>>> prompt, run the following commands to create multiple tables.
// Create tables via multiple commands in a single line. vector>>> create table t7(a int unique, b text); create table t8(a int unique, b text); vector>>> .schema +-------+------+----------+-----------------------------------------+ | type | name | tbl_name | sql | +-------+------+----------+-----------------------------------------+ | TABLE | t7 | t7 | create table t7(a int unique, b text); | | TABLE | t8 | t8 | create table t8(a int unique, b text); | +-------+------+----------+-----------------------------------------+ // Create tables via multiple commands in multiple lines. vector>>> create table t7( a int unique, b text); create table t8( a int unique, b text); vector>>> .schema +-------+------+----------+---------------------------------------+ | type | name | tbl_name | sql | +-------+------+----------+---------------------------------------+ | TABLE | t7 | t7 | create table t7(a int unique,b text); | | TABLE | t8 | t8 | create table t8(a int unique,b text); | +-------+------+----------+---------------------------------------+
[h2]Querying a Table
At the vector>>> prompt, run the .table command to list all table names in the database. The following information is displayed.
vector>>>.table +------+ | name | +------+ | T1 | | T2 | | T3 | +------+
Run the .schema command to display the structure information of all tables in the database. The following information is displayed.
vector>>>.schema +-------+-------+----------+----------------------------------------+ | type | name | tbl_name | sql | +-------+-------+----------+----------------------------------------+ | TABLE | T1 | T1 | create table t1(a int unique, b text); | | TABLE | T2 | T2 | create table t2(a int unique, b text); | | TABLE | T3 | T3 | create table t3(a int, b text); | | TABLE | t7 | t7 | create table t7(a int unique,b text); | | TABLE | t8 | t8 | create table t8(a int unique,b text); | Press 'q' to quit, 'n' to continue: i Invalid input. Press 'q' to quit, 'n' to continue: n | TABLE | T9 | T9 | create table t9(a int unique,b text); | +-------+-------+----------+----------------------------------------+
When the number of displayed data items reaches 5, the system asks you whether to continue displaying or exit. Enter q to exit the display or enter n to continue displaying.
[h2]Renaming a Table
At the vector>>> prompt, run the alter table t1 rename to new_t1; command to rename the table. The following information is displayed.
vector>>> .schema +-------+------+----------+--------------------------------------+ | type | name | tbl_name | sql | +-------+------+----------+--------------------------------------+ | TABLE | T1 | T1 | create table t1( a int, new_b text); | +-------+------+----------+--------------------------------------+ vector>>> alter table t1 rename to new_t1; // Rename t1 to new_t1. vector>>> .schema +-------+--------+----------+------------------------------------------+ | type | name | tbl_name | sql | +-------+--------+----------+------------------------------------------+ | TABLE | NEW_T1 | NEW_T1 | create table NEW_T1( a int, new_b text); | +-------+--------+----------+------------------------------------------+
[h2]Adding a Table Field
At the vector>>> prompt, run the alter table t1 add column c text; command to add a table field. The following information is displayed.
vector>>> create table t1( a int, b text); vector>>> .schema +-------+------+----------+----------------------------------+ | type | name | tbl_name | sql | +-------+------+----------+----------------------------------+ | TABLE | T1 | T1 | create table t1( a int, b text); | +-------+------+----------+----------------------------------+ vector>>> alter table t1 add column c text; // Add a field named c of the text type to the table t1. vector>>> .schema +-------+------+----------+------------------------------------------+ | type | name | tbl_name | sql | +-------+------+----------+------------------------------------------+ | TABLE | T1 | T1 | create table t1( a int, b text, c text); | +-------+------+----------+------------------------------------------+
[h2]Renaming a Table Field
At the vector>>> prompt, run the alter table t1 rename b to new_b; command to rename the table field. The following information is displayed.
vector>>> .schema +-------+------+----------+----------------------------------+ | type | name | tbl_name | sql | +-------+------+----------+----------------------------------+ | TABLE | T1 | T1 | create table t1( a int, b text); | +-------+------+----------+----------------------------------+ vector>>> alter table t1 rename b to new_b; // Rename column b of table t1 to new_b. vector>>> .schema +-------+------+----------+--------------------------------------+ | type | name | tbl_name | sql | +-------+------+----------+--------------------------------------+ | TABLE | T1 | T1 | create table t1( a int, new_b text); | +-------+------+----------+--------------------------------------+
[h2]Deleting a Table Field
At the vector>>> prompt, run the alter table t1 drop column c; command to delete the specified field from the table. The following information is displayed.
vector>>> .schema +-------+------+----------+------------------------------------------+ | type | name | tbl_name | sql | +-------+------+----------+------------------------------------------+ | TABLE | T1 | T1 | create table t1( a int, b text, c text); | +-------+------+----------+------------------------------------------+ vector>>> alter table t1 drop column c; // Delete the c field from the t1 table. vector>>> .schema +-------+------+----------+----------------------------------+ | type | name | tbl_name | sql | +-------+------+----------+----------------------------------+ | TABLE | T1 | T1 | create table t1( a int, b text); | +-------+------+----------+----------------------------------+
[h2]Deleting a Table
At the vector>>> prompt, run the drop table t1; command to delete the t1 table from the database. The following information is displayed.
vector>>>drop table t1; // Delete table t1. vector>>>.table +------+ | name | +------+ | T2 | +------+
[h2]Adding a Table Index
At the vector>>> prompt, run the create index idx_1 on t3(a); command to add an index to the corresponding column of the table. The following information is displayed.
vector>>> create table t3(a int, b text); // An index can be created only when no data is added to the table. vector>>> create index idx_1 on t3(a); // Add an index idx_1 to the corresponding column of the table. vector>>> .index +-------+ | name | +-------+ | idx_1 | +-------+
[h2]Inserting Data
At the vector>>> prompt, run the insert into t2 values(1,'xx'),(2,'yy'); command to insert the specified KV pair. The following information is displayed.
vector>>> insert into t2 values(1,'xx'),(2,'yy'); vector>>> select * from t2; +----+----+ | a | b | +----+----+ | 1 | xx | | 2 | yy | +----+----+ vector>>> create table t1(a int unique, b text); vector>>> insert into t1 values(1,'x'),(2,'y'); vector>>> select * from t1; +----+----+ | a | b | +----+----+ | 1 | x | | 2 | y | +----+----+
At the vector>>> prompt, run the following commands to insert multiple data records.
// Insert multiple data records via a single multi-line command. vector>>> insert into t7 values(1,'x'), (2,'y'); vector>>> select * from t7; +----+---+ | a | b | +----+---+ | 1 | x | | 2 | y | +----+---+ // Insert multiple data records via multiple commands in a single line. vector>>> insert into t7 values(1,'x');insert into t7 values(2,'y'); vector>>> select * from t7; +----+---+ | a | b | +----+---+ | 1 | x | | 2 | y | +----+---+ // Insert multiple data records via multiple commands in multiple lines. vector>>> insert into t7 values(1,'x'), (2,'y'); insert into t8 values(1,'xx'), (2,'yy'); vector>>> select * from t7; +----+---+ | a | b | +----+---+ | 1 | x | | 2 | y | +----+---+ vector>>> select * from t8; +----+----+ | a | b | +----+----+ | 1 | xx | | 2 | yy | +----+----+
[h2]Querying Data
Scans the full table.
At the vector>>> prompt, run the .mode print and select * from table name; commands to query all data in the specified table. The following information is displayed.
vector>>> .mode print vector>>> select * from t1; [row-0] a = 1 b = x [row-1] a = 2 b = y
At the vector>>> prompt, run the .mode table and select * from table name; commands to query all data in the specified table. The following information is displayed.
vector>>> .mode table vector>>> select * from t1; +----+---+ | a | b | +----+---+ | 1 | x | | 2 | y | +----+---+
At the vector>>> prompt, run the select * from table name where filter condition command to query the KV pair of a specified key. The following information is displayed.
vector>>> select * from t1 where a =1; +----+---+ | a | b | +----+---+ | 1 | x | +----+---+
At the vector>>> prompt, run the .count command to list the total number of records in all tables. The following information is displayed.
vector>>> .count +------------+--------------+ | table_name | record_count | +------------+--------------+ | T1 | 2 | | T2 | 2 | | T3 | 0 | +------------+--------------+
[h2]Updating Data
At the vector>>> prompt, run the update t1 set b = 'z' where a =3; command to update the KV pair. The following information is displayed.
vector>>> select * from t1; +----+----+ | a | b | +----+----+ | 1 | x | | 2 | y | | 3 | xx | +----+----+ vector>>> update t1 set b = 'z' where a =3; vector>>> select * from t1; +----+---+ | a | b | +----+---+ | 1 | x | | 2 | y | | 3 | z | +----+---+
[h2]Deleting Data
At the vector>>> prompt, run the delete from t1 where b = 'z'; command to delete the specified KV pair from the table. The following information is displayed.
vector>>> select * from t1; +----+---+ | a | b | +----+---+ | 1 | x | | 2 | y | | 3 | z | +----+---+ vector>>> delete from t1 where b = 'z';// Delete z from the t1 table. vector>>> select * from t1; +----+---+ | a | b | +----+---+ | 1 | x | | 2 | y | +----+---+
At the vector>>> prompt, you can run the .q or .quit command to exit the database interaction mode. The following information is displayed.
vector>>>.q $