ALTER WAREHOUSE

Suspende ou retoma um warehouse virtual, ou anula todas as consultas (e outras instruções SQL) para um warehouse. Também pode ser usado para renomear ou definir/remover as propriedades de um warehouse.

Consulte também:

CREATE WAREHOUSE , DESCRIBE WAREHOUSE , DROP WAREHOUSE , SHOW WAREHOUSES

Sintaxe

ALTER WAREHOUSE [ IF EXISTS ] [ <name> ] { SUSPEND | RESUME [ IF SUSPENDED ] }

ALTER WAREHOUSE [ IF EXISTS ] [ <name> ] ABORT ALL QUERIES

ALTER WAREHOUSE [ IF EXISTS ] <name> RENAME TO <new_name>

ALTER WAREHOUSE [ IF EXISTS ] <name> SET [ objectProperties ]
                                         [ objectParams ]

ALTER WAREHOUSE [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER WAREHOUSE [ IF EXISTS ] <name> UNSET TAG <tag_name> [ , <tag_name> ... ]

ALTER WAREHOUSE [ IF EXISTS ] <name> UNSET { <property_name> | <param_name> } [ , ... ]
Copy

Onde:

objectProperties ::=
  WAREHOUSE_TYPE = { STANDARD | 'SNOWPARK-OPTIMIZED' }
  WAREHOUSE_SIZE = { XSMALL | SMALL | MEDIUM | LARGE | XLARGE | XXLARGE | XXXLARGE | X4LARGE | X5LARGE | X6LARGE }
  WAIT_FOR_COMPLETION = { TRUE | FALSE }
  MAX_CLUSTER_COUNT = <num>
  MIN_CLUSTER_COUNT = <num>
  SCALING_POLICY = { STANDARD | ECONOMY }
  AUTO_SUSPEND = { <num> | NULL }
  AUTO_RESUME = { TRUE | FALSE }
  RESOURCE_MONITOR = <monitor_name>
  COMMENT = '<string_literal>'
  ENABLE_QUERY_ACCELERATION = { TRUE | FALSE }
  QUERY_ACCELERATION_MAX_SCALE_FACTOR = <num>
Copy
objectParams ::=
  MAX_CONCURRENCY_LEVEL = <num>
  STATEMENT_QUEUED_TIMEOUT_IN_SECONDS = <num>
  STATEMENT_TIMEOUT_IN_SECONDS = <num>
Copy

Propriedades/Parâmetros

name

Especifica o identificador do warehouse a ser modificado. Se o identificador contiver espaços ou caracteres especiais, toda a cadeia de caracteres deverá ser delimitada por aspas duplas. Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais detalhes, consulte Requisitos para identificadores.

Nota

Um identificador do warehouse é necessário ou opcional, dependendo do seguinte:

  • Ao retomar/suspender um warehouse ou abortar consultas para um warehouse, se um warehouse estiver atualmente em uso para a sessão, o identificador pode ser omitido.

  • Ao renomear um warehouse ou realizar qualquer outra operação em um warehouse, o identificador deve ser obrigatoriamente especificado.

{ SUSPEND | RESUME [ IF SUSPENDED ] }

Especifica a ação a ser executada no warehouse:

  • SUSPEND remove todos os nós de computação de um warehouse e coloca o warehouse em um estado ‘Suspenso’.

  • RESUME [ IF SUSPENDED ] coloca um warehouse suspenso em um estado ‘em execução’ utilizável, através do provisionamento de recursos de computação.

    A cláusula opcional IF SUSPENDED especifica se o comando ALTER WAREHOUSE é concluído com sucesso ao retomar um warehouse que já está em execução:

    • Se omitido, o comando falha e retorna um erro se o warehouse já estiver em funcionamento.

    • Se especificado, o comando é concluído com sucesso, independentemente de o warehouse estar em funcionamento.

ABORT ALL QUERIES

Aborta todas as consultas atualmente em andamento ou em fila no warehouse.

RENAME TO new_name

Especifica um novo identificador do warehouse; deve ser único para sua conta.

Para obter mais detalhes, consulte Requisitos para identificadores.

SET ...

Especifica uma ou mais propriedades/parâmetros a serem definidos para o warehouse (separados por espaços em branco, vírgulas ou novas linhas):

WAREHOUSE_TYPE = { STANDARD | 'SNOWPARK-OPTIMIZED' }

Especifica o tipo de warehouse.

Valores válidos:
  • STANDARD, 'STANDARD'

  • 'SNOWPARK-OPTIMIZED'

Padrão:

STANDARD

Nota

Para usar um valor que contenha um hífen ('SNOWPARK-OPTIMIZED'), você deve incluir o valor entre aspas simples, como mostrado.

WAREHOUSE_SIZE = string_constant

Especifica o tamanho do warehouse virtual. O tamanho determina a quantidade de recursos de computação em cada cluster e, portanto, o número de créditos consumidos enquanto o warehouse está em funcionamento.

Para obter mais informações, consulte Redimensionamento de um warehouse.

Valores válidos:
  • XSMALL , 'X-SMALL'

  • SMALL

  • MEDIUM

  • LARGE

  • XLARGE , 'X-LARGE'

  • XXLARGE , X2LARGE , '2X-LARGE'

  • XXXLARGE , X3LARGE , '3X-LARGE'

  • X4LARGE , '4X-LARGE'

  • X5LARGE , '5X-LARGE'

  • X6LARGE , '6X-LARGE'

Padrão:

XLARGE

Nota

  • Os tamanhos XSMALL, SMALL, X5LARGE e X6LARGE não oferecem suporte aos warehouses otimizados para Snowpark. O tamanho padrão dos warehouses otimizados para Snowpark é MEDIUM.

  • Para usar um valor que contenha um hífen (por exemplo, '2X-LARGE'), você deve incluir o valor entre aspas simples, como mostrado.

  • Para bloquear o retorno imediato do comando ALTER WAREHOUSE até que o redimensionamento esteja completo, adicione o parâmetro WAIT_FOR_COMPLETION.

WAIT_FOR_COMPLETION = { TRUE | FALSE }

Ao redimensionar um warehouse, você pode usar este parâmetro para bloquear o retorno do comando ALTER WAREHOUSE até que o redimensionamento tenha terminado de provisionar todos os seus recursos de computação. Bloquear o retorno do comando ao redimensionar para warehouse de um tamanho maior serve para notificá-lo de que seus recursos de computação foram totalmente provisionados e o warehouse agora está pronto para executar consultas usando todos os novos recursos.

Valores válidos:
  • TRUE: o comando ALTER WAREHOUSE bloqueará até que o warehouse seja redimensionado.

  • FALSE: o comando ALTER WAREHOUSE retorna imediatamente, antes que o warehouse seja redimensionado.

Padrão:

FALSE

Nota

  • O valor deste parâmetro não é persistente e deve ser definido como TRUE em cada execução, se você quiser que o redimensionamento do warehouse seja concluído antes do retorno do comando.

  • Se ajustado como TRUE e você anular o comando ALTER WAREHOUSE, apenas a espera será anulada e o redimensionamento do warehouse será feito. Para redimensionar o warehouse de volta ao seu tamanho original, será necessário executar outro comando ALTER WAREHOUSE.

  • Este parâmetro deve ser utilizado com o parâmetro WAREHOUSE_SIZE, caso contrário, será lançada uma exceção.

MAX_CLUSTER_COUNT = num

Especifica o número máximo de clusters para um warehouse multicluster. Para um warehouse monocluster, este valor é sempre 1.

Valores válidos:

1 a 10

Observe que especificar um valor maior que 1 indica que o warehouse é um warehouse multicluster; entretanto, o valor só pode ser definido para um valor maior no Snowflake Enterprise Edition (ou superior).

Para obter mais informações, consulte Warehouses multicluster.

Padrão:

1 (warehouse monocluster)

Dica

Para o Snowflake Enterprise Edition (ou superior), recomendamos sempre definir o valor como maior que 1 para ajudar a manter a alta disponibilidade e o ótimo desempenho de um warehouse (multicluster). Isso também ajuda a garantir a continuidade no improvável caso de falha de um cluster.

MIN_CLUSTER_COUNT = num

Especifica o número mínimo de clusters para um warehouse multicluster.

Valores válidos:

1 a 10

Observe, no entanto, que MIN_CLUSTER_COUNT deve ser igual ou menor que MAX_CLUSTER_COUNT:

  • Se ambos os parâmetros forem iguais, o warehouse funciona no modo maximizado.

  • Se MIN_CLUSTER_COUNT for menor que MAX_CLUSTER_COUNT, o warehouse funcionará no modo Dimensionamento automático.

Para obter mais informações, consulte Warehouses multicluster.

Padrão:

1

SCALING_POLICY = { STANDARD | ECONOMY }

Parâmetro de objeto que especifica a política para iniciar e fechar automaticamente os clusters em um warehouse multicluster funcionando em modo Dimensionamento automático.

Para uma descrição detalhada deste parâmetro, consulte Como definir a política de escalonamento para um warehouse multicluster.

AUTO_SUSPEND = { num | NULL }

Especifica o número de segundos de inatividade após os quais um warehouse é automaticamente suspenso.

Valores válidos:

Qualquer número inteiro maior ou igual a 0, ou NULL:

  • É permitido definir um valor menor que 60, mas pode não resultam no comportamento desejado/esperado porque o processo em segundo plano que suspende um warehouse é executado aproximadamente a cada 60 segundo e, portanto, não se destina a permitir o controle exato da suspensão do warehouse.

  • A definição de um valor 0 ou NULL significa que o warehouse nunca é suspenso.

Padrão:

600 (o warehouse é suspenso automaticamente após 10 minutos de inatividade)

Importante

A configuração AUTO_SUSPEND como 0 ou NULL não é recomendada, a menos que suas cargas de trabalho de consulta exijam um warehouse em funcionamento contínuo. Note que isso pode resultar em um consumo significativo de créditos (e encargos relacionados), especialmente em warehouses maiores.

Para obter mais detalhes, consulte Considerações sobre warehouses.

AUTO_RESUME = { TRUE | FALSE }

Especifica se deve retomar automaticamente um warehouse quando uma instrução SQL (por exemplo, consulta) é enviada a ele. Se FALSE, o warehouse só começará novamente quando explicitamente retomado usando ALTER WAREHOUSE ou através da interface da web do Snowflake.

Valores válidos:
  • TRUE: o warehouse é retomado quando uma nova consulta é enviada.

  • FALSE: o warehouse só é retomado quando retomado explicitamente usando ALTER WAREHOUSE ou através da interface da web do Snowflake.

Padrão:

TRUE (o warehouse é retomado automaticamente quando uma instrução SQL é enviada a ele)

INITIALLY_SUSPENDED = { TRUE | FALSE }

Não aplicável quando se altera um warehouse

RESOURCE_MONITOR = monitor_name

Especifica o identificador de um monitor de recursos que é explicitamente atribuído ao warehouse. Quando um monitor de recursos é explicitamente atribuído a um warehouse, o monitor controla os créditos mensais usados pelo warehouse (e todos os outros warehouses aos quais o monitor é atribuído).

Valores válidos:

Qualquer monitor de recursos existente.

Para obter mais detalhes, consulte Como trabalhar com monitores de recursos.

Padrão:

Sem valor (sem monitor de recursos atribuído ao warehouse)

Dica

Para ver todos os monitores de recursos e seus identificadores, use o comando SHOW RESOURCE MONITORS.

COMMENT = 'string_literal'

Adiciona um comentário ou substitui um comentário existente para o warehouse.

MAX_CONCURRENCY_LEVEL = num

Parâmetro de objeto que especifica o nível de concorrência para instruções SQL (ou seja, consultas e DML) executadas por um cluster do warehouse. Quando o nível for atingido:

  • Para um warehouse monocluster ou um warehouse multicluster (no modo Maximizado), instruções adicionais são colocadas em fila até que os recursos estejam disponíveis.

  • Para um warehouse multicluster (em modo Dimensionanento automático), são iniciados clusters adicionais.

Este parâmetro pode ser usado em conjunto com STATEMENT_QUEUED_TIMEOUT_IN_SECONDS para garantir que um warehouse nunca fique em atraso.

Para uma descrição detalhada deste parâmetro, consulte MAX_CONCURRENCY_LEVEL.

STATEMENT_QUEUED_TIMEOUT_IN_SECONDS = num

Parâmetro do objeto que especifica a hora, em segundos, uma instrução SQL (consulta, DDL, DML etc.) pode ser colocada em fila em um warehouse antes de ser cancelada pelo sistema.

Este parâmetro pode ser usado em conjunto com MAX_CONCURRENCY_LEVEL para garantir que um warehouse nunca fique em atraso.

Para uma descrição detalhada deste parâmetro, consulte STATEMENT_QUEUED_TIMEOUT_IN_SECONDS.

STATEMENT_TIMEOUT_IN_SECONDS = num

Parâmetro de objeto que especifica a hora, em segundos, após a qual uma instrução SQL em execução (consulta, DDL, DML etc.) é cancelada pelo sistema.

Para uma descrição detalhada deste parâmetro, consulte STATEMENT_TIMEOUT_IN_SECONDS.

TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]

Especifica o nome da tag e o valor da cadeia de caracteres dela.

O valor de tag é sempre uma cadeia de caracteres, e o número máximo de caracteres do valor da tag é 256.

Para obter informações sobre como especificar tags em uma instrução, consulte Cotas de tags para objetos e colunas.

ENABLE_QUERY_ACCELERATION = { TRUE | FALSE }

Especifica se deve habilitar o Query Acceleration Service para consultas que dependem deste warehouse para computar os recursos.

Valores válidos:
  • TRUE habilita o Query Acceleration

  • FALSE Desabilita o Query Acceleration

Padrão:

FALSE: Query Acceleration está desativado

QUERY_ACCELERATION_MAX_SCALE_FACTOR = num

Especifica o fator de escala máximo para emprestar recursos de computação para aceleração da consulta. O fator de escala é utilizado como multiplicador baseado no tamanho do warehouse.

Definir o QUERY_ACCELERATION_MAX_SCALE_FACTOR como 0 elimina o limite e permite que as consultas peguem emprestado tantos recursos quantos forem necessários e disponíveis para atender à consulta.

Independentemente do valor QUERY_ACCELERATION_MAX_SCALE_FACTOR, a quantidade de recursos de computação disponíveis para aceleração da consulta é limitada pelos recursos disponíveis no serviço e pelo número de outras solicitações simultâneas. Para obter mais detalhes, consulte Ajuste do fator de escala.

Valores válidos:

0 a 100

Padrão:

8

UNSET ...

Especifica uma (ou mais) propriedades e/ou parâmetros a serem removidos da definição para o banco de dados, que os redefine aos padrões:

  • property_name

  • param_name

    • TAG tag_name [ , tag_name ... ]

Você pode redefinir várias propriedades/parâmetros com uma única instrução ALTER; no entanto, cada propriedade/parâmetro deve ser separado por uma vírgula. Além disso, ao reiniciar uma propriedade/parâmetro, você especifica apenas o nome; não é necessário nenhum valor.

Nota

UNSET pode ser usado para remover todas as propriedades e parâmetros de um warehouse, exceto WAREHOUSE_SIZE, que só pode ser alterado usando SET.

Requisitos de controle de acesso

Uma função usada para executar esse comando SQL deve ter pelo menos um dos seguintes privilégios, no mínimo:

Privilégio

Objeto

Notas

APPLY

Tag

Permite definir uma tag em um warehouse.

MODIFY

Warehouse

Permite alterar quaisquer propriedades de um warehouse, incluindo alterar seu tamanho. Necessário para atribuir um warehouse a um monitor de recursos. Somente a função ACCOUNTADMIN pode atribuir warehouses a monitores de recursos.

MONITOR

Warehouse

Permite exibir consultas atuais e passadas executadas em um warehouse, assim como estatísticas de uso do warehouse.

OPERATE

Warehouse

Permite mudar o estado de um warehouse (parar, iniciar, suspender, retomar) e permite exibir consultas atuais e passadas executadas em um warehouse e cancelar qualquer consulta em execução.

USAGE

Warehouse

Permite utilizar um warehouse virtual e, como resultado, executar consultas no warehouse. Se o warehouse for configurado para retomada automática quando uma instrução SQL (por exemplo, consulta) for enviada a ele, o warehouse é retomado automaticamente e executa a instrução.

Dica

A concessão do privilégio global MANAGE WAREHOUSES é equivalente a conceder os privilégios MODIFY, MONITOR e OPERATE em todos os warehouses em uma conta. Você pode conceder esse privilégio a uma função cuja finalidade inclua o gerenciamento de um warehouse para simplificar o gerenciamento de controle de acesso do Snowflake.

Para obter mais detalhes, consulte Como delegar o gerenciamento do warehouse.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso

  • Um warehouse não precisa ser suspenso para definir ou alterar qualquer uma de suas propriedades, exceto o tipo.

  • Para alterar o tipo do warehouse, ele deve estar no estado suspended. Execute a seguinte instrução para suspender um warehouse:

    ALTER WAREHOUSE mywh SUSPEND;
    
    Copy
  • Quando o tamanho do warehouse é alterado, a alteração não afeta nenhuma instrução, incluindo consultas, que estejam sendo executadas atualmente. Uma vez que as instruções estejam completas e os recursos de computação estejam totalmente provisionados, o novo tamanho é usado para todas as instruções subsequentes.

  • Suspender um warehouse não aborta qualquer consulta sendo processada pelo warehouse no momento em que ele é suspenso. Em vez disso, o warehouse conclui as consultas, depois desliga os recursos de computação utilizados para processar as consultas. Durante este período, o warehouse está no modo desativação. Quando todos os recursos de computação são desligados, o status do warehouse muda para Suspenso.

  • Em relação aos metadados:

    Atenção

    Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

  • A retomada de um warehouse virtual otimizado para Snowpark pode demorar mais do que os warehouses padrão.

  • Os warehouses otimizados para Snowpark não oferecem suporte a Query Acceleration.

  • Os warehouses otimizados para Snowpark não são suportados em tamanhos de warehouse XSMall, SMALL, X5LARGE ou X6LARGE.

  • A especificação da cláusula IF EXISTS exige que a função em uso ou uma função na hierarquia de funções ativas tenha os privilégios apropriados do warehouse no warehouse.

Exemplos

Renomear warehouse wh1 como wh2:

ALTER WAREHOUSE IF EXISTS wh1 RENAME TO wh2;
Copy

Retomar um warehouse chamado my_wh e depois mudar o tamanho do warehouse enquanto ele estiver em execução:

ALTER WAREHOUSE my_wh RESUME;

ALTER WAREHOUSE my_wh SET warehouse_size=MEDIUM;
Copy