Quản lý chỉ mục trong Cloud Firestore

Cloud Firestore đảm bảo hiệu suất truy vấn bằng cách yêu cầu một chỉ mục cho mỗi truy vấn. Các chỉ mục cần thiết cho các truy vấn cơ bản nhất sẽ được tự động tạo cho bạn. Khi bạn sử dụng và kiểm thử ứng dụng, Cloud Firestore sẽ tạo thông báo lỗi để giúp bạn tạo thêm các chỉ mục mà ứng dụng yêu cầu. Trang này mô tả cách quản lý các chỉ mục một trường, hợp thành và vectơ.

Tạo chỉ mục bị thiếu thông qua thông báo lỗi

Nếu bạn cố gắng thực hiện truy vấn phức hợp có mệnh đề phạm vi không liên kết đến chỉ mục hiện có, bạn sẽ gặp lỗi. Thông báo lỗi bao gồm một đường liên kết trực tiếp để tạo chỉ mục bị thiếu trong bảng điều khiển Firebase.

Lưu ý: Bạn có thể quản lý Cloud Firestore thông qua bảng điều khiển Firebase hoặc Bảng điều khiển Google Cloud Platform, nhưng các đường liên kết này sẽ luôn mở trong bảng điều khiển Firebase.

Truy cập vào bảng điều khiển Firebase theo đường liên kết được tạo, xem lại thông tin được điền tự động rồi nhấp vào Tạo.

Lưu ý: Đối với các trường không phải mảng và không phải bản đồ, bạn phải chọn thứ tự tăng dần hoặc giảm dần, ngay cả khi bạn không cần trường này để sắp xếp. Lựa chọn của bạn không ảnh hưởng đến hành vi của các toán tử bằng trong truy vấn.

Trong trường hợp cần có chỉ mục vectơ, thông báo lỗi sẽ bao gồm lệnh Google Cloud CLI để tạo chỉ mục vectơ bị thiếu. Chạy lệnh để tạo chỉ mục bị thiếu.

Lưu ý: Hiện tại, bạn không thể tạo chỉ mục vectơ trong bảng điều khiển Firebase hoặc Bảng điều khiển Google Cloud Platform.

Vai trò và quyền

Để có thể tạo chỉ mục trong Cloud Firestore, hãy đảm bảo rằng bạn được chỉ định một trong các vai trò sau:

Lưu ý: Các vai trò sau đây được quản lý thông qua tính năng Quản lý danh tính và quyền truy cập (IAM). Để biết thêm thông tin về các vai trò và quyền liên quan, hãy xem bài viết Vai trò được xác định trước.

• roles/datastore.owner
• roles/datastore.indexAdmin
• roles/editor
• roles/owner

Nếu bạn đã xác định các vai trò tuỳ chỉnh, hãy chỉ định tất cả các quyền sau để tạo chỉ mục:

• datastore.indexes.create
• datastore.indexes.delete
• datastore.indexes.get
• datastore.indexes.list
• datastore.indexes.update

Sử dụng bảng điều khiển của Firebase

Cách tạo chỉ mục mới theo cách thủ công trong bảng điều khiển Firebase:

1. Chuyển đến phần Cloud Firestore của bảng điều khiển của Firebase.
2. Chuyển đến thẻ Chỉ mục rồi nhấp vào Thêm chỉ mục.
3. Nhập tên bộ sưu tập và đặt các trường mà bạn muốn sắp xếp chỉ mục theo.
4. Nhấp vào Tạo.

Các trường chỉ mục phải tuân thủ các quy tắc ràng buộc về đường dẫn trường.

Quá trình tạo chỉ mục có thể mất vài phút, tuỳ thuộc vào kích thước của truy vấn. Sau khi tạo, bạn có thể xem các chỉ mục và trạng thái của các chỉ mục đó trong phần Chỉ mục tổng hợp. Nếu các bản dựng vẫn đang tạo, bảng điều khiển Firebase sẽ có một thanh trạng thái bản dựng.

Xoá chỉ mục

Cách xoá chỉ mục:

1. Chuyển đến phần Cloud Firestore của bảng điều khiển của Firebase.
2. Nhấp vào thẻ Chỉ mục.
3. Di chuột qua chỉ mục bạn muốn xoá rồi chọn Delete (Xoá) trong trình đơn theo bối cảnh.
4. Xác nhận rằng bạn muốn xoá thông báo đó bằng cách nhấp vào Xoá trong thông báo.

Sử dụng Giao diện dòng lệnh (CLI) của Firebase

Bạn cũng có thể triển khai chỉ mục bằng Giao diện dòng lệnh (CLI) của Firebase. Để bắt đầu, hãy chạy firebase init firestore trong thư mục dự án. Trong quá trình thiết lập, Firebase CLI sẽ tạo một tệp JSON có các chỉ mục mặc định ở định dạng chính xác. Chỉnh sửa tệp để thêm các chỉ mục khác và triển khai tệp đó bằng lệnh firebase deploy.

Để chỉ triển khai các chỉ mục và quy tắc Cloud Firestore, hãy thêm cờ --only firestore.

Nếu bạn chỉnh sửa các chỉ mục bằng bảng điều khiển Firebase, hãy nhớ cập nhật tệp chỉ mục cục bộ. Hãy tham khảo tài liệu tham khảo về định nghĩa chỉ mục JSON.

Sử dụng Terraform

Tạo chỉ mục trong cơ sở dữ liệu

Cơ sở dữ liệu Cloud Firestore có thể bao gồm cả chỉ mục đơn trường và chỉ mục tổng hợp. Bạn có thể chỉnh sửa tệp cấu hình Terraform để tạo chỉ mục cho cơ sở dữ liệu. Chỉ mục đơn trường và chỉ mục tổng hợp sử dụng các loại tài nguyên Terraform riêng biệt (google_firestore_index và google_firestore_field).

Chỉ mục một trường

Tệp cấu hình Terraform mẫu sau đây tạo một chỉ mục một trường trên trường name trong tập hợp chatrooms:

firestore.tf

resource "random_id" "variable"{
  byte_length = 8
}

resource "google_firestore_field" "single-index" {
  project = "project-id"
  database = "database-id"
  collection = "chatrooms_${random_id.variable.hex}"
  field = "name"

  index_config {
    indexes {
        order = "ASCENDING"
        query_scope = "COLLECTION_GROUP"
    }
    indexes {
        array_config = "CONTAINS"
    }
  }

  ttl_config {}
}

• Thay thế project-id bằng mã dự án của bạn. Mã dự án phải là duy nhất.
• Thay database-id bằng mã cơ sở dữ liệu của bạn.

Chỉ mục tổng hợp

Tệp cấu hình Terraform mẫu sau đây tạo một chỉ mục tổng hợp cho tổ hợp trường name và trường description trong tập hợp chatrooms:

firestore.tf

resource "google_firestore_index" "composite-index" {
  project = "project-id"
  database = "database-id"

  collection = "chatrooms"

  fields {
    field_path = "name"
    order      = "ASCENDING"
  }

  fields {
    field_path = "description"
    order      = "DESCENDING"
  }

}

• Thay thế project-id bằng mã dự án của bạn. Mã dự án phải là duy nhất.
• Thay database-id bằng mã cơ sở dữ liệu của bạn.

Chỉ mục vectơ

Tệp cấu hình Terraform mẫu sau đây tạo một chỉ mục vectơ trên trường embedding trong tập hợp chatrooms:

firestore.tf

resource "google_firestore_index" "vector-index" {
  project = "project-id"
  database = "database-id"
  collection = "chatrooms"

  fields {
    field_path = "__name__"
    order = "ASCENDING"
  }

  fields {
    field_path = "embedding"
    vector_config {
      dimension = 128
      flat {}
    }
  }
}

• Thay thế project-id bằng mã dự án của bạn. Mã dự án phải là duy nhất.
• Thay database-id bằng mã cơ sở dữ liệu của bạn.

Thời gian tạo chỉ mục

Để tạo một chỉ mục, Cloud Firestore phải thiết lập chỉ mục đó rồi điền lại chỉ mục bằng dữ liệu hiện có. Thời gian tạo chỉ mục là tổng thời gian thiết lập và thời gian điền lại:

• Quá trình thiết lập chỉ mục sẽ mất vài phút. Thời gian tạo tối thiểu cho một chỉ mục là vài phút, ngay cả đối với cơ sở dữ liệu trống.

• Thời gian bổ sung dữ liệu phụ thuộc vào lượng dữ liệu hiện có trong chỉ mục mới. Càng có nhiều giá trị trường khớp với định nghĩa chỉ mục, thì thời gian điền lại chỉ mục càng lâu.

Bản dựng chỉ mục là các thao tác chạy trong thời gian dài.

Thuật ngữ chính: Cloud Firestore hỗ trợ một số thao tác quản trị có thể mất nhiều thời gian để hoàn tất. Các thao tác này được gọi là các thao tác chạy trong thời gian dài. Cloud Firestore bao gồm các tính năng để thực thi và quản lý các thao tác chạy trong thời gian dài. Các thao tác chạy trong thời gian dài được hỗ trợ bao gồm bản dựng chỉ mục và thao tác xuất.

Sau khi bạn bắt đầu tạo một bản dựng chỉ mục, Cloud Firestore sẽ gán tên riêng cho thao tác đó. Tên toán tử có tiền tố là projects/[PROJECT_ID]/databases/(default)/operations/, ví dụ:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Tuy nhiên, bạn có thể bỏ qua tiền tố khi chỉ định tên thao tác cho lệnh describe.

Liệt kê tất cả các thao tác chạy trong thời gian dài

Để liệt kê các thao tác chạy trong thời gian dài, hãy sử dụng lệnh gcloud firestore operations list. Lệnh này liệt kê các thao tác đang diễn ra và các thao tác đã hoàn tất gần đây. Các thao tác sẽ được liệt kê trong vài ngày sau khi hoàn tất:

gcloud firestore operations list

Kiểm tra trạng thái hoạt động

Thay vì liệt kê tất cả các thao tác chạy trong thời gian dài, bạn có thể liệt kê thông tin chi tiết về một thao tác:

gcloud firestore operations describe operation-name

Ước tính thời gian hoàn thành

Khi thao tác chạy, hãy xem giá trị của trường state để biết trạng thái tổng thể của thao tác.

Yêu cầu về trạng thái của một thao tác chạy trong thời gian dài cũng trả về các chỉ số workEstimated và workCompleted. Các chỉ số này được trả về cho số lượng tài liệu. workEstimated cho biết tổng số tài liệu ước tính mà một thao tác sẽ xử lý. workCompleted cho biết số lượng tài liệu đã xử lý đến thời điểm hiện tại. Sau khi thao tác hoàn tất, workCompleted sẽ phản ánh tổng số tài liệu thực sự được xử lý. Giá trị này có thể khác với giá trị của workEstimated.

Chia workCompleted cho workEstimated để ước tính tiến trình một cách tương đối. Số liệu ước tính có thể không chính xác vì nó phụ thuộc vào việc thu thập số liệu thống kê bị trễ.

Ví dụ: sau đây là trạng thái tiến trình của một bản dựng chỉ mục:

{
  "operations": [
    {
      "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI",
      "metadata": {
        "@type": "type.googleapis.com/google.firestore.admin.v1.IndexOperationMetadata",
        "common": {
          "operationType": "CREATE_INDEX",
          "startTime": "2020-06-23T16:52:25.697539Z",
          "state": "PROCESSING"
        },
        "progressDocuments": {
          "workCompleted": "219327",
          "workEstimated": "2198182"
        }
       },
    },
    ...

Khi một thao tác hoàn tất, nội dung mô tả thao tác sẽ chứa "done": true. Xem giá trị của trường state để biết kết quả của phép toán. Nếu bạn không đặt trường done trong phản hồi, thì giá trị của trường này sẽ là false. Không phụ thuộc vào sự tồn tại của giá trị done cho các thao tác đang diễn ra.

Lỗi tạo chỉ mục

Bạn có thể gặp lỗi tạo chỉ mục khi quản lý chỉ mục tổng hợp và trường hợp miễn trừ chỉ mục một trường. Thao tác lập chỉ mục có thể không thành công nếu Cloud Firestore gặp vấn đề với dữ liệu mà nó đang lập chỉ mục. Thông thường, điều này có nghĩa là bạn đã đạt đến giới hạn chỉ mục. Ví dụ: thao tác có thể đã đạt đến số lượng mục nhập chỉ mục tối đa cho mỗi tài liệu.

Nếu không tạo được chỉ mục, bạn sẽ thấy thông báo lỗi trong bảng điều khiển. Sau khi bạn xác minh rằng bạn không gặp phải bất kỳ giới hạn lập chỉ mục nào, hãy thử lại thao tác lập chỉ mục.