facet
互換性
facet 次のいずれかのバージョンを実行している Atlas クラスターでのみ使用できます。
MongoDB 5.0.4+
MongoDB 6.0+
MongoDB 7.0+
注意
シャーディングされたコレクションに対してファセットクエリを実行するには、クラスターで MongoDB v6.0 以降を実行する必要があります。
explain で facet クエリを実行できません。
定義
facetfacetコレクターは、指定されたファセット フィールドの値または範囲で結果をグループ化し、各グループのカウントを返します。$searchステージと$searchMetaステージの両方でfacetを使用できます。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> } } } }
フィールド
ファセットの定義
ファセット定義ドキュメントには、ファセット名とファセットの種類に固有のオプションが含まれています。Atlas Search は次の型のファセットをサポートしています。
文字列ファセット
文字列ファセットを使用すると、指定された文字列フィールド内の最も頻繁に出現する文字列値に基づいて、Atlas 検索結果を絞り込むことができます。文字列フィールドは 文字列ファセット としてインデックス付けする必要があることに注意してください。埋め込まれたドキュメント内の文字列フィールドをファセットするには、親フィールドも ドキュメント型としてインデックス付けする必要があります。
注意
埋め込まれたドキュメント内の文字列フィールドをファセットすると、Atlas Search は一致する親ドキュメントの数のみのファセット数を返します。
構文
文字列ファセットの構文は次のとおりです。
{ "$searchMeta": { "facet":{ "operator": { <operator-specification> }, "facets": { "<facet-name>" : { "type" : "string", "path" : "<field-path>", "numBuckets" : <number-of-categories>, } } } } }
オプション
オプション | タイプ | 説明 | 必須 |
|---|---|---|---|
numBuckets | 整数 | 結果で返されるファセット カテゴリの最大数。値は 1000 以下である必要があります。指定した場合、データがリクエストされた数よりも少ないカテゴリにグループ化されると、Atlas Search はリクエストされた数よりも少ないカテゴリを返すことがあります。省略した場合、デフォルトは 10 になります。つまり、Atlas Search はカウントで上位 10 個のファセット カテゴリのみを返します。 | no |
path | string | ファセットのフィールドパス。文字列ファセット としてインデックス付けされたフィールドを指定できます。 | はい |
type | string | ファセットの型。値は stringでなければなりません。 | はい |
例
例
次の例では、sample_mflix.movies コレクションで default という名前のインデックスを使用します。コレクション内の genres フィールドは 文字列ファセット 型としてインデックス付けされ、year フィールドは number 型としてインデックス付けされます。
{ "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 | 数字の配列 | 各バケットの境界を指定する数値のリスト（昇順）。少なくとも 2 つの境界を指定する必要があります。隣接する各値のペアは、バケットの包括的な下限と排他的な上限として機能します。次の BSON types の値の任意の組み合わせを指定できます。
| はい |
default | string | 指定された境界内に含まれない、演算子から返されたドキュメントをカウントする追加のバケットの名前。省略した場合、Atlas Search には、指定されたバケットに該当しないファセット演算子の結果も含まれますが、バケット数には含まれません。 | no |
path | string | ファセットのフィールドパス。numberFacet 型としてインデックス付けされたフィールドを指定できます。 | はい |
type | string | ファセットの型。値は numberでなければなりません。 | はい |
例
例
次の例では、sample_mflix.movies コレクションで default という名前のインデックスを使用します。コレクション内の year フィールドは、numberFacet および number 型としてインデックス付けされます。
{ "mappings": { "dynamic": false, "fields": { "year": [ { "type": "numberFacet" }, { "type": "number" } ] } } }
クエリは、$searchMeta ステージを使用して、movies コレクションの year フィールドで 1980 年から 2000 年までの映画を検索し、クエリのメタデータ結果を検索します。クエリでは 3 つのバケットを指定します。
1980（このバケットの下限値を含む）1990（1980バケットの上限（排他的）とこのバケットの下限（包括的））2000（1990バケットの排他的上限）
クエリでは、指定された境界のいずれにも該当しないクエリの結果を検索するために、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 | string | 指定された境界内に含まれない、演算子から返されたドキュメントをカウントする追加のバケットの名前。省略した場合、Atlas Search には指定されたバケットに該当しないファセット演算子の結果も含まれますが、Atlas Search はこれらの結果をバケット カウントに含めません。 | no |
path | string | ファセットのフィールドパス。dateFacet 型としてインデックス付けされたフィールドを指定できます。 | はい |
type | string | ファセットの型。値は dateでなければなりません。 | はい |
例
例
次の例では、sample_mflix.movies コレクションで default という名前のインデックスを使用します。コレクション内の released フィールドは、dateFacet 型および date 型としてインデックス付けされます。
{ "mappings": { "dynamic": false, "fields": { "released": [ { "type": "dateFacet" }, { "type": "date" } ] } } }
クエリは、$searchMeta ステージを使用して、movies コレクションの released フィールドで 2000 年から 2015 年までの映画を検索し、クエリ文字列 のメタデータ結果を取得します。このクエリでは、次の 4 つのバケットを指定します。
2000-01-01（このバケットの下限値を含む）2005-01-01（2000-01-01バケットの上限（排他的）とこのバケットの下限（包括的））2010-01-01（2005-01-01バケットの上限（排他的）とこのバケットの下限（包括的））2015-01-01（2010-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 | 整数 | このファセット バケット内のドキュメントの数。 count フィールドについて詳しくは、「Atlas 検索結果のカウント」を参照してください。 |
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ドキュメントへの出力を制限します
注意
結果が 16 MB のドキュメントに収まるように、制限を小さくする必要があります。
$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') } ] } } } } ]
これらの結果の詳細については、「ファセット結果」を参照してください。