vector-store Database Debugging Tool Guide-ArkData Debugging Tool-ArkData-Application Framework

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.

NOTE

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.

Expand

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.

NOTE

For the vector-store database debugging tool, the -p and -c parameters are not involved.

Collapse
Word wrap
Dark theme
Copy code
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:

Collapse
Word wrap
Dark theme
Copy code
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:

Collapse
Word wrap
Dark theme
Copy code
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.

Collapse
Word wrap
Dark theme
Copy code
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.

Expand

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.

Expand

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.

Command Usage and Examples

Help Command (.help)

After the vector-store database is opened, you can run the help command to view the supported commands.

Collapse
Word wrap
Dark theme
Copy code
vector>>> .help

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.

Collapse
Word wrap
Dark theme
Copy code
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.

Collapse
Word wrap
Dark theme
Copy code
$ 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.

Collapse
Word wrap
Dark theme
Copy code
$ arkdata -t vector -f ./data/vector/arkdata
Enter ".help" for usage hints.
vector>>>

Creating a Table

At the vector>>> prompt, run the create table command to create a table.

Collapse
Word wrap
Dark theme
Copy code
// 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.

Collapse
Word wrap
Dark theme
Copy code
// 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); |
+-------+------+----------+---------------------------------------+

Querying a Table

At the vector>>> prompt, run the .table command to list all table names in the database. The following information is displayed.
Collapse
Word wrap
Dark theme
Copy code
```
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.

Collapse
Word wrap
Dark theme
Copy code
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);  |
+-------+-------+----------+----------------------------------------+

NOTE

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.

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.

Collapse
Word wrap
Dark theme
Copy code
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); |
+-------+--------+----------+------------------------------------------+

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.

Collapse
Word wrap
Dark theme
Copy code
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); |
+-------+------+----------+------------------------------------------+

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.

Collapse
Word wrap
Dark theme
Copy code
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); |
+-------+------+----------+--------------------------------------+

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.

Collapse
Word wrap
Dark theme
Copy code
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); |
+-------+------+----------+----------------------------------+

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.

Collapse
Word wrap
Dark theme
Copy code
vector>>>drop table t1;  // Delete table t1.
vector>>>.table
+------+
| name |
+------+
| T2   |
+------+

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.

Collapse
Word wrap
Dark theme
Copy code
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 |
+-------+

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.

Collapse
Word wrap
Dark theme
Copy code
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.

Collapse
Word wrap
Dark theme
Copy code
// 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 |
+----+----+

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.
  Collapse
  Word wrap
  Dark theme
  Copy code
```
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.
  Collapse
  Word wrap
  Dark theme
  Copy code
```
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.
Collapse
Word wrap
Dark theme
Copy code
```
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.

Collapse
Word wrap
Dark theme
Copy code
vector>>> .count
+------------+--------------+
| table_name | record_count |
+------------+--------------+
| T1         | 2            |
| T2         | 2            |
| T3         | 0            |
+------------+--------------+

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.

Collapse
Word wrap
Dark theme
Copy code
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 |
+----+---+

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.

Collapse
Word wrap
Dark theme
Copy code
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.

Collapse
Word wrap
Dark theme
Copy code
vector>>>.q
$

Emulator Support

This tool supports the Emulator.

FAQs

How do I delete characters?

You can press Ctrl+Backspace to delete a single character and press Ctrl+U to delete all characters.