hithink-finance-data

hithink-finance-data

Local data lifecycle and SQL entry point. Responsible for making data available, verifiable, and exportable, rather than explaining all research conclusions.

Prerequisites table

Condition	Action
First use of this domain	Read shared rules; content already loaded in the same session can be reused
First execution or version change	Check capabilities --format json and the target schema <id> --format json; when the combination rules are unclear, check --help
Need to execute one of the commands in the table below	First read the corresponding reference file; do not guess parameters from the command name alone
Whole market, paginated, multiple symbols, or long ranges	Use the --output <path> declared by the command to write to disk, and report only a summary

Quick decisions

User intent	Preferred command / route
First-time database creation or import from dump	data init
Incremental/re-sync local data	data sync
View database path and schema	data status
Quality validation	data validate
Migration plan or apply	data migrate
Rebuild derived data such as adjustments	data repair
Clean download cache	data clean
Delete local database	data remove --plan preview first
View tables/views	db describe
Read-only SQL query	db query --sql <sql>
Export large results	db export --sql <sql> --output <file>

Shortcuts

Command	When to use
data clean	Only cleans the CLI-managed download cache; does not delete the database.
data init	Remote initialization requires an API Key; first reuse the existing credential source per shared rules; local file import requires no remote authentication.
data migrate	By default only outputs the migration plan; ask the user to confirm before applying migrations.
data remove	High-risk operation; first run --plan to report the path and size.
data repair	Used to rebuild local derived data such as derived adjustment factors.
data status	View the database path and schema version; this command can create a missing database, so strictly read-only tasks must first confirm the target exists via the file system.
data sync	Requires an API Key; first reuse the existing credential source per shared rules. auth status only checks the system credential store; configured=false does not mean environment variable or stdin credentials are missing.
data validate	The quality check will first apply ordinary migrations. Strictly read-only research must first confirm the target file exists, and use the default plan of data migrate to confirm that versions is empty.
db describe	Query the list of tables and views, and apply ordinary migrations; strictly read-only research uses db query to query information_schema.
db export	Used for large results or downstream pandas/notebook consumption.
db query	Read-only SQL; only small results can be read directly as JSON.

Native commands and schema

hithink-finance capabilities --format json
hithink-finance schema <capability-id> --format json
hithink-finance data <command> --help
hithink-finance db <command> --help

schema provides the current command options; reference supplements the relationships between business parameters and acceptance methods. For global parameters, credentials, and output conventions, see the shared rules.

Boundary statement

• SQL must be read-only; writes, DDL, deletions, or external side effects do not belong to db query。
• Before deleting the database or clearing data, first use plan/status output to have the user confirm; actual deletion requires an explicit --yes。
• data init / data sync The download phase can be canceled immediately; after the database import is submitted, it will first complete the adjustment, metadata, and quality consistency finalization before reporting cancellation.
• Use when local resources need to be limited HITHINK_FINANCE_DUCKDB_THREADS / HITHINK_FINANCE_DUCKDB_MEMORY_LIMIT；DATA_LOCK_OPEN_FAILED should check the status directory permissions and storage.
• When there are many query results, use db export --output <file>, do not echo the entire table.