복합 색인 구성

Datastore 모드의 Firestore는 애플리케이션이 수행하는 모든 쿼리에 색인을 사용합니다. 이러한 색인은 항목이 변경될 때마다 업데이트되므로 애플리케이션이 쿼리를 생성할 때 결과가 신속하게 반환될 수 있습니다. Datastore 모드는 기본 제공 색인을 자동으로 제공하지만 애플리케이션에서 필요로 하는 복합 색인을 사전에 알고 있어야 합니다. 애플리케이션이 필요로 하는 복합 색인은 구성 파일에서 지정하면 됩니다. Datastore 에뮬레이터는 애플리케이션을 테스트할 때 Datastore 모드 복합 색인 구성을 자동으로 생성할 수 있습니다. gcloud 명령줄 도구는 프로덕션 Datastore 모드 데이터베이스에서 사용할 수 있는 색인을 업데이트하는 명령어를 제공합니다.

시스템 요구사항

gcloud CLI를 사용하려면 Google Cloud CLI가 설치되어 있어야 합니다.

index.yaml 정보

애플리케이션이 실행하는 모든 Datastore 모드 쿼리에는 상응하는 색인이 필요합니다. 단일 속성 쿼리처럼 단순한 쿼리의 색인은 자동으로 생성됩니다. 복잡한 쿼리의 복합 색인은 index.yaml이라는 구성 파일에 정의되어야 합니다. 이 파일은 애플리케이션과 함께 업로드되어 Datastore 모드 데이터베이스에 복합 색인을 생성합니다.

애플리케이션이 구성 파일에 적절한 항목이 없는 복합 색인을 필요로 하는 쿼리를 실행하려고 하면 Datastore 에뮬레이터가 이 파일에 항목을 자동으로 추가합니다. 파일을 편집하여 직접 복합 색인을 조정하거나 새로운 색인을 생성할 수 있습니다. index.yaml은 <project-directory>/WEB-INF/ 폴더에 위치합니다. 기본적으로 WEB-INF/appengine-generated/index.yaml이 있는 데이터 디렉터리는 ~/.config/gcloud/emulators/datastore/입니다. 추가 세부정보는 Datastore 에뮬레이터 프로젝트 디렉터리를 참조하세요.

다음은 index.yaml 파일의 예시입니다.

indexes:

- kind: Task
  ancestor: no
  properties:
  - name: done
  - name: priority
    direction: desc

- kind: Task
  properties:
  - name: collaborators
    direction: asc
  - name: created
    direction: desc

- kind: TaskList
  ancestor: yes
  properties:
  - name: percent_complete
    direction: asc
  - name: type
    direction: asc

index.yaml 구문은 YAML 형식입니다. 이 구문에 대한 자세한 내용은 YAML 웹사이트를 참조하세요.

복합 색인 정의

index.yaml 파일에는 indexes이라는 단일 목록 요소가 있습니다. 목록의 각 요소는 애플리케이션의 복합 색인을 나타냅니다.

색인 요소에는 다음과 같은 요소가 있을 수 있습니다.

kind
쿼리 항목의 종류입니다. 필수 요소입니다.
properties

복합 색인의 열로서 포함할 속성 목록으로, 균등 필터에 사용되는 속성이 먼저 표시되고 비균등 필터에 사용되는 속성이 다음에 표시됩니다. 그런 다음 정렬 순서와 방향이 표시됩니다.

목록의 각 요소에는 다음과 같은 요소가 포함됩니다.

name
속성의 Datastore 모드 이름입니다.
direction
정렬 방향입니다. 오름차순의 경우 asc, 내림차순의 경우 desc입니다. 쿼리의 정렬 순서에 사용되는 속성에만 필요하며 쿼리에서 사용하는 방향과 일치해야 합니다. 기본값은 asc입니다.
ancestor

쿼리에 상위 절이 있는 경우 yes입니다. 기본값은 no입니다.

자동 및 수동 복합 색인

Datastore 에뮬레이터가 생성된 복합 색인 정의를 index.yaml에 추가할 때는 다음 줄 아래에 추가하고 필요한 경우 줄을 삽입합니다.

# AUTOGENERATED

에뮬레이터는 이 행 아래의 모든 복합 색인 정의가 자동 생성되었다고 인식하므로 애플리케이션이 쿼리를 생성할 때 이 행 아래에 기존 정의를 업데이트할 수 있습니다.

이 행 위의 모든 복합 색인 정의는 수동 제어되는 것으로 인식되어 에뮬레이터에서 업데이트하지 않습니다. 에뮬레이터는 이 줄 아래의 내용만 변경하며, 완성된 index.yaml 파일에서 애플리케이션에 의해 실행되는 쿼리에 대한 복합 색인이 설명되지 않는 경우에만 변경합니다. 자동 복합 색인 정의를 제어하려면 색인을 이 줄 위로 옮깁니다.

복합 색인 업데이트

datastore indexes create 명령어는 로컬 Datastore 복합 색인 구성(index.yaml 파일)을 확인하며, 복합 색인 구성이 프로덕션 Datastore 모드 데이터베이스에 아직 존재하지 않는 복합 색인을 정의하는 경우 데이터베이스는 새 복합 색인을 생성합니다. indexes create을 사용하는 방법의 예시는 gcloud CLI를 사용하는 개발 워크플로를 참조하세요.

복합 색인을 만들려면 데이터베이스에서 복합 색인을 설정한 후 복합 색인을 기존 데이터로 백필해야 합니다. 복합 색인 생성 시간은 설정 시간과 백필 시간의 합계입니다.

  • 복합 색인을 설정하는 데는 몇 분 정도 걸립니다. 복합 색인의 최소 생성 시간은 비어 있는 데이터베이스인 경우에도 몇 분 정도입니다.

  • 백필 시간은 새 복합 색인에 속하는 기존 데이터의 양에 따라 다릅니다. 복합 색인에 속하는 속성 값이 많을수록 복합 색인을 백필하는 데 시간이 오래 걸립니다.

애플리케이션이 아직 빌드를 마치지 않은 복합 색인이 필요한 쿼리를 수행하는 경우 쿼리에서 예외가 발생합니다. 이러한 경우를 방지하려면 신규 복합 색인이 빌드를 끝내기 전에 복합 색인을 필요로 하는 새로운 버전의 애플리케이션 배포를 주의해야 합니다.

Google Cloud 콘솔의 색인 페이지에서 복합 색인의 상태를 확인할 수 있습니다.

사용되지 않는 복합 색인 삭제

복합 색인 구성에서 복합 색인을 변경하거나 삭제해도 원본 복합 색인은 Datastore 모드 데이터베이스에서 자동으로 삭제되지 않습니다. 새로운 복합 색인이 빌드되는 동안에도 계속해서 이전 버전의 애플리케이션을 실행하거나 최신 버전에서 문제가 발견되면 기존 버전으로 즉시 되돌릴 수 있는 기회가 있습니다.

이전 복합 색인이 더 이상 필요하지 않으면 datastore indexes cleanup 명령어를 사용하여 삭제할 수 있습니다. 이 명령어는 로컬 버전 index.yaml에 언급되지 않은 프로덕션 Datastore 모드 인스턴스의 모든 복합 색인을 삭제합니다. indexes cleanup을 사용하는 방법의 예시는 gcloud CLI를 사용하는 개발 워크플로를 참조하세요.

명령줄 인수

복합 색인 생성 및 삭제를 위한 명령줄 인수에 대한 자세한 내용은 각각 datastore indexes create 및 datastore indexes cleanup을 참조하세요. gcloud CLI의 명령줄 인수에 대한 자세한 내용은 gcloud CLI 참조를 확인하세요.

장기 실행 작업 관리

복합 색인 빌드는 장기 실행 작업이므로 완료하는 데 상당한 시간이 걸릴 수 있습니다.

복합 색인 빌드를 시작한 후 Datastore 모드에서 작업에 고유한 이름을 할당합니다. 작업 이름은 다음 예시와 같이 projects/[PROJECT_ID]/databases/(default)/operations/로 시작합니다.

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

그러나 describe 명령어에 작업 이름을 지정할 때 프리픽스를 생략할 수 있습니다.

모든 장기 실행 작업 나열

장기 실행 작업을 나열하려면 gcloud datastore operations list 명령어를 사용합니다. 이 명령어는 진행 중인 작업과 최근에 완료된 작업을 나열합니다. 작업은 완료 후 며칠 동안 나열됩니다.

gcloud

gcloud datastore operations list

rest

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • project-id: 프로젝트 ID입니다.

HTTP 메서드 및 URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/operations

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

아래에서 응답에 대한 정보를 참조하세요.

예를 들어 최근에 완료된 복합 색인 빌드에는 다음 정보가 표시됩니다.

{
  "operations": [
  {
    "name": "projects/project-id/operations/S01vcFVpSmdBQ0lDDCoDIGRiNTdiZDQNmE4YS0yMTVmNWUzZSQadGx1YWZlZAcSMXRzYWVzdS1yZXhlZG5pLW5pbWRhFQpWEg",
    "done": true,
    "metadata": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
      "common": {
        "endTime": "2020-06-23T16:55:29.923562Z",
        "operationType": "CREATE_INDEX",
        "startTime": "2020-06-23T16:55:10Z",
        "state": "SUCCESSFUL"
      },
      "indexId": "CICAJiUpoMK",
      "progressEntities": {
        "workCompleted": "2193027",
        "workEstimated": "2198182"
      }
    },
    "response": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.Index",
      "ancestor": "NONE",
      "indexId": "CICAJiUpoMK",
      "kind": "Task",
      "projectId": "project-id",
           "properties": [
        {
          "direction": "ASCENDING",
          "name": "priority"
        },
        {
          "direction": "ASCENDING",
          "name": "done"
        },
        {
          "direction": "DESCENDING",
          "name": "created"
        }
      ],
      "state": "READY"
    }
  },
  ]
}

단일 작업 설명

장기 실행 작업을 모두 나열하는 대신 단일 작업의 세부정보를 나열할 수 있습니다.

gcloud

operations describe 명령어를 사용하여 복합 색인 빌드의 상태를 표시하세요.

gcloud datastore operations describe operation-name

rest

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • project-id: 프로젝트 ID입니다.

HTTP 메서드 및 URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/operations

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

아래에서 응답에 대한 정보를 참조하세요.

완료 시간 예상

작업이 실행되면 state 필드 값을 통해 작업의 전체 상태를 확인할 수 있습니다.

또한 장기 실행 작업 상태를 요청하면 workEstimated 및 workCompleted 측정항목이 반환됩니다. 이러한 측정항목은 항목 수만큼 반환됩니다. workEstimated는 데이터베이스 통계를 기준으로 작업에서 처리할 것으로 예상되는 총 항목 수를 나타냅니다. workCompleted는 현재까지 처리된 항목 수를 나타냅니다. 작업이 완료되면 workCompleted에 실제로 처리된 총 항목 수가 반영되며, 이는 workEstimated 값과 다를 수 있습니다.

workCompleted를 workEstimated로 나누면 예상 진행도를 대략적으로 추정할 수 있습니다. 이 예상치는 통계 수집 지연으로 인해 부정확할 수 있습니다.

예를 들어 복합 색인 빌드 진행 상태는 다음과 같습니다.

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

작업이 완료되면 작업 설명에 "done": true가 포함됩니다. 작업 결과는 state 필드의 값을 참조하세요. 응답에 done 필드가 설정되지 않으면 이 값은 false입니다 진행 중인 작업에 done 값을 사용해서는 안 됩니다.