Azure Cosmos DB からのインポート

この記事では、Azure Machine Learning Studio (クラシック) の データのインポート モジュールを使用して、機械学習の実験で使用する Azure Cosmos DB からデータをインポートする方法について説明します。

注意

適用対象: Machine Learning Studio (クラシック)

このコンテンツは、Studio (クラシック) のみに関連しています。 Azure Machine Learning デザイナーに同様のドラッグアンドドロップモジュールが追加されました。 この記事では、2つのバージョンの比較について詳しく説明します。

Azure Cosmos DB は、柔軟なデータモデルを使用して NoSQL database storage をサポートしています。 Machine learning のこのデータストアで SQL Api を使用する利点には、高速で予測可能なパフォーマンス、自動スケーリング、グローバル分散、豊富なクエリ機能などがあります。

Azure SQL Database と共に、このオプションを使用すると、受信データセットを動的にフィルター処理できます。

動作方法については、 Azure Cosmos DB に関するページを参照してください。

  • Azure Cosmos DB のデータを使用して機械学習を開始するには、関連するドキュメントのコレクションを含む既存の Azure Cosmos DB アカウントにアクセスできる必要があります。

注意

Azure Machine Learning Studio (クラシック) のユーザーインターフェイスでも、多くの場所で DocumentDB という名前が使用されます。 そのため、API が Azure Cosmos DB に組み込まれていても、DocumentDB への参照を引き続き参照できます。

Azure Cosmos DB でのデータのインポートの使用方法

スキーマが正しいことを確認するために、データはインポート前にプロファイルしておくことを強くお勧めします。 スキーマは、インポート プロセスでいくつかの見出し行をスキャンすることによって特定されますが、後続の行に余分な列やエラーの原因となるデータが含まれている可能性もあります。

ウィザードを使用してデータをインポートする

モジュールには新しいウィザードが用意されており、ストレージオプションを選択したり、既存のサブスクリプションとアカウントの中から選択したり、すべてのオプションをすばやく構成したりすることができます。

  1. データのインポート モジュールを実験に追加します。 [ データの入力と出力] の下にモジュールがあります。

  2. [ データのインポートウィザードの起動 ] をクリックし、画面の指示に従います。

  3. 構成が完了したら、実際にデータを実験にコピーするには、モジュールを右クリックし、[選択ファイルの 実行] を選択します。

ヒント

既存のデータ接続を編集する必要がある場合は、以前のすべての構成の詳細が読み込まれます。 最初からやり直す必要はありません。

データのインポート モジュールのプロパティを手動で設定する

次の手順では、インポート元を手動で構成する方法について説明します。

  1. データのインポート モジュールを実験に追加します。 このモジュールは、[ データ入力と出力 ] カテゴリで確認できます。

  2. [ データソース] で、[ Azure DocumentDB] を選択します。

    場合によっては、ドキュメントデータベースの接続情報の指定が必要になることがあります。

    ヒント

    後で変更するには、Machine Learning Studio (クラシック) でオプションの名前を探します。 インポート機能は、名前の変更の影響を受けませんでした。

  3. [ エンドポイント URL] の Azure Portal で、[ キー] をクリックし、ページの上部にある [ URI ] フィールドの内容をコピーします。

  4. [ データベース ID] には、使用するデータベースの名前を貼り付けます。

    Azure Portal からデータベース名を取得するには、[ Document Explorer] をクリックします。 このペインには、データベースとコレクションの一覧が表示されます。

  5. DocumentDB キー の場合は、アカウントのアクセスキーを貼り付けます。

    キーを検索するには、[ キー] をクリックし、[ 主キー ] フィールドまたは [ セカンダリキー ] フィールドの内容をコピーします。

  6. [ コレクション ID] に、指定した CosmosDB データベースに表示されるコレクションの名前を入力します。

  7. Sql クエリと sql クエリのパラメーター オプションを使用して、データに対する sql クエリとフィルター条件を定義します。

    [ SQL クエリ] には、コレクションから取得するデータを定義するクエリを入力します。 クエリエクスプローラーを使用して、CosmosDB クエリを事前に作成し、テストすることをお勧めします。

    SQL クエリパラメーター には、返されるデータを動的にフィルター処理するために使用できる JSON 形式の式を指定します。 通常は、Web サービスの一部として実験を実行するときに、パラメーター値の実際の値を指定します。

    パラメーターを使用する場合は、[ SQL クエリ ] テキストボックスで指定した where 句の一部として、フィルター変数名を定義する必要があります。

    フィルター式を指定しない場合、既定では、値は "" に設定され、 {} すべてのレコードが返されます。

    CosmosDB の SQL クエリに関する例、既知の問題、およびその他のアドバイスについては、「 テクニカルノート 」のセクションを参照してください。

  8. 既存の結果を再利用する場合は、[キャッシュされた 結果を使用 する] オプションを選択します。

    このオプションの選択を解除すると、データが同じであるかどうかに関係なく、実験を実行するたびにソースからデータが読み取られます。

    Azure Machine Learning では、キャッシュされたデータを CosmosDB アカウントのデータと比較する ことはできません 。 そのため、Azure Machine Learning から増分更新を実行することはできません。

    データが変更されたときにのみ再インポートする場合は、Azure Data Factory などの別のアプリケーションでそのロジックを定義する必要があります。 詳細については、「Azure Data Factory を使用した Azure Cosmos DB との間でのデータの移動」を参照してください。

  9. 実験を実行するか、データの インポート モジュールだけを選択して [選択ファイルの 実行] をクリックします。

結果

モジュールまたは実験を実行した後、モジュールの出力を右クリックして、結果を表形式で視覚化できます。

データセットとして Azure Machine Learning ワークスペースのこのデータのスナップショットを取得するには、モジュールの出力を右クリックし、[ データセットとして保存] を選択します。 ただし、これを行うと、インポート時に利用可能なデータのみがキャプチャされます。 データが頻繁に変更されることが予想される場合は、必要に応じて データのインポート を再実行します。

Machine learning のデータソースとして Azure Cosmos DB を使用する方法の詳細なチュートリアルについては、 Azure AI Galleryを参照してください。

テクニカルノート

ここでは、詳細な構成オプションとよく寄せられる質問への回答について説明します。

単純なクエリとパラメーター化されたクエリの例

1万フィート未満の標高で火山上のデータのみを使用するとします。

単純なクエリ

[ SQL クエリ ] テキストボックスに次のクエリを貼り付けます。 Select * from volcanodb where volcanodb.Elevation < 10000

この場合、フィルター式の値は "" に設定され、 {} すべてのレコードが返されます。

パラメーター化クエリ

特定の国に関連する火山データだけを取得するには、実行時にクエリに渡されるパラメーターとして country 値を指定します。 これには、次の変更が必要です。

  1. [ Sql クエリ ] テキストボックスで、 Country sql クエリの一部としてフィールドに適用する変数を定義します。

    Select * from volcanodb where volcanodb.Country = @param1

  2. [ SQL クエリパラメーター ] ボックスで、次のように、JSON 形式でパラメーター名とその値を指定します。

    {"@param1":"Turkey"}

リソース

既存のドキュメントストアがない場合は、これらの記事を参照して作業を開始してください。

データの移行とクエリ構文のヘルプ

JSON データストアに対するクエリのサンプルについては、 Azure Cosmos DB クエリのサンプルシートをダウンロードしてください。

コンテンツを Azure Cosmos DB にアップロードする必要がある場合は、 移行ツールの Azure Cosmos DBをお勧めします。 データの検証、アップロード、およびインデックス作成を行います。 このツールでは、MongoDB、Amazon DynamoDB、HBase、SQL Server データベース、CSV ファイルなどの複数のソースがサポートされています。

スキーマレスクエリの使用

データの一貫性と予測可能性を向上させるには、などの単純な SQL に似た構文を使用でき SELECT * FROM <document collection> ます。 これは、返される正確な属性に名前が付けられていないため、 スキーマレスクエリ と呼ばれます。 このようなクエリを実行すると、指定したコレクションのすべてのフィールドとすべての行が返されます。

ただし、スキーマを指定しないと、ドキュメントに一貫性のないスキーマが含まれている場合、予期しない結果や実行時エラーが発生する可能性があります。 これは、 データのインポート モジュールが、次のようにあらかじめ定義された数の行に基づいてスキーマを推論しようとするためです。

  1. 属性が指定されていない場合、モジュールは CosmosDB データベースの最初の行をスキャンします。
  2. モジュールは、属性に基づいて列名を作成し、その列のデータ型が行の例にどのようなものであるかを推測します。
  3. 後の行に新しい属性または異なる属性が含まれている場合は、実行時エラーが生成されます。

そのため、CosmosDB データストアから返す属性と値を常に指定することをお勧めします。 たとえば、構文を使用するのではなく、次のように、 SELECT * クエリによって取得されるすべての属性に名前を指定することをお勧めします。

SELECT MyTable.Gender, MyTable.Age, MyTable.Name FROM <document collection>

モジュールのパラメーター

次の表は、Azure Cosmos DB オプションに適用できる データのインポート モジュールのパラメーターのみを示しています。

名前 Range Type 必須 Default 説明
データ ソース list HTTP 必須 なし データソースには、HTTP、FTP、匿名の HTTPS または FTPS、Azure BLOB storage 内のファイル、Azure テーブル、Azure SQL Database、Hive テーブル、OData エンドポイント、Azure Cosmos dB などがあります。
エンドポイント URL any string 必須 なし Azure Cosmos DB サーバーの URI を指定します
データベース ID any string 必須 なし Azure Cosmos DB データベースの名前を指定します。
DocumentDB キー any SecureString 必須 なし Azure Cosmos DB アカウントに有効な API キーを指定してください
コレクション ID any string 必須 なし Azure Cosmos DB データベース内のコレクションの名前を指定します。
SQL クエリ any string 必須 なし Azure Cosmos DB データストアから返されるレコードを指定する SQL クエリ

出力

名前 Type 説明
結果のデータセット データ テーブル ダウンロードしたデータを含むデータセット

例外

例外 説明
エラー 0003 1 つ以上の入力が null または空の場合に、例外が発生します。
エラー 0029 無効な URI が渡された場合に、例外が発生します。
エラー 0002 1 つ以上のパラメーターが解析できなかった、または指定した型から対象のメソッドの種類で必要な型に変換されなかった場合に、例外が発生します。
エラー 0048 ファイルを開けない場合、例外が発生します。
エラー 0049 ファイルを解析できない場合、例外が発生します。

Studio (クラシック) モジュール固有のエラーの一覧については、「 Machine Learning エラーコード」を参照してください。

API 例外の一覧については、「 Machine Learning REST API のエラーコード」を参照してください。

関連項目

データのインポート
データのエクスポート
HTTP 経由で Web URL からインポートする
Hive クエリからのインポート
Azure SQL Database からのインポート
Azure Blob Storage からのインポート
データフィードプロバイダーからのインポート
オンプレミスの SQL Server データベースからのインポート