Quick Start

Docker is all you need to try SQLRec. The demo image includes the tables, SQL function, and API required by the quick start. Its example tables use the filesystem connector and keep data in process memory, so Redis, PostgreSQL, Hive Metastore, Flink, and Kubernetes are not required.

Start the Demo

docker run --rm -d --name sqlrec-demo \
  -p 30000:30000 \
  -p 30001:30001 \
  sqlrec/sqlrec-demo:latest

Follow the logs to confirm that the service has started:

docker logs -f sqlrec-demo

After startup completes, press Ctrl+C to stop following the logs. The container continues running in the background.

Open the SQLRec CLI

Run the bundled SQLRec CLI inside the container. Its usage is similar to connecting to SQLRec with beeline:

docker exec -it sqlrec-demo bash /app/cli.sh

Start by inspecting the objects loaded by the demo:

show tables;
show functions;
show apis;

Insert Test Data

The quick-start filesystem tables start empty. Insert one user preference and five hot items in the CLI:

insert into demo_user_interest_category values
  (1000001, 'pc', 100);

insert into demo_category_hot_item values
  ('pc', 1000001, 100),
  ('pc', 1000002, 90),
  ('pc', 1000003, 80),
  ('pc', 1000004, 70),
  ('pc', 1000005, 60);

select * from demo_user_interest_category;
select * from demo_category_hot_item;

The data exists only in the current CLI process and is cleared when the CLI exits.

Get Recommendations

The demo defines a demo_rec SQL function. Continue in the same CLI session, create its input table, and call it:

cache table quick_start_user as
select cast(1000001 as bigint) as user_id;

call demo_rec(quick_start_user);

The function returns two hot items with their recommendation reasons, request timestamp, and request ID. Exposure records are written to the current process's in-memory demo_exposure_item table; later calls use these records for deduplication.

Call the Recommendation API

The CLI and HTTP service run in separate processes inside the container, so each process maintains its own filesystem data in memory. The demo image enables the SQL API by default. First, use /sql/v1 to insert test data into the HTTP service process:

curl -X POST http://localhost:30001/sql/v1 \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "sqls": [
    "insert into demo_user_interest_category values (1000001, 'pc', 100)",
    "insert into demo_category_hot_item values ('pc', 1000001, 100), ('pc', 1000002, 90), ('pc', 1000003, 80)"
  ]
}
JSON

Then call the demo_rec 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 endpoint returns the result of demo_rec. Test data inserted through the SQL API and exposure data generated by recommendations remain in the HTTP service process until the container stops.

Open the UI

Open http://localhost:30001/ui/static/index.html to inspect tables, APIs, SQL functions, and their execution DAGs.

Demo Directory Layout

SQL_SCHEMA_DIR is consistently set to /app/sql, and SQLRec recursively loads both example directories. The two examples use distinct table, function, and API identifiers:

sqlrec-demo/src/main/sql/
├── quick_start/
│   ├── api/demo_rec.sql
│   ├── function/demo_rec.sql
│   └── table/
│       ├── demo_category_hot_item.sql
│       ├── demo_exposure_item.sql
│       └── demo_user_interest_category.sql
└── movielens/
    ├── api/
    ├── function/
    ├── model/
    ├── service/
    ├── table/
    └── udf/

The three quick-start tables configure only 'connector' = 'filesystem'; no data file path is specified. The complete MovieLens example demonstrates a full pipeline involving Redis, Milvus, Kafka, model training, and online inference.

Developing DDL in Local Metadata Mode

Local metadata mode recursively loads SQL files from SQL_SCHEMA_DIR when the process starts. It therefore does not allow DDL statements such as CREATE TABLE, CREATE SQL FUNCTION, or CREATE API to be executed through either the CLI or SQL API. The SQL API enabled by the demo is intended only for queries and test-data writes.

To develop a new table, function, or API locally, write its definition in SQL files on the host, mount the complete directory into the container, and point SQL_SCHEMA_DIR to the mounted path. For example:

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

The ./sql directory must contain every SQL definition required for that run. Restart the container after changing a file so that SQLRec reloads the definitions.

If you need to execute and persist DDL interactively like a database, follow Service Deployment to set up the complete cluster, then connect through beeline, JDBC, or another SQLRec client.

Stop the Demo

docker stop sqlrec-demo

Because the container was started with --rm, Docker removes it after it stops.

For more datasource configuration, see Built-in Connectors.