Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas Search
/
쿼리 생성 및 실행
/
쿼리 생성
/
2. 연산자 및 수집기 사용

facet

이 페이지의 내용

  • 호환성
  • 정의
  • 구문
  • 필드
  • 패싯 정의
  • 문자열 패싯
  • 숫자 패싯
  • 날짜 패싯
  • 패싯 결과
  • SEARCH_META 집계 변수
  • 제한 사항
  • 예시

호환성

facet 은 다음 버전 중 하나를 실행하는 Atlas 클러스터에서만 사용할 수 있습니다.

  • MongoDB 5.0.4+

  • MongoDB 6.0+

  • MongoDB 7.0+

    참고

    샤딩된 컬렉션에 대해 패싯 쿼리를 실행하려면 클러스터에서 MongoDB v6.0 이상을 실행해야 합니다.

explain을 사용하여 facet 쿼리를 실행할 수 없습니다.

정의

facet

facet 수집기는 지정된 패싯 필드의 값 또는 범위별로 결과를 그룹화하고 해당 그룹 각각의 개수를 반환합니다.

facet을 $search와 $searchMeta 단계 모두에 사용할 수 있습니다. MongoDB는 facet을 $searchMeta 단계와 함께 사용하여 쿼리에 대한 메타데이터 결과만 검색할 것을 권장합니다. $search 단계를 사용하여 메타데이터 결과 및 쿼리 결과를 조회하려면 $$SEARCH_META 집계 변수를 사용해야 합니다. 자세한 내용은 SEARCH_META 집계 변수를 참조하세요.

구문

facet 의 구문은 다음과 같습니다:

{
  "$searchMeta"|"$search": {
    "index": <index name>, // optional, defaults to "default"
    "facet": {
      "operator": {
        <operator-specifications>
      },
      "facets": {
        <facet-definitions>
      }
    }
  }
}

필드

필드
유형
필수 사항입니다.
설명
facets
문서
네
각 패싯의 데이터를 버킷에 넣기 위한 정보입니다. 패싯 정의는 하나 이상 지정해야 합니다.
operator
문서
no
패싯을 수행하는 데 사용하는 연산자 입니다. 이를 생략하면 Atlas Search가 컬렉션의 모든 문서에 대해 패싯을 수행합니다.

패싯 정의

패싯 정의 문서는 패싯 이름과 패싯 유형에 특정한 옵션을 포함하고 있습니다. Atlas Search는 다음 유형의 패싯을 지원합니다:

문자열 패싯

문자열 패싯을 사용하면 지정된 문자열 필드에서 가장 빈번한 문자열 값을 기준으로 Atlas Search 결과의 범위를 좁힐 수 있습니다. 참고로 문자열 필드는 StringFacet으로 인덱싱되어야 합니다. 내장된 문서의 문자열 필드를 활용하려면 상위 필드도 문서 유형으로 인덱싱해야 합니다.

참고

포함된 문서 내의 문자열 필드에 패싯을 지정하면 Atlas Search에서 일치하는 상위 문서의 수에 대해서만 패싯 수를 반환합니다.

구문

문자열 패싯의 구문은 다음과 같습니다:

{
  "$searchMeta": {
    "facet":{
      "operator": {
        <operator-specification>
      },
      "facets": {
        "<facet-name>" : {
          "type" : "string",
          "path" : "<field-path>",
          "numBuckets" : <number-of-categories>,
        }
      }
    }
  }
}

옵션

옵션
유형
설명
필수 사항입니다.
numBuckets
int
결과에 반환할 패싯 카테고리의 최대 개수입니다. 값은 1000보다 작거나 같아야 합니다. 지정한 경우, 데이터가 요청된 수보다 적은 카테고리로 그룹화됐다면 Atlas Search는 요청된 것보다 적은 카테고리를 반환할 수 있습니다. 생략하면 기본값은 10 으로, Atlas Search는 개수 기준으로 상위 10 패싯 범주만 반환합니다.
no
path
문자열
패싯을 설정할 필드 경로입니다. stringFacet으로 인덱싱되는 필드를 지정할 수 있습니다.
네
type
문자열
패싯의 유형입니다. 값은 string이어야 합니다.
네

예시

예시

다음 예시에서는 sample_mflix.movies컬렉션의 default 인덱스를 사용합니다. 컬렉션의 genres 필드는 stringFacet 유형으로 인덱싱되고 year 필드는 숫자 유형으로 인덱싱됩니다.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "genres": {
        "type": "stringFacet"
      },
      "year": {
        "type": "number"
      }
    }
  }
}

이 쿼리는 $searchMeta 단계를 사용하여 movies 컬렉션의 year 필드에서 2000년부터 2015년까지의 영화를 검색하고 각 장르의 영화 수 개수를 검색합니다.

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "year",
            "gte": 2000,
            "lte": 2015
          }
        },
        "facets": {
          "genresFacet": {
            "type": "string",
            "path": "genres"
          }
        }
      }
    }
  }
])

이 쿼리는 다음과 같은 결과를 반환합니다:

[
  {
    count: { lowerBound: Long("13718") },
    facet: {
      genresFacet: {
        buckets: [
          { _id: 'Drama', count: Long("7759") },
          { _id: 'Comedy', count: Long("3937") },
          { _id: 'Romance', count: Long("1916") },
          { _id: 'Thriller', count: Long("1705") },
          { _id: 'Documentary', count: Long("1703") },
          { _id: 'Action', count: Long("1558") },
          { _id: 'Crime', count: Long("1475") },
          { _id: 'Adventure', count: Long("1111") },
          { _id: 'Horror', count: Long("1008") },
          { _id: 'Biography', count: Long("877") }
        ]
      }
    }
  }
]

이러한 결과에 대해 자세히 알아보려면 패싯 결과를 참조하세요.

숫자 패싯

숫자 패싯은 결과를 숫자의 별도 범위로 나누어 검색 결과 내의 숫자 값 빈도를 파악할 수 있게 합니다.

참고

제한 사항

내장된 문서의 숫자 필드에는 패싯을 사용할 수 없습니다.

구문

숫자 패싯의 구문은 다음과 같습니다:

{
  "$searchMeta": {
    "facet":{
      "operator": {
        <operator-specification>
      },
      "facets": {
        "<facet-name>" : {
          "type" : "number",
          "path" : "<field-path>",
          "boundaries" : <array-of-numbers>,
          "default": "<bucket-name>"
        }
      }
    }
  }
}

옵션

옵션
유형
설명
필수 사항입니다.
boundaries
숫자 배열

각 버킷의 경계를 지정하는 숫자 값의 오름차순 목록입니다. 경계를 두 개 이상 지정해야 합니다. 각 인접한 값 쌍은 버킷의 포괄적인 하한과 배타적인 상한으로 작용합니다. 다음 BSON 유형의 값을 원하는 대로 조합하여 지정할 수 있습니다:

  • 32비트 정수 (int32)

  • 64비트 정수 (int64)

  • 64비트 이진 부동 소수점(double)

네
default
문자열
지정된 경계에 속하지 않는 연산자로부터 반환된 문서를 계산하는 추가 버킷의 이름입니다. 이를 생략하면 Atlas Search는 지정된 버킷에 포함되지 않는 패싯 연산자의 결과도 포함하지만, 버킷 계산에는 포함하지 않습니다.
no
path
문자열
패싯을 설정할 필드 경로입니다. numberFacet 유형으로 인덱싱되는 필드를 지정할 수 있습니다.
네
type
문자열
패싯의 유형입니다. 값은 number이어야 합니다.
네

예시

예시

다음 예시에서는 sample_mflix.movies 컬렉션의 default 인덱스를 사용합니다. 컬렉션의 year 필드는 numberFacet 및 숫자 유형으로 인덱싱됩니다.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "year": [
        {
          "type": "numberFacet"
        },
        {
          "type": "number"
        }
      ]
    }
  }
}

이 쿼리는 $searchMeta 단계를 사용하여 movies 컬렉션의 year 필드에서 1980년부터 2000년 사이의 영화를 검색하고 쿼리에 대한 메타데이터 결과를 검색합니다. 쿼리는 3개의 버킷을 지정합니다.

  • 1980이 버킷에 대한 포괄적인 하한값

  • 19901980 버킷에 대한 배타적 상한과 이 버킷에 대한 포괄적 하한입니다.

  • 20001990 버킷에 대한 배타적 상한

이 쿼리는 또한 지정된 경계에 속하지 않는 쿼리 결과를 검색하기 위해 other이라는 이름의 default 버킷을 지정합니다.

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "year",
            "gte": 1980,
            "lte": 2000
          }
        },
        "facets": {
          "yearFacet": {
            "type": "number",
            "path": "year",
            "boundaries": [1980,1990,2000],
            "default": "other"
          }
        }
      }
    }
  }
])

이 쿼리는 다음과 같은 결과를 반환합니다:

[
  {
    count: { lowerBound: Long('6095') },
    facet: {
      yearFacet: {
        buckets: [
          { _id: 1980, count: Long('1956') },
          { _id: 1990, count: Long('3558') },
          { _id: 'other', count: Long('581') }
        ]
      }
    }
  }
]

이러한 결과에 대해 자세히 알아보려면 패싯 결과를 참조하세요.

날짜 패싯

날짜 패싯을 사용하면 날짜를 기준으로 검색 결과의 범위를 좁힐 수 있습니다.

참고

제한 사항

내장된 문서의 날짜 필드에는 패싯을 사용할 수 없습니다.

구문

날짜 패싯의 구문은 다음과 같습니다:

{
  "$searchMeta": {
    "facet":{
      "operator": {
        <operator-specification>
      },
      "facets": {
        "<facet-name>" : {
          "type" : "date",
          "path" : "<field-path>",
          "boundaries" : <array-of-dates>,
          "default": "<bucket-name>"
        }
      }
    }
  }
}

옵션

옵션
유형
설명
필수 사항입니다.
boundaries
숫자 배열

각 버킷의 경계를 지정하는 날짜 값 목록입니다. 다음을 지정해야 합니다:

  • 최소 두 개의 경계

  • 값이 오름차순으로 표시되며 가장 빠른 날짜가 먼저 표시됩니다.

각 인접한 값 쌍은 버킷의 포괄적인 하한과 배타적인 상한으로 작용합니다.

네
default
문자열
지정된 경계에 속하지 않는 연산자로부터 반환된 문서를 계산하는 추가 버킷의 이름입니다. 이를 생략하면 Atlas Search는 지정된 버킷에 포함되지 않는 패싯 연산자의 결과도 포함하지만, 버킷 계산에는 포함하지 않습니다.
no
path
문자열
패싯을 설정할 필드 경로입니다. dateFacet 유형으로 인덱싱되는 필드를 지정할 수 있습니다.
네
type
문자열
패싯의 유형입니다. 값은 date이어야 합니다.
네

예시

예시

다음 예시에서는 sample_mflix.movies 컬렉션의 default 인덱스를 사용합니다. 컬렉션의 released 필드는 dateFacet 및 날짜 유형으로 인덱싱됩니다.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "released": [
        {
          "type": "dateFacet"
        },
        {
          "type": "date"
        }
      ]
    }
  }
}

이 쿼리는 $searchMeta 단계를 사용하여 movies 컬렉션의 released 필드에서 2000년부터2015 사이의 영화를 검색하고 쿼리 문자열에 대한 메타데이터 결과를 검색합니다. 쿼리는 4개의 버킷을 지정합니다:

  • 2000-01-01이 버킷에 대한 포괄적인 하한값

  • 2005-01-012000-01-01 버킷에 대한 배타적 상한과 이 버킷에 대한 포괄적 하한입니다.

  • 2010-01-012005-01-01 버킷에 대한 배타적 상한과 이 버킷에 대한 포괄적 하한입니다.

  • 2015-01-012010-01-01 버킷에 대한 배타적 상한

이 쿼리는 또한 지정된 경계에 속하지 않는 쿼리 결과를 검색하기 위해 other이라는 이름의 default 버킷을 지정합니다.

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "released",
            "gte": ISODate("2000-01-01T00:00:00.000Z"),
            "lte": ISODate("2015-01-31T00:00:00.000Z")
          }
        },
        "facets": {
          "yearFacet": {
            "type": "date",
            "path": "released",
            "boundaries": [ISODate("2000-01-01"), ISODate("2005-01-01"), ISODate("2010-01-01"), ISODate("2015-01-01")],
            "default": "other"
          }
        }
      }
    }
  }
])

이 쿼리는 다음과 같은 결과를 반환합니다:

[
  {
    count: { lowerBound: Long('11922') },
    facet: {
      yearFacet: {
        buckets: [
          {
            _id: ISODate('2000-01-01T00:00:00.000Z'),
            count: Long('3028')
          },
          {
            _id: ISODate('2005-01-01T00:00:00.000Z'),
            count: Long('3953')
          },
          {
            _id: ISODate('2010-01-01T00:00:00.000Z'),
            count: Long('4832')
          },
          { _id: 'other', count: Long('109') }
        ]
      }
    }
  }
]

이러한 결과에 대해 자세히 알아보려면 패싯 결과를 참조하세요.

패싯 결과

패싯 쿼리의 경우 Atlas Search는 정의된 패싯 이름을 결과의 해당 패싯에 대한 버킷 배열에 매핑합니다. 패싯 결과 문서에는 패싯에 대한 결과 버킷의 배열인 buckets 옵션이 포함되어 있습니다. 배열의 각 패싯 버킷 문서에는 다음과 같은 필드가 있습니다.

옵션
유형
설명
_id
객체
이 패싯 버킷을 식별하는 고유 식별자입니다. 이 값은 패싯 처리되는 데이터 형식과 일치합니다.
count
int
이 패싯 버킷에 있는 문서의 개수입니다. count 필드에 대해 자세히 알아보려면 Atlas Search Results 수량을 참조하세요.

SEARCH_META 집계 변수

$search 단계를 사용하여 쿼리를 실행하면 Atlas Search는 메타데이터 결과를 $$SEARCH_META 변수에 저장하고 검색 결과만 반환합니다. 지원되는 모든 집계 파이프라인 단계에서 $$SEARCH_META 변수를 사용하여 $search 쿼리에 대한 메타데이터 결과를 볼 수 있습니다.

MongoDB는 검색 결과와 메타데이터 결과가 모두 필요한 경우에만 $$SEARCH_META 변수를 사용할 것을 권장합니다. 해당 경우가 아니면 다음을 사용하세요.

  • $search 검색 결과만 표시하는 단계.

  • $searchMeta 메타데이터 결과만 표시하는 단계.

제한 사항

다음과 같은 제한 사항이 적용됩니다:

  • 단일 필드에 대해서만 패싯 쿼리를 실행할 수 있습니다. 필드 그룹에 대해서는 패싯 쿼리를 실행할 수 없습니다.

  • MongoDB v6.0을 실행하는 클러스터에서만 샤딩된 컬렉션에 대해 패싯 쿼리를 실행할 수 있습니다.

예시

다음 예시에서는 sample_mflix.movies 컬렉션을 사용합니다. 메타데이터 결과 예시에서는 facet을 사용하여 $searchMeta 쿼리를 실행해 결과에서 메타데이터만 조회하는 방법을 보여 줍니다. 메타데이터 및 검색 결과 예시에서는 facet 및 $SEARCH_META 집계 변수를 사용하여 $search 쿼리를 실행해 검색 및 메타데이터 결과를 모두 조회하는 방법을 보여 줍니다.

인덱스 정의는 인덱싱할 필드에 대해 다음을 지정합니다.

필드 이름
데이터 유형
directors
year
released
{
  "mappings": {
    "dynamic": false,
    "fields": {
      "directors": {
        "type": "stringFacet"
      },
      "year": {
        "type": "numberFacet"
      },
      "released": {
        "type": "date"
      }
    }
  }
}

다음 쿼리는 2000년 1월 1일부터 2015년 1월 31일 사이에 개봉한 영화를 검색합니다. directors, year 필드에 대한 메타데이터를 요청합니다.

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "released",
            "gte": ISODate("2000-01-01T00:00:00.000Z"),
            "lte": ISODate("2015-01-31T00:00:00.000Z")
          }
        },
        "facets": {
          "directorsFacet": {
            "type": "string",
            "path": "directors",
            "numBuckets" : 7
          },
          "yearFacet" : {
            "type" : "number",
            "path" : "year",
            "boundaries" : [2000,2005,2010, 2015]
          }
        }
      }
    }
  }
])

Atlas Search가 반환하는 결과:

[
  {
    "count" : { "lowerBound" : NumberLong(13064) },
    "facet" : {
      "yearFacet" : {
        "buckets" : [
          { "_id" : 2000, "count" : NumberLong(3283) },
          { "_id" : 2005, "count" : NumberLong(4365) },
          { "_id" : 2010, "count" : NumberLong(5123) }
        ]
      },
      "directorsFacet" : {
        "buckets" : [
         { "_id" : "Takashi Miike", "count" : NumberLong(29) },
          { "_id" : "Johnnie To", "count" : NumberLong(23) },
          { "_id" : "Steven Soderbergh", "count" : NumberLong(21) },
          { "_id" : "Michael Winterbottom", "count" : NumberLong(19) },
          { "_id" : "Ken Loach", "count" : NumberLong(16) },
          { "_id" : "Ki-duk Kim", "count" : NumberLong(16) },
          { "_id" : "Ridley Scott", "count" : NumberLong(15) }
        ]
      }
    }
  }
]

결과는 sample_mflix.movies 컬렉션에 있는 다음과 같은 것들의 개수를 표시합니다.

  • Atlas Search에서 쿼리에 대해 반환한 2000년부터 2015년(하한 포함)까지의 영화 수(상한 제외)

  • Atlas Search가 쿼리에 대해 반환한 각 감독의 영화 수

인덱스 정의는 인덱싱할 필드에 대해 다음을 지정합니다.

필드 이름
데이터 유형
genres
released
{
  "mappings": {
    "dynamic": false,
    "fields": {
      "genres": {
        "type": "stringFacet"
      },
      "released": {
        "type": "date"
      }
    }
  }
}

다음 쿼리는 $search 단계를 사용하여 1999년 7월 01일 경에 개봉된 영화를 검색합니다. 쿼리에는 다음 하위 파이프라인 단계를 사용하여 입력 문서를 처리하는 $facet 단계가 포함됩니다.

  • $project 단계에서 docs 출력 필드의 title 및 released 필드를 제외한 문서의 모든 필드를 제외합니다.

  • $limit 단계를 사용하여 다음을 수행합니다.

    • $search 단계 출력을 2개 문서로 제한합니다.

    • meta 출력 필드에 있는 1개 문서로 출력을 제한합니다.

    참고

    결과를 16MB 문서에 맞추려면 제한이 작아야 합니다.

  • $replaceWith 스테이지를 사용하여 $$SEARCH_META 변수에 저장된 메타데이터 결과를 meta 출력 필드에 포함시킵니다.

쿼리에는 meta 필드를 추가하는 $set 단계도 포함되어 있습니다.

참고

다음 쿼리에 대한 메타데이터 결과를 보려면 Atlas Search가 쿼리와 일치하는 문서를 반환해야 합니다.

db.movies.aggregate([
  {
    "$search": {
      "facet": {
        "operator": {
          "near": {
            "path": "released",
            "origin": ISODate("1999-07-01T00:00:00.000+00:00"),
            "pivot": 7776000000
          }
        },
        "facets": {
          "genresFacet": {
            "type": "string",
            "path": "genres"
          }
        }
      }
    }
  },
  { "$limit": 2 },
  {
    "$facet": {
      "docs": [
        { "$project":
          {
            "title": 1,
            "released": 1
          }
        }
      ],
      "meta": [
        {"$replaceWith": "$$SEARCH_META"},
        {"$limit": 1}
      ]
    }
  },
  {
    "$set": {
      "meta": {
        "$arrayElemAt": ["$meta", 0]
      }
    }
  }
])

쿼리는 다음과 같은 결과를 반환합니다.

[
  {
    docs: [
      {
        _id: ObjectId("573a1393f29313caabcde1ae"),
        title: 'Begone Dull Care',
        released: ISODate("1999-07-01T00:00:00.000Z")
      },
      {
        _id: ObjectId("573a13a9f29313caabd2048a"),
        title: 'Fara',
        released: ISODate("1999-07-01T00:00:00.000Z")
      }
    ],
    meta: {
      count: { lowerBound: Long("20878") },
      facet: {
        genresFacet: {
          buckets: [
            { _id: 'Drama', count: Long('12149') },
            { _id: 'Comedy', count: Long('6436') },
            { _id: 'Romance', count: Long('3274') },
            { _id: 'Crime', count: Long('2429') },
            { _id: 'Thriller', count: Long('2400') },
            { _id: 'Action', count: Long('2349') },
            { _id: 'Adventure', count: Long('1876') },
            { _id: 'Documentary', count: Long('1755') },
            { _id: 'Horror', count: Long('1432') },
            { _id: 'Biography', count: Long('1244') }
          ]
        }
      }
    }
  }
]

이러한 결과에 대해 자세히 알아보려면 패싯 결과를 참조하세요.

돌아가기

이 존재합니다

다음

geoShape