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 những 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ý chỉ mục tự động, thủ công và vectơ của bạn.

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 một truy vấn kết hợp có mệnh đề phạm vi không liên kết với một chỉ mục hiện có, thì bạn sẽ nhận được thông báo lỗi. Thông báo lỗi này có chứa 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 của Firebase.

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

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

Vai trò và quyền

Trước khi 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:

  • 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 đây để 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 của Firebase:

hình ảnh về giao diện lập chỉ mục firestore trong bảng điều khiển của firebase

  1. Chuyển đến mục Cloud Firestore của bảng điều khiển của Firebase.
  2. Chuyển đến thẻ Indexes (Chỉ mục) rồi nhấp vào Add Index (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 theo các ràng buộc về đường dẫn trường.

Quá trình xây dựng 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 chúng trong mục Composite Indexes (Chỉ mục kết hợp). Nếu các chỉ mục vẫn đang được xây dựng, bảng điều khiển của Firebase sẽ có một thanh trạng thái xây dựng.

Xoá chỉ mục

Cách xoá một chỉ mục:

  1. Chuyển đến mục Cloud Firestore của bảng điều khiển của Firebase.
  2. Nhấp vào thẻ Indexes (Chỉ mục).
  3. Di chuột qua chỉ mục mà 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á bằng cách nhấp vào Delete (Xoá) trong cảnh báo.

Sử dụng Firebase CLI

Bạn cũng có thể triển khai chỉ mục bằng Firebase CLI. Để 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 ở đúng định dạng. Chỉnh sửa tệp để thêm nhiều chỉ mục hơn và triển khai tệp đó bằng lệnh firebase deploy.

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

Nếu bạn chỉnh sửa chỉ mục bằng bảng điều khiển của Firebase, hãy nhớ cập nhật cả tệp chỉ mục cục bộ. 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 một trường (tự động) và chỉ mục kết hợp (thủ công). 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 tự động và chỉ mục thủ công 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ự động)

Tệp cấu hình Terraform ví dụ sau đây tạo một chỉ mục một trường trên trường name trong bộ sưu tậ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 thế database-id bằng mã cơ sở dữ liệu của bạn.

Chỉ mục kết hợp (thủ công)

Tệp cấu hình Terraform ví dụ sau đây tạo một chỉ mục kết hợp cho sự kết hợp của trường name và trường description trong bộ sưu tậ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 thế 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 ví dụ sau đây tạo một chỉ mục vectơ trên trường embedding trong bộ sưu tậ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 thế database-id bằng mã cơ sở dữ liệu của bạn.

Thời gian xây dựng chỉ mục

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

  • Quá trình thiết lập chỉ mục mất vài phút. Thời gian xây dựng 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ó thuộc về 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 bổ sung dữ liệu vào chỉ mục càng lâu.

Quá trình xây dựng chỉ mục là các thao tác dài kỳ.

Sau khi bạn bắt đầu xây dựng chỉ mục, Cloud Firestore sẽ gán cho thao tác đó một tên duy nhất. Tên thao tác 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 dài kỳ

Để liệt kê các thao tác dài kỳ, 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 đượ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 thao tác

Thay vì liệt kê tất cả các thao tác dài kỳ, bạn có thể liệt kê thông tin chi tiết của 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 của bạn 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 dài kỳ 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 đã được xử lý cho đến nay. Sau khi thao tác hoàn tất, workCompleted sẽ phản ánh tổng số tài liệu đã được xử lý thực tế, có thể khác với giá trị của workEstimated.

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

Ví dụ: sau đây là trạng thái tiến trình của quá trình xây 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, phần 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 thao tác. Nếu trường done không được đặt trong phản hồi, thì giá trị của trường đó là false. Không phụ thuộc vào sự tồn tại của giá trị done đối với các thao tác đang diễn ra.

Lỗi xây dựng chỉ mục

Bạn có thể gặp lỗi xây dựng chỉ mục khi quản lý chỉ mục thủ công và các trường hợp miễn trừ chỉ mục tự động. Một 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à thao tác đó đang lập chỉ mục. Thông thường nhất, đ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 trên mỗi tài liệu.

Nếu quá trình tạo chỉ mục không thành công, bạn sẽ thấy thông báo lỗi trong bảng điều khiển. Sau khi xác minh rằng bạn không đạt đến bất kỳ giới hạn chỉ mụcnào, hãy thử lại thao tác chỉ mục.