색인 관리

Firestore를 사용하면 모든 쿼리에 색인을 요청하므로 쿼리 성능이 보장됩니다. 대부분의 기본 쿼리에 필요한 색인은 자동으로 생성됩니다. 앱을 사용하고 테스트할 때 Cloud Firestore는 오류 메세지를 생성합니다. 이는 앱에 필요한 추가 색인을 만드는 데 유용합니다. 이 페이지에서는 단일 필드 색인과 복합 색인을 관리하는 방법을 설명합니다.

오류 메시지를 통해 누락된 색인 생성

기존 색인에 매핑되지 않는 범위 절이 포함된 복합 쿼리를 시도하면 오류가 발생합니다. 오류 메시지에는 Firebase Console에서 누락된 색인을 만드는 직접 링크가 포함됩니다.

생성된 링크를 따라 Firebase Console로 이동하고 자동으로 입력된 정보를 검토한 후 만들기를 클릭합니다.

역할 및 권한

Firestore에서 색인을 만들려면 먼저 다음 역할 중 하나를 할당받아야 합니다.

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

커스텀 역할을 정의한 경우 다음 권한을 모두 할당하여 색인을 만듭니다.

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

Google Cloud Platform Console 사용

Google Cloud Platform Console에서 단일 필드 색인 생성 예외와 복합 색인을 관리할 수 있습니다.

복합 색인 만들기

GCP Console에서 새 복합 색인을 수동으로 만들려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 색인을 클릭한 후 복합 탭을 클릭합니다.
색인 만들기를 클릭합니다.
컬렉션 ID를 입력합니다. 색인을 생성할 필드의 이름과 각 필드의 색인 모드를 추가합니다. 색인 저장을 클릭합니다.

새 색인이 복합 색인 목록에 표시되고 Firestore에서 색인 생성을 시작합니다. 색인 생성이 완료되면 색인 옆에 녹색 체크표시가 나타납니다.

복합 색인 삭제

복합 색인을 삭제하려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 색인을 클릭한 후 복합 탭을 클릭합니다.
복합 색인 목록에서 삭제할 색인의 더보기 버튼 를 클릭합니다. 삭제를 클릭합니다.
알림에서 색인 삭제를 클릭하여 이 색인을 삭제할지 여부를 확인합니다.

단일 필드 색인 예외 추가

단일 필드 색인 예외를 사용하면 컬렉션의 특정 필드에서 자동 색인 설정을 재정의할 수 있습니다. Console에서 단일 필드 예외를 추가할 수 있습니다.

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 색인을 클릭한 후 단일 필드 탭을 클릭합니다.
예외 추가를 클릭합니다.
컬렉션 ID와 필드 경로를 입력합니다.
이 필드의 새 색인 생성 설정을 선택합니다. 이 필드에 자동으로 업데이트되는 오름차순, 내림차순, 배열 포함 단일 필드 색인을 사용 설정하거나 중지합니다.
예외 저장을 클릭합니다.

컬렉션 수준 예외 추가

컬렉션 ID 아래의 모든 필드에 적용되는 단일 필드 색인 예외를 정의하려면 다음 안내를 따르세요.

예외 추가를 클릭합니다.
컬렉션 그룹에 컬렉션 ID를 입력하고 필드 경로를 *로 설정합니다.
컬렉션 그룹의 모든 필드에 적용할 색인 생성 예외를 선택합니다.
예외 저장을 클릭합니다.

단일 필드 색인 예외 삭제

단일 필드 색인 예외를 삭제하려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 색인을 클릭한 후 단일 필드 탭을 클릭합니다.
단일 필드 색인 예외 목록에서 삭제할 예외의 더보기 버튼 을 클릭합니다. 삭제를 클릭합니다.
알림에서 삭제를 클릭하여 이 예외를 삭제할 것인지 확인합니다.

단일 필드 예외를 삭제하면 지정된 필드 또는 하위 필드가 상속된 색인 생성 설정을 사용합니다. 문서 필드는 데이터베이스의 자동 색인 설정으로 돌아갑니다. 매핑된 하위 필드는 자동 색인 설정을 상속하기 전에 상위 필드의 예외를 상속합니다.

Firebase CLI 사용

Firebase CLI를 사용하여 색인을 배포할 수도 있습니다. 시작하려면 프로젝트 디렉터리에서 firebase init firestore를 실행하면 됩니다. 설정하는 동안 Firebase CLI에서 기본 색인을 사용한 올바른 형식의 JSON 파일을 생성합니다. 파일을 수정해 색인을 추가하고 firebase deploy 명령어를 사용해 배포합니다.

Firestore 색인과 규칙만 배포하려면 --only firestore 플래그를 추가합니다.

Firebase Console에서 색인을 수정할 경우 로컬 색인 파일도 업데이트해야 합니다. JSON 색인 정의 참조를 참조하세요.

색인 빌드 시간

색인을 빌드하려면 Firestore가 색인을 설정한 다음 색인을 기존 데이터로 백필해야 합니다. 색인 빌드 시간은 설정 시간과 백필 시간의 합계입니다.

색인 설정에는 몇 분 정도 걸립니다. 색인의 최소 빌드 시간은 비어 있는 데이터베이스인 경우에도 몇 분 정도 걸립니다.
백필 시간은 새 색인에 속하는 기존 데이터의 양에 따라 다릅니다. 색인 정의와 일치하는 필드 값이 많을수록 색인을 백필하는 데 시간이 오래 걸립니다.

색인 빌드는 장기 실행 작업입니다.

색인 빌드를 시작한 후 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 값을 사용해서는 안 됩니다.

색인 빌드 오류

복합 색인 및 단일 필드 색인 예외를 관리할 때 색인 빌드 오류가 발생할 수 있습니다. Firestore에서 색인을 생성하는 데이터 문제가 발생하면 색인 생성 작업이 실패할 수 있습니다. 대부분의 경우 이는 색인 한도에 도달했음을 의미합니다. 예를 들어 작업이 문서당 최대 색인 항목 수에 도달했을 수 있습니다.

색인 생성이 실패하면 Console에 오류 메시지가 표시됩니다. 색인 한도에 도달했는지 확인한 후 색인 작업을 다시 시도하세요.