API Collaboration Snowflake Data Clean Rooms

Introdução

Esta é a página de referência da API Collaboration Snowflake Data Clean Rooms. Essa API usa os namespaces COLLABORATION e REGISTRY, e não os namespaces PROVIDER ou CONSUMER utilizados pelas APIs Provider e Consumer.

Nota

Você deve desabilitar as funções secundárias em seu ambiente ao usar a API Collaboration:

USE SECONDARY ROLES NONE;
Copy

Gerenciar o acesso à API Collaboration DCR

Os colaboradores podem usar a função de alto nível SAMOOHA_APP_ROLE para chamar todos os procedimentos da API Collaboration DCR.

Entretanto, recomendamos que os administradores concedam acesso mais granular a colaborações ou funções específicas, com base em suas necessidades. Você pode encontrar os privilégios mais granulares documentados em Procedimentos de gerenciamento de acesso.

Para conceder privilégios granulares de API a um usuário, siga estas etapas:

  1. Crie uma função.

  2. Conceda à função o uso no warehouse que está sendo usado.

  3. Chame GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE, se necessário, para conceder a uma função os privilégios apropriados em uma colaboração específica.

  4. Chame GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE, se necessário, para conceder à função os privilégios de alto nível apropriados em todas as colaborações na conta.

  5. Conceda a função ao usuário, que agora pode chamar procedimentos de colaboração para participar da colaboração.

Exemplo

Este é um exemplo de criação de duas funções da API Collaboration: uma função que pode criar e ingressar em colaborações, e outra função que pode visualizar recursos e executar análises em uma colaboração (mas não ingressar em ou modificar uma colaboração).

-- Create a role that can create and join collaborations.
USE ROLE ACCOUNTADMIN;
CREATE ROLE COLLABORATION_CREATOR_ROLE;
GRANT USAGE ON WAREHOUSE APP_WH TO COLLABORATION_CREATOR_ROLE;
GRANT APPLY ROW ACCESS POLICY ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE APPLICATION ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE DATABASE ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE LISTING ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE SHARE ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT IMPORT SHARE ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT MANAGE SHARE TARGET ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'COLLABORATION_CREATOR_ROLE');
GRANT ROLE COLLABORATION_CREATOR_ROLE TO USER george_washington;

-- Create a role that can run analyses on a specific collaboration.
USE ROLE COLLABORATION_CREATOR_ROLE;
CREATE ROLE ANALYST_ROLE;

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  'RUN',
  'COLLABORATION',
  $collaboration_name,
  'ANALYST_ROLE'
);

-- Also grant READ, which gives permission to read the resources available to use in a collaboration.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  'READ',
  'COLLABORATION',
  $collaboration_name,
  'ANALYST_ROLE'
);

GRANT ROLE ANALYST_ROLE to USER alexander_hamilton;
Copy

Folha de referências de metadados

Veja como encontrar algumas informações frequentemente buscadas sobre uma colaboração:

Para aprender isso…

Chame isto

Em quais colaborações eu posso ingressar?

VIEW_COLLABORATIONS. Procure por colaborações em que a coluna COLLABORATION_NAME seja NULL.

Em quais colaborações eu ingressei?

VIEW_COLLABORATIONS. Procure por colaborações em que a coluna COLLABORATION_NAME não seja NULL, o que pode significar que você criou ou ingressou na colaboração.

Quais colaborações são minhas?

VIEW_COLLABORATIONS. Procure na coluna OWNER_ACCOUNT.

Qual é o status de todos os colaboradores em uma colaboração?

GET_STATUS

Qual é meu status de ingressão ou criação de uma colaboração?

GET_STATUS ou VIEW_COLLABORATIONS

Quem é o proprietário de uma determinada colaboração?

GET_STATUS. Procure por OWNER na coluna ROLES.

Qual é minha função em uma determinada colaboração?

GET_STATUS. Procure na coluna ROLES.

Quais funções são atribuídas em uma determinada colaboração?

GET_STATUS. Procure na coluna ROLES.

Qual é a especificação em uma determinada colaboração?

VIEW_COLLABORATIONS. Procure na coluna COLLABORATION_SPEC.

A especificação está atualizada?

Não há como saber se uma determinada especificação tem alterações em andamento, mas você pode chamar VIEW_COLLABORATIONS para ver quando as últimas atualizações foram aplicadas.

Quais solicitações com atualizações pendentes eu tenho?

VIEW_UPDATE_REQUESTS. Procure as linhas em que STATUS = PENDING.

Mostrar para mim a especificação de uma determinada colaboração

REVIEW retorna a especificação da colaboração. Se você já chamou REVIEW ou ingressou na colaboração, chame o seguinte comando SQL pelo nome da colaboração conforme indicado:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS() ->>
  SELECT "COLLABORATION_SPEC" FROM $1
    WHERE "SOURCE_NAME" = <collaboration name>;
Copy

Procedimentos de modelos

REGISTER_TEMPLATE

Esquema:

REGISTRY

Registra um modelo para permitir que seja usado em uma colaboração. Cada modelo registrado deve ter um nome e uma versão exclusivos em todos os registros na sua conta.

Sintaxe

REGISTER_TEMPLATE( ['<registry_name>' ,] <template_spec> )
Copy

Argumentos

registry_name (opcional)

Nome de um registro personalizado no qual registrar o modelo. Se não for especificado, registra o modelo no registro da conta padrão.

template_spec

Definição do modelo no formato YAML, como uma cadeia de caracteres.

Retornos

O ID de um modelo para usar na especificação da colaboração.

Exemplos

Registrar um modelo no registro padrão:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_TEMPLATE(
  $$
  api_version: 2.0.0
  spec_type: template
  name: my_test_template
  version: 2026_01_12_V1
  type: sql_analysis
  description: A test template
  template:
    SELECT * FROM IDENTIFIER({{ source_table[0] }}) LIMIT 10;
$$);
Copy

Registrar um modelo em um registro personalizado:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_TEMPLATE(
  'my_custom_registry',
  $$
  api_version: 2.0.0
  spec_type: template
  name: my_test_template
  version: 2026_01_12_V1
  type: sql_analysis
  description: A test template
  template:
    SELECT * FROM IDENTIFIER({{ source_table[0] }}) LIMIT 10;
$$);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando os procedimentos a seguir.

Para registrar objetos no registro padrão:

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('REGISTER TEMPLATE', 'role name')

Para registrar itens em um registro personalizado:

  • Você tem privilégios de leitura e gravação em qualquer registro personalizado criado por você mesmo.

  • Para acessar um registro personalizado criado por outro usuário, você precisa de GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('REGISTER', 'REGISTRY', 'MY_REGISTRY', 'role name').

VIEW_REGISTERED_TEMPLATES

Esquema:

REGISTRY

Lista todos os modelos que você registrou. Para registrar um modelo, chame REGISTRY.REGISTER_TEMPLATE.

Sintaxe

VIEW_REGISTERED_TEMPLATES( [ '<registry_name>' ] )
Copy

Argumentos

registry_name (opcional)

Nome de um registro personalizado do qual listar os modelos. Se não for especificado, listará os modelos do registro de contas padrão.

Retornos

Uma tabela que lista os detalhes de todos os modelos que você registrou nesta conta.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.VIEW_REGISTERED_TEMPLATES();
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir.

Para ver os itens no registro padrão:

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('VIEW REGISTERED TEMPLATES', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Para ver os itens em um registro personalizado:

  • Você tem privilégios de leitura e gravação em qualquer registro personalizado criado por você mesmo.

  • Para acessar um registro personalizado criado por outro usuário, você precisa de GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'REGISTRY', 'MY_REGISTRY', 'role name').

ADD_TEMPLATE_REQUEST

Esquema:

COLLABORATION

Envia uma solicitação para adicionar um modelo a uma colaboração existente. Se o remetente for afetado pela solicitação, ele aprovará automaticamente a solicitação. Todos os outros colaboradores afetados devem aprovar a solicitação para que a alteração seja aplicada. Todos os colaboradores precisam chamar esse procedimento para adicionar um modelo a uma colaboração existente, até mesmo o proprietário da colaboração.

Para adicionar outros compartilhadores de modelo, você pode chamar esse procedimento novamente com os respectivos aliases. Cada chamada adiciona os usuários listados em share_with.

Para ver o status da solicitação, chame VIEW_UPDATE_REQUESTS.

Veja o fluxo de adição de modelo.

Sintaxe

ADD_TEMPLATE_REQUEST( <collaboration_name>, <template_id>, <share_with> )
Copy

Argumentos

collaboration_name

Nome da colaboração à qual o modelo será adicionado.

template_id

ID do modelo que será adicionado à colaboração. Registre o modelo para obter esse valor.

share_with

Matriz de aliases de executores de análise com quem compartilhar o modelo. Os colaboradores listados aqui serão adicionados além de todos os outros colaboradores associados ao modelo. Todos os colaboradores listados aqui devem ser executores de análise, ou o procedimento falhará sem compartilhar o modelo com ninguém.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

-- Ask to add the template only for Collaborator3 in this collaboration.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.ADD_TEMPLATE_REQUEST(
  $collaboration_name,
  $template_alias,
  ['Collaborator3']
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando os seguintes procedimentos:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • Um dos seguintes privilégios:

    • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name'), além de todos os privilégios adicionais no nível da conta que devem ser concedidos manualmente à função.

    • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name'), além de todos os privilégios adicionais no nível da conta que devem ser concedidos manualmente à função.

  • Se o modelo estiver em um registro personalizado, você também deverá ter GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE( 'READ', 'registry name', 'role name').

REMOVE_TEMPLATE

Esquema:

COLLABORATION

Solicitação assíncrona para remover um modelo de uma determinada colaboração para colaboradores especificados. Somente o colaborador que registrou o modelo pode remover um modelo. Nenhuma aprovação é necessária de outra pessoa para remover um modelo que você registrou. Quando um modelo é removido de um colaborador, esse colaborador não pode ver ou exibir o modelo.

Sintaxe

REMOVE_TEMPLATE( <collaboration_name>, <template_id>, <remove_for> )
Copy

Argumentos

collaboration_name

Nome da colaboração da qual remover o modelo.

template_id

ID do modelo para remover da colaboração.

remove_for

Matriz de um ou mais aliases de executores de análise nesta colaboração que não poderão mais ver ou usar este modelo.

Retornos

Uma mensagem de sucesso de cadeia de caracteres. Para ver se um modelo foi removido de um colaborador, exiba a especificação da colaboração.

Exemplo

-- Prevent collaborator_1234 from using the specified template
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.REMOVE_TEMPLATE(
  $collaboration_name,
  $template_id,
  ['collaborator_1234']
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando os seguintes procedimentos:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • Um dos seguintes privilégios:

    • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name'), além de todos os privilégios adicionais no nível da conta que devem ser concedidos manualmente à função.

    • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name'), além de todos os privilégios adicionais no nível da conta que devem ser concedidos manualmente à função.

  • Se o modelo estiver em um registro personalizado ou fizer referência a uma especificação de código em um registro personalizado, você também deverá ter GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE( 'READ', 'registry name', 'role name').

VIEW_TEMPLATES

Esquema:

COLLABORATION

Mostra todos os modelos que você pode executar ou que enviou para a colaboração especificada.

Sintaxe

VIEW_TEMPLATES( <collaboration_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração. Você deve revisar ou ingressar na colaboração antes de listar seus modelos.

Retornos

Uma tabela que lista informações sobre os modelos que você pode executar nesta colaboração, incluindo os que você registrou. As informações incluem o ID do modelo (usado para executar o modelo), o corpo do modelo, os parâmetros, quem o criou e quem pode executá-lo.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_TEMPLATES(
  $collaboration_name
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('VIEW TEMPLATES', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

ENABLE_TEMPLATE_AUTO_APPROVAL

Esquema:

COLLABORATION

Faz com que todas as solicitações de atualização de modelo enviadas por outros colaboradores sejam aprovadas automaticamente. As solicitações ainda aparecerão no log de solicitações. Isso afeta apenas as solicitações enviadas depois que a aprovação automática foi habilitada.

Sintaxe

ENABLE_TEMPLATE_AUTO_APPROVAL( <collaboration_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.ENABLE_TEMPLATE_AUTO_APPROVAL(
  $collaboration_name
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE TEMPLATE AUTO APPROVAL', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

DISABLE_TEMPLATE_AUTO_APPROVAL

Esquema:

COLLABORATION

Desabilita a aprovação automática para solicitações de modelo feitas por outros colaboradores. Todas as solicitações futuras devem ser aprovadas manualmente chamando APPROVE_UPDATE_REQUEST.

Sintaxe

DISABLE_TEMPLATE_AUTO_APPROVAL( <collaboration_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.DISABLE_TEMPLATE_AUTO_APPROVAL(
  $collaboration_name
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE TEMPLATE AUTO APPROVAL', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Procedimentos de oferta de dados

REGISTER_DATA_OFFERING

Esquema:

REGISTRY

Registra uma oferta de dados para que ela possa ser adicionada a uma definição de colaboração. Não é possível cancelar o registro de uma oferta de dados registrada. Não é possível substituir uma oferta de dados existente, mas você pode registrar uma nova com o mesmo nome e uma nova versão. Criar uma nova versão de uma oferta de dados não remove as versões anteriores.

Cada oferta de dados deve ter um nome e uma versão exclusivos em todos os registros na sua conta.

Se você quiser compartilhar esta tabela com outras pessoas na colaboração, adicione-a à especificação da colaboração antes que a colaboração seja criada.

Você deve ter o privilégio OWNERSHIP em todos os dados que compartilha em uma colaboração. Caso contrário, você receberá um erro de «concessão de uso de referência ausente» ao tentar ingressar na colaboração ou registrar o objeto. Saiba como resolver esse problema.

Sintaxe

REGISTER_DATA_OFFERING( ['<registry_name>' ,] <data_offering_spec> )
Copy

Argumentos

registry_name (opcional)

Nome de um registro personalizado no qual registrar a oferta de dados. Se não for especificado, registra a oferta de dados no registro da conta padrão.

data_offering_spec

Uma definição de oferta de dados no formato YAML que descreve a oferta de dados.

Retornos

O ID da oferta de dados para usar no campo data_offerings.id de uma colaboração.

Exemplos

Registrar uma oferta de dados no registro padrão:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_DATA_OFFERING(
    $$
    api_version: 2.0.0
    spec_type: data_offering
    version: v1
    name: customers
    datasets:
     - alias: customers_1
       data_object_fqn: SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS
       allowed_analyses: template_only
       schema_and_template_policies:
         hashed_email:
           category: join_custom
         status:
           category: passthrough
    $$
  );
Copy

Registrar uma oferta de dados em um registro personalizado:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_DATA_OFFERING(
    'my_custom_registry',
    $$
    api_version: 2.0.0
    spec_type: data_offering
    version: v1
    name: customers
    datasets:
     - alias: customers_1
       data_object_fqn: SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS
       allowed_analyses: template_only
       schema_and_template_policies:
         hashed_email:
           category: join_custom
         status:
           category: passthrough
    $$
  );
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando os procedimentos a seguir.

Para registrar uma oferta de dados no registro padrão:

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('REGISTER DATA OFFERING', 'role name')

Para registrar itens em um registro personalizado:

  • Você tem privilégios de leitura e gravação em qualquer registro personalizado criado por você mesmo.

  • Para acessar um registro personalizado criado por outro usuário, você precisa de GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('REGISTER', 'REGISTRY', 'MY_REGISTRY', 'role name').

VIEW_REGISTERED_DATA_OFFERINGS

Esquema:

REGISTRY

Lista todas as ofertas de dados que você registrou. Para visualizar as ofertas de dados em uma colaboração adicionada por outras pessoas, chame COLLABORATION.VIEW_DATA_OFFERINGS.

Sintaxe

VIEW_REGISTERED_DATA_OFFERINGS( [ '<registry_name>' ] )
Copy

Argumentos

registry_name (opcional)

Nome de um registro personalizado do qual listar as ofertas de dados. Se não for especificado, listará as ofertas de dados do registro de contas padrão.

Retornos

Uma tabela que lista todas as ofertas de dados que você registrou usando esta conta.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS();
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir.

Para ver os itens no registro padrão:

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('VIEW REGISTERED DATA OFFERINGS', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Para ver os itens em um registro personalizado:

  • Você tem privilégios de leitura e gravação em qualquer registro personalizado criado por você mesmo.

  • Para acessar um registro personalizado criado por outro usuário, você precisa de GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'REGISTRY', 'MY_REGISTRY', 'role name').

VIEW_DATA_OFFERINGS

Esquema:

COLLABORATION

Lista todas as ofertas de dados presentes em uma colaboração especificada que você pode acessar como executor de análise ou que você mesmo adicionou. Para ver apenas as ofertas de dados que você registrou, chame REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS.

Você poderá ver as ofertas de dados do colaborador X somente depois que X tiver ingressado na colaboração.

Sintaxe

VIEW_DATA_OFFERINGS( <collaboration_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração a ser explorada.

Retornos

Informações sobre todas as ofertas de dados na colaboração especificada. A tabela inclui as seguintes colunas:

  • FREEFORM_SQL_COLUMN_POLICIES: uma representação JSON de todas as políticas de coluna de forma livre nesta colaboração, inseridas por tipo de política.

  • FREEFORM_SQL_VIEW_NAME: o nome totalmente qualificado da tabela usado em consultas SQL de forma livre, quando o conjunto de dados oferece suporte a consultas SQL de forma livre. Esta célula estará vazia se o conjunto de dados não oferecer consultas SQL de forma livre.

  • SHARE_WITH: quem pode usar os dados em uma análise. Se esse valor for LOCAL, o conjunto de dados local não foi compartilhado com nenhum colaborador, exceto a parte que hospeda os dados.

  • TEMPLATE_VIEW_NAME: o nome totalmente qualificado da tabela usado em um modelo ao chamar COLLABORATION.RUN.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS(
  $collaboration_name
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('VIEW DATA OFFERINGS', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Atualizar os procedimentos de solicitação

Estes procedimentos são usados para gerenciar solicitações de atualização de colaboração que exigem aprovação, como o fluxo de adição de modelo.

VIEW_UPDATE_REQUESTS

Esquema:

COLLABORATION

Veja todas as solicitações de atualização que você criou, ou que pode aprovar ou negar, na colaboração especificada. Pode levar alguns segundos para que uma solicitação de atualização seja registrada, portanto, talvez você não veja uma solicitação que acabou de enviar.

Veja o fluxo de adição de modelo.

Sintaxe

VIEW_UPDATE_REQUESTS( <collaboration_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração.

Retornos

Uma tabela de solicitações de atualização enviadas nesta colaboração. As informações incluem:

  • ID: o ID da solicitação. Use-o para aprovar ou negar uma solicitação.

  • TYPE: o tipo de solicitação. Os seguintes valores são suportados:

    • «Add Template»

  • STATUS: o status atual da solicitação. Os seguintes status podem ser relatados:

    • REJECTED: alguém na colaboração rejeitou a solicitação.

    • PENDING: a solicitação está aguardando sua aprovação ou rejeição.

    • AWAITING_PARTNER_APPROVAL: você aprovou a solicitação, mas a solicitação ainda precisa ser aprovada por um ou mais colaboradores.

    • APPROVED: todos os aprovadores necessários aprovaram a solicitação, e a alteração foi aplicada à colaboração.

  • APPROVAL_LOG: log de todas as aprovações e rejeições da solicitação. Se a solicitação foi rejeitada, o motivo apresentado pela parte que a rejeitou também é exibido aqui.

  • DETAILS: os detalhes específicos do tipo de solicitação, como o nome do modelo, a descrição e com quem ela foi compartilhada para uma solicitação «Add Template».

  • SPEC: os detalhes do recurso que está sendo atualizado, como a especificação do modelo para uma solicitação «Add Template».

  • UPDATED_ON: o carimbo de data/hora em que a última ação foi executada na solicitação (por exemplo, aprovação ou rejeição).

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_UPDATE_REQUESTS(
  $collaboration_name
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

APPROVE_UPDATE_REQUEST

Esquema:

COLLABORATION

Aprova uma solicitação de atualização de colaboração. Veja sua lista de solicitações pendentes chamando VIEW_UPDATE_REQUESTS. Depois de aprovar uma solicitação, você não poderá rejeitá-la mais tarde.

Todos os colaboradores afetados devem aprovar uma solicitação para que a alteração seja realmente aplicada à colaboração.

Veja o fluxo de adição de modelo.

Sintaxe

APPROVE_UPDATE_REQUEST( <collaboration_name>, <request_id> )
Copy

Argumentos

collaboration_name

Nome da colaboração.

request_id

O ID da solicitação.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.APPROVE_UPDATE_REQUEST(
  $collaboration_name,
  $request_id
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE UPDATE REQUEST', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

REJECT_UPDATE_REQUEST

Esquema:

COLLABORATION

Rejeita uma solicitação de atualização de colaboração. Uma única rejeição impede que a alteração seja aplicada à colaboração. Você não pode aprovar uma solicitação depois de rejeitá-la.

Sintaxe

REJECT_UPDATE_REQUEST( <collaboration_name>, <request_id>, <reason> )
Copy

Argumentos

collaboration_name

Nome da colaboração.

request_id

O ID da solicitação.

reason

Uma descrição legível do motivo pelo qual a solicitação foi rejeitada. O argumento é obrigatório, mas você pode enviar uma cadeia de caracteres vazia.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.REJECT_UPDATE_REQUEST(
  $collaboration_name,
  'request_1324f934457',
  'Needs more cowbell'
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE UPDATE REQUEST', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Procedimentos de gerenciamento de colaboração

INITIALIZE

Esquema:

COLLABORATION

O proprietário faz essa chamada para criar uma colaboração e, opcionalmente, ingressar na colaboração.

O envio de uma definição de colaboração com o mesmo valor name de uma colaboração existente gera um erro.

Leva um tempo para criar e ingressar em uma colaboração, portanto você deve chamar GET_STATUS para saber quando a ingressão na colaboração foi feita.

Depois que o proprietário ingressar na colaboração, todos os colaboradores listados poderão vê-la ao chamar VIEW_COLLABORATIONS, além de poder revisá-la e ingressar nela.

Sintaxe

INITIALIZE( <collaboration_spec> [, '<auto_join_warehouse>'] )
Copy

Argumentos

collaboration_spec

Definição da colaboração no formato YAML, como uma cadeia de caracteres.

auto_join_warehouse (opcional)

Cadeia de caracteres que especifica um nome de warehouse como um identificador válido do Snowflake. Se especificado, a colaboração será criada e a ingressão nela será feita usando esse warehouse. Se não for especificado, o warehouse atual será usado para criar a colaboração, e você deve chamar JOIN para ingressar na colaboração. É recomendado um warehouse XS.

Retornos

Uma tabela com as seguintes colunas:

  • COLLABORATION_NAME: o nome da colaboração. Use-o em qualquer procedimento que exija que você especifique uma de colaboração.

  • MESSAGE: informações sobre a solicitação de inicialização.

Exemplos

O exemplo a seguir cria uma colaboração em que Alice é a proprietária e pode executar uma análise usando os dados fornecidos por Bob.

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.INITIALIZE(
  $$
  api_version: 2.0.0
  spec_type: collaboration
  name: basic_collaboration
  owner: alice
  collaborator_identifier_aliases:
    alice: corp_id.account_id
    bob: corp2_id.account2_id
  analysis_runners:
    alice:
      data_providers:
        bob:
          data_offerings:
          - id: bob_data_v1
      templates:
      - id: alice_test_template_2026_01_12_V1
  $$,
  'APP_WH'
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando o procedimento a seguir:

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

    Se o parâmetro auto-join-warehouse for fornecido e uma função diferente de SAMOOHA_APP_ROLE for usada, a função também deverá receber o privilégio EXECUTE TASK no nível da conta.

Consulte GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE para saber as permissões de função adicionais necessárias.

TEARDOWN

Esquema:

COLLABORATION

Chamado pelo proprietário para excluir uma colaboração de todas as partes.

Você deve chamar esse procedimento duas vezes. Chame-o uma vez, depois chame GET_STATUS até que ele retorne LOCAL_DROP_PENDING e, por fim, chame esse procedimento novamente.

Nota

Esse procedimento só pode ser chamado em uma colaboração que você criou e na qual ingressou. Se você criou, mas ainda não ingressou na colaboração, deve ingressar nela para conseguir removê-la.

Sintaxe

TEARDOWN( <collaboration_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração a ser excluída.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

-- Start the process.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.TEARDOWN($collaboration_name);

-- Call until it returns LOCAL_DROP_PENDING.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS($collaboration_name);

-- Final call.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.TEARDOWN($collaboration_name);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Consulte GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE para saber as permissões de função adicionais necessárias.

GET_STATUS

Esquema:

COLLABORATION

Mostra informações sobre todos os colaboradores em uma determinada colaboração.

Sempre que executar uma operação assíncrona, como criar ou ingressar em uma colaboração, você deve verificar o status para saber quando a última operação foi concluída antes de executar ações adicionais nessa colaboração, como realizar análises. Esse procedimento pode ser chamado por qualquer colaborador convidado para uma colaboração.

Os proprietários das colaborações podem ver o seguinte caminho de status:

  • CREATING » CREATED » INSTALLING » IN_REVIEW (ou INSTALLATION_FAILED) » JOINING » JOINED (ou JOIN_FAILED)

Não proprietários verão o seguinte caminho de status:

  • INSTALLING » IN_REVIEW (ou INSTALLATION_FAILED) » JOINING » JOINED (ou JOIN_FAILED)

Sintaxe

GET_STATUS( <collaboration_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração da qual ver o status. Você pode ver uma lista de suas colaborações chamando COLLABORATION.VIEW_COLLABORATIONS. Você deve ser convidado para, ou ter ingressado em, uma colaboração para poder chamar GET_STATUS nela.

Retornos

Uma tabela que mostra os detalhes da última tentativa de ingressão de todos os colaboradores na colaboração especificada. A tabela inclui as seguintes colunas:

  • UPDATED_ON: carimbo de data/hora em que o status foi relatado pelo sistema.

  • COLLABORATOR_ACCOUNT: ID da conta de compartilhamento de dados deste colaborador.

  • COLLABORATOR_NAME: alias do colaborador, conforme declarado na especificação da colaboração.

  • COLLABORATOR_ROLES: as funções reais e potenciais deste colaborador. Os valores incluem owner, data_provider e analysis_runner.

  • STATUS: status na hora atualizada. Os valores a seguir são permitidos e mostram o status do colaborador nomeado na colaboração especificada.

    • CREATING: a criação da colaboração foi iniciada.

    • CREATE_FAILED: falha na criação da colaboração.

    • CREATED: a colaboração foi criada e está pronta para uso em operação.

    • INSTALLING: instalação do pacote de aplicativo e preparação dos detalhes da colaboração para revisão.

    • IN_REVIEW: a colaboração está em revisão.

    • INSTALLATION_FAILED: falha na instalação; pacote de aplicativo não instalado e não pode ser revisado.

    • INVITED: o participante foi convidado.

    • REVIEWING: revisando a colaboração no momento.

    • JOINING: O processo de ingressão foi iniciado.

    • JOIN_FAILED: Falha no processo de ingressão.

    • JOINED: a ingressão na colaboração foi feita com sucesso. Você pode começar a usá-la.

    • INVITE_STARTED: o processo de convite foi iniciado.

    • INVITE_ACCEPTED: o convite foi aceito.

    • LEAVING: o processo de saída foi iniciado.

    • LEAVE_FAILED: falha no processo de saída.

    • LEFT: saiu com sucesso da colaboração.

    • LOCAL_DROP_PENDING: você fez uma solicitação bem-sucedida para descartar ou sair da colaboração. Complete o processo chamando TEARDOWN ou LEAVE novamente.

    • DROPPING: o processo de descarte foi iniciado.

    • DROPPED: descartado com sucesso.

    • DROP_FAILED: o processo de descarte falhou.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS(
  $collaboration_name
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

ENABLE_EXTERNAL_TABLE_ANALYSIS_FOR_COLLABORATION

Esquema:

ADMIN

Habilita tabelas externas e Apache Iceberg™ a serem usadas para executar uma análise em sua conta. Um executor de análise deve chamar esse procedimento antes de executar qualquer análise que inclua tabelas externas ou Iceberg. Esse procedimento é chamado uma vez por colaboração, não uma vez por análise.

Sintaxe

ENABLE_EXTERNAL_TABLE_ANALYSIS_FOR_COLLABORATION( <collaboration_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.ENABLE_EXTERNAL_TABLE_ANALYSIS_FOR_COLLABORATION(
  $collaboration_name
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido o privilégio MANAGE FIREWALL CONFIGURATION para chamar esse procedimento.

VIEW_COLLABORATIONS

Esquema:

COLLABORATION

Visualize informações sobre colaborações que você criou, pode revisar ou nas quais ingressou.

Sintaxe

VIEW_COLLABORATIONS()
Copy

Argumentos

Nenhum

Retornos

Uma tabela que lista os detalhes de todas as colaborações que você pode acessar. A tabela inclui as seguintes colunas:

  • SOURCE_NAME: o nome da colaboração, conforme especificado pelo valor name na especificação da colaboração.

  • COLLABORATION_NAME: o nome da colaboração instalada. O valor será NULL até que a colaboração seja instalada chamando JOIN (proprietários) ou REVIEW (não proprietários).

  • OWNER_ACCOUNT: ID de compartilhamento de dados da conta que criou a colaboração.

  • UPDATED_ON: quando a colaboração foi atualizada pela última vez.

  • COLLABORATION_SPEC: a especificação para esta colaboração no formato YAML. Isso mostra a versão mais recente da colaboração, incluindo todos os recursos adicionados ou removidos após a criação da colaboração. No entanto, pode haver solicitações de atualização em andamento que serão adicionadas em breve, como modelos ou ofertas de dados novos ou removidos.

Exemplos

Visualizar todas as colaborações:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS();
Copy

Visualizar a especificação de uma determinada colaboração por nome:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS() ->>
SELECT "COLLABORATION_SPEC" FROM $1 WHERE "SOURCE_NAME" = $collaboration_name;
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('RUN', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('VIEW COLLABORATIONS', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

REVIEW

Esquema:

COLLABORATION

Apresenta detalhes sobre uma colaboração para a qual você foi convidado. Chame COLLABORATION.VIEW_COLLABORATIONS para ver para quais colaborações você foi convidado e nas quais ainda não ingressou. Todos os colaboradores, exceto o proprietário, devem chamar esse procedimento antes de chamar JOIN. Não é possível chamar esse procedimento em uma colaboração na qual você ingressou. Você deve usar a mesma função para chamar REVIEW e JOIN. Se sua conta estiver em uma região de hospedagem em nuvem diferente da do proprietário, talvez seja necessário chamar esse procedimento várias vezes até que ele retorne uma resposta bem-sucedida.

Esse procedimento instala o aplicativo subjacente em sua conta.

Observações importantes:

  • Os proprietários não podem chamar REVIEW em suas próprias colaborações.

  • Todos, exceto o proprietário, devem chamar REVIEW antes de chamar JOIN.

  • Depois de ingressar em uma colaboração, você não poderá chamar REVIEW novamente.

Sintaxe

REVIEW( <source_name>, <owner_account> )
Copy

Argumentos

source_name

Nome da colaboração para a qual você foi convidado a ingressar. Você pode ver uma lista de suas colaborações chamando COLLABORATION.VIEW_COLLABORATIONS.

owner_account

Identificador da conta de compartilhamento de dados do proprietário. Ele pode ser encontrado na resposta a COLLABORATION.VIEW_COLLABORATIONS.

Retornos

Tabela de informações sobre a colaboração, incluindo o ID, o proprietário e a especificação da colaboração.

Se sua conta estiver em uma região de hospedagem em nuvem diferente daquela do proprietário da colaboração, REVIEW poderá retornar uma mensagem informando que etapas adicionais de configuração ainda estão sendo executadas. Se você receber essa mensagem, continue chamando REVIEW até ele retornar a tabela de informações sobre a colaboração.

Exemplo

-- View the collaboration for your own usage.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.REVIEW(
  $collaboration_name,
  'org1.account1234'
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Consulte GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE para saber as permissões de função adicionais necessárias.

JOIN

Esquema:

COLLABORATION

Método assíncrono para ingressar em uma colaboração especificada. Observe que você pode acessar somente os recursos listados na colaboração no momento em que ingressar nela. Esse procedimento leva algum tempo para ser executado.

Você precisa do privilégio de conta REGISTER DATA OFFERING para ingressar em uma colaboração na qual possa ativar dados (ou seja, você é executor de análise e a especificação da colaboração inclui um campo activation_destinations). Consulte o guia de referência da API de gerenciamento de acesso.

Você não pode ter uma função secundária ativa ao executar esse procedimento. Execute o seguinte código SQL para desabilitar as funções secundárias:

USE SECONDARY ROLES NONE;
Copy

Todos, exceto o criador da colaboração, devem chamar COLLABORATION.REVIEW antes de chamar esse procedimento.

Esse procedimento é assíncrono. Chame GET_STATUS para determinar quando você ingressou na colaboração com sucesso.

Qualquer pessoa que envia um recurso para a colaboração ou deseja executar um modelo na colaboração deve primeiro ingressar nela. O criador da colaboração é ingressado automaticamente ao chamar``INITIALIZE`` (a menos que auto_join_warehouse seja fornecido).

Sintaxe

JOIN( <collaboration_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração na qual ingressar. Você pode ver uma lista de suas colaborações chamando COLLABORATION.VIEW_COLLABORATIONS. Se você foi convidado a ingressar em várias colaborações com o mesmo nome, o padrão é definido como a última em que você chamou COLLABORATION.REVIEW.

Retornos

Uma mensagem de sucesso de cadeia de caracteres. Se você receber um erro sobre uma concessão de uso de referência ausente, consulte o Guia de solução de problemas.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.JOIN(
  $collaboration_name
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Consulte GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE para saber as permissões de função adicionais necessárias.

LEAVE

Esquema:

COLLABORATION

Sai de uma colaboração na qual você ingressou. Não é possível reingressar em uma colaboração depois de sair dela.

Você deve chamar esse procedimento duas vezes. Chame-o uma vez, depois chame GET_STATUS até que ele retorne LOCAL_DROP_PENDING e, por fim, chame esse procedimento novamente.

Sintaxe

LEAVE( <collaboration_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração da qual sair.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

-- Start the process.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.LEAVE($collaboration_name);

-- Call until it returns LOCAL_DROP_PENDING.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS($collaboration_name);

-- Final call.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.LEAVE($collaboration_name);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Consulte GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE para saber as permissões de função adicionais necessárias.

Executando análises e ativações

RUN

Esquema:

COLLABORATION

Executa uma análise na sala limpa de dados. Você pode passar os detalhes de execução como parâmetros individuais ou passar uma cadeia de caracteres de especificação YAML da análise.

Leia a referência de consumer.run_analysis para obter informações sobre como executar um modelo em uma sala limpa de dados.

Existem duas versões desse procedimento: uma que usa os argumentos de execução como uma única cadeia de caracteres com formatação YAML, e uma que usa os argumentos como parâmetros individuais.

Sintaxe do argumento YAML

RUN( <collaboration_name>, <analysis_spec> )
Copy
Argumentos
collaboration_name

Nome da colaboração na qual será executada esta análise.

analysis_spec

Definição da análise no formato YAML como uma cadeia de caracteres, descrevendo o modelo, as tabelas e os valores de modelo a serem usados nesta análise.

Sintaxe explícita dos parâmetros

RUN( <collaboration_name>, <template_id>, <template_view_names>, <local_template_view_names>, <arguments> )
Copy
Argumentos
collaboration_name

Nome da colaboração na qual será executada esta análise.

template_id

ID do modelo a ser executado.

template_view_names

Matriz de nomes de cadeia de caracteres das tabelas de origem a serem usadas na análise. Use os nomes de tabela retornados por VIEW_DATA_OFFERINGS na coluna TEMPLATE_VIEW_NAME. O formato para cada entrada é user_alias.data_offering_id.dataset_alias

local_template_view_names

Matriz de IDs de cadeia de caracteres das suas próprias tabelas para usar na análise. Você deve primeiro vincular essas tabelas chamando LINK_LOCAL_DATA_OFFERING.

arguments

Objeto JSON que contém argumentos nomeados usados pelo modelo, em que cada chave é um nome de argumento de modelo e o valor representa esse argumento.

Retornos

Resultados da análise em formato de tabela.

Exemplos

Exemplo de passagem por parâmetro:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.RUN(
  $collaboration_name,
  $template_name,
  ['Provider.data_offering_1_2026_01_12_v0.test_dataset'], -- Tables to pass to source_tables variable.
  [],
  {} -- Template takes no parameters.
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('RUN', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

VIEW_ACTIVATIONS

Esquema:

COLLABORATION

Mostra o status de ativação de qualquer execução de análise que você acionou para enviar a um colaborador, ou das ativações que um colaborador acionou para enviar a você. As solicitações de ativação para enviar dados a você mesmo não são listadas.

Para obter mais informações sobre ativação, consulte Ativar os resultados da consulta.

Sintaxe

VIEW_ACTIVATIONS( <collaboration_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração.

Retornos

Uma tabela com os detalhes de cada ativação. A tabela inclui as seguintes colunas:

  • UPDATED_ON: hora em que o status foi atualizado pela última vez.

  • SEGMENT_NAME: uma cadeia de caracteres arbitrária atribuída pelo executor da análise para identificar a ativação. Para obter mais informações, consulte Ativação de resultados de consulta.

  • ACTIVATION_ID: ID desta solicitação de ativação. Para obter mais informações, consulte Exibição dos resultados da ativação de provedor e consumidor.

  • TEMPLATE_ID: modelo usado para produzir os dados da ativação.

  • SHARED_BY: o colaborador que executou a análise.

  • SHARED_WITH: o colaborador que deve receber os dados da análise.

  • STATUS: status da ativação. Os seguintes valores são suportados:

    • PENDING: a ativação foi solicitada, mas está aguardando para ser processada.

    • SHARED: os dados da ativação estão prontos para serem processados. Chame PROCESS_ACTIVATION para enviar os resultados à sua conta.

    • FAILED: o processamento de ativação falhou. Consulte as informações na coluna DETAILS.

    • PROCESSED: os resultados da ativação foram enviados para a conta especificada na solicitação de ativação.

  • DETAILS: detalhes da falha, se a ativação tiver falhado.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_ACTIVATIONS(
  $collaboration_name
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('VIEW ACTIVATIONS', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('RUN', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

PROCESS_ACTIVATION

Esquema:

COLLABORATION

Se o executor da análise estiver enviando dados para a conta de outro colaborador, esse colaborador deverá chamar PROCESS_ACTIVATION para importar os dados da ativação para a conta dele. O colaborador deve chamar VIEW_ACTIVATIONS e aguardar até que a saída mostre que o status da ativação para um determinado segmento é SHARED antes de chamar PROCESS_ACTIVATION.

Sintaxe

PROCESS_ACTIVATION( <collaboration_name>, <segment_name> )
Copy

Argumentos

collaboration_name

Nome da colaboração.

segment_name

Uma cadeia de caracteres arbitrária atribuída para identificar a ativação na tabela de resultados. O nome do segmento é atribuído na consulta da análise usando template_configuration.arguments.segment_name. Para obter mais informações, consulte Ativação de resultados de consulta.

Retornos

O nome da tabela em que o usuário pode recuperar os resultados e o nome do segmento especificado para os resultados. Consulte Ativar os resultados da consulta para saber como ler os resultados.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.PROCESS_ACTIVATION(
  $collaboration_name,
  'q1_2025_segment'
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando um dos procedimentos a seguir:

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('PROCESS ACTIVATION', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Procedimentos de gerenciamento de registro

CREATE_REGISTRY

Esquema:

REGISTRY

Cria um registro personalizado para organizar recursos, como modelos e ofertas de dados. Um registro personalizado pode armazenar recursos de um único tipo, designado quando você cria o registro.

Use os registros personalizados para agrupar recursos relacionados separadamente do registro local padrão. Adicione recursos a esse registro usando o parâmetro de nome de registro opcional.

Sintaxe

CREATE_REGISTRY( '<registry_name>', <registry_type> )
Copy

Argumentos

registry_name

Nome do registro a ser criado. Deve ser um nome exclusivo em todos os registros da conta.

registry_type

O tipo de recursos que este registro conterá. Valores suportados: TEMPLATE, DATA OFFERING.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.CREATE_REGISTRY(
  'my_custom_registry',
  'TEMPLATE'
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando o procedimento a seguir:

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE REGISTRY', 'role name')

DROP_REGISTRY

Esquema:

REGISTRY

Descarta um registro personalizado e cancela o registro de todos os objetos que ele contém. Você pode descartar apenas os registros que você criou.

Sintaxe

DROP_REGISTRY( '<registry_name>' )
Copy

Argumentos

registry_name

Nome do registro a ser descartado.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.DROP_REGISTRY(
  'my_custom_registry'
);
Copy

Requisitos de acesso

Se você não usa a função SAMOOHA_APP_ROLE, deve usar uma função que tenha recebido privilégios chamando o procedimento a seguir:

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE REGISTRY', 'role name')

Procedimentos de gerenciamento de acesso

A função SAMOOHA_APP_ROLE concede acesso a todos os procedimentos da API Collaboration DCR. Entretanto, se um administrador quiser conceder privilégios mais granulares a funções específicas, você poderá criar uma função e conceder a ela privilégios específicos com os procedimentos descritos nesta seção.

Saiba mais sobre como conceder acesso em Gerenciar o acesso à API Collaboration DCR.

Os procedimentos a seguir são usados para gerenciar o acesso refinado à API Snowflake Collaboration Data Clean Room:

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE

Esquema:

ADMIN

Concede a uma função específica os direitos de chamar procedimentos específicos em um determinado objeto. O tipo de objeto é definido usando o argumento OBJECT_TYPE.

Você pode chamar esse procedimento várias vezes para conceder várias permissões à mesma função. Execute esse procedimento usando a função proprietária do objeto.

Sintaxe

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  <privilege>,
  <object_type>,
  <object_name>,
  <account_role_name> )
Copy

Argumentos

privilege

Que permissão esta função deve receber. Consulte a tabela abaixo para saber quais privilégios estão disponíveis para quais objetos.

object_type

O tipo de objeto no qual esta função está recebendo permissões. Valores com suporte:

  • COLLABORATION

  • REGISTRY

object_name

O ID do objeto, conforme indicado na especificação do objeto.

account_role_name

A função que está sendo concedida.

As seguintes combinações de privilégio e tipo de objeto são permitidas:

Privilégio

Tipo de objeto

Procedimentos habilitados

READ

COLLABORATION

VIEW_COLLABORATIONS, GET_STATUS, VIEW_DATA_OFFERINGS, VIEW_UPDATE_REQUESTS, VIEW_TEMPLATES

RUN

COLLABORATION

RUN, VIEW_ACTIVATIONS, VIEW_COLLABORATIONS

UPDATE

COLLABORATION

LINK_DATA_OFFERING, UNLINK_DATA_OFFERING, LINK_LOCAL_DATA_OFFERING, UNLINK_LOCAL_DATA_OFFERING, ADD_TEMPLATE_REQUEST, REMOVE_TEMPLATE, APPROVE_UPDATE_REQUEST, REJECT_UPDATE_REQUEST, ENABLE_TEMPLATE_AUTO_APPROVAL, DISABLE_TEMPLATE_AUTO_APPROVAL, VIEW_UPDATE_REQUESTS

READ

REGISTRY

Visualizar os recursos registrados em um registro personalizado.

REGISTER

REGISTRY

Registrar recursos, como modelos e ofertas de dados, em um registro personalizado.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

Este exemplo cria uma função que os analistas podem usar para executar análises em uma colaboração chamada my_collaboration e a atribui a um usuário.

USE ROLE role_that_created_this_collaboration;

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  'RUN',
  'COLLABORATION',
  $collaboration_name,
  'collaborator_analyst_role'
);
GRANT ROLE collaborator_analyst_role to USER alexander_hamilton;
Copy

Requisitos de acesso

Você deve usar a mesma função que criou o objeto para chamar GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE nesse objeto.

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE

Esquema:

ADMIN

Concede privilégios no nível da conta a uma função. Esse procedimento permite que qualquer pessoa que use essa função chame os procedimentos listados para esse privilégio.

Sintaxe

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE( <privilege>, <account_role_name> )
Copy

Argumentos

privilege

O privilégio para conceder a esta função. Os seguintes valores de cadeia de caracteres são compatíveis:

  • JOIN COLLABORATION: concede permissão para executar COLLABORATION.JOIN e os seguintes procedimentos na colaboração da ingressão:

    • ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE

    • COLLABORATION.ADD_TEMPLATE_REQUEST

    • COLLABORATION.APPROVE_UPDATE_REQUEST

    • COLLABORATION.ENABLE_TEMPLATE_AUTO_APPROVAL

    • COLLABORATION.DISABLE_TEMPLATE_AUTO_APPROVAL

    • COLLABORATION.REMOVE_TEMPLATE

    • COLLABORATION.GET_STATUS

    • COLLABORATION.LEAVE

    • COLLABORATION.LINK_DATA_OFFERING

    • COLLABORATION.LINK_LOCAL_DATA_OFFERING

    • COLLABORATION.PROCESS_ACTIVATION

    • COLLABORATION.REJECT_UPDATE_REQUEST

    • COLLABORATION.REVIEW

    • COLLABORATION.RUN

    • COLLABORATION.TEARDOWN

    • COLLABORATION.UNLINK_DATA_OFFERING

    • COLLABORATION.UNLINK_LOCAL_DATA_OFFERING

    • COLLABORATION.VIEW_ACTIVATIONS

    • COLLABORATION.VIEW_COLLABORATIONS

    • COLLABORATION.VIEW_DATA_OFFERINGS

    • COLLABORATION.VIEW_TEMPLATES

    • COLLABORATION.VIEW_UPDATE_REQUESTS

    • REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS

    • REGISTRY.VIEW_REGISTERED_TEMPLATES

    Esse privilégio requer que os seguintes privilégios no nível da conta sejam concedidos manualmente à função:

    • APPLY ROW ACCESS POLICY

    • CREATE APPLICATION

    • CREATE DATABASE

    • CREATE LISTING

    • CREATE SHARE

    • IMPORT SHARE

    • MANAGE SHARE TARGET

  • CREATE COLLABORATION: concede permissão para executar COLLABORATION.INITIALIZE, além de todos os procedimentos permitidos por JOIN COLLABORATION para a colaboração da ingressão. Exige que os seguintes privilégios no nível da conta sejam concedidos manualmente à função:

    • APPLY ROW ACCESS POLICY

    • CREATE APPLICATION

    • CREATE DATABASE

    • CREATE LISTING

    • CREATE SHARE

    • IMPORT SHARE

    • MANAGE SHARE TARGET

    • EXECUTE TASK (se estiver usando a ingressão automática no procedimento INITIALIZE)

  • VIEW COLLABORATIONS: concede permissão para executar COLLABORATION.VIEW_COLLABORATIONS. Exige que os seguintes privilégios sejam concedidos manualmente à função:

    • IMPORT SHARE

  • REGISTER DATA OFFERING: concede permissão para executar REGISTRY.REGISTER_DATA_OFFERING. Essa permissão é necessária para qualquer executor de análise ingressar em uma colaboração que implementa a ativação.

  • VIEW REGISTERED DATA OFFERINGS: concede permissão para executar REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS.

  • VIEW REGISTERED TEMPLATES: concede permissão para executar REGISTRY.VIEW_REGISTERED_TEMPLATES.

  • REGISTER TEMPLATE: concede permissão para executar REGISTRY.REGISTER_TEMPLATE.

  • CREATE REGISTRY: concede permissão para executar REGISTRY.CREATE_REGISTRY e REGISTRY.DROP_REGISTRY, além da capacidade de ler registros personalizados.

  • MANAGE LISTING AUTO FULFILLMENT: Concede permissão para um colaborador ingressar em uma colaboração em outra região de hospedagem na nuvem. Para obter mais informações, consulte Habilitar o preenchimento automático entre nuvens.

account_role_name

O nome de uma função no nível da conta.

Retornos

Uma mensagem de sucesso de cadeia de caracteres.

Exemplo

USE ROLE ACCOUNTADMIN;
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE(
  'REGISTER DATA OFFERING',
  'COLLABORATOR_ANALYST_ROLE'
);
Copy

Requisitos de acesso

Você precisa da função ACCOUNTADMIN para executar esse procedimento.