Cloud Firestore를 사용하면 모든 쿼리에 색인을 요청하므로 쿼리 성능이 보장됩니다. 대부분의 기본 쿼리에 필요한 색인이 자동으로 생성됩니다. 앱을 사용하고 테스트할 때 Cloud Firestore는 오류 메세지를 생성합니다. 이는 앱에 필요한 추가 색인을 만드는 데 유용합니다. 이 페이지에서는 단일 필드, 복합, 벡터 색인을 관리하는 방법을 설명합니다.
오류 메시지를 통해 누락된 색인 생성
기존 색인에 매핑되지 않는 범위 절이 포함된 복합 쿼리를 시도하면 오류가 발생합니다. 오류 메시지에는 Firebase Console에서 누락된 색인을 만드는 직접 링크가 포함됩니다.
생성된 링크를 따라 Firebase Console로 이동하고 자동으로 입력된 정보를 검토한 후 만들기를 클릭하세요.
벡터 색인이 필요한 경우 누락된 벡터 색인을 만드는 Google Cloud CLI 명령어가 오류 메시지에 포함됩니다. 명령어를 실행하여 누락된 색인을 만듭니다.
역할 및 권한
Cloud Firestore에서 색인을 만들려면 먼저 다음 역할 중 하나를 할당받아야 합니다.
roles/datastore.ownerroles/datastore.indexAdminroles/editorroles/owner
커스텀 역할을 정의한 경우 다음 권한을 모두 할당하여 색인을 만듭니다.
datastore.indexes.createdatastore.indexes.deletedatastore.indexes.getdatastore.indexes.listdatastore.indexes.update
Firebase Console 사용
Firebase Console에서 수동으로 새 색인을 만들려면 다음 안내를 따르세요.
- Firebase Console의 Cloud Firestore 섹션으로 이동합니다.
- 색인 탭으로 이동하고 색인 추가를 클릭합니다.
- 컬렉션 이름을 입력하고 색인의 정렬 기준으로 사용할 필드를 설정합니다.
- 만들기를 클릭합니다.
색인 필드는 필드 경로 제약 조건을 준수해야 합니다.
쿼리의 크기에 따라 색인을 만드는 데 몇 분 정도 걸릴 수 있습니다. 색인이 생성되면 복합 색인 섹션에서 색인과 색인의 상태를 확인할 수 있습니다. 여전히 생성 중이면 Firebase Console에 생성 상태 표시줄이 포함됩니다.
색인 삭제
색인을 삭제하려면 다음 안내를 따르세요.
- Firebase Console의 Cloud Firestore 섹션으로 이동합니다.
- 색인 탭을 클릭합니다.
- 삭제할 색인에 마우스를 가져가고 컨텍스트 메뉴에서 삭제를 선택합니다.
- 알림에서 삭제를 클릭하여 삭제 의사를 확인합니다.
Firebase CLI 사용
Firebase CLI를 사용하여 색인을 배포할 수도 있습니다.
시작하려면 프로젝트 디렉터리에서 firebase init firestore를 실행하면 됩니다.
설정하는 동안 Firebase CLI에서 기본 색인을 사용한 올바른 형식의 JSON 파일을 생성합니다. 파일을 수정해 색인을 추가하고 firebase deploy 명령어를 사용해 배포합니다.
Cloud Firestore 색인과 규칙만 배포하려면 --only firestore 플래그를 추가합니다.
Firebase Console에서 색인을 수정할 경우 로컬 색인 파일도 업데이트해야 합니다. JSON 색인 정의 참조를 참조하세요.
Terraform 사용
데이터베이스에서 색인 만들기
Cloud Firestore 데이터베이스에는 단일 필드 색인과 복합 색인이 모두 포함될 수 있습니다. Terraform 구성 파일을 수정하여 데이터베이스의 색인을 만들 수 있습니다.
단일 필드 색인과 복합 색인은 고유한 Terraform 리소스 유형을 사용합니다(google_firestore_index 및 google_firestore_field).
단일 필드 색인
다음 Terraform 구성 파일 예시에서는 chatrooms 컬렉션의 name 필드에 대한 단일 필드 색인을 만듭니다.
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 {}
}
- project-id를 프로젝트 ID로 바꿉니다. 프로젝트 ID는 고유해야 합니다.
- database-id를 데이터베이스 ID로 바꿉니다.
복합 색인
다음 Terraform 구성 파일 예시에서는 chatrooms 컬렉션의 name 필드와 description 필드 조합에 대한 복합 색인을 만듭니다.
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"
}
}
- project-id를 프로젝트 ID로 바꿉니다. 프로젝트 ID는 고유해야 합니다.
- database-id를 데이터베이스 ID로 바꿉니다.
벡터 색인
다음 Terraform 구성 파일 예시에서는 chatrooms 컬렉션의 embedding 필드에 대한 벡터 색인을 만듭니다.
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 {}
}
}
}
- project-id를 프로젝트 ID로 바꿉니다. 프로젝트 ID는 고유해야 합니다.
- database-id를 데이터베이스 ID로 바꿉니다.
색인 빌드 시간
색인을 빌드하려면 Cloud Firestore가 색인을 설정한 다음 색인을 기존 데이터로 백필해야 합니다. 색인 빌드 시간은 설정 시간과 백필 시간의 합계입니다.
색인 설정에는 몇 분 정도 걸립니다. 색인의 최소 빌드 시간은 비어 있는 데이터베이스인 경우에도 몇 분 정도 걸립니다.
백필 시간은 새 색인에 속하는 기존 데이터의 양에 따라 다릅니다. 색인 정의와 일치하는 필드 값이 많을수록 색인을 백필하는 데 시간이 오래 걸립니다.
색인 빌드는 장기 실행 작업입니다.
색인 빌드를 시작한 후 Cloud Firestore는 작업에 고유한 이름을 할당합니다. 작업 이름은 다음 예시와 같이 projects/[PROJECT_ID]/databases/(default)/operations/로 시작합니다.
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
그러나 describe 명령어에 작업 이름을 지정할 때 프리픽스를 생략할 수 있습니다.
모든 장기 실행 작업 나열
장기 실행 작업을 나열하려면 gcloud datastore operations list 명령어를 사용합니다. 이 명령어는 진행 중인 작업과 최근에 완료된 작업을 나열합니다. 작업은 완료 후 며칠 동안 나열됩니다.
gcloud firestore operations list
작업 상태 확인
장기 실행 작업을 모두 나열하는 대신 단일 작업의 세부정보를 나열할 수 있습니다.
gcloud firestore operations describe operation-name
완료 시간 예상
작업이 실행되면 state 필드 값을 통해 작업의 전체 상태를 확인할 수 있습니다.
또한 장기 실행 작업 상태를 요청하면 workEstimated 및 workCompleted 측정항목이 반환됩니다. 이러한 측정항목은 문서 수에 따라 반환됩니다. workEstimated는 작업에서 처리할 것으로 예상되는 총 문서 수를 나타냅니다. workCompleted는 현재까지 처리된 문서 수를 나타냅니다. 작업이 완료되면 workCompleted에 실제로 처리된 총 문서 수가 반영되며 이는 workEstimated 값과 다를 수 있습니다.
workCompleted를 workEstimated로 나누면 예상 진행도를 대략적으로 추정할 수 있습니다. 이 예상치는 통계 수집 지연으로 인해 부정확할 수 있습니다.
예를 들어 색인 빌드의 진행 상태는 다음과 같습니다.
{
"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"
}
},
},
...
작업이 완료되면 작업 설명에 "done":
true가 포함됩니다. 작업 결과는 state 필드의 값을 참조하세요. 응답에 done 필드가 설정되지 않으면 이 값은 false입니다 진행 중인 작업에 done 값을 사용해서는 안 됩니다.
색인 빌드 오류
복합 색인 및 단일 필드 색인 예외를 관리할 때 색인 빌드 오류가 발생할 수 있습니다. Cloud Firestore에서 색인을 생성하는 데이터 문제가 발생하면 색인 생성 작업이 실패할 수 있습니다. 대부분의 경우 이는 색인 한도에 도달했음을 의미합니다. 예를 들어 작업이 문서당 최대 색인 항목 수에 도달했을 수 있습니다.
색인 생성이 실패하면 Console에 오류 메시지가 표시됩니다. 색인 한도에 도달했는지 확인한 후 색인 작업을 다시 시도하세요.