/ /

データストアのパスシンタックスの定義

注意

ドキュメントを簡素化するために、このページで見つかった例はAWS S3 のデータストアに基づいていますが、Google Cloud とAzure Private Link にも適用されます。

Overview

データストア内のドキュメントをクエリする場合、Atlas Data Federation path 値により、Data Federation はドキュメント内のデータをドキュメントのファイル名にマッピングできます。

path は、計算フィールドへのデータ保存へのファイル名の解析をサポートしています。Data Federation は、解析済みファイルから生成された各ドキュメントに計算フィールドを追加できます。Data Federation は、計算されたフィールド値に対するクエリの対象をファイル名が一致するファイルのみにすることができます。詳細については、サポートされている解析関数および例を参照してください。

path は、ファイルへのパスでパーティション属性を使用したパーティションの作成もサポートしています。 Data Federation は、パーティション属性で定義されたパラメーターに対するクエリの対象として、ファイル名またはパーティションプレフィックスにクエリが含まれるファイルのみを対象にできます。

例

S3バケット内の次のファイルを検討します。

/users/26/1234.json
/users/26/5678.json

The JSON document 1234.json contains the following:

{
  "name": "jane doe",
  "age": 26,
  "userID": "1234"
}

S3バケット内のファイルのフェデレーティッドデータベースインスタンスの構成では、次の path が定義されます。

"path": "/users/{age int}/{userID string}"

次は、Data Federation がpath定義から作成されたパーティションにクエリをマッピングする方法を示しています。

db.users.findOne(                /users
  {                                /40
    "age": 26 ----------------->   /26
    "userID": "1234" ---------->     /1234.json
  }                                  /5678.json
)

Data Federation は、パーティション属性の計算フィールドをドキュメントに追加します。上記の例では、Data Federation は ageフィールドと値を 1234.json に追加します。

Atlas Data Federation は、ドキュメントに同じ名前のフィールドが既に存在する場合でも、ドキュメントにパーティション属性を追加し、重複するフィールド名が作成されます。 MongoDB は重複するフィールド名をサポートしていません。重複するフィールド名を回避するには、omitAttributes を true に設定するか、ドキュメントに表示されないパーティション属性名を使用します。

サポートされている解析関数

ファイル名に単一の解析関数を指定できます。

/path/to/files/{<fieldA> <data-type>}

ファイル名に複数の解析関数を指定できます。

/path/to/files/{<fieldA> <data-type>}-{<fieldB> <data-type>}

ファイル名内の静的文字列と一緒に解析関数を指定できます。

/path/to/files/prefix-{<fieldA> <data-type>}-suffix

ドット（ファイル名へのパスにある. ）の順にクリックします。

/path/to/files/{<fieldA>.<fieldB> <data-type>}

フィールド名に : や # などの特殊文字が含まれている場合は、フィールド名を一重引用符（'）で囲むことができます。

/path/to/files/{'<fieldA>' <data-type>}

パーティションを作成するファイルへのパスにObjectIdsを指定できます。

/path/to/files/{objid objectid}

パーティションを作成するファイルへのパスで、 ObjectIdsの範囲を指定できます。

/path/to/files/{min(obj) objectid}-{max(obj) objectid}

ファイル名へのパスと一緒に解析関数を指定できます。

/path/{<fieldA> <data-type>}/{<fieldB> <data-type>}/{<fieldC> <data-type>}/*

ファイル名へのパスに応じてISODateの正規表現を指定できます。

/path/to/files/{<field-name> isodate("<date-format>"):\\<regex>}

注意

pathを指定する場合

パーティション属性のデータ型を指定します。
パーティション属性の型が解析するデータ型と一致していることを確認します。
delimiterで指定された区切り文字を使用します。

同じ型の属性を指定する場合は、以下のいずれかを行います。

属性の間に定数のセパレーターを追加します。
正規表現を使用して、検索パターンを記述します。詳細については、「サポートされていない解析関数」を参照してください。

ファイル名からの NULL 値の解析

Data Federation は、ファイルパス内の属性の代わりに空の文字列（""）を、string を除くすべての Atlas Data Federation 属性タイプのBSON null 値として自動的に解析します。string を使用すると、空の文字列は BSON null 値または BSON 空の文字列値のいずれかを表すことができます。Atlas Data Federation は、string 属性タイプのBSON値を解析しません。これにより、データ保存から読み取られたドキュメントに競合するタイプのBSON値が追加されるのを回避できます。

例

次の S3フェデレーティッドデータベースインスタンスストアについて考えてみましょう。

/records/january/1.json
/records/february/1.json
/records//1.json
For the path ``/records/{month string}/*``, Data Federation does not add any
computed fields for the ``month`` attribute to documents generated
from the third record in the above store.

注意

When writing files to S3, write BSON null values as empty strings in filenames for all Atlas Data Federation attribute types.

ファイル名からパディングされた数字の解析

ファイルパスには、先頭にゼロがある数値を含めることができます。 Data Federation がint 、 epoch_millis 、 epoch_secsなどの属性タイプの埋め込み数値を正しく解析するには、正規表現を使用して値の桁数を指定します。

例

次のファイルを含む S3 ストアについて考えてみましょう。

|--users
   |--001.json
   |--002.json
   ...

次のpath構文では、正規表現を使用してファイル名内の桁の数を指定します。 Data Federation は、パーティション属性に対応するパスの部分を識別し、そのパーティション属性をタイプintにマッピングします。

/users/{user_id int:\\d{3}}

サポートされていない解析関数

同じファイル名に対して、区別なしで連続した解析関数を指定すると、結果の整合性が失われる可能性があります。

例

次のファイルを含む S3 ストアについて考えてみましょう。

|--food
   |--icecream
   |--peanutbutter

ここで、 foodディレクトリ内のファイルへの次のパスを検討します。

/food/{first string}{second string}/

ファイル名部分文字列のどの部分が first 文字列属性と second string属性と一致するかを判断する方法はありません。したがって、Atlas Data Federation はすべてをfirstに一致させます。

代わりに、次のような正規表現を持つ属性を使用することを検討してください。

/food/{first string:\\D{3}}{second string:\\D{5}}
上記のパスでは、 firstが3桁の非数字の文字と一致するようにし、 secondが次の5桁の非数字の文字と一致することを指定しています。
/food/{first string:[A-Z]{3}}{second string:[a-z]{5}}
上記のパスは、 firstから3の大文字と小文字、 secondから5の小文字に一致します。

例

次の例は、ファイル名を計算フィールドに解析する方法を示しています。

ファイル名から単一フィールドを解析
ファイル名から複数のフィールドを解析
正規表現を使用してファイル名からフィールドを解析します
ファイル名からクエリ可能なデータの範囲を識別する
ファイル名からネストされたフィールドを識別する
ファイル名からの特殊文字を持つフィールドの識別
ObjectId からのパーティションの作成
ファイルパスからのパーティションの作成
ISODate からのパーティションの作成
ファイルパスからの動的コレクション名の生成

ファイル名から単一フィールドを解析

フェデレーティッドデータベースインスタンスストアaccountingArchiveに含まれるファイル名で、ファイル名が請求日を記述するファイルを含む場合を考えてみましょう。たとえば、ファイル名/invoices/1564671291998.jsonには UNIX タイムスタンプ1564671291998の請求書が含まれています。

次のdatabasesオブジェクトは、ファイル名を UNIX タイムスタンプとして解析してフィールドinvoiceDateを生成します。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{invoiceDate epoch_millis}"
          }
        ]
      }
    ]
  }
]

Data Federation は、計算されたフィールドと値を、ファイル名から生成された各ドキュメントに追加します。サンプルファイル名から生成されたドキュメントには、フィールドinvoiceDate: ISODate("2019-08-01T14:54:51Z")が含まれています。 invoiceDateフィールドのクエリは、指定された値に一致するファイルのみを対象にすることができます。

ファイル名から複数のフィールドを解析

フェデレーティッドデータベースインスタンスストアaccountingArchiveに請求書番号と請求日が記載されているファイルを含むものを考えてみましょう。たとえば、ファイル名/invoices/MONGO12345-1564671291998.jsonには UNIX タイムスタンプ1564671291998の請求書MONGODB12345が含まれています。

次のdatabasesオブジェクトは以下を生成します。

ファイル名の最初のセグメントを string として解析する場合のフィールドinvoiceNumber 。
ファイル名の 2 番目のセグメントを UNIX タイムスタンプとして解析するフィールドinvoiceDate 。

"databases" : [
  {
    "name": "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{invoiceNumber string}-{invoiceDate epoch_millis}"
          }
        ]
      }
    ]
  }
]

Data Federation は、計算されたフィールドと値を、ファイル名から生成された各ドキュメントに追加します。サンプルファイル名から生成されたドキュメントには、次のフィールドが含まれます。

invoiceNumber : "MONGODB12345"
invoiceDate : ISODate("2019-08-01T14:54:51Z")

フィールドと invoiceNumberinvoiceDateフィールドの両方を含むクエリは、指定された値に一致するファイルのみを対象にすることができます。

正規表現を使用してファイル名からフィールドを解析します

フェデレーティッドデータベースインスタンスストアaccountingArchiveに請求書番号と請求日が記載されているファイルを含むものを考えてみましょう。たとえば、ファイル名/invoices/MONGODB12345-20190102.jsonには日付20190102の請求書MONGODB12345が含まれています。

次のdatabasesオブジェクトは以下を生成します。

フィールドinvoiceNumber （ファイル名の最初のセグメントを string として解析）
フィールドyearは、正規表現を使用して、ファイル名の 2 番目のセグメントの最初の4桁のみを int として解析します。
フィールドmonthは、正規表現を使用して、ファイル名の 2 番目のセグメントの次の2桁のみを int として解析します。
フィールドdayは、正規表現を使用して、ファイル名の 2 番目のセグメントの次の2桁のみを int として解析します。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{invoiceNumber string}-{year int:\\d{4}}{month int:\\d{2}}{day int:\\d{2}}"
          }
        ]
      }
    ]
  }
]

invoiceNumber : "MONGODB12345"
year : 2019
month: 01
day: 02

重要

path で指定された正規表現stringをエスケープする必要があります。たとえば、正規表現stringにdouble引用符が含まれている場合は、それらの値をエスケープする必要があります。 Data Federation はパッケージ構文をサポートしますストレージ構成の正規表現用。

生成されたすべてのフィールドを含むクエリは、指定された値に一致するファイルのみを対象にすることができます。

Tip

ファイル名からパディングされた数字の解析

ファイル名からクエリ可能なデータの範囲を識別する

フェデレーティッドデータベースインスタンスストアaccountingArchiveに含まれるファイルについて考えてみましょう。ファイル名はファイルに含まれるデータの範囲を記述するため、たとえば、ファイル名/invoices/1546367712000-1549046112000.jsonには、2019-01-01 から 2019-01-02 までの期間の請求書が含まれており、日付範囲は UNIX エポックからの経過ミリ秒で表されます。

次のdatabasesオブジェクトは、ファイル名の最初のセグメントとして最小時間範囲を識別し、ファイル名の 2 番目のセグメントとして最大時間範囲を識別します。

"databases" : [
  {
    "name: "accounting",
    "collections" : [
      {
        "name: "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{min(invoiceDate) epoch_millis}-{max(invoiceDate) epoch_millis}"
          }
        ]
      }
    ]
  }
]

Data Federation は"invoiceDate"フィールドのクエリを受信すると、指定されたパスを使用して、クエリに一致するデータが含まれるファイルを識別します。

invoiceDateフィールドのクエリは、 minとmaxの日付を含め、指定された値をキャプチャする範囲のファイルのみを対象にすることができます。

重要

予期しない動作や望ましくない動作を避けるために、ファイルに含まれるすべてのドキュメントに最小範囲と最大範囲に指定されたフィールドが存在する必要があります。 Data Federation は、基礎となるデータがこの制約に準拠しているかどうかの検証を実行しません。

Tip

ファイル名からパディングされた数字の解析

ファイル名からネストされたフィールドを識別する

Data Federation は、ネストされたデータ値がファイル名でもある場合に、ネストされたデータのクエリをサポートします。ドット演算子（ { pathの. ）を使用して、ストレージ構成内のパーティション属性をドキュメント内のネストされたフィールドにマッピングします。

フェデレーティッドデータベースインスタンスストアaccountingArchiveについて考えてみましょう。フェデレーティッドデータベースインスタンスストアには、ドキュメント内のネストされたフィールドの値と一致する名前を持つファイルが含まれています。例:

accountingArchive
|--invoices
   |--January.json
   |--February.json
   ...

たとえば、 January.jsonファイルに次のフィールドを含むドキュメントが含まれているとします。

{
  "invoice": {
     "invoiceNumber" : "MONGODB12345",
     "year" : 2019,
     "month": "January", //value matches filename
     "date": 02
  },
  "vendor": "MONGODB",
  ...
}

次のdatabasesオブジェクトは、 monthをドキュメント内のネストされたフィールドとして識別します。 databasesオブジェクトは、ドキュメントを含むファイルの名前としてmonthの値も識別します。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{invoice.month string}"
          }
        ]
      }
    ]
  }
]

Atlas Data Federation は、 Januaryなどの特定の月に関するクエリを受信すると、指定されたパスを使用して、クエリに一致するデータが含まれるファイルを識別します。

ファイル名からの特殊文字を持つフィールドの識別

フィールド名にコロン（）や数字記号（: ）などの特殊文字が含まれている場合は、# 内のフィールド名を一重引用符（' path）で囲みます。それ以外の場合、Atlas Data Federation はストレージ構成を無効と見なします。ネストされたフィールドを区切るドットを含むフィールド名全体を引用符で囲みます。

ドキュメント内のネストされたフィールドの値と一致する名前を持つファイルを含むフェデレーティッドデータベースインスタンスストア accountingArchive の例を考えてみます。例、ファイルに次のフィールドを持つドキュメントが含まれているとします。

{
  "m:invoice": {
    "m:asOfDate": {
      "#value": "2026-08-01T14:54:51Z"
    }
  },
  "vendor": "MONGODB",
  ...
}

databases次のm:invoice.m:asOfDate.#value オブジェクトは、各ファイルに含まれる日付の範囲を識別するために、フィールド名を一重引用符で囲みます。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{min('m:invoice.m:asOfDate.#value') isodate}-{max('m:invoice.m:asOfDate.#value') isodate}/*"
          }
        ]
      }
    ]
  }
]

ObjectId からのパーティションの作成

ファイルへのパスで ObjectId を指定できます。ファイル名にObjectId が含まれているファイルの場合、Atlas Data Federation は各ObjectId のパーティションを作成します。

次のフェデaccountingArchiveデータベースインスタンスストアについて考えてみましょう。このデータストアには、ファイル名にObjectIdが含まれるファイルが含まれています。

accountingArchive
|--invoices
   |--507f1f77bcf86cd799439011.json
   |--507f1f77bcf86cd799439012.json
   |--507f1f77bcf86cd799439013.json
   |--507f1f77bcf86cd799439014.json
   |--507f1f77bcf86cd799439015.json

次のdatabasesオブジェクトはObjectIds用のパーティションを作成します。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{objid objectid}"
          }
        ]
      }
    ]
  }
]

または、フェデレーティッドデータベースインスタンスストアaccountingArchiveに、ファイル名にObjectIdsの範囲が含まれるファイルが含まれているとします。例:

accountingArchive
|--invoices
   |--507f1f77bcf86cd799439011-507f1f77bcf86cd799439020.json
   |--507f1f77bcf86cd799439021-507f1f77bcf86cd799439030.json
   |--507f1f77bcf86cd799439031-507f1f77bcf86cd799439040.json

次のdatabasesオブジェクトは、 ObjectIdsの指定された範囲のパーティションを作成します。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{min(obj) objectid}-{max(obj) objectid}"
          }
        ]
      }
    ]
  }
]

Data Federation はObjectIdのクエリを受信すると、指定されたパスを使用して、クエリに一致するデータが含まれるファイルを識別します。

ファイルパスからのパーティションの作成

ファイル名までの任意のパスで解析関数を指定できます。各計算フィールドは、パス上の解析関数に基づいています。データをクエリする際、Atlas Data Federation は各計算フィールドをパーティションに変換します。次に、サブディレクトリと同義であるパーティションは、精度の高いファイルをフィルタリングするために使用されます。

次のディレクトリ構造を持つフェデレーティッドデータベースインスタンスストアaccountingArchiveについて考えます。

invoices
|--MONGO12345
   |--2019
      |--01
         |--02

次のdatabasesオブジェクトは、フィルタリングされたファイルの少数を含むinvoiceNumber 、 year 、 month 、 dayのパーティションを作成します。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{invoiceNumber string}/{year int}/{month int:\\d{2}}/{day int:\\d{2}}/*"
          }
        ]
      }
    ]
  }
}

Tip

ファイル名からパディングされた数字の解析

ISODate からのパーティションの作成

ファイルへのパスでISODate を指定できます。ファイル名にISODate が含まれているファイルの場合、Atlas Data Federation は各ISODate のパーティションを作成します。

次のフェデaccountingArchiveデータベースインスタンスストアについて考えてみましょう。このデータストアには、ファイル名にISODateが含まれるファイルが含まれています。

accountingArchive
|--invoices
   |--01_02_2022_2301.json
   |--02_02_2022_2301.json
   |--03_02_2022_2301.json
   |--04_02_2022_2301.json
   |--05_02_2022_2301.json

次のdatabases オブジェクトはISODate 用のパーティションを作成します。path は、日付が RFC3339 形式でない場合に、日付形式に正規表現を使用する方法を示しています。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/creationDate isodate('01_02_2006_1504'):\\d{2}_\\d{2}_\\d{4}_\\d{4}.json"
          }
        ]
      }
    ]
  }
]

サポートされている他の形式の詳細については、「パーティション属性タイプの使用」を参照してください。

ファイルパスからの動的コレクション名の生成

次のディレクトリ構造を持つフェデレーティッドデータベースインスタンスストアaccountingArchiveについて考えます。

invoices
|--SuperSoftware
|--UltraSoftware
|--MegaSoftware

次のdatabasesオブジェクトは、ファイルパスから動的コレクション名を生成します。

"databases" : [
  {
    "name" : "invoices",
    "collections" : [
      {
        "name" : "*",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{collectionName()}/"
          }
        ]
      }
    ]
  }
]

サンプルディレクトリ構造に適用すると、パスによって次のコレクションが生成されます。

スーパーソフトウェア
ultra ソフトウェア
メガソフトウェア

または、次のファイルを含むフェデレーティッドデータベースインスタンスストアaccountingArchiveを検討してください。

/orders/MONGODB/invoices/January.json
/orders/MONGODB/purchaseOrders/January.json
/orders/MONGODB/invoices/February.json
...

次のdatabasesオブジェクトは、ファイルパスから動的コレクション名を生成します。

"databases" : [
  {
    "name" : "invoices",
    "collections" : [
      {
        "name" : "*",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/orders/MONGODB/{collectionName()}/{invoiceMonth string}.json/"
          }
        ]
      }
    ]
  }
]

サンプルファイル名に適用すると、パスによって次のコレクションが生成されます。

invoices
purchaseOrders

注意

ファイル名からコレクションを動的に生成する場合、コレクション数はData Federationビューに正確に報告されません。

戻る

コレクションの生成

AWS S3 暗号化