EXECUTE JOB SERVICE¶
Nota
Esta operação não é atualmente coberta pelo nível de serviço definido na Política de suporte e Acordo de nível de serviço da Snowflake.
Executa um serviço do Snowpark Container Services como um trabalho.
Um serviço criado usando CREATE SERVICE é de longa duração e você deve interrompê-lo explicitamente quando não for mais necessário. Por outro lado, um trabalho criado usando EXECUTE JOB SERVICE é um serviço que termina quando seu código sai, semelhante a um procedimento armazenado. Quando todos os contêineres saírem, o trabalho estará concluído.
Por padrão, o trabalho é executado de forma síncrona; o comando EXECUTE JOB SERVICE é concluído somente após a saída de todos os contêineres. Após a conclusão do trabalho, o Snowflake realiza automaticamente a limpeza necessária. No entanto, essa limpeza não é imediata, pois o Snowflake retém o trabalho por um curto período para permitir que os clientes monitorem e depurem o serviço de trabalho após a execução.
Como alternativa, você pode executar o serviço de trabalho de forma assíncrona especificando o parâmetro opcional ASYNC
. Nesse caso, o comando retorna imediatamente enquanto o trabalho está em execução. Você pode usar o comando DESCRIBE SERVICE para sondar a conclusão do trabalho e, em seguida, chamar a função SYSTEM$WAIT_FOR_SERVICES para aguardar a conclusão do trabalho.
Para trabalhos assíncronos, o Snowflake não realiza a limpeza automática após a conclusão. Você deve executar explicitamente o comando DROP SERVICE para remover o trabalho.
Quando o trabalho for concluído, se nenhum outro trabalho ou serviço estiver em execução nesse nó do pool de computação, o Snowflake poderá considerar que o nó está ocioso e recuperá-lo. Quando isso acontecer, SYSTEM$GET_SERVICE_LOGS não retornará logs de contêineres locais dos contêineres de trabalho. Você pode considerar a persistência dos logs do contêiner em uma tabela de eventos. Para obter mais informações, consulte Acesso aos logs de contêiner.
Observe que os parâmetros do comando devem ser especificados em uma ordem específica. Para obter mais informações, consulte Notas de uso.
- Consulte também:
SYSTEM$GET_SERVICE_STATUS — Obsoleto , SYSTEM$GET_SERVICE_LOGS
Sintaxe¶
EXECUTE JOB SERVICE
IN COMPUTE POOL <compute_pool_name>
{
fromSpecification
| fromSpecificationTemplate
}
NAME = [<db>.<schema>.]<name>
[ ASYNC = { TRUE | FALSE } ]
[ QUERY_WAREHOUSE = <warehouse_name> ]
[ COMMENT = '<string_literal>']
[ EXTERNAL_ACCESS_INTEGRATIONS = ( <EAI_name> [ , ... ] ) ]
[ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
Onde:
fromSpecification ::= { FROM @<stage> SPECIFICATION_FILE = '<yaml_file_stage_path>' | FROM SPECIFICATION <specification_text> }fromSpecificationTemplate ::= { FROM @<stage> SPECIFICATION_TEMPLATE_FILE = '<yaml_file_stage_path>' | FROM SPECIFICATION_TEMPLATE <specification_text> } USING ( <key> => <value> [ , <key> => <value> [ , ... ] ] )
Parâmetros obrigatórios¶
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 stage
Especifica o estágio interno do Snowflake onde o arquivo de especificação está armazenado; por exemplo,
@tutorial_stage
.SPECIFICATION_FILE = 'yaml_file_stage_path'
Especifica o caminho para o arquivo de especificação de serviço no estágio; por exemplo,
'some-dir/echo_spec.yaml'
.SPECIFICATION_TEMPLATE_FILE = 'yaml_file_stage_path'
Especifica o caminho para o arquivo de modelo de especificação de serviço no estágio; por exemplo,
'some-dir/echo_template_spec.yaml'
. QuandoSPECIFICATION_TEMPLATE_FILE
é especificado, o parâmetroUSING
é obrigatório.FROM SPECIFICATION specification_text
Especifica a especificação de serviço. Você pode usar um par de cifrões (
$$
) para delimitar o início e o fim da cadeia de caracteres de especificação.FROM SPECIFICATION_TEMPLATE specification_text
Especifica a especificação de serviço. Você pode usar um par de cifrões (
$$
) para delimitar o início e o fim da cadeia de caracteres de especificação. QuandoSPECIFICATION_TEMPLATE
é especificado, o parâmetroUSING
é obrigatório.NAME = [db.schema.]name
O nome (que é o identificador) do serviço, que é executado como um trabalho; ele 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.
Parâmetros opcionais¶
ASYNC = { TRUE | FALSE }
Especifica se o trabalho deve ser executado de forma assíncrona.
Padrão: FALSE
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. Esse parâmetro também oferece suporte a referências de objeto em Native Apps. Para obter mais informações, consulte Solicitação de referências e privilégios de nível de objeto de consumidores.
Padrão: nenhum.
EXTERNAL_ACCESS_INTEGRATIONS = ( EAI_name [ , ... ] )
Especifica os nomes das integrações de acesso externo que permitem que seu trabalho 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 trabalho acesse um site externo, crie uma integração de acesso externo (EAI) e configure seu trabalho para usar essa integração. Para obter mais informações, consulte Configuração da saída da rede.
COMMENT = 'string_literal'
Especifica um comentário para o serviço.
Padrão: sem valor
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 Cota de tags para objetos.
USING ( key => value [ , key => value [ , ... ] ] )
Permite que você forneça valores para parametrizar a expansão do modelo de especificação.
USING
é necessário ao usar um modelo de especificação (FROM SPECIFICATION_TEMPLATE_FILE
ouFROM SPECIFICATION_TEMPLATE
). Os pares chave-valor devem formar uma lista separada por vírgulas.Onde:
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.
Requisitos de controle de acesso¶
A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:
Privilégio |
Objeto |
Notas |
---|---|---|
CREATE SERVICE |
Esquema |
|
USAGE |
Pool de computação |
|
READ |
Estágio |
Este é o estágio onde a especificação é armazenada. |
READ |
Repositório de imagens |
Repositório de imagens referenciadas pela especificação. |
O privilégio USAGE no banco de dados e no esquema pai é necessário para executar operações em qualquer objeto de um esquema.
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 EXECUTE JOB SERVICE, os parâmetros devem ser fornecidos nesta ordem: especifique o pool de computação, seguido por outras propriedades e, finalmente, a especificação do serviço (forneça o nome do arquivo de especificação no estágio ou a especificação em linha).
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¶
Execute um serviço de trabalho do Snowpark Container Services de forma assíncrona:
EXECUTE JOB SERVICE
IN COMPUTE POOL tutorial_compute_pool
NAME = tutorial_db.data_schema.example_job
ASYNC = TRUE
FROM @tutorial_stage
FROM SPECIFICATION $$
<job specification>
$$;
Execute um serviço de trabalho com o armazenamento em bloco montado:
EXECUTE JOB SERVICE
IN COMPUTE POOL tutorial_compute_pool
NAME=tutorial_job_service
FROM SPECIFICATION $$
spec:
container:
- name: main
image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
volumeMounts:
- name: block-vol1
mountPath: /opt/block/path
volumes:
- name: block-vol1
source: block
size: 10Gi
blockConfig:
iops: 4000
throughput: 200
$$
O comando não especifica o parâmetro opcional ASYNC
. Portanto, o Snowflake executa o comando de forma síncrona.