A brief history of Notion's data catalog

Notion · 2024 · 3. Quy mô lớn · Độ khó: Trung bình — bài gốc

Phần sinh mô tả bảng bằng LLM được tóm tắt ngắn; lõi của bài là đưa schema về nguồn (code) và lan metadata theo lineage.

Bối cảnh

Giai đoạn 1 (không catalog): dữ liệu tăng tự phát, phần lớn ở dạng JSON không cấu trúc, đổ vào công cụ như Amplitude để phân tích nhanh. Hệ quả: kiến thức truyền miệng, tên không thống nhất, không phân biệt event quan trọng hay không, không rõ ai sở hữu (một event bị sửa nhầm làm hỏng consumer phía sau), không ai biết có dữ liệu gì; thêm nhiều nguồn (warehouse, stream, data lake, kho vận hành).
Giai đoạn 2: dùng Acryl DataHub nối thẳng vào warehouse để hiện bảng và schema; lập phân hạng event (P0, P1…) kèm chủ sở hữu. Kỹ thuật chạy tốt nhưng ít người dùng.
Phân tích nguyên nhân: nhiều dữ liệu nguồn là cột JSON blob không có schema; nhiều bảng thiếu mô tả, mô tả có thì lỗi thời theo logic nghiệp vụ; mô tả không được lan xuống bảng dẫn xuất và công cụ phân tích. Warehouse có vài trăm bảng analytics (2024).

Schema từ nguồn, bằng TypeScript: thay vì Protobuf/Avro/JSON Schema như thường lệ, dùng kiểu TypeScript làm IDL, vì codebase đã định nghĩa nhiều data model bằng TypeScript, kiểu của TypeScript biểu đạt mạnh hơn, và engineer đã quen. Kiểu này sinh được kiểu Swift, Kotlin, Python cho các codebase khác.
Quy trình ba bước cho analytics event: engineer chạy công cụ sinh một kiểu TypeScript cho mỗi event (kèm mô tả từng thuộc tính, team sở hữu, mức tier); type check bắt buộc đủ thuộc tính khi log (trước đó mọi thuộc tính là tuỳ chọn, không ai ép). Job hằng ngày đổi kiểu thành JSON Schema bằng ts-json-schema-generator, đưa lên S3 (có lịch sử phiên bản theo cấu trúc file); job hằng ngày khác ghi schema vào DataHub qua SDK.
Mô tả bảng dẫn xuất bằng LLM + người duyệt: gom metadata (định nghĩa SQL model và macro, mô tả sẵn có, JSON Schema của event, tài liệu nội bộ, kết quả duyệt lần trước) cho bảng và các bảng ngay phía trên nó, sinh mô tả từ thượng nguồn xuống để định nghĩa lan theo lineage. Người đẩy thay đổi code duyệt mô tả (bước chặn); phản hồi đưa vào lần sinh sau; mô tả đã duyệt đồng bộ vào DataHub rồi tới repo SQL, warehouse và công cụ BI.

Catalog chỉ phản ánh được thứ có cấu trúc; dữ liệu JSON không schema thì catalog có cũng trống. Phải "cầm máu" ở nguồn trước (event mới bắt buộc có kiểu), backfill sau (Pipeline dữ liệu và analytics).
Theo Notion, chọn định dạng hợp với workflow sẵn có của engineer quan trọng hơn chọn định dạng chuẩn ngành; mô tả phải xuất hiện ở công cụ người dùng đang dùng, không chỉ trong catalog.

Ghi ownership và tier ngay lúc tạo event, bằng công cụ, để metadata không phụ thuộc trí nhớ.
Một catalog ít người dùng thường là vấn đề về nội dung (thiếu schema, thiếu mô tả, không lan), không phải về công cụ.
Mô tả tự sinh cần người duyệt chặn trước khi công bố, vì mô tả sai đắt hơn không có mô tả.