Cách khắc phục lỗi MongoDB: 'FieldPath field names may not start with $'

Tại sao lỗi này xảy ra

Thông báo lỗi MongoServerError: FieldPath field names may not start with '$' thường có nghĩa là bạn đã gặp lỗi cú pháp trong một aggregation pipeline. Điều này xảy ra khi bạn cố gắng đặt tên cho một trường mới (một key) bằng một chuỗi bắt đầu bằng dấu đô la.

MongoDB coi tiền tố $ là một tín hiệu đặc biệt. Nó được sử dụng cho hai mục đích cụ thể:

• Toán tử (Operators): Các lệnh như $match, $group, hoặc $limit.
• Tham chiếu đường dẫn trường (Field Path References): Khi được sử dụng làm giá trị (như "$price"), nó yêu cầu MongoDB lấy dữ liệu từ trường 'price'.

Cơ sở dữ liệu bị nhầm lẫn vì bạn đang cố gắng sử dụng tiền tố dành riêng đó làm nhãn (label) cho đầu ra của mình. MongoDB đơn giản là không cho phép dấu $ ở đầu các key trong các ngữ cảnh này.

// Mã này sẽ luôn thất bại
db.orders.aggregate([
  {
    $project: {
      "$total_cost": "$amount" // Lỗi! Bạn không thể bắt đầu một key bằng $
    }
  }
]);

Các tình huống thường gặp và cách khắc phục nhanh

1. Nhầm lẫn khi nhập liệu trong $project hoặc $addFields

Hầu hết các lập trình viên gặp phải lỗi này do thói quen gõ dấu $ cho các giá trị và vô tình áp dụng nó cho cả tên trường. Nếu bạn đang đổi tên một trường, tên mới phải là một chuỗi thuần túy.

Cách khắc phục: Loại bỏ dấu $ ở phía bên trái của dấu hai chấm.

// ❌ SAI
{ $project: { "$user_display_name": "$name" } }

// ✅ ĐÚNG
{ $project: { "user_display_name": "$name" } }

2. Đặt tên cho các tổng hợp (totals) trong $group

Trong giai đoạn $group, _id của bạn có thể (và thường nên) sử dụng dấu $ để tham chiếu đến một trường. Tuy nhiên, bất kỳ bộ tích lũy (accumulators) nào như tổng (sum) hoặc trung bình (average) theo sau phải có tên tiêu chuẩn. Ví dụ: nếu bạn đang tính doanh thu cho 500 giao dịch, nhãn cho tổng đó không được bắt đầu bằng dấu đô la.

// ❌ SAI
db.sales.aggregate([
  {
    $group: {
      _id: "$category",
      "$monthly_revenue": { $sum: "$price" } // Lỗi: "$monthly_revenue" không hợp lệ
    }
  }
]);

// ✅ ĐÚNG
db.sales.aggregate([
  {
    $group: {
      _id: "$category",
      "monthly_revenue": { $sum: "$price" } // Chỉ cần sử dụng tên trực tiếp
    }
  }
]);

3. Xử lý các key động trong Node.js hoặc Python

Nếu ứng dụng của bạn tạo tên trường một cách linh hoạt, bạn có thể vô tình truyền một biến có chứa dấu $. Điều này thường xảy ra khi xử lý dữ liệu biểu mẫu do người dùng gửi hoặc payload từ API bên ngoài.

// Ví dụ về key động trong Node.js
const rawInput = "$profit"; 

// ❌ Điều này sẽ làm hỏng truy vấn của bạn
const pipeline = [
  { $addFields: { [rawInput]: { $subtract: ["$revenue", "$costs"] } } }
];

// ✅ Khắc phục: Làm sạch chuỗi của bạn trước
const cleanKey = rawInput.startsWith('$') ? rawInput.slice(1) : rawInput;
const safePipeline = [
  { $addFields: { [cleanKey]: { $subtract: ["$revenue", "$costs"] } } }
];

4. Sai sót về dấu ngoặc

Việc thiếu dấu ngoặc nhọn có thể khiến MongoDB hiểu lầm một toán tử thực chất là một tên trường. Nếu bạn quên bao bọc $sum trong dấu ngoặc nhọn, trình phân tích cú pháp sẽ giả định $sum là key mà bạn đang cố gắng tạo.

// ❌ SAI (Trình phân tích cú pháp coi $sum là một key ở đây)
{ $project: { total: $sum: "$items" } }

// ✅ ĐÚNG
{ $project: { total: { $sum: "$items" } } }

Cách xác minh việc khắc phục

Đừng đoán xem lỗi ở đâu. Hãy sử dụng các bước sau để xác định chính xác:

• Sử dụng MongoDB Compass: Dán pipeline của bạn vào Aggregation Tab. Compass sẽ làm nổi bật giai đoạn cụ thể bị lỗi trong thời gian thực, giúp bạn không phải lục tìm trong hàng trăm dòng mã.
• Tách biệt các giai đoạn: Nếu pipeline của bạn có 10 giai đoạn, hãy comment bỏ 5 giai đoạn cuối. Nếu nó hoạt động, lỗi nằm ở nửa sau. Tiếp tục thu hẹp phạm vi cho đến khi bạn tìm thấy nguyên nhân.
• Kiểm tra log của Driver: Thông thường, stack trace đầy đủ sẽ chỉ ra chính xác key của đối tượng gây ra lỗi xác thực.

Các phương pháp hay nhất để tránh lỗi cú pháp

Sự nhất quán là cách bảo vệ tốt nhất của bạn trước các lỗi này. Hãy làm theo các quy tắc sau để giữ cho các truy vấn của bạn sạch sẽ:

• Đặt tên nghiêm ngặt: Không bao giờ bắt đầu tên trường cơ sở dữ liệu bằng dấu $ trong schema của bạn. Mặc dù MongoDB 5.0+ cho phép điều này trong một số tài liệu, nhưng nó làm cho việc aggregation trở nên khó khăn hơn và dễ xảy ra lỗi hơn.
• Mô hình tư duy Key và Value: Hãy nhớ quy tắc vàng: Key là nhãn tùy chỉnh của bạn (không có $); Value là tham chiếu đến dữ liệu hiện có (sử dụng $).
• Sử dụng một IDE: Các công cụ như VS Code với tiện ích mở rộng MongoDB cung cấp tính năng làm nổi bật cú pháp. Chúng thường sẽ gắn cờ một dấu $ đặt sai vị trí trước khi bạn nhấn 'Execute'.