CREATE SERVICE¶

Sintaxe¶

CREATE SERVICE [ IF NOT EXISTS ] <name>
  IN COMPUTE POOL <compute_pool_name>
  {
     fromSpecification
     | fromSpecificationTemplate
  }
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <EAI_name> [ , ... ] ) ]
  [ AUTO_RESUME = { TRUE | FALSE } ]
  [ MIN_INSTANCES = <num> ]
  [ MIN_READY_INSTANCES = <num> ]
  [ MAX_INSTANCES = <num> ]
  [ QUERY_WAREHOUSE = <warehouse_name> ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ COMMENT = '{string_literal}']

Onde:

fromSpecification ::=
  {
    FROM SPECIFICATION_FILE = '<yaml_file_path>' -- for native app service.
    | FROM @<stage> SPECIFICATION_FILE = '<yaml_file_path>' -- for non-native app service.
    | FROM SPECIFICATION <specification_text>
  }

Copy

fromSpecificationTemplate ::=
  {
    FROM SPECIFICATION_TEMPLATE_FILE = '<yaml_file_stage_path>' -- for native app service.
    | FROM @<stage> SPECIFICATION_TEMPLATE_FILE = '<yaml_file_stage_path>' -- for non-native app service.
    | FROM SPECIFICATION_TEMPLATE <specification_text>
  }
  USING ( <key> => <value> [ , <key> => <value> [ , ... ] ]  )

Copy

Parâmetros obrigatórios¶

name

Cadeia de caracteres que especifica o identificador (ou seja, o nome) do serviço; deve ser exclusivo para o esquema no qual o serviço é criado.

Nomes entre aspas para caracteres especiais ou nomes que diferenciam maiúsculas de minúsculas não são suportados. A mesma restrição também se aplica a nomes de bancos de dados e esquemas onde você cria um serviço. Ou seja, nomes de bancos de dados e esquemas sem aspas são válidos na criação de um serviço.

IN COMPUTE POOL compute_pool_name

Especifica o nome do pool de computação na sua conta no qual o serviço será executado.

FROM ...

Identifica a especificação ou a especificação de modelo para o serviço.

Como usar uma especificação de serviço

É possível definir a especificação em linha ou em um arquivo separado.

SPECIFICATION_FILE = 'yaml_file_path' ou . @stage SPECIFICATION_FILE = 'yaml_file_path' ou . SPECIFICATION specification_text

Especifica o arquivo com a especificação do serviço ou a especificação do serviço em linha. Se a especificação do serviço estiver em um arquivo, use SPECIFICATION_FILE. Para serviços criados em um Snowflake Native App, omita @stage e especifique um caminho relativo ao diretório raiz do aplicativo. Para serviços criados em outros contextos, especifique o estágio interno do Snowflake e o caminho para o arquivo de especificação de serviço.

Como usar um modelo de especificação de serviço

É possível definir a especificação do modelo em linha ou em um arquivo separado.

SPECIFICATION_TEMPLATE_FILE = 'yaml_file_path' ou . @stage SPECIFICATION_TEMPLATE_FILE = 'yaml_file_path' ou . SPECIFICATION_TEMPLATE specification_text

Especifica o arquivo com o modelo de especificação de serviço ou o modelo de especificação de serviço em linha. Se o modelo de especificação de serviço estiver em um arquivo, use SPECIFICATION_TEMPLATE_FILE. Para serviços criados em um Snowflake Native App, omita @stage e especifique um caminho relativo ao diretório raiz do aplicativo. Para serviços criados em outros contextos, especifique o estágio interno do Snowflake e o caminho para o arquivo de especificação de serviço. Ao usar a especificação de modelo, também é necessário incluir o parâmetro USING.

USING ( key => value [ , key => value [ , ... ] ]  )

Especifica as variáveis do modelo e os valores dessas variáveis.

• key é o nome da variável do modelo. O nome da variável do modelo pode, opcionalmente, ser colocado entre aspas duplas (").

• value é o valor a ser atribuído à variável no modelo. Os valores da cadeia de caracteres devem ser colocados entre ' ou $$. O valor deve ser alfanumérico ou JSON válido.

Use uma vírgula entre cada par chave-valor.

Parâmetros opcionais¶

EXTERNAL_ACCESS_INTEGRATIONS = ( EAI_name [ , ... ] )

Especifica os nomes das integrações de acesso externo que permitem que seu serviço acesse sites externos. Os nomes nesta lista diferenciam maiúsculas de minúsculas. Por padrão, os contêineres de aplicativos não têm permissão para acessar a internet. Se você quiser permitir que seu serviço acesse um site externo, crie uma integração de acesso externo (EAI) e configure seu serviço para usar essa integração. Para obter mais informações, consulte Saída de rede.

AUTO_RESUME = { TRUE | FALSE }

Especifica se um serviço deve ser retomado automaticamente quando uma função de serviço ou entrada é chamada.

• Se AUTO_RESUME for FALSE, você precisará retomar explicitamente o serviço (usando ALTER SERVICE … RESUME).

• Se AUTO_RESUME for TRUE, o Snowflake retoma o serviço suspenso quando uma função de serviço é chamada ou quando uma solicitação é recebida (entrada).

MIN_INSTANCES = num

Especifica o número mínimo de instâncias de serviço a serem executadas.

Padrão: 1

MIN_READY_INSTANCES = num

Indica as instâncias mínimas de serviço que devem estar prontas para que o Snowflake considere que o serviço está pronto para processar solicitações. MIN_READY_INSTANCES deve ser igual ou menor que MIN_INSTANCES.

Nota

Após criar um serviço, se você quiser usar o comando SHOW SERVICES ou DESCRIBE SERVICE para encontrar o MIN_READY_INSTANCES configurado para o serviço, é necessário habilitar o pacote de mudança de comportamento 2024_08 em sua conta. Para ativar este pacote em sua conta, execute a seguinte instrução:

SELECT SYSTEM$ENABLE_BEHAVIOR_CHANGE_BUNDLE('2024_08');

Copy

Funciona da seguinte forma: Suponha que MIN_INSTANCES esteja definido como três para um serviço. Então, o Snowflake não considera o serviço como READY até que pelo menos três instâncias estejam disponíveis. Enquanto o serviço não estiver pronto, o Snowflake bloqueia o acesso a ele, o que significa que as funções de serviço associadas ou solicitações de entrada serão negadas até que a prontidão seja confirmada.

Em alguns casos, você pode querer que o Snowflake considere o serviço pronto (e encaminhe solicitações recebidas), mesmo que haja menos instâncias disponíveis do que o mínimo especificado. É possível conseguir isso configurando a propriedade MIN_READY_INSTANCES.

Considere outro cenário: Durante a manutenção ou uma atualização contínua do serviço, o Snowflake pode encerrar uma ou mais instâncias de serviço. Isso pode levar a menos instâncias disponíveis do que o MIN_INSTANCES especificado, fazendo com que o serviço não fique em um estado READY. Nesses casos, talvez você queira definir um valor MIN_READY_INSTANCES menor que MIN_INSTANCES para garantir que o serviço possa continuar aceitando solicitações.

Padrão: O valor da propriedade MIN_INSTANCES.

MAX_INSTANCES = num

Especifica o número máximo de instâncias de serviço a serem executadas.

Padrão: O valor da propriedade MIN_INSTANCES.

QUERY_WAREHOUSE = warehouse_name

Warehouse a ser usado se um contêiner de serviço se conectar ao Snowflake para executar uma consulta, mas não especificar explicitamente um warehouse a ser usado.

Padrão: nenhum.

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.

COMMENT = 'string_literal'

Especifica um comentário para o serviço.

Padrão: sem valor

Requisitos de controle de acesso¶

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

Observe que operar em qualquer objeto de um esquema também requer o privilégio USAGE no banco de dados e esquema principais.

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¶

• Ao chamar CREATE SERVICE, os parâmetros devem ser fornecidos nesta ordem: especifique o pool de computação, seguido pela especificação do serviço (arquivo de especificação do provedor no estágio ou especificação em linha) e, em seguida, outras propriedades.

• 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.

Exemplos¶

Crie um serviço com duas instâncias de serviço em execução:

CREATE SERVICE echo_service
  IN COMPUTE POOL tutorial_compute_pool
  FROM @tutorial_stage
  SPECIFICATION_FILE='echo_spec.yaml'
  MIN_INSTANCES=2
  MAX_INSTANCES=2