MongoDB

Kết nối một database MongoDB với Fresco BI. Fresco BI chỉ đọc: liệt kê các collection của một database, suy ra cột từ một mẫu document, rồi import từng collection vào một bảng dữ liệu.

Tính năng	Hỗ trợ
Import	Có
DirectQuery	Không
SSL/TLS	Luôn bật và kiểm tra chứng chỉ
SSH tunnel	Không
Cloud	Có
On-premises (qua Gateway)	Không

Điều kiện cần

• Một máy chủ hoặc cluster MongoDB truy cập được từ internet qua TLS (ví dụ MongoDB Atlas).
• Tên database cần đọc.
• Một quản trị viên có quyền tạo user trong database.

Bước 1: Tạo user chỉ đọc

Fresco BI cần role có sẵn read trên database cần đọc. Dùng mongosh, kết nối bằng tài khoản quản trị:

use admin
db.createUser({
  user: "fresco_reader",
  pwd: "<strong-password>",
  roles: [ { role: "read", db: "<database>" } ]
})

User ở trên nằm trong database admin, cũng là database xác thực mặc định của nguồn. Nếu bạn tạo user ở database khác, hãy nhập database đó làm database xác thực.

MongoDB Atlas. Trong Database Access, thêm một database user xác thực bằng mật khẩu và chỉ cấp role read trên <database> (dùng custom role hoặc “Specific Privileges”), không cấp role read-write.

Fresco BI chỉ liệt kê các collection mà user được phép đọc và bỏ qua các collection system.*. View cũng được liệt kê.

Bước 2: Mở quyền truy cập mạng

Cloud. Cho phép kết nối vào từ các địa chỉ IP đi ra của Fresco BI (hướng dẫn bên cạnh form nguồn dữ liệu có liệt kê) ở cổng MongoDB (mặc định 27017).

• MongoDB Atlas: trong Network Access, thêm từng IP vào IP Access List.
• Máy chủ tự quản: cho mongod lắng nghe trên interface public, mở cổng trên firewall chỉ cho các IP này, và bật TLS trên máy chủ.

Với MongoDB, Fresco BI không có SSH tunnel và không có kiểu On-premises (Gateway): máy chủ phải truy cập được qua internet.

Bước 3: Điền thông tin

Form web cho MongoDB chưa có. Nguồn này nhận các thiết lập sau:

1. Kiểu địa chỉ: srv (mặc định) hoặc standard.
2. Hosts: với srv, đúng một tên máy chủ, không kèm cổng, và tên phải có domain cha (ví dụ cluster0.abcde.mongodb.net). Với standard, từ 1 đến 7 host, mỗi host có thể kèm cổng (bỏ trống là 27017).
3. Database: database cần đọc.
4. Database xác thực: nơi đã tạo user; mặc định admin.
5. Replica set: tên replica set, không bắt buộc.
6. Tài khoản và Mật khẩu: user ở Bước 1. Mật khẩu được lưu mã hóa và không hiển thị lại.
7. Read preference: secondaryPreferred (mặc định), primary hoặc secondary.
8. Số document mẫu: số document lấy mẫu để tìm cột, từ 100 đến 1.000 (mặc định 1.000).
9. Độ sâu làm phẳng: số cấp object lồng nhau được tách thành cột riêng, từ 0 đến 3 (mặc định 1). Trường address.city thành cột address_city; object sâu hơn và mảng giữ nguyên dạng văn bản JSON.
10. Chứng chỉ CA (PEM): không bắt buộc. Dán vào khi chứng chỉ máy chủ do CA riêng ký.

Với địa chỉ srv, Fresco BI tự tra bản ghi SRV và TXT. Mọi máy chủ trong kết quả SRV phải cùng domain cha với tên SRV, và bản ghi TXT chỉ được đặt authSource, replicaSet và loadBalanced.

Cách dữ liệu được đọc

• Cột được suy ra từ mẫu tối đa 1.000 document; tối đa 500 cột mỗi collection. Document thiếu một trường thì ô đó để trống.
• Document được đọc theo thứ tự _id. Trên replica set hoặc sharded cluster chạy MongoDB 5.0 trở lên, lần đọc dùng snapshot nên dữ liệu import nhất quán.
• TLS luôn bật và chứng chỉ máy chủ luôn được kiểm tra; không có tùy chọn tắt.

Khắc phục sự cố

• Máy chủ từ chối tài khoản hoặc mật khẩu. Kiểm tra user, mật khẩu và database xác thực (user của Atlas nằm trong admin).
• Tài khoản không có quyền đọc đối tượng này. Cấp role read trên database cho user.
• Không phân giải được tên máy chủ (DNS). Kiểm tra lại ô Máy chủ. Kiểm tra tên host SRV. Với srv, bản ghi SRV và mọi máy chủ trong đó phải phân giải được; máy chủ ngoài domain cha bị từ chối.
• Không mở được kết nối tới máy chủ và cổng này. Kiểm tra máy chủ, cổng, và firewall đã cho phép IP của Fresco BI chưa. Thêm các địa chỉ IP đi ra của Fresco BI (hướng dẫn bên cạnh form nguồn dữ liệu có liệt kê) vào IP Access List hoặc firewall.
• Máy chủ không phản hồi kịp. Thường do firewall chặn im lặng hoặc sai máy chủ, cổng. Kiểm tra IP Access List của Atlas và cổng.
• Không thiết lập được kết nối SSL với chế độ đã chọn. Kiểm tra chế độ SSL và chứng chỉ CA. Máy chủ phải bật TLS, với chứng chỉ cấp cho đúng tên host đã nhập. Nếu dùng CA riêng, dán CA vào ô chứng chỉ CA.
• Địa chỉ máy chủ thuộc dải bị chặn (nội bộ, loopback hoặc metadata). Database trong mạng nội bộ cần kết nối On-premises qua Gateway. MongoDB chưa dùng được Gateway; máy chủ cần địa chỉ public.
• Không tìm thấy database hoặc đối tượng này trên máy chủ. Collection đã bị xóa hoặc đổi tên sau khi tạo bảng dữ liệu.
• Vượt giới hạn kích thước hoặc số kết nối đồng thời. Lần đọc dài vượt quá snapshot window của máy chủ; thử lại khi collection ít tải hơn.