Refresh コマンド (TMSL)

[アーティクル]
11/10/2023

適用対象:SQL Server 2016 以降の Analysis Services Azure Analysis Services Fabric/Power BI Premium

現在のデータベース内のオブジェクトを処理します。
更新は、Sequence コマンド (TMSL) で調整しない限り、常に並列に実行されます。

データ更新操作中に、一部のオブジェクトの一部のプロパティをオーバーライドできます。

Partition オブジェクトの QueryDefinition プロパティを変更して、その場でフィルター式を使用してデータをインポートします。
DataSource オブジェクトの ConnectionString プロパティで、Refresh コマンドの一部としてデータソースの資格情報を指定します。この方法は、資格情報が提供され、保存されるのではなく、操作の期間中に一時的に使用されるため、より安全であると見なすことができます。

既定の Power BI セマンティックモデルの増分更新ポリシーをオーバーライドします。

これらのプロパティのオーバーライドの図については、このトピックの例を参照してください。

注意

多次元処理とは異なり、表形式処理の処理エラーに対する特別な処理はありません。

要求

Refresh は、型パラメーターとオブジェクト定義を受け取ります。

    {  
        "refresh": {  
            "description": "Parameters of Refresh command of Analysis Services JSON API",  
            "properties": {  
            "type": {  
                "enum": [  
                "full",  
                "clearValues",  
                "calculate",  
                "dataOnly",  
                "automatic",  
                "add",  
                "defragment"  
                ]  
            },  
            "objects": [

型パラメーターは、処理操作のスコープを設定します。

更新の種類	適用対象	説明
フル	データベーステーブル Partition	指定されたパーティション、テーブル、データベースのすべてのパーティションに対して、データが更新され、すべての依存が再計算されます。計算パーティションに対して、パーティションとそのすべての依存を再計算します。
clearValues	データベーステーブル Partition	このオブジェクトとそのすべての依存の値をクリアします。
計算	データベーステーブル Partition	必要な場合にのみ、このオブジェクトとそのすべての依存を再計算します。この値は、揮発性の数式を除き、再計算を強制しません。
dataOnly	データベーステーブル Partition	このオブジェクトのデータを更新し、すべての依存をクリアします。
automatic	データベーステーブル Partition	オブジェクトを更新し、再計算する必要がある場合、オブジェクトとそのすべての依存を更新し、再計算します。パーティションの状態が準備完了以外の場合に適用されます。
add	Partition	このパーティションにデータを追加し、すべての依存を再計算します。このコマンドは通常のパーティションにのみ有効であり、計算パーティションでは利用できません。
最適化	データベーステーブル	指定されたテーブル内のデータを最適化します。データがテーブルに追加されるか、テーブルから削除されると、各列のディクショナリに、実際の列値にはもう存在しない値が入力されることがあります。最適化オプションを利用すると、使用されなくなったディクショナリの値が消去されます。

次のオブジェクトを更新できます。

Database オブジェクト (TMSL) データベースを処理します。

{  
  "refresh": {  
    "type": "automatic",  
    "objects": [  
      {  
        "database": "AdventureWorksTabular1200"  
      }  
    ]  
  }  
}

Tables オブジェクト (TMSL) 1 つのテーブルを処理します。

{  
  "refresh": {  
    "type": "automatic",  
    "objects": [  
      {  
        "database": "AdventureWorksTabular1200",  
        "table": "Date"  
      }  
    ]  
  }  
}

Partitions オブジェクト (TMSL) テーブル内の 1 つのパーティションを処理します。

{  
  "refresh": {  
    "type": "automatic",  
    "objects": [  
      {  
        "database": "AdventureWorksTabular1200",  
        "table": "FactSalesQuota",  
        "partition": "FactSalesQuota"  
      },  
      {  
        "database": "AdventureWorksTabular1200",  
        "table": "FactSalesQuota",  
        "partition": "FactSalesQuota - 2011"  
      }  
    ]  
  }  
}

省略可能なパラメーター

Power BI セマンティックモデルの場合、TMSL 更新コマンドに次のパラメーターを追加して、既定の増分更新動作をオーバーライドできます。

applyRefreshPolicy – テーブルで増分更新ポリシーが定義されている場合、そのポリシーを適用するかどうかは applyRefreshPolicy で決定されます。ポリシーが適用されていない場合、完全処理操作では、パーティション定義は変わらないままで、テーブル内のすべてのパーティションは完全に更新されます。既定値は true です。
effectiveDate – 増分更新ポリシーが適用されている場合は、履歴範囲と増分範囲に対するローリングウィンドウ範囲を決定するために現在の日付を把握しておく必要があります。 effectiveDate パラメーターを使用すると、現在の日付をオーバーライドすることができます。これは、データを過去または将来の日付まで増分更新するテスト、デモ、およびビジネスのシナリオにおいて役立ちます (たとえば、将来の予算)。既定値は現在の日付です。

{
  "refresh": {
    "type": "full",

    "applyRefreshPolicy": true,
    "effectiveDate": "12/31/2013",

    "objects": [
      {
        "database": "IR_AdventureWorks", 
        "table": "FactInternetSales" 
      }
    ]
  }
}

次の表は、増分更新ポリシーを含むテーブルの各更新の種類に 対する applyRefreshPolicy が true (既定値) の場合の影響を示しています。

更新の種類	影響
フル	ポリシーは、「 Power BI での増分更新」の説明に従って適用されます。以前の更新操作によって履歴パーティションが既に作成されていると仮定すると、概要は次のように記述されています。 - 必要に応じて、新しいパーティションが増分範囲に追加されます。 - データ変更を検出するために pollingExpression が定義されていない場合、増分範囲内のすべてのパーティションが完全に更新されます。 - pollingExpression が定義されている場合は、増分範囲内のパーティションごとに評価されます。前回の更新操作と比較して異なるポーリング結果を返すポーリング結果のみが完全に更新されます。 - 履歴パーティションは、データがクリアされているかどうかに関係なく更新されません。 - 範囲外の履歴パーティションが削除されます。 - 影響を受けるパーティションと依存の再計算。
clearValues	applyRefreshPolicy は動作に影響しません。
計算	applyRefreshPolicy は動作に影響しません。
dataOnly	type=full と同じですが、影響を受けるパーティションと依存の再計算はありません。
automatic	type=full と同じですが、増分範囲内のパーティションは type=automatic を使用して更新されます。
add	applyRefreshPolicy は動作に影響しません。
最適化	applyRefreshPolicy は動作に影響しません。

Response

コマンドが成功したときに空の結果を返します。それ以外の場合は、XMLA 例外が返されます。

例

パーティションの ConnectionString と QueryDefinition の両方をオーバーライドします。

{
  "refresh": {
    "type": "dataOnly",
    "objects": [
      {
        "database": "AdventureWorksDW2017",
        "table": "DimCustomer"
      }
    ],
    "overrides": [
      {
        "dataSources": [ // Bindings for DataSources
          {
            "originalObject": {
              "database": "AdventureWorksDW2017",
              "dataSource": "SqlServer localhost"
            },
            "connectionString": "Provider=SQLNCLI11.1;Data Source=.;Persist Security Info=True;User ID=YourSQLLogin;Password=YourPassword;Initial Catalog=AdventureWorksDW2017"
          }
        ],
        "partitions": [ // Bindings for Partitions
          {
            "originalObject": {
              "database": "AdventureWorksDW2017",
              "table": "DimCustomer",
              "partition": "DimCustomer"
            },
            "source": {
              "query": "SELECT * FROM [dbo].[DimCustomer]"
            }
          }
        ]
      }
    ]
  }
}

型パラメーターを dataOnly 更新に 設定することで、特定のオーバーライドをスコープします。メタデータはそのまま残ります。

{
  "refresh": {
    "type": "dataOnly",
    "objects": [
      {
        "database": "TMTestDB",
        "table": "Customer"
      },
      {
        "database": "TMTestDB",
        "table": "Sales"
      }
    ],
    "overrides": [
      {
        "scope": {
          "database": "TMTestDB",
          "table": "Sales"
        },
        "dataSources": [
          {
            "originalObject": {
              "dataSource": "SqlServer sqlcldb2 AS_foodmart_2000"
            },
            "connectionString": "Provider=SQLNCLI11;Data Source=sqlcldb2;Initial Catalog=AS_foodmart_2000;Integrated Security=SSPI;Persist Security Info=false"
          }
        ]
      }
    ]
  }
}

使用法 (エンドポイント)

このコマンド要素は、XMLA エンドポイントに対する Execute メソッド (XMLA) 呼び出しのステートメントで使用され、次の方法で公開されます。

SQL Server Management Studio (SSMS) の XMLA ウィンドウとして
invoke-ascmd PowerShell コマンドレットへの入力ファイルとして
SSIS タスクまたはSQL Server エージェントジョブへの入力として

SSMS からこのコマンドの既製スクリプトを生成できます。たとえば、[処理] ダイアログボックスで [スクリプト ] をクリックできます。

Refresh コマンド (TMSL)

要求

省略可能なパラメーター

Response

例

使用法 (エンドポイント)

フィードバック

フィードバック

その他のリソース