색인 관리

이 페이지에서는 색인을 관리하는 방법을 설명합니다. 색인에 대해 자세히 알아보려면 색인 개요를 참조하세요.

시작하기 전에

MongoDB 호환성을 갖춘 Firestore에서 색인을 만들려면 먼저 다음 역할 중 하나가 할당되어야 합니다.

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

역할을 부여하려면 단일 역할 부여를 참조하세요. Firestore 역할 및 관련 권한에 대한 자세한 내용은 사전 정의된 역할을 참고하세요.

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

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

색인 만들기

색인을 만들려면 다음 단계를 완료하세요.

MongoDB API

createIndex() 메서드를 사용하여 색인을 만듭니다. 예를 들면 다음과 같습니다.

  •   db.restaurants.createIndex({"cuisine" : 1})
  
  •   db.restaurants.createIndex({"cuisine" : 1}, {sparse: true})

  • db.runCommand()를 사용한 색인 생성도 최대 하나의 색인으로 지원됩니다.

      db.runCommand({"createIndexes":"restaurant", "index": [{"key": {"cuisine":1}, {"name": "cuisine_index"}]})

유의해야 할 제한사항은 다음과 같습니다.

  • 요청당 하나의 색인만 만들 수 있습니다. db.collection.createIndexes()는 지원되지 않습니다.
  • MongoDB API를 사용한 색인 생성의 감사 로그는 google.firestore.admin.v1.FirestoreAdmin.CreateIndex라는 메서드 이름을 사용합니다.
  • 지원되는 색인 옵션은 색인 및 색인 속성을 참조하세요.
Google Cloud 콘솔

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

    데이터베이스로 이동

  2. 데이터베이스 목록에서 데이터베이스를 선택합니다.
  3. 탐색 메뉴에서 색인을 클릭합니다.
  4. 색인 만들기를 클릭합니다.
  5. 컬렉션 ID를 입력합니다.
  6. 필드 경로를 하나 이상 추가하고 각 필드의 색인 옵션을 선택합니다.
  7. 필드 존재 옵션(비희소 또는 희소)을 선택합니다.
  8. 원하는 경우 멀티 키 색인 또는 고유 색인 옵션을 설정합니다.
  9. 만들기를 클릭합니다.
  10. 새 색인이 색인 목록에 표시되고 MongoDB 호환성을 갖춘 Firestore에서 색인 생성을 시작합니다. 색인이 생성되면 색인 옆에 녹색 체크표시가 나타납니다. 색인이 생성되지 않으면 색인 빌드 오류에서 가능한 원인을 확인하세요.
gcloud CLI

색인을 만들려면 gcloud firestore indexes composite create 명령어를 사용합니다. api-scope를 mongodb-compatible-api로 설정합니다. 

gcloud firestore indexes composite create \
--database='DATABASE_ID' \
--collection-group=COLLECTION \
--field-config=FIELD_CONFIGURATION \
--query-scope=collection-group \
--density=dense \
--api-scope=mongodb-compatible-api

다음을 바꿉니다.

  • DATABASE_ID: 데이터베이스 ID
  • COLLECTION: 컬렉션 이름
  • FIELD_CONFIGURATION: 필드 구성. 각 필드에 --field-config=field-path=를 추가합니다. 예를 들면 다음과 같습니다. 
        --field-config=field-path=user-id,order=descending \
    --field-config=field-path=score,order=descending

    이러한 필드 구성에 대한 자세한 내용은 --field-config를 참조하세요.

희소 색인을 만들려면 --density=sparse-any를 설정합니다.

멀티 키 색인을 만들려면 --multikey 플래그를 추가합니다.

고유 색인을 만들려면 --unique 플래그를 추가합니다.

Terraform

google_firestore_index 리소스를 사용하고 api_scope를 MONGODB_COMPATIBLE_API로, query_scope를 COLLECTION_GROUP으로 설정합니다. 

resource "google_firestore_index" "index" {
  database    = "DATABASE_ID"
  collection  = "COLLECTION"
  api_scope   = "MONGODB_COMPATIBLE_API"
  query_scope = "COLLECTION_GROUP"

  // You can include multiple field blocks
  fields {
    field_path = "FIELD_PATH"
    order      = "ORDER"
  }

  // Optional
  multikey = true
  density  = "DENSITY"
}

다음을 바꿉니다.

  • DATABASE_ID: 선택한 데이터베이스의 데이터베이스 ID
  • COLLECTION: 색인을 생성할 컬렉션의 이름
  • FIELD_PATH: 색인을 생성할 필드의 이름
  • ORDER: ASCENDING 또는 DESCENDING 중 하나
  • DENSITY: SPARSE_ANY 또는 DENSE 중 하나

텍스트 색인 만들기

컬렉션 내에서 특정 문자열에 대한 텍스트 검색을 실행하려면 텍스트 색인을 만드세요.

컬렉션의 텍스트 색인을 만들려면 다음 단계를 완료하세요.

MongoDB API

createIndex() 메서드를 사용하여 텍스트 색인을 만듭니다. 다음 예에서 country 또는 food 필드가 채워진 상태로 문서가 cities 컬렉션에 작성되면 이러한 필드는 검색 목적으로 색인이 생성됩니다.

db.cities.createIndex({"country": "text", "food": "text"})

필드는 색인화하려면 문자열 또는 문자열 배열이어야 합니다. 배열 색인은 검색 색인이 생성되지 않습니다. 따라서 a.1.b를 색인 생성하면 {a: {1: {b: something}}}에는 something가 색인 생성되지만 {a: [one, {b: something}]}에는 색인 생성되지 않습니다.

db.runCommand()로 색인을 만들 수도 있습니다. 컬렉션당 하나의 텍스트 색인만 있을 수 있지만 하나의 db.runCommand()에 여러 유형의 색인을 만들 수 있습니다. 다음 예에서는 db.runCommand()를 사용하여 텍스트 색인을 만듭니다.

db.runCommand({
  createIndexes: "cities",
  indexes: [
    {
      key: { "country": "text", "food": "text" },
      name: "country_text_food_text"
    }
  ]
})

기본 언어 지정

기본 언어 또는 기본 언어를 포함할 문서의 필드 경로를 선택적으로 지정할 수도 있습니다.

다음 예시에서는 myLanguageField이 language_override로 지정되었습니다. cities 컬렉션의 문서에 myLanguageField이라는 필드가 포함된 경우 해당 필드의 값은 특정 문서의 country 필드 색인 생성을 위한 언어를 결정하는 데 사용됩니다. 이 값은 french의 기본 언어를 재정의합니다.

db.cities.createIndex({"country": "text"}, {"default_language": "french", "language_override": "myLanguageField"})
  • 언어는 긴 형식 이름 (english) 또는 두 글자 ISO 언어 코드 (en)로 입력할 수 있습니다.
  • 기본 언어를 설정하지 않으면 Firestore는 기본적으로 영어로 설정됩니다.
  • 언어 재정의 필드는 최상위 필드여야 합니다. 설정하지 않으면 언어 재정의 필드의 기본값은 language입니다.
  • 기본 언어를 null 문자로 설정하면 MongoDB 호환성을 갖춘 Firestore는 필드를 언어 재정의로 사용하지 않습니다.

지원되는 언어 목록을 보려면 펼치세요.

언어 코드 언어 이름
"und" 자동 감지
'af' 아프리칸스어
'ak' 아칸어
'sq' 알바니아어
'am' 암하라어
"ar" 아랍어
'안녕' 아르메니아어
"az" 아제르바이잔어
'eu' 바스크어
'be' 벨라루스어
'bn' 벵골어
'bs' 보스니아어
"bg" 불가리아어
'my' 버마어
'ca' 카탈로니아어
"ceb" 세부아노어
'chr' 체로키어
"zh" 중국어
'zh-Hant' Chinese_Traditional
'hr' 크로아티아어
"cs" 체코
"da" 덴마크어
"nl" 네덜란드어
'en' 영어
"eo" 에스페란토어
'et' 에스토니아어
'fil' 필리핀어
'fi' 핀란드어
'fr' 프랑스어
'gl' 갈리시아어
'ka' 조지아어
'de' 독일어
'el' 그리스어
'gu' 구자라트어
'ht' Haitian_Creole
'ha' 하우사어
'haw' 하와이어
'iw' 히브리어
'안녕' 힌디어
'hmn' 몽어
'hu' 헝가리어
'is' 아이슬란드어
'ig' 이그보어
'id' 인도네시아어
'ga' 아일랜드어
"it" 이탈리아어
'ja' 일본어
'jv' 자바어
'kn' 칸나다어
"kk" 카자흐어
'km' 크메르어
'ko' 한국어
"lo" 라오어
"la" 라틴어
"lv" 라트비아어
"lt" 리투아니아어
'lb' 룩셈부르크어
'mk' 마케도니아어
'mg' 마다가스카르어
'ms' 말레이어
'ml' 말라얄람어
'mt' 몰타어
'mi' 마오리어
"mr" 마라타어
'mfe' 모리시엔어
'mn' 몽골어
'sr-ME' Serbian_Montenegro
'ne' 네팔어
'아니요' 노르웨이어
"ny" 니안자어
'또는' 오리야어
'fa' 페르시아어
'pl' 폴란드어
'pt-BR' Portuguese_Brazil
'pt-PT' Portuguese_Portugal
'pa' 펀자브어
'ro' 루마니아어
'ru' 러시아어
'gd' 스코틀랜드 게일어
'sr' 세르비아어
'st' 소토어(남부)
'si' 싱할라어
"sk" 슬로바키아어
'sl' 슬로베니아어
'so' 소말리어
"es" 스페인어
"su" 순다어
'sw' 스와힐리어
"sv" 스웨덴어
'tg' 타지크어
"ta" 타밀어
'te' 텔루구어
'th' 태국어
'tr' 터키어
'uk' 우크라이나어
'ur' 우르두어
'uz' 우즈베크어
"vi" 베트남어
"cy" 웨일즈어
"yi" 이디시어
"yo" 요루바어
'zu' 줄루어

텍스트 색인 파티셔닝

필드를 사용하여 색인을 파티셔닝하여 특정 필드 값으로 쿼리를 필터링할 수도 있습니다. 이 구성을 사용하면 항상 쿼리하는 색인에서 필터를 적용한 특정 필드가 필요한 경우 성능이 더 우수한 쿼리를 실행할 수 있습니다.

파티션이 있는 색인을 만들려면 firestoreOptions 필드를 다음과 같이 구성합니다.

db.runCommand({
  createIndexes: "cities",
  indexes: [
    {
      key: { "country": "text", "food": "text"},
      name: "country_text_food_text"
      firestoreOptions: {"customPartitionFields": ["PARTITIONED_FIELD"]
    }
  ]
})

각 항목의 의미는 다음과 같습니다.

  • PARTITIONED_FIELD은 파티션에 사용되는 필드의 이름입니다. 이 값은 문자열이어야 하며 최상위 필드를 참조해야 합니다. 파티셔닝된 색인에 대해 쿼리를 실행할 때 이 필드의 값을 기준으로 결과를 필터링할 수 있습니다. 예를 들어 city를 사용하여 색인을 파티셔닝할 수 있습니다. 텍스트 색인에 city 필드가 정의되어 있으면 사용자가 특정 도시에 대해 쿼리할 수 있습니다.

    파티션은 하나의 필드여야 합니다. 색인을 파티셔닝하면 파티셔닝된 필드가 지정된 쿼리만 실행할 수 있습니다.

제한사항

  • 요청당 하나의 색인만 만들 수 있습니다.
  • MongoDB API를 사용한 색인 생성의 감사 로그는 google.firestore.admin.v1.FirestoreAdmin.CreateIndex라는 메서드 이름을 사용합니다.
  • 지원되는 색인 옵션은 색인 및 색인 속성을 참고하세요.

Google Cloud 콘솔

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

    데이터베이스로 이동

  2. 데이터베이스 목록에서 데이터베이스를 선택합니다.

  3. 탐색 메뉴에서 색인을 클릭합니다.

  4. 색인 만들기를 클릭한 다음 검색 색인 만들기를 클릭합니다.

  5. (선택사항) 색인 이름을 입력합니다.

  6. 검색 유형으로 이동하여 텍스트를 선택합니다.

  7. 컬렉션 ID를 입력합니다.

  8. 필드 경로를 하나 이상 입력합니다.

  9. 선택사항: 기본 언어를 지정합니다.

    예를 들어 언어 재정의 경로를 myLanguageField로 설정합니다. 컬렉션의 문서에 myLanguageField라는 필드가 포함된 경우 해당 필드의 값은 색인 내에 정의된 필드의 색인 생성을 위한 언어를 결정하는 데 사용됩니다. 이 값은 색인의 기본 언어를 재정의합니다.

  10. 만들기를 클릭합니다.

  11. 새 색인이 색인 목록에 표시되고 MongoDB 호환 작업에서 색인 생성을 시작합니다. 색인이 생성되면 색인 옆에 녹색 체크표시가 나타납니다. 색인이 생성되지 않으면 색인 빌드 오류에서 가능한 원인을 확인하세요.

2dsphere 색인 만들기

2dsphere 색인을 만들어 지리 공간 쿼리를 실행하고 특정 경도와 위도에서 특정 범위 내에 있는 문서를 검색합니다.

컬렉션의 2dsphere 색인을 만들려면 다음 단계를 완료하세요.

MongoDB API

createIndex() 메서드를 사용하여 색인을 만듭니다. 예를 들면 다음과 같습니다.

db.restaurants.createIndex({"location" : "2dsphere", "region": "2dsphere"})

db.runCommand()를 사용한 색인 생성도 최대 하나의 색인으로 지원됩니다.

db.runCommand({
  createIndexes: "restaurants",
  indexes: [
    {
      key: { "location": "2dsphere", "region": "2dsphere" },
      name: "location_2dsphere_region_2dsphere"
    }
  ]
})

2dsphere 색션 분할

필드를 사용하여 색인을 파티셔닝하여 특정 필드 값으로 쿼리를 필터링할 수도 있습니다. 이 구성을 사용하면 항상 쿼리하는 색인에서 필터를 적용한 특정 필드가 필요한 경우 성능이 더 우수한 쿼리를 실행할 수 있습니다.

파티션이 있는 색인을 만들려면 firestoreOptions 필드를 다음과 같이 구성합니다.

db.runCommand({
  createIndexes: "restaurants",
  indexes: [
    {
      key: { "location": "2dsphere", "region": "2dsphere" },
      name: "location_2dsphere_region_2dsphere"
      firestoreOptions: {"customPartitionFields": ["PARTITIONED_FIELD"]
    }
  ]
})

각 항목의 의미는 다음과 같습니다.

  • PARTITIONED_FIELD은 파티션에 사용되는 필드의 이름입니다. 파티셔닝된 색인에 대해 쿼리를 실행할 때 이 필드의 값을 기준으로 결과를 필터링할 수 있습니다. 예를 들어 색인에 지역 위치를 나타내는 region 필드가 있는 경우 사용자가 자신의 지역에 있는 음식점을 쿼리할 수 있도록 region를 사용하여 색인을 파티셔닝할 수 있습니다.

    색인을 파티셔닝하면 파티셔닝된 필드가 지정된 쿼리만 실행할 수 있습니다.

제한사항

  • 요청당 하나의 색인만 만들 수 있습니다.
  • MongoDB API를 사용한 색인 생성의 감사 로그는 google.firestore.admin.v1.FirestoreAdmin.CreateIndex라는 메서드 이름을 사용합니다.
  • 지원되는 색인 옵션은 색인 및 색인 속성을 참고하세요.

Google Cloud 콘솔

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

    데이터베이스로 이동

  2. 데이터베이스 목록에서 데이터베이스를 선택합니다.

  3. 탐색 메뉴에서 색인을 클릭합니다.

  4. 색인 만들기를 클릭한 다음 검색 색인 만들기를 클릭합니다.

  5. 컬렉션 ID를 입력합니다.

  6. 검색 유형으로 이동하여 지역 (2dsphere)을 선택합니다.

  7. 만들기를 클릭합니다.

  8. 새 색인이 색인 목록에 표시되고 MongoDB 호환 작업에서 색인 생성을 시작합니다. 색인이 생성되면 색인 옆에 녹색 체크표시가 나타납니다. 색인이 생성되지 않으면 색인 빌드 오류에서 가능한 원인을 확인하세요.

색인 삭제

색인을 삭제하려면 다음 단계를 완료하세요.

MongoDB API

dropIndex() 메서드를 사용하여 색인을 삭제합니다. 예를 들면 다음과 같습니다.

색인 이름을 사용하여 색인 삭제

db.restaurants.dropIndex("cuisine_index")

색인 정의를 사용하여 색인 삭제

db.restaurants.dropIndex({"cuisine" : 1})
Google Cloud 콘솔

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

    데이터베이스로 이동

  2. 데이터베이스 목록에서 데이터베이스를 선택합니다.
  3. 탐색 메뉴에서 색인을 클릭합니다.
  4. 색인 목록에서 삭제할 색인의 더보기 버튼 에서 삭제를 선택합니다.
  5. 색인 삭제를 클릭합니다.
gcloud CLI

  1. 색인 이름을 찾으려면 gcloud firestore indexes composite list 명령어를 사용합니다.

    gcloud firestore indexes composite list \
--database='DATABASE_ID'

    DATABASE_ID를 데이터베이스 ID로 바꿉니다.

  2. 색인을 삭제하려면 gcloud firestore indexes composite delete 명령어를 사용합니다.

    gcloud firestore indexes composite delete INDEX_NAME \
--database='DATABASE_ID'

    다음을 바꿉니다.

    • INDEX_NAME: 색인 이름
    • DATABASE_ID: 데이터베이스 ID

색인 빌드 시간

색인을 빌드하려면 MongoDB 호환성을 갖춘 Firestore가 색인을 만든 다음 색인 항목을 기존 데이터로 백필해야 합니다. 색인을 만드는 데 필요한 시간은 다음에 따라 결정됩니다.

  • 색인의 최소 빌드 시간은 비어 있는 데이터베이스인 경우에도 몇 분 정도 걸립니다.

  • 색인 항목을 백필하는 데 필요한 시간은 새 색인에 속하는 기존 데이터의 양에 따라 다릅니다. 색인 정의와 일치하는 필드 값이 많을수록 색인 항목을 백필하는 데 시간이 오래 걸립니다.

장기 실행 작업 관리

색인 빌드는 장기 실행 작업입니다. 다음 섹션에서는 색인의 장기 실행 작업을 사용하는 방법을 설명합니다.

색인 생성을 시작하면 MongoDB 호환성을 갖춘 Firestore에서 작업에 고유한 이름을 할당합니다. 작업 이름은 다음 예시와 같이 projects/PROJECT_ID/databases/DATABASE_ID/operations/로 시작합니다.

projects/PROJECT_ID/databases/DATABASE_ID/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

describe 명령어에 작업 이름을 지정할 때 프리픽스는 제외할 수 있습니다.

모든 장기 실행 작업 나열

장기 실행 작업을 나열하려면 gcloud firestore 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 필드가 설정되지 않으면 작업이 완료되지 않은 것입니다.