Comando Refresh (TMSL)

Artigo
11/10/2023

Aplica-se a: SQL Server 2016 e posteriores do Analysis Services Azure Analysis Services Fabric/Power BI Premium

Processa objetos no banco de dados atual.
A atualização sempre é executada em paralelo, a menos que você a restrinja com o comando Sequence (TMSL).

Você pode substituir algumas propriedades de alguns objetos durante uma operação de atualização de dados:

Altere a propriedade QueryDefinition de um objeto Partition para importar dados usando uma expressão de filtro on-the-fly.
Forneça credenciais de fonte de dados como parte de um comando Refresh , na propriedade ConnectionString de um objeto DataSource . Essa abordagem pode ser considerada mais segura, pois as credenciais são fornecidas e usadas temporariamente durante a operação, em vez de armazenadas.

Substitua a política de atualização incremental padrão do modelo semântico do Power BI.

Consulte os exemplos neste tópico para obter uma ilustração dessas substituições de propriedade.

Observação

Ao contrário do processamento multidimensional, não há tratamento especial de erros de processamento para processamento tabular.

Solicitação

A atualização usa um parâmetro de tipo e uma definição de objeto.

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

O parâmetro type define um escopo na operação de processamento.

Tipo de atualização	Aplica-se a	Descrição
completa	Database Tabela Partition	Para todas as partições na partição, tabela ou banco de dados especificado, atualize os dados e recalcule todos os dependentes. Para uma partição de cálculo, recalcule a partição e todos os seus dependentes.
clearValues	Database Tabela Partition	Limpe os valores nesse objeto e todos os seus dependentes.
Calcular	Database Tabela Partition	Recalcule este objeto e todos os seus dependentes, mas somente se necessário. Esse valor não força o recálculo, exceto fórmulas voláteis.
dataOnly	Database Tabela Partition	Atualize os dados neste objeto e limpe todos os dependentes.
automático	Database Tabela Partition	Se o objeto precisar ser atualizado e recalculado, atualize e recalcule o objeto e todos os seus dependentes. Será aplicado se a partição estiver em um estado diferente de Ready.
add	Partition	Acrescente dados a esta partição e recalcule todos os dependentes. Este comando é válido apenas para partições regulares, e não para partições de cálculo.
Desfragmentar	Database Tabela	Desfragmente os dados na tabela especificada. Como os dados são adicionados ou removidos de uma tabela, os dicionários de cada coluna podem ficar poluídos com valores que não existem mais nos valores de coluna reais. A opção de desfragmentar limpará os valores nos dicionários que não são mais usados.

Você pode atualizar os seguintes objetos:

Objeto database (TMSL) Processar um banco de dados.

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

Objeto Tables (TMSL) Processar uma única tabela.

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

Objeto Partitions (TMSL) Processe uma única partição dentro de uma tabela.

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

Parâmetros opcionais

Para modelos semânticos do Power BI, os seguintes parâmetros podem ser adicionados a um comando de atualização TMSL para substituir o comportamento de atualização incremental padrão:

applyRefreshPolicy – se uma tabela tiver uma política de atualização incremental definida, applyRefreshPolicy determinará se a política será aplicada ou não. Se a política não for aplicada, uma operação de processo completa deixará as definições de partição inalteradas e todas as partições na tabela serão totalmente atualizadas. O valor padrão é true.
effectiveDate – se uma política de atualização incremental estiver sendo aplicada, ela precisará saber a data atual para determinar os intervalos de janela sem interrupção para o intervalo histórico e o intervalo incremental. O parâmetro effectiveDate permite que você substitua a data atual. Isso é útil para testes, demonstrações e cenários de negócios em que os dados são atualizados incrementalmente em datas passados ou futuras (por exemplo, orçamentos futuros). O valor padrão é a data atual.

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

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

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

A tabela a seguir mostra o impacto quando applyRefreshPolicy é true (padrão) em cada um dos tipos de atualização de uma tabela que contém uma política de atualização incremental:

Tipo de atualização	Impacto
completa	A política é aplicada conforme descrito em Atualização incremental no Power BI. Supondo que as partições históricas já tenham sido criadas por uma operação de atualização anterior, um resumo é descrito aqui: - Novas partições são adicionadas ao intervalo incremental, se necessário. - Se nenhuma sondagemExpression for definida para detecção de alterações de dados, todas as partições no intervalo incremental serão atualizadas na íntegra. - Se uma pollingExpression for definida, ela será avaliada para cada partição no intervalo incremental. Somente aqueles que retornam um resultado de sondagem diferente em comparação com a operação de atualização anterior são atualizados na íntegra. - As partições históricas não são atualizadas independentemente de terem sido limpas dos dados. – As partições históricas que ficam fora do intervalo são excluídas. - Recálculo de partições e dependentes afetados.
clearValues	applyRefreshPolicy não afeta o comportamento.
Calcular	applyRefreshPolicy não afeta o comportamento.
dataOnly	O mesmo que type=full, mas sem recálculo de partições e dependentes afetados.
automático	O mesmo que type=full, mas as partições no intervalo incremental são atualizadas usando type=automatic.
add	applyRefreshPolicy não afeta o comportamento.
Desfragmentar	applyRefreshPolicy não afeta o comportamento.

Resposta

Retorna um resultado vazio quando o comando é bem-sucedido. Caso contrário, uma exceção XMLA será retornada.

Exemplos

Substitua ConnectionString e QueryDefinition de uma partição.

{
  "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]"
            }
          }
        ]
      }
    ]
  }
}

Substituições específicas de escopo definindo o parâmetro de tipo como uma atualização dataOnly , os metadados permanecem intactos.

{
  "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"
          }
        ]
      }
    ]
  }
}

Uso (pontos de extremidade)

Esse elemento de comando é usado em uma instrução da chamada do Método Execute (XMLA) em um ponto de extremidade XMLA, exposto das seguintes maneiras:

Como uma janela XMLA no SSMS (SQL Server Management Studio)
Como um arquivo de entrada para o cmdlet do PowerShell invoke-ascmd
Como uma entrada para uma tarefa do SSIS ou trabalho de SQL Server Agent

Você pode gerar um script pronto para esse comando do SSMS. Por exemplo, você pode clicar no Script em uma caixa de diálogo Processamento.