Enterprise 버전 색인 개요

색인 생성 동작은 데이터베이스 버전에 따라 다릅니다. 이 페이지에서는 Firestore Enterprise 버전의 색인 생성을 설명합니다. Firestore Standard 버전의 경우 Firestore Standard 버전 색인 개요를 참고하세요.

이 섹션에서는 Firestore Enterprise 버전의 색인 생성을 설명합니다. Firestore Enterprise 버전은 기본적으로 색인을 생성하지 않습니다. 비용을 절감하고 데이터베이스 성능을 개선하려면 가장 자주 사용되는 쿼리에 대한 색인을 만드세요.

색인은 데이터베이스 성능에 큰 영향을 미칩니다. 쿼리에 대한 색인이 있으면 데이터베이스는 스캔해야 하는 데이터 양을 줄이고 결과를 정렬하는 데 필요한 작업을 줄여 결과를 효율적으로 반환할 수 있습니다. 하지만 색인 항목은 스토리지 비용과 색인이 생성된 필드에 대한 쓰기 작업 중에 실행되는 작업량을 늘립니다.

색인 정의 및 구조

색인은 다음과 같이 구성됩니다.

  • 컬렉션 ID
  • 지정된 컬렉션의 필드 목록
  • 각 필드의 색인 모드(오름차순, 내림차순 또는 배열 포함)

색인은 희소 또는 고유 옵션을 사용 설정할 수도 있습니다.

색인 순서

각 필드의 순서와 정렬 방향은 색인을 고유하게 정의합니다. 예를 들어 다음 색인은 서로 다른 두 개의 색인이며 서로 바꿔 사용할 수 없습니다.

컬렉션 필드
cities 국가(오름차순), 인구(내림차순)
cities 인구(내림차순), 국가(오름차순)

쿼리를 지원하는 색인을 만들 때는 쿼리와 동일한 순서로 필드를 포함합니다.

색인 밀도

기본적으로 색인 항목은 컬렉션의 모든 문서에서 데이터를 저장합니다. 이를 비희소 색인이라고 합니다. 문서에 색인에 지정된 필드가 포함되어 있는지 여부와 관계없이 문서에 색인 항목이 추가됩니다. 존재하지 않는 필드는 색인 항목을 생성할 때 NULL 값을 갖는 것으로 처리됩니다. 이 동작을 변경하려면 색인을 희소 색인으로 정의하면 됩니다.

희소 색인

희소 색인은 색인이 생성된 필드 중 하나 이상에 값(null 포함)이 포함된 컬렉션의 문서만 색인을 생성합니다. 희소 색인은 스토리지 비용을 줄이고 성능을 향상시킬 수 있습니다.

배열에 포함 색인

array-contains 또는 array-contains-any를 사용하여 배열 필드를 쿼리할 때 쿼리 성능을 최적화하려면 array-contains 모드로 필드에 색인을 생성하면 됩니다. 색인에는 array-contains 모드의 필드가 최대 1개까지 포함될 수 있습니다.

array-contains 모드에서 배열 필드를 색싱하면 쿼리 엔진이 특정 배열 값이 포함된 문서를 빠르게 찾을 수 있습니다. 색인이 없으면 쿼리는 컬렉션의 전체 스캔을 수행하여 배열 값을 확인하므로 컬렉션 크기가 커짐에 따라 쿼리 지연 시간과 읽기 비용이 증가합니다.

배열 필드를 색인으로 지정하려면 필드가 다음 요구사항을 충족해야 합니다.

  • 비어 있지 않은 배열 요구사항: 색인 항목은 배열 필드가 문서에 있고 비어 있지 않은 배열인 경우에만 생성됩니다. 필드가 누락되었거나, 배열이 아니거나, 배열이 비어 있는 문서는 색인이 생성되지 않습니다.

밀도가 array-contains 색인과 관련되는 방식

array-contains 필드가 포함된 색인의 경우 색인 밀도 규칙은 정렬된 색인 필드에만 적용됩니다. 비어 있지 않은 배열 요구사항이 충족되면 색인의 나머지 정렬된 색인 필드에 밀도 규칙이 적용됩니다.

  • 희소하지 않은 색인 (DENSE): 문서에 대해 색인 항목이 생성됩니다. 색인에서 누락된 정렬된 색인 필드는 색인 항목에 null로 저장됩니다.
  • 희소 색인 (SPARSE): 순서가 지정된 색인이 생성된 필드 중 하나 이상이 문서에 있는 경우에만 색인 항목이 생성됩니다.

예: 색인 항목 생성

다음 색인 users (tags[*], status ASC)을 고려해 보겠습니다.

문서 NON-SPARSE 색인 SPARSE 색인
{
  tags: ["news"],
  status: "active"
}		 색인 생성됨:
• (태그: "news", 상태: "active")		 색인 생성됨:
• (태그: "news", 상태: "active")
{
  tags: ["news", "sports"],
  status: "active"
}		 색인 생성됨:
• (태그: "news", 상태: "active")
• (태그: "sports", 상태: "active")		 색인 생성됨:
• (태그: "news", 상태: "active")
• (태그: "sports", 상태: "active")
{
  tags: ["news", "news"],
  status: "active"
}		 색인 생성됨:
• (태그: "news", 상태: "active") (중복 삭제됨)		 색인 생성됨:
• (태그: "news", 상태: "active") (중복 제거됨)
{
  tags: [null],
  status: "active"
}		 색인 생성됨:
• (태그: null, 상태: "active")		 색인 생성됨:
• (태그: null, 상태: "active")
{
  tags: ["news"]
}		 색인 생성됨:
• (태그: "news", 상태: null)		 색인이 생성되지 않음 (status 필드 누락)
{
  tags: "news",
  status: "active"
}		 색인이 생성되지 않음 (필드가 배열이 아님) 색인이 생성되지 않음 (필드가 배열이 아님)
{
  tags: null,
  status: "active"
}		 색인이 생성되지 않음 (필드가 배열이 아님) 색인이 생성되지 않음 (필드가 배열이 아님)
{
  status: "active"
}		 색인이 생성되지 않음 (tags 필드 누락) 색인이 생성되지 않음 (tags 필드 누락)
{
  tags: [],
  status: "active"
}		 색인이 생성되지 않음 (빈 배열) 색인이 생성되지 않음 (빈 배열)

쿼리 예시

웹
// Query for users where 'tags' contains 'news' and 'status' is 'active'
const query = db.collection("users")
  .where("tags", "array-contains", "news")
  .where("status", "==", "active");

// Documents returned by the query:
// [
//   {
//     "id": "alice",
//     "tags": ["news", "tech"],
//     "status": "active"
//   }
// ]

고유 색인

색인이 생성된 필드에 고유한 값을 적용하도록 고유 색인 옵션을 설정합니다. 여러 필드의 색인의 경우 값의 각 조합이 색인에서 고유해야 합니다. 데이터베이스는 중복된 값이 있는 색인 항목을 만들려고 하는 업데이트 및 삽입 작업을 거부합니다. 색인이 생성된 필드의 데이터에 중복 값이 포함되어 있고 고유 색인을 만들려고 하면 작업 세부정보에 오류 메시지가 표시되면서 색인 빌드가 실패합니다.

고유 색인에 없는 필드

고유 색인의 필드가 누락된 문서를 삽입하면 색인은 누락된 필드에 null 값을 설정합니다. 결과 색인 항목은 고유해야 합니다. 그렇지 않으면 작업이 실패합니다.

예를 들어 다음 색인의 경우

컬렉션 색인이 지정된 필드 쿼리 범위
cities 이름(오름차순) 컬렉션

문서 {"abbreviation": "LA"}를 컬렉션에 추가하면 고유 색인에서 name이 null로 설정된 항목을 만듭니다. 그런 다음 문서 {"abbreviation": "NYC"}를 추가하려고 하면 고유 색인의 결과 항목이 동일하므로 작업이 실패합니다.

여러 필드가 있는 고유 색인에도 동일한 동작이 적용됩니다. 문서를 만들거나 업데이트할 때 색인이 생성된 필드가 누락되면 null로 설정되며 결과 색인 항목은 색인에서 고유해야 합니다.

배열 값의 고유 색인

고유한 array-contains 색인은 배열 요소가 중복되는 문서를 금지합니다.

이 유형의 색인은 단일 문서 내에서 배열에 고유한 값이 있는지 적용하지 않습니다.

예를 들어 tags 필드에 고유 색인이 있는 경우 다음과 같습니다.

다음 문서(doc1)는 삽입할 수 있습니다.

{
  "tags": [ "news", "tech", "news", "music" ]
}

색인은 단일 문서의 동일한 배열 내에서 중복 값 ("news")을 허용합니다.

중복 요소가 있는 두 번째 문서 doc2를 삽입하려고 하면 작업이 실패합니다.

{
  "tags": [ "sports", "music" ]
}

"music"가 이미 doc1의 배열에 있고 색인에 매핑되어 있으므로 작업이 실패합니다.

단일 문서의 동일한 배열 내 요소가 고유해야 하는 경우 애플리케이션 로직에서 이를 처리하세요.

빈 배열, 누락된 필드, null 값

일반적으로 고유 색인의 누락된 필드는 null로 처리되며 문서 간에 고유해야 합니다 (고유 색인에 없는 필드 참고). 하지만 배열 필드의 고유 색인의 경우 다음 사항에 유의하세요.

  • 빈 배열, 누락된 필드, 독립형 null: 배열 필드가 비어 있거나 완전히 누락되었거나 독립형 null 값을 보유하는 경우 (배열 내에 없음) 문서에 색인 키가 생성되지 않습니다. 따라서 여러 문서에 중복 키 오류를 트리거하지 않고 빈 필드 또는 독립형 null 값이 있을 수 있습니다.
  • 배열 내의 null 요소: 배열에 null 값이 요소로 포함된 경우 (예: ["news", null]) null 요소가 색인화됩니다. 색인이 생성된 배열 필드에 null 요소가 포함된 후속 문서는 중복 키 오류로 인해 실패합니다.

색인 빌드 오류 문제 해결

색인을 관리할 때 색인 빌드 오류가 발생할 수 있습니다. 데이터베이스에서 데이터 문제가 발생하면 색인 생성 작업이 실패할 수 있습니다. 다음과 같은 이유로 색인 작업이 실패할 수 있습니다.

  • 색인 한도에 도달했습니다. 예를 들어 작업이 문서당 최대 색인 항목 수에 도달했을 수 있습니다. 색인 생성이 실패하면 오류 메시지가 표시됩니다. 색인 한도에 도달하지 않은 경우 색인 작업을 다시 시도하세요.
  • 고유 색인 옵션을 설정하고 색인이 생성된 필드의 데이터가 중복 색인 항목을 생성합니다. 계속하려면 데이터에서 중복된 값 조합을 삭제하세요.