Quick Start
Docker is the only prerequisite. The demo includes sample data, a recommendation function, and its API; no external services are needed.
Start the Demo
docker run --rm -d --name sqlrec-demo \
-p 30000:30000 \
-p 30001:30001 \
sqlrec/sqlrec-demo:latestWatch the startup log:
docker logs -f sqlrec-demoAfter startup, press Ctrl+C to leave the log viewer. The container keeps running in the background.
Call the Recommendation API
curl -X POST http://localhost:30001/api/v1/demo_rec \
-H "Content-Type: application/json" \
-d '{"data":{"user_info":[{"user_id":1000001}]}}'The first call usually returns two items. The response's data contains result rows with user_id, item_id, item_name, rec_reason, req_time, and req_id. This excerpt shows fields from one result row; the item may differ:
{
"data": [
{"item_id": 1000001, "rec_reason": "user_category_interest_recall:book"}
]
}Use user IDs 1000001 through 1000005. Repeated calls exclude previously recommended items. Restart the container when the sample candidates are exhausted.
View the UI
Open http://localhost:30001/ui/static/index.html to inspect tables, functions, APIs, and execution DAGs.
Stop the Demo
docker stop sqlrec-demoThe container is removed automatically because it was started with --rm.
Optional: Open the SQLRec CLI
While the demo is running, open the SQL CLI from the host:
docker exec -it sqlrec-demo /app/cli.shAt the sqlrec> prompt, enter statements ending with a semicolon:
show tables;
show functions;
show apis;
select * from demo_user_interest_category;
cache table quick_start_user as
select cast(1000001 as bigint) as user_id;
call demo_rec(quick_start_user);quick_start_user is the function's input table. Press Ctrl+D to exit.
For batch execution with cli.sh -e "SQL;" or cli.sh -f statements.sql, a SQL failure stops subsequent statements and returns exit code 1, with errors written to stderr. Successful batches return 0. Interactive SQL errors still allow further input.
Demo Data Scope
Data is held in memory. The CLI and HTTP service have separate data, so CLI changes do not affect the API. Reopening the CLI restores its initial data; restarting the container resets the HTTP service's data.
Use INSERT to add rows and UPDATE to change them. To write test data to the HTTP service, use /sql/v1; local CLI changes are not visible to it.
Modify the Demo SQL
The recommendation logic is in sqlrec-demo/src/main/sql/quick_start/function/demo_rec.sql. Alongside it, table/ defines tables, api/ publishes the function, and data/ holds initial CSV data.
The image loads definitions through SQL_SCHEMA_DIR=/app/sql. See Writing a Recommendation Flow for SQL logic. To load your own files, prepare a complete SQL directory as shown below.
Managing Local SQL Definitions
SQL-file mode loads definitions at startup; restart after editing files. The Demo image enables SQL_SCHEMA_DDL_ENABLED=true, so CLI and /sql/v1 also accept supported in-memory DDL. Those changes are process-local, are not written back to files, and disappear on restart. Set the variable to false to disable runtime DDL. This example manages definitions as files.
Use SHOW TABLES, SHOW CREATE TABLE, DESCRIBE, and SHOW FUNCTIONS to inspect loaded definitions without connecting to HMS or Gateway. See Metadata Queries for supported behavior.
Prepare the SQL Files
Create the directories on the host:
mkdir -p sql/table sql/function sql/apiSave the following definitions in separate files.
sql/table/hot_item.sql:
CREATE TABLE hot_item (
item_id BIGINT,
score FLOAT,
PRIMARY KEY (item_id) NOT ENFORCED
) WITH (
'connector' = 'filesystem'
);sql/function/recommend.sql:
CREATE OR REPLACE SQL FUNCTION recommend;
DEFINE INPUT TABLE user_info (
user_id BIGINT
);
CACHE TABLE result_table AS
SELECT item_id, score
FROM hot_item
ORDER BY score DESC
LIMIT 10;
RETURN result_table;sql/api/recommend.sql:
CREATE OR REPLACE API recommend WITH recommend;Load and Call
Mount the complete directory and set SQL_SCHEMA_DIR:
docker run --rm -d --name sqlrec-custom \
-p 30000:30000 \
-p 30001:30001 \
-v "$(pwd)/sql:/workspace/sql:ro" \
-e SQL_SCHEMA_DIR=/workspace/sql \
sqlrec/sqlrec-demo:latest./sql must contain all definitions needed for this startup. Write data to the HTTP service, then call the API:
curl -X POST http://localhost:30001/sql/v1 \
-H "Content-Type: application/json" \
-d '{"sqls":["insert into hot_item values (1001, 0.9), (1002, 0.8)"]}'
curl -X POST http://localhost:30001/api/v1/recommend \
-H "Content-Type: application/json" \
-d '{"data":{"user_info":[{"user_id":1000001}]}}'This API returns hot items ordered by score without using user features. Extend the function to add your own recommendation logic.
Filesystem tables are for demos and tests; writes do not update source files. See Built-in Connectors for configuration and data limits.
For serving, version the complete SQL directory with the image or deployment configuration and redeploy to update it. Use remote metadata when you need persistent, shared runtime DDL.