Snowpark Container Services: execução de SQL¶

Opções de configuração de credenciais¶

A Snowflake recomenda que os contêineres de aplicativo usem credenciais fornecidas pelo Snowflake para autenticação no Snowflake ao executar SQL. É possível usar outras credenciais conectando-se por meio de uma integração de acesso externo (External Access Integration, EAI), mas a conexão por meio de uma EAI considera que o serviço está sendo executado fora do Snowflake e usa uma conexão de internet para se conectar ao Snowflake.

Você tem três opções para se conectar ao Snowflake de um contêiner de serviço:

• Usar as credenciais de usuário de serviço fornecidas pelo Snowflake: o Snowflake fornece a cada serviço credenciais chamadas de «credenciais de serviço». Um serviço usa essas credenciais para se conectar ao Snowflake como usuário do serviço.

• Usar as credenciais de autor da chamada fornecidas pelo Snowflake (direitos do autor da chamada): quando você configura seu serviço com direitos do autor da chamada, o Snowflake também fornece credenciais para que o serviço se conecte ao Snowflake como o usuário que faz a chamada.

• Usar outras credenciais: nesse caso, você usa uma integração de acesso externo (EAI) que permite que seu serviço se conecte ao ponto de extremidade de internet do Snowflake usando credenciais de autenticação válidas. Essa opção requer que um administrador crie a EAI e, em seguida, conceda o privilégio USAGE na integração à função de proprietário do serviço.

  Nota

  Se você usar integrações de acesso externo para acessar o Snowflake, poderá enviar informações potencialmente confidenciais pela Internet.

Para obter exemplos de código que usa vários drivers do Snowflake para se conectar ao Snowflake, consulte Amostras de conexão com o Snowflake.

SNOWFLAKE_ACCOUNT = os.getenv('SNOWFLAKE_ACCOUNT')
SNOWFLAKE_HOST = os.getenv('SNOWFLAKE_HOST')

def get_login_token():
  with open('/snowflake/session/token', 'r') as f:
    return f.read()

conn = snowflake.connector.connect(
  host = os.getenv('SNOWFLAKE_HOST'),
  account = os.getenv('SNOWFLAKE_ACCOUNT'),
  token = get_login_token(),
  authenticator = 'oauth'
)

ALTER USER my_user SET DEFAULT_SECONDARY_ROLES = ( 'ALL' );

-- Permissions to resolve the table's name.
GRANT CALLER USAGE ON DATABASE <db_name> TO ROLE <service_owner_role>;
GRANT CALLER USAGE ON SCHEMA <schema_name> TO ROLE <service_owner_role>;
-- Permissions to use a warehouse
GRANT CALLER USAGE ON WAREHOUSE <warehouse_name> TO ROLE <service_owner_role>;
-- Permissions to query the table.
GRANT CALLER SELECT ON TABLE T1 TO ROLE <service_owner_role>;

conn = snowflake.connector.connect(
  account = '<acct-name>',
  user = '<user-name>',
  password = '<password>'
)

Configuração do contexto de banco de dados e esquema para execução de SQL¶

Além de fornecer as credenciais, o Snowflake fornece o contexto de banco de dados e esquema no qual o serviço é criado. O código do contêiner pode usar essa informação para executar SQL no mesmo contexto de banco de dados e esquema que o serviço.

Esta seção explica dois conceitos:

• A lógica que o Snowflake usa para determinar o banco de dados e o esquema no qual criar seu serviço.

• O método pelo qual o Snowflake transmite essas informações aos seus contêineres, permitindo assim que o código do contêiner execute SQL no mesmo banco de dados e contexto de esquema.

O Snowflake usa o nome do serviço para determinar o banco de dados e o esquema no qual criar um serviço:

• Exemplo 1: nos seguintes comandos CREATE SERVICE e EXECUTE JOB SERVICE, o nome do serviço não especifica explicitamente um nome de banco de dados e esquema. O Snowflake cria o serviço e o serviço de trabalho no banco de dados e esquema atuais.

  -- Create a service.
  CREATE SERVICE test_service IN COMPUTE POOL ...
  
  -- Execute a job service.
  EXECUTE JOB SERVICE
    IN COMPUTE POOL tutorial_compute_pool
    NAME = example_job_service ...
  

  Copy

• Exemplo 2: nos seguintes comandos CREATE SERVICE e EXECUTE JOB SERVICE, o nome do serviço inclui um nome de banco de dados e esquema. Snowflake cria o serviço e serviço do trabalho no banco de dados (test_db) e esquema (test_schema) especificados, independentemente do esquema atual.

  -- Create a service.
  CREATE SERVICE test_db.test_schema.test_service IN COMPUTE POOL ...
  
  -- Execute a job service.
  EXECUTE JOB SERVICE
    IN COMPUTE POOL tutorial_compute_pool
    NAME = test_db.test_schema.example_job_service ...
  

  Copy

Quando o Snowflake inicia um serviço, ele fornece informações de banco de dados e esquema para os contêineres em execução usando as seguintes variáveis de ambiente:

• SNOWFLAKE_DATABASE

• SNOWFLAKE_SCHEMA

O código do contêiner pode usar variáveis de ambiente no código de conexão para determinar qual banco de dados e esquema usar, conforme mostrado neste exemplo:

conn = snowflake.connector.connect(
  host = os.getenv('SNOWFLAKE_HOST'),
  account = os.getenv('SNOWFLAKE_ACCOUNT'),
  token = get_login_token(),
  authenticator = 'oauth',
  database = os.getenv('SNOWFLAKE_DATABASE'),
  schema = os.getenv('SNOWFLAKE_SCHEMA')
)

Exemplo

No Tutorial 2, você cria um serviço de trabalho do Snowflake que se conecta ao Snowflake e executa instruções SQL. As etapas a seguir resumem como o código do tutorial usa as variáveis de ambiente:

1. Na configuração comum (consulte a seção Configuração comum), você cria recursos, incluindo um banco de dados e um esquema. Você também define o banco de dados e o esquema atuais para a sessão:

   USE DATABASE tutorial_db;
   ...
   USE SCHEMA data_schema;
   

   Copy

2. Depois de criar um serviço de trabalho (executando EXECUTE JOB SERVICE), o Snowflake inicia o contêiner e define as seguintes variáveis de ambiente no contêiner para o banco de dados e o esquema atuais da sessão:

   • SNOWFLAKE_DATABASE é definido como “TUTORIAL_DB”

   • SNOWFLAKE_SCHEMA é definido como “DATA_SCHEMA”

3. O código do trabalho (consulte main.py no Tutorial 2) lê estas variáveis de ambiente:

   SNOWFLAKE_DATABASE = os.getenv('SNOWFLAKE_DATABASE')
   SNOWFLAKE_SCHEMA = os.getenv('SNOWFLAKE_SCHEMA')
   

   Copy

4. O código do trabalho define o banco de dados e o esquema como o contexto no qual executar as instruções SQL (função run_job() em main.py):

   {
      "account": SNOWFLAKE_ACCOUNT,
      "host": SNOWFLAKE_HOST,
      "authenticator": "oauth",
      "token": get_login_token(),
      "warehouse": SNOWFLAKE_WAREHOUSE,
      "database": SNOWFLAKE_DATABASE,
      "schema": SNOWFLAKE_SCHEMA
   }
   ...
   

   Copy

   Nota

   SNOWFLAKE_ACCOUNT, SNOWFLAKE_HOST, SNOWFLAKE_DATABASE, SNOWFLAKE_SCHEMA são variáveis de ambiente que o Snowflake gera para o contêiner do aplicativo, mas SNOWFLAKE_WAREHOUSE não é (o código do aplicativo do Tutorial 2 criou essa variável porque o Snowflake não passa um nome de warehouse para um contêiner).

Como especificar o warehouse para seu contêiner¶

Se seu serviço se conectar ao Snowflake para executar uma consulta em um warehouse do Snowflake, você terá as seguintes opções para especificar um warehouse:

• Especifique um warehouse no código do seu aplicativo. Especifique um warehouse como parte da configuração da conexão ao iniciar uma sessão do Snowflake para executar consultas no seu código. Para obter um exemplo, consulte Tutorial 2.

• Especifique um warehouse padrão ao criar um serviço. Especifique o parâmetro opcional QUERY_WAREHOUSE no comando CREATE SERVICE ou EXECUTE JOB SERVICE para fornecer um warehouse padrão. Se o código do seu aplicativo não fornecer um warehouse como parte da configuração da conexão, o Snowflake usará o warehouse padrão. Use o comando ALTER SERVICE para mudar o warehouse padrão.

  Nota

  O warehouse especificado usando o parâmetro QUERY_WAREHOUSE é o padrão somente para o usuário do serviço. Quando o serviço se conecta ao Snowflake em nome de outro usuário, no contexto do cenário de direitos do autor da chamada, o Snowflake usa o warehouse padrão do usuário.

Se você especificar um warehouse usando ambos os métodos, o warehouse especificado no código do aplicativo será usado.

Acessar o histórico de consultas do usuário do serviço¶

Encontre as consultas executadas pelo seu serviço como usuário do serviço filtrando a função Exibição QUERY_HISTORY ou QUERY_HISTORY, em que user_type is SNOWFLAKE_SERVICE.

Exemplo 1: Busca de consultas executadas por um serviço.

SELECT *
FROM snowflake.account_usage.query_history
WHERE user_type = 'SNOWFLAKE_SERVICE'
AND user_name = '<service_name>'
AND user_database_name = '<service_db_name>'
AND user_schema_name = '<service_schema_name>'
order by start_time;

Na cláusula WHERE:

• user_name = '<service_name>': você especifica o nome do serviço como o nome de usuário porque um serviço executa consultas como o usuário do serviço, e o nome do usuário do serviço é o mesmo que o nome do serviço.

• user_type = 'SNOWFLAKE_SERVICE' e user_name = '<service_name>': isso limita o resultado da consulta para recuperar apenas as consultas executadas por um serviço.

• user_database_name e user_schema_name: para um usuário do serviço, esses são o banco de dados e o esquema do serviço.

Você pode obter os mesmos resultados chamando a função QUERY_HISTORY.

SELECT *
FROM TABLE(<service_db_name>.information_schema.query_history())
WHERE user_database_name = '<service_db_name>'
AND user_schema_name = '<service_schema_name>'
AND user_type = 'SNOWFLAKE_SERVICE'
AND user_name = '<service_name>'
order by start_time;

Na cláusula WHERE:

• user_type = 'SNOWFLAKE_SERVICE' e user_name = '<service_name>' limitam o resultado da consulta para recuperar apenas as consultas executadas por um serviço.

• Os nomes user_database_name e user_schema_name (para um usuário de serviço) são o banco de dados e o esquema do serviço.

Exemplo 2: buscar consultas executadas por serviços e as informações de serviço correspondentes.

SELECT query_history.*, services.*
FROM snowflake.account_usage.query_history
JOIN snowflake.account_usage.services
ON query_history.user_name = services.service_name
AND query_history.user_schema_id = services.service_schema_id
AND query_history.user_type = 'SNOWFLAKE_SERVICE'

A consulta une as exibições QUERY_HISTORY e SERVICES para recuperar informações sobre as consultas e os serviços que executaram as consultas. Observe o seguinte:

• Para consultas executadas por serviços, query_history.user_name é o nome do usuário do serviço, que é o mesmo que o nome do serviço.

• A consulta une as exibições usando os IDs de esquema (não o nome do esquema) para garantir que você se refira ao mesmo esquema, porque se você remover e recriar um esquema, o ID do esquema será alterado, mas o nome permanecerá o mesmo.

Você pode adicionar filtros opcionais à consulta. Por exemplo:

• Filtre query_history para recuperar apenas serviços que executaram consultas específicas.

• Filtre services para recuperar apenas consultas executadas por serviços específicos.

Exemplo 3: Para cada serviço, busque informações do usuário do serviço.

SELECT services.*, users.*
FROM snowflake.account_usage.users
JOIN snowflake.account_usage.services
ON users.name = services.service_name
AND users.schema_id = services.service_schema_id
AND users.type = 'SNOWFLAKE_SERVICE'

A consulta une as exibições SERVICES e USERS no esquema ACCOUNT_USAGE para recuperar serviços e informações do usuário do serviço. Observe o seguinte:

• Quando um serviço executa consultas, ele as executa como usuário do serviço e o nome do usuário do serviço é o mesmo que o nome do serviço. Portanto, você especifica a condição de junção: users.name = services.service_name.

• Os nomes de serviço são exclusivos apenas dentro de um esquema. Portanto, a consulta especifica a condição de junção (users.schema_id = services.service_schema_id) para garantir que cada usuário do serviço seja correspondido ao serviço específico ao qual pertence (e não a qualquer outro serviço com o mesmo nome em execução em esquemas diferentes).