Cloud Firestore의 색인 유형

색인은 데이터베이스 성능에 중요한 요소입니다. 책에 포함된 여러 주제를 페이지 번호에 연결하는 도서 색인처럼 데이터베이스 색인은 데이터베이스의 항목을 데이터베이스의 항목 위치에 매핑합니다. 데이터베이스를 쿼리할 때 데이터베이스는 색인을 사용하여 요청한 항목의 위치를 빠르게 식별할 수 있습니다.

이 페이지에서는 Cloud Firestore에서 사용하는 두 가지 색인 유형인 단일 필드 색인과 복합 색인을 설명합니다.

색인 정의 및 구조

색인은 지정된 문서의 필드 목록에 각 필드의 해당 색인 모드와 함께 정의됩니다.

색인에는 색인 정의에 명명된 모든 필드의 항목이 포함되어 있습니다. 색인에는 해당 색인을 기반으로 한 쿼리의 잠재적인 결과가 될 수 있는 모든 문서가 포함됩니다. 색인에 사용되는 모든 필드에 색인이 생성된 값이 설정된 경우에만 문서가 색인에 포함됩니다. 색인 정의가 문서에 값이 설정되지 않은 필드를 참조하는 경우 해당 문서는 색인에 표시되지 않습니다. 이 경우 색인을 기반으로 하는 쿼리의 결과로 문서가 반환되지 않습니다.

복합 색인은 색인 정의에 지정된 순서에 따라 필드 값별로 정렬됩니다.

모든 쿼리에 색인 지원

쿼리에 색인이 없으면 대부분의 데이터베이스에서 항목별로 콘텐츠 항목을 크롤링하므로 데이터베이스가 커질수록 처리 속도가 느려집니다. Cloud Firestore는 모든 쿼리에 색인을 사용하므로 높은 쿼리 성능이 보장됩니다. 따라서 쿼리 성능은 데이터베이스의 항목 수가 아닌 결과 모음의 크기에 따라 달라집니다.

색인 관리 부담을 줄이고 앱 개발에 집중 가능

Cloud Firestore에는 색인 관리에 소비하는 시간을 줄여주는 기능이 포함되어 있습니다. 가장 기본적인 쿼리에 필요한 색인이 자동으로 생성됩니다. 앱을 사용하고 테스트할 때 Cloud Firestore를 사용하면 앱에 필요한 추가 색인을 식별하고 만들 수 있습니다.

색인 유형

Cloud Firestore에서는 두 가지 색인 유형인 단일 필드와 복합을 사용합니다. 색인이 지정된 필드 수 외에도 단일 필드 색인과 복합 색인은 관리하는 방법이 서로 다릅니다.

단일 필드 색인

단일 필드 색인은 특정 필드가 있는 컬렉션에 모든 문서가 정렬된 매핑을 저장합니다. 단일 필드 색인의 각 항목은 특정 필드의 문서 값 및 데이터베이스 내 해당 문서 위치를 기록합니다. Cloud Firestore는 이러한 색인을 사용하여 다양한 기본 쿼리를 수행합니다. 단일 필드 색인은 데이터베이스의 자동 색인 생성 설정 및 색인 예외를 구성하여 관리할 수 있습니다.

자동 색인 생성

Cloud Firestore는 기본적으로 문서의 각 필드와 맵의 각 하위 필드에 대한 단일 필드 색인을 자동으로 유지합니다. Cloud Firestore는 단일 필드 색인에 다음 기본 설정을 사용합니다.

• 배열과 맵이 아닌 필드의 경우 Cloud Firestore는 2개의 컬렉션 범위 단일 필드 색인을 하나는 오름차순 모드로, 다른 하나는 내림차순 모드로 정의합니다.

• 각 맵 필드에 대해 Cloud Firestore는 다음을 만듭니다.

  • 배열과 맵이 아닌 각 하위 필드에 대한 컬렉션 범위 오름차순 색인 1개.
  • 배열과 맵이 아닌 각 하위 필드에 대한 컬렉션 범위 내림차순 색인 1개.
  • 각 배열 하위 필드에 대한 컬렉션 범위 배열 포함 색인 1개.
  • Cloud Firestore는 각 맵 하위 필드에 대해 재귀적으로 색인을 만듭니다.

• 문서의 배열 필드마다 Cloud Firestore는 컬렉션 범위 배열 포함 색인을 만들고 유지합니다.

• 기본적으로 컬렉션 그룹 범위가 지정된 단일 필드 색인은 유지되지 않습니다.

단일 필드 색인 예외

단일 필드 색인 예외를 만들면 자동 색인 생성 설정에서 특정 필드를 제외할 수 있습니다. 색인 생성 예외는 데이터베이스 전체의 자동 색인 설정을 재정의합니다. 예외는 달리 설정하지 않았을 경우 자동 색인 생성 설정을 중지한 단일 필드 색인을 사용 설정하거나 자동 색인 생성 설정을 사용 설정한 단일 필드 색인을 중지합니다. 예외를 유용하게 활용할 수 있는 경우를 확인하려면 색인 생성 권장사항을 참조하세요.

* 필드 경로 값을 사용하여 컬렉션 그룹의 모든 필드에 컬렉션 수준 색인 예외를 추가합니다. 예를 들어 컬렉션 그룹 comments의 경우 comments 컬렉션 그룹의 모든 필드와 일치하도록 필드 경로를 *로 설정하고 컬렉션 그룹에 속한 모든 필드의 색인 생성을 중지합니다. 그런 다음 예외를 추가하여 쿼리에 필요한 필드에 대해서만 색인을 생성할 수 있습니다. 색인이 생성된 필드 수를 줄이면 스토리지 비용이 줄어들고 쓰기 성능이 향상될 수 있습니다.

맵 필드에 단일 필드 색인 예외를 만들면 맵의 하위 필드에서 해당 설정을 상속합니다. 그러나 특정 하위 필드에 대한 단일 필드 색인 예외를 정의할 수 있습니다. 하위 필드의 예외를 삭제하면 하위 필드가 상위 필드의 예외 설정(상위 필드 예외가 있는 경우) 또는 데이터베이스 전체 설정(상위 필드 예외가 없는 경우)을 상속합니다.

단일 필드 색인 예외를 만들고 관리하려면 색인 관리를 참조하세요.

복합 색인

복합 색인은 색인 생성 순서가 지정된 필드 목록에 따라 모든 문서의 정렬된 매핑을 컬렉션에 저장합니다.

Cloud Firestore는 복합 색인을 사용하여 단일 필드 색인에서 아직 지원하지 않는 쿼리를 지원합니다.

가능한 필드 조합 수가 많기 때문에, Cloud Firestore에서는 단일 필드 색인과는 달리 복합 색인을 자동으로 만들지 않습니다. 대신 Cloud Firestore를 통해 앱을 빌드할 때 필요한 복합 색인을 식별하고 만들 수 있습니다.

색인에서 지원하지 않는 쿼리를 시도할 때마다 Cloud Firestore는 누락된 색인을 생성할 수 있는 링크가 포함된 오류 메시지를 반환합니다.

또한 Console이나 Firebase CLI를 사용하여 직접 복합 색인을 정의하고 관리할 수 있습니다. 복합 색인 생성 및 관리에 대한 자세한 내용은 색인 관리를 참조하세요.

색인 모드 및 쿼리 범위

단일 필드 색인 및 복합 색인을 구성하는 방법은 각각 다르지만 두 색인 모두 색인 모드와 쿼리 범위를 구성해야 합니다.

색인 모드

색인을 정의할 때 색인이 생성되는 각 필드의 색인 모드를 선택합니다. 각 필드의 색인 모드는 해당 필드의 특정 쿼리 절을 지원합니다. 색인 모드는 다음 중에서 선택할 수 있습니다.

쿼리 범위

각 색인의 범위는 컬렉션 또는 컬렉션 그룹 중 하나로 지정됩니다. 이 범위를 색인의 쿼리 범위라고 합니다.

컬렉션 범위

Cloud Firestore는 기본적으로 색인을 만들 때 컬렉션 범위를 지정합니다. 이러한 색인은 단일 컬렉션의 결과를 반환하는 쿼리를 지원합니다.

컬렉션 그룹 범위

컬렉션 그룹은 컬렉션 ID가 동일한 모든 컬렉션으로 구성됩니다. 컬렉션 그룹에서 필터링된 결과나 순서가 지정된 결과를 반환하는 컬렉션 그룹 쿼리를 실행하려면 컬렉션 그룹 범위에 해당하는 색인을 만들어야 합니다.

기본 순서 지정 및 __name__ 필드

색인은 각 필드에 지정된 색인 모드(오름차순 또는 내림차순)로 문서를 정렬할 뿐만 아니라 각 문서의 __name__ 필드를 기준으로 최종 정렬을 적용합니다. __name__ 필드의 값은 전체 문서 경로로 설정됩니다. 즉, 동일한 필드 값을 가진 결과 세트의 문서는 문서 경로를 기준으로 정렬됩니다.

기본적으로 __name__ 필드는 색인 정의에서 마지막으로 정렬된 필드와 같은 방향으로 정렬됩니다. 예를 들면 다음과 같습니다.

기본이 아닌 __name__ 방향으로 결과를 정렬하려면 해당 색인을 만들어야 합니다.

색인 속성

쿼리를 가장 효율적으로 실행할 수 있는 색인은 다음 속성으로 정의됩니다.

• 일치 필터에 사용되는 필드
• 정렬 순서에 사용되는 필드
• 범위 및 불일치 필터에 사용되는 필드(정렬 순서에 아직 포함되지 않음)
• 집계에 사용되는 필드(정렬 순서와 범위 및 불일치 필터에 아직 포함되지 않음)

Cloud Firestore는 다음과 같이 쿼리의 결과를 계산합니다.

1. 쿼리의 컬렉션, 필터 속성, 필터 연산자, 정렬 순서에 해당하는 색인을 식별합니다.
2. 스캔이 시작되는 색인 위치를 식별합니다. 시작 위치에는 쿼리의 일치 필터가 접두사로 붙고 첫 번째 orderBy 필드의 범위 및 비균등 필터로 끝납니다.
3. 색인 스캔을 시작하여 스캔 프로세스가 다음 중 하나를 수행할 때까지 모든 필터를 충족하는 각 문서를 반환합니다.
   • 필터 조건을 충족하지 않는 문서를 발견하고 후속 문서가 필터 조건을 완전히 충족하지 않을 것임을 확인합니다.
   • 색인 끝에 도달합니다.
   • 쿼리에서 요청한 최대 개수의 결과를 수집합니다.

색인 생성 예시

Cloud Firestore가 단일 필드 색인을 자동으로 만들기 때문에 애플리케이션에서 가장 기본적인 데이터베이스 쿼리를 신속하게 지원할 수 있습니다. 단일 필드 색인을 사용하면 필드 값과 비교 연산자(<, <=, ==, >=, >, in)를 기반으로 간단한 쿼리를 수행할 수 있습니다. 배열 필드에서는 array-contains 및 array-contains-any 쿼리를 수행할 수 있습니다.

자세히 알아보기 위해 다음 예시를 색인 생성의 관점에서 살펴보겠습니다. 다음 스니펫은 cities 컬렉션에 city 문서를 여러 개 만들고 각 문서에 name, state, country, capital, population, tags 필드를 설정합니다.

var citiesRef = db.collection("cities");

citiesRef.doc("SF").set({
    name: "San Francisco", state: "CA", country: "USA",
    capital: false, population: 860000,
    regions: ["west_coast", "norcal"] });
citiesRef.doc("LA").set({
    name: "Los Angeles", state: "CA", country: "USA",
    capital: false, population: 3900000,
    regions: ["west_coast", "socal"] });
citiesRef.doc("DC").set({
    name: "Washington, D.C.", state: null, country: "USA",
    capital: true, population: 680000,
    regions: ["east_coast"] });
citiesRef.doc("TOK").set({
    name: "Tokyo", state: null, country: "Japan",
    capital: true, population: 9000000,
    regions: ["kanto", "honshu"] });
citiesRef.doc("BJ").set({
    name: "Beijing", state: null, country: "China",
    capital: true, population: 21500000,
    regions: ["jingjinji", "hebei"] });
test.firestore.js

자동 색인 생성의 기본 설정을 가정할 때 Cloud Firestore는 배열이 아닌 필드에 오름차순 단일 필드 색인 1개, 배열이 아닌 필드에 내림차순 단일 필드 색인 1개, 배열 필드에 배열 포함 단일 필드 색인 1개를 업데이트합니다. 다음 테이블의 각 행은 단일 필드 색인의 항목을 나타냅니다.

단일 필드 색인에서 지원하는 쿼리

자동으로 생성된 단일 필드 색인을 사용하여 다음과 같은 간단한 쿼리를 실행할 수 있습니다.

const stateQuery = citiesRef.where("state", "==", "CA");
const populationQuery = citiesRef.where("population", "<", 100000);
const nameQuery = citiesRef.where("name", ">=", "San Francisco");
test.firestore.js

in 및 복합 일치(==) 쿼리를 만들 수도 있습니다.

citiesRef.where('country', 'in', ["USA", "Japan", "China"])

// Compound equality queries
citiesRef.where("state", "==", "CO").where("name", "==", "Denver")
citiesRef.where("country", "==", "USA")
         .where("capital", "==", false)
         .where("state", "==", "CA")
         .where("population", "==", 860000)

범위 비교(<, <=, >, >=)를 사용하는 복합 쿼리를 실행해야 하거나 다른 필드로 정렬해야 하는 경우에는 해당 쿼리에 대한 복합 색인을 만들어야 합니다.

array-contains 색인을 사용하면 다음과 같이 regions 배열 필드를 쿼리할 수 있습니다.

citiesRef.where("regions", "array-contains", "west_coast")
// array-contains-any and array-contains use the same indexes
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])

복합 색인에서 지원하는 쿼리

Cloud Firestore는 복합 색인을 사용하여 단일 필드 색인에서 아직 지원하지 않는 복합 쿼리를 지원합니다. 예를 들어 다음 쿼리의 경우 복합 색인이 필요합니다.

citiesRef.where("country", "==", "USA").orderBy("population", "asc")
citiesRef.where("country", "==", "USA").where("population", "<", 3800000)
citiesRef.where("country", "==", "USA").where("population", ">", 690000)
// in and == clauses use the same index
citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)

이러한 쿼리에 아래의 복합 색인이 필요합니다. 이 쿼리는 country 필드에 등호(== 또는 in)를 사용하므로 이 필드에 오름차순 또는 내림차순 색인 모드를 사용할 수 있습니다. 기본적으로 불일치 절은 불일치 절의 필드를 기준으로 오름차순 정렬을 적용합니다.

동일한 쿼리를 내림차순으로 정렬하여 실행하려면 population에 대한 내림차순으로 추가 복합 색인이 있어야 합니다.

citiesRef.where("country", "==", "USA").orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", "<", 3800000)
         .orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", ">", 690000)
         .orderBy("population", "desc")

citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)
         .orderBy("population", "desc")

색인 병합으로 인한 성능 저하를 방지하려면 복합 색인을 만들어 array-contains 또는 array-contains-any 쿼리를 추가 절과 결합하는 것이 좋습니다.

citiesRef.where("regions", "array-contains", "east_coast")
         .where("capital", "==", true)

// array-contains-any and array-contains use the same index
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])
         .where("capital", "==", true)

컬렉션 그룹 색인에서 지원하는 쿼리

컬렉션 그룹 범위가 지정된 색인에 대해 알아보기 위해 landmarks 하위 컬렉션을 city 문서 중 일부에 추가합니다.

var citiesRef = db.collection("cities");

citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Bridge",
    category : "bridge" });
citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Park",
    category : "park" });

citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Gallery of Art",
    category : "museum" });
citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Mall",
    category : "park" });

컬렉션 범위가 있는 다음 단일 필드 색인을 사용하면 category 필드를 기준으로 단일 도시의 landmarks 컬렉션을 쿼리할 수 있습니다.

citiesRef.doc("SF").collection("landmarks").where("category", "==", "park")
citiesRef.doc("SF").collection("landmarks").where("category", "in", ["park", "museum"])

예를 들어 모든 도시의 랜드마크를 쿼리하려는 경우모든 landmarks 컬렉션으로 구성된 컬렉션 그룹에서 이 쿼리를 실행합니다. 또한 컬렉션 그룹 범위가 지정된 landmarks 단일 필드 색인을 사용 설정해야 합니다.

이 색인을 사용 설정한 상태에서 landmarks 컬렉션 그룹을 쿼리할 수 있습니다.

var landmarksGroupRef = db.collectionGroup("landmarks");

landmarksGroupRef.where("category", "==", "park")
landmarksGroupRef.where("category", "in", ["park", "museum"])

필터링 결과나 순서가 지정된 결과를 반환하는 컬렉션 그룹 쿼리를 실행하려면 컬렉션 그룹 범위에 해당하는 단일 필드 색인 또는 복합 색인을 생성해야 합니다. 하지만 결과를 필터링하거나 순서를 지정하지 않는 컬렉션 그룹 쿼리에는 추가로 색인을 정의할 필요가 없습니다.

예를 들어 추가 색인 없이 다음 컬렉션 그룹 쿼리를 실행할 수 있습니다.

db.collectionGroup("landmarks").get()

색인 항목

프로젝트의 구성된 색인과 문서 구조에 따라 문서의 색인 항목 수가 결정됩니다. 색인 항목 수는 색인 항목 수 한도에 반영됩니다.

다음 예시에서는 문서의 색인 항목을 보여줍니다.

문서

/cities/SF

city_name : "San Francisco"
temperatures : {summer: 67, winter: 55}
neighborhoods : ["Mission", "Downtown", "Marina"]

단일 필드 색인

• city_name ASC
• city_name DESC
• temperatures.summer ASC
• temperatures.summer DESC
• temperatures.winter ASC
• temperatures.winter DESC
• neighborhoods Array Contains(ASC 및 DESC)

복합 색인

• city_name ASC, neighborhoods ARRAY
• city_name DESC, neighborhoods ARRAY

색인 항목

이 색인 구성은 문서에 다음 색인 항목 12개를 생성합니다.

색인 및 가격 책정

색인 비용은 애플리케이션의 스토리지 비용에 추가됩니다. 색인의 스토리지 크기를 계산하는 방법에 대한 자세한 내용은 색인 항목 크기를 참조하세요.

색인 병합 사용

Cloud Firestore는 모든 쿼리에 색인을 사용하지만, 쿼리당 하나의 색인이 필요한 것은 아닙니다. 일치(==) 절 여러 개와 orderBy 절(선택사항)이 있는 쿼리의 경우 Cloud Firestore는 기존 색인을 재사용할 수 있습니다. Cloud Firestore는 간단한 일치 필터용 색인을 병합하여 크기가 큰 일치 쿼리에 필요한 복합 색인을 빌드할 수 있습니다.

색인 병합을 사용할 수 있는 상황을 파악하면 색인 비용을 줄일 수 있습니다. 예를 들어 레스토랑 별점 앱의 restaurants 컬렉션을 가정해서 설명해 보겠습니다.

• collections_bookmark restaurants

  • class burgerthyme

    name : "Burger Thyme"
category : "burgers"
city : "San Francisco"
editors_pick : true
star_rating : 4
    

이 앱은 다음과 같은 쿼리를 사용합니다. 앱이 category, city, editors_pick에 일치 절의 조합을 사용하지만 항상 오름차순 star_rating으로 정렬합니다.

db.collection("restaurants").where("category", "==", "burgers")
                            .orderBy("star_rating")

db.collection("restaurants").where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==" "San Francisco")
                            .where("editors_pick", "==", true )
                            .orderBy("star_rating")

각 쿼리에 대한 색인을 만들 수 있습니다.

Cloud Firestore의 일치 절 색인 병합 기능을 활용하여 색인 수를 줄이는 게 보다 나은 방법이 될 수 있습니다.

색인 모음의 크기가 더 작을 뿐만 아니라 추가 쿼리도 지원합니다.

db.collection("restaurants").where("editors_pick", "==", true)
                            .orderBy("star_rating")

색인 생성 한도

색인에 대한 한도는 다음과 같습니다. 할당량 및 한도에 대한 자세한 내용은 할당량 및 한도를 참조하세요.

색인 생성 권장사항

대부분의 앱에서는 자동 색인 생성 및 오류 메시지 링크를 사용하여 색인을 관리할 수 있습니다. 하지만 다음과 같은 경우에는 단일 필드 예외를 추가할 수 있습니다.

여러 필드에서 범위 및 불일치 연산자가 있는 쿼리를 사용하는 경우 Cloud Firestore 쿼리의 성능 및 비용을 최적화하기 위해 고려해야 하는 색인 생성 고려사항을 참조하세요.

색인 생성 문제(색인 팬아웃, INVALID_ARGUMENT 오류)를 해결하는 방법에 대한 자세한 내용은 문제 해결 페이지를 참조하세요.