Files on S3 (Parquet, CSV)

Đọc tệp Parquet và CSV từ một bucket Amazon S3 hoặc kho lưu trữ tương thích S3 (MinIO, Ceph, Cloudflare R2…). Mỗi bảng bạn khai báo là một mẫu tệp (file pattern); mọi tệp khớp được import chung vào một bảng dữ liệu. Fresco BI chỉ liệt kê và đọc tệp, không bao giờ ghi vào bucket.

Tính năng	Hỗ trợ
Import	Có
DirectQuery	Không
SSL/TLS	Luôn bật (HTTPS)
SSH tunnel	Không
Cloud	Có
On-premises (qua Gateway)	Không

Điều kiện cần

• Một bucket, và thư mục (prefix) chứa tệp.
• Một access key chỉ có quyền đọc trên bucket và prefix đó.
• Với endpoint không phải AWS: quản trị viên tổ chức cần thêm tên máy chủ của nó vào Cài đặt tổ chức › Endpoint S3 được phép trước (tối đa 20 máy chủ). Endpoint AWS S3 luôn được phép.

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

Trên AWS, tạo một IAM user (hoặc role) chỉ có policy dưới đây, rồi tạo access key cho nó. Thay <bucket> và <prefix> (prefix kết thúc bằng /; bỏ phần prefix nếu muốn cho đọc cả bucket):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::<bucket>",
      "Condition": { "StringLike": { "s3:prefix": "<prefix>*" } }
    },
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::<bucket>/<prefix>*"
    }
  ]
}

Không cấp s3:PutObject, s3:DeleteObject hay s3:*.

Với kho tương thích S3, tạo một user hoặc key chỉ có quyền đọc và liệt kê trên bucket.

Có thể dùng credential tạm thời: nhập thêm session token cùng với key.

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

Cloud. Fresco BI kết nối tới endpoint qua HTTPS (cổng 443 nếu bạn không đặt cổng khác). Nếu bucket hoặc kho lưu trữ giới hạn IP truy cập (ví dụ điều kiện aws:SourceIp trong bucket policy, hoặc firewall đứng trước MinIO), hãy cho phép 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ê).

Endpoint phải phân giải ra địa chỉ public; địa chỉ nội bộ, loopback và metadata bị từ chối. Trình kết nối này không có SSH tunnel và không có kiểu On-premises (Gateway).

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

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

1. Endpoint: chỉ tên máy chủ, không kèm https://, cổng hay đường dẫn; địa chỉ IP bị từ chối. Mặc định s3.amazonaws.com. Máy chủ AWS S3 (s3.amazonaws.com, s3.<region>.amazonaws.com) luôn được phép; máy chủ khác phải có trong danh sách được phép của tổ chức.
2. Port: không bắt buộc; để trống là 443.
3. Region: ví dụ ap-southeast-1, hoặc auto (Cloudflare R2). Mặc định us-east-1.
4. Bucket: tên bucket.
5. Prefix: thư mục, không bắt buộc, kết thúc bằng /, không có ký tự đại diện, ví dụ exports/. Fresco BI không đọc được gì ngoài s3://<bucket>/<prefix>.
6. URL style: vhost (mặc định, bucket.endpoint) hoặc path (endpoint/bucket, hay dùng với MinIO).
7. Access key ID, Secret access key và Session token (không bắt buộc). Các giá trị này được lưu mã hóa và không hiển thị lại.
8. Tables: từ 1 đến 100 bảng, tên không trùng. Mỗi bảng có Tên bảng, File pattern tính từ prefix (ví dụ sales/**/*.parquet) và Format: parquet (mặc định) hoặc csv.
9. Tùy chọn CSV (chỉ cho bảng CSV): Delimiter , (mặc định), ;, tab hoặc |; Dòng đầu là tiêu đề (mặc định bật); Quote " (mặc định) hoặc '; Số dòng bỏ qua từ 0 đến 100.

Pattern dùng ký tự của key S3 cùng *, ** và ?; dấu ngoặc nhọn, ngoặc vuông và .. bị từ chối. Bảng Parquet đọc tệp có đuôi .parquet; bảng CSV đọc .csv, .csv.gz, .csv.zst và .tsv. Tệp khác khớp pattern sẽ bị bỏ qua.

Giới hạn

• Tối đa 1.000 tệp mỗi bảng và tổng 20 GiB mỗi bảng.
• Tối đa 5 GiB mỗi tệp Parquet và 2 GiB mỗi tệp CSV.
• Tối đa 500 cột mỗi bảng.
• Danh sách tệp được chốt khi bắt đầu tải. Nếu các tệp khớp thay đổi trong lúc tải, lần tải dừng lại thay vì trộn tệp cũ và mới; hãy chạy lại.

Khắc phục sự cố

• Máy chủ từ chối tài khoản hoặc mật khẩu. S3 trả 401 hoặc 403. Kiểm tra key, và policy đã cấp s3:ListBucket và s3:GetObject trên đúng bucket và prefix chưa (thiếu quyền cũng hiện thông báo này).
• Không tìm thấy database hoặc đối tượng này trên máy chủ. Bucket không tồn tại, hoặc không có tệp đúng đuôi nào khớp pattern. Kiểm tra bucket, prefix, pattern và format.
• Thông tin kết nối chưa hợp lệ: kiểm tra lại các ô được đánh dấu. Thường do sai region (S3 trả redirect hoặc 400), hoặc endpoint không phải AWS chưa có trong danh sách được phép của tổ chức.
• Vượt giới hạn kích thước hoặc số kết nối đồng thời. Quá nhiều tệp, tệp hoặc bảng vượt giới hạn dung lượng, quá nhiều cột, hoặc thiếu bộ nhớ. Thu hẹp pattern hoặc tách bảng.
• Nguồn trả về kiểu dữ liệu trình kết nối chưa hỗ trợ. Có tệp không phải Parquet hoặc CSV hợp lệ. Kiểm tra format và tùy chọn CSV.
• Cấu trúc bảng nguồn đã thay đổi so với bảng dữ liệu. Các tệp khớp thay đổi trong lúc tải, hoặc một cột mà bảng dữ liệu đang đọc không còn trong tệp. Chạy lại lần tải, hoặc kiểm tra tệp.
• 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. Chứng chỉ của endpoint không do CA public tin cậy ký. Trình kết nối này không thêm được CA riêng.
• Đị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. Endpoint phân giải ra địa chỉ nội bộ. Hãy dùng endpoint public.
• 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. Kiểm tra endpoint, cổng và mọi giới hạn IP trên kho lưu trữ.