Truy vấn SQL (SQL query)

Mục đích

Bước Truy vấn SQL (SQL query) kết nối tới cơ sở dữ liệu hoặc kho dữ liệu của doanh nghiệp, thực thi một câu lệnh SQL và lưu kết quả trả về vào biến quy trình để các bước tiếp theo sử dụng.

Theo mặc định — và với hầu hết các trường hợp sử dụng — bước này chạy ở chế độ chỉ đọc: câu lệnh chạy bên trong một transaction chỉ đọc nên không thể thay đổi dữ liệu nguồn. Đây không phải giới hạn duy nhất của bước: khi kết nối và tác giả quy trình đáp ứng đủ điều kiện, bước cũng có thể chạy ở chế độ ghi (Write mode) để chèn/cập nhật dữ liệu — xem mục Chế độ ghi (Write mode) bên dưới.

Khi nào dùng

• Cần tra cứu thông tin từ hệ thống ERP, CRM hoặc kho dữ liệu nội bộ trong khi chạy quy trình.
• Muốn đưa dữ liệu thực vào một bước Trợ lý AI (Agent) hoặc Công việc người dùng (Human task) — ví dụ: kéo lịch sử đơn hàng trước khi xét duyệt mua sắm.
• Muốn điền sẵn thông tin vào Biểu mẫu hoặc Mẫu tài liệu mà không cần nhập tay.

Ghi chú

Bước này yêu cầu một kết nối loại database hoặc data warehouse đã được thiết lập trong mục Tích hợp. Nếu chưa có kết nối nào, hãy thêm kết nối trước.

Cài đặt chính

Cài đặt	Bắt buộc	Mô tả
Connection	Có	Kết nối cơ sở dữ liệu hoặc kho dữ liệu. Chỉ hiển thị kết nối loại database / data_warehouse.
Mode (Chế độ)	Không	Chỉ đọc (mặc định) hoặc Ghi. Tùy chọn Ghi chỉ xuất hiện khi kết nối đã chọn cho phép ghi VÀ tác giả có quyền phù hợp — xem mục Chế độ ghi (Write mode) bên dưới.
SQL	Có	Câu lệnh SQL cần thực thi. Dùng $1, $2, … làm tham số vị trí. Câu lệnh là cố định — không nhúng biến trực tiếp vào chuỗi SQL.
Parameters	Không	Danh sách giá trị gán vào $1, $2, … theo thứ tự. Mỗi tham số có nhãn, kiểu dữ liệu (text, int, date, …) và giá trị lấy từ biến quy trình, template hoặc giá trị cố định.
Capture to	Không	Đường dẫn biến để lưu kết quả, ví dụ vars.result. Dùng tiền tố vars.* hoặc input.*.
Safe columns	Không	Các cột được phép hiển thị với người dùng không phải quản trị viên. Nhấn Describe columns để tải danh sách cột rồi tích chọn. Cột không được chọn sẽ bị ẩn.
Timeout (s)	Không	Giới hạn thời gian chạy câu lệnh tính bằng giây.
Max rows	Không	Số dòng tối đa trả về.
Max bytes	Không	Kích thước kết quả tối đa tính bằng byte.

Mẹo

Luôn khai báo Safe columns nếu kết quả chứa thông tin nhạy cảm. Nếu để trống, toàn bộ kết quả sẽ bị ẩn với người dùng thông thường.

Chế độ ghi (Write mode)

Ngoài chế độ chỉ đọc mặc định, bước Truy vấn SQL có thể chạy ở chế độ ghi (Write mode) để chèn, cập nhật hoặc xóa dữ liệu tại kết nối đích. Đây là tính năng tùy chọn (opt-in) theo từng bước và chỉ khả dụng khi cả hai điều kiện sau đều đúng:

1. Kết nối cho phép ghi. Quản trị viên phải bật cho phép ghi khi thiết lập kết nối cơ sở dữ liệu trong mục Tích hợp — xem Tích hợp. Theo mặc định, một kết nối mới không cho phép ghi.
2. Tác giả quy trình có quyền workflow.sql.write. Người thiết kế bước này phải được cấp quyền workflow.sql.write, hoặc là quản trị viên tổ chức — quản trị viên tổ chức được bỏ qua yêu cầu quyền này.

Chỉ khi cả hai điều kiện trên được thỏa, cài đặt Mode (Chế độ) mới cho chọn Ghi bên cạnh Chỉ đọc. Nếu một trong hai điều kiện không còn đúng sau khi bước đã được cấu hình ở chế độ ghi — ví dụ quyền workflow.sql.write bị thu hồi, hoặc quản trị viên tắt cho phép ghi trên kết nối — Trình thiết kế hiển thị cảnh báo giải thích điều kiện nào đang thiếu, kèm nút Chuyển sang chỉ đọc để đưa bước về trạng thái chạy được ngay.

Chú ý

Chế độ ghi chạy theo ngữ nghĩa ít nhất một lần (at-least-once) — câu lệnh có thể được chạy lại khi hệ thống thử lại. Hãy viết câu lệnh có tính idempotent (ví dụ dùng ON CONFLICT / MERGE, hoặc một khóa idempotency) để lần chạy lại không tạo ra dữ liệu trùng lặp.

Ở chế độ ghi, trường đầu ra rowsAffected trả về số dòng bị thay đổi bởi câu lệnh (ở chế độ chỉ đọc, giá trị này luôn là null).

Cả hai điều kiện trên đều được máy chủ kiểm tra lại tại thời điểm xuất bản quy trình và khi phiên chạy thực thi bước — cấu hình phía Trình thiết kế chỉ giúp trải nghiệm rõ ràng hơn, không thay thế việc kiểm tra ở backend.

Ví dụ

Trong quy trình Đề xuất mua sắm, sau khi người dùng điền biểu mẫu yêu cầu, một bước Truy vấn SQL tra cứu ngân sách còn lại của phòng ban:

SELECT department_id, remaining_budget
FROM department_budgets
WHERE department_id = $1
  AND fiscal_year = $2

Cấu hình tham số:

• $1 — kiểu uuid, lấy từ biến nodes.start.output.department_id
• $2 — kiểu int, giá trị cố định 2025

Đặt Capture to là vars.budget. Bước Trợ lý AI (Agent) tiếp theo có thể đọc vars.budget.remaining_budget để đánh giá mức độ hợp lý của đề xuất trước khi chuyển sang bước phê duyệt.

Xem thêm cách dùng biến quy trình tại Biến & biểu thức.