Referência do esquema do Collaboration Data Clean Rooms

Este tópico descreve os esquemas de especificação para todos os recursos de colaboração. As especificações são exibidas no formato YAML.

As especificações têm um campo de versão de esquema api_version. Use o número da versão da API exibido aqui; o suporte para versões de esquema anteriores não é garantido.

Versão atual da API do DCR Collaboration: 2.0.0

Especificação da colaboração

Define a colaboração de alto nível. A especificação define quais executores de análise são convidados e, para cada executor de análise, quais dados e modelos eles podem acessar e executar. Quaisquer modelos ou ofertas de dados listados aqui devem ser registrados antes de serem incluídos na especificação de colaboração.

O proprietário envia essa definição chamando COLLABORATION.INITIALIZE.

Esquema:

api_version: 2.0.0              # Required: Must be "2.0.0"
spec_type: collaboration        # Required: Must be "collaboration"
name: <collaboration_name>      # Required: Unique name (max 75 chars)
version: <version_string>       # Optional: Version identifier (max 20 chars)
description: <collaboration_description>  # Optional: Description (max 1,000 chars)
owner: <owner_alias>            # Optional: Alias of owner

collaborator_identifier_aliases:  # Required: Map aliases to account identifiers
  <alias_1>: <account_identifier_1>  # One or more alias mappings...

analysis_runners:               # Required: Who can run analyses
  <analysis_runner_alias>:      # One or more analysis runner definitions...
    data_providers:             # Required: Data providers for this runner
      <provider_alias>:         # One or more provider definitions...
        data_offerings:         # Required: List of offerings (can be empty [])
          - id: <data_offering_id>  # Zero or more data offering IDs...
    templates:                  # Optional: Templates this runner can use
      - id: <template_id>       # One or more template IDs...
    activation_destinations:    # Optional: Where results can be sent
      snowflake_collaborators:  # Optional: Collaborators who can receive results
        - <collaborator_alias>  # One or more collaborator aliases...
Copy
api_version

A versão da API do Collaboration utilizada. Deve ser 2.0.0.

spec_type

Identificador do tipo de especificação. Deve ser collaboration.

name: collaboration_name

Nome amigável para essa colaboração. Deve ser único na conta do criador e seguir as :doc:`regras do identificador do Snowflake </sql-reference/identifiers-syntax>`(máximo de 75 caracteres).

version (opcional)

Um identificador de versão para essa colaboração (máximo de 20 caracteres). Deve seguir as regras do identificador do Snowflake. Um bom formato para usar é YYYY_MM_DD_V#. Por exemplo: 2025_10_22_V1.

description: collaboration_description (opcional)

Uma descrição legível da colaboração (máximo de 1.000 caracteres), para que os colaboradores possam ler.

owner: owner_alias (opcional)

Alias ​​ou identificador da conta de compartilhamento de dados o proprietário da colaboração. Se não for especificado, a conta que registrar esta especificação será atribuída como proprietária.

collaborator_identifier_aliases

Mapeamento dos aliases dos colaboradores para os identificadores de conta de compartilhamento de dados. Somente os usuários listados aqui podem participar da colaboração. Use os aliases definidos aqui para se referir a todos os colaboradores, em vez de usar diretamente o identificador da conta de compartilhamento de dados deles.

analysis_runners

Descreve quem pode executar uma análise nesta colaboração. Cada executor de análise é identificado por um alias exclusivo. Você deve permitir que pelo menos uma conta execute uma análise nesta colaboração.

<analysis_runner_alias>

Alias ​​da conta que pode executar uma análise nesta colaboração. O alias é definido na lista collaborator_identifier_aliases.

data_providers

Provedores de dados cujos dados este executor de análise pode acessar. Cada provedor é identificado pelo alias definido em collaborator_identifier_aliases.

data_offerings

Uma lista de ofertas de dados deste provedor de dados que o executor de análise pode acessar ou uma matriz vazia []. Se houver itens, cada um terá as seguintes propriedades:

  • data_offering_id: O ID de referência para esta oferta de dados, gerada quando o provedor de dados chama REGISTRY.REGISTER_DATA_OFFERING.

templates (opcional)

Os modelos que podem ser utilizados ​​por este executor de análise. Cada modelo é referenciado por um ID próprio.

activation_destinations (opcional)

Define as configurações de ativação para os resultados da análise.

snowflake_collaborators (opcional)

Lista de colaboradores que podem receber resultados de análise ativados. Use o alias da lista collaborator_identifier_aliases nesta especificação. Todos os colaboradores listados aqui devem ter as permissões descritas em Ativar os resultados da consulta.

Exemplos

api_version: 2.0.0
spec_type: collaboration
name: my_sample_collaboration
owner: Owner
collaborator_identifier_aliases:
  Owner: ENG.OWNER
  AnalysisRunner_1: ENG.CONSUMER_1
  DataProvider_1: ENG.PROVIDER_1
  DataProvider_2: ENG.PROVIDER_2
  AnalysisRunner_2: ENG.PROVIDER_3
analysis_runners:
  AnalysisRunner_1:
    data_providers:
      DataProvider_1:
        data_offerings:
        - id: DCR_PREPROD_CI_PROVIDER_ANY_NAME_ZUDFTMULHQ_iuDfn_v0
      DataProvider_2:
        data_offerings: []
    templates:
    - id: test_sca_three_party_template_JOaVG_v0
  AnalysisRunner_2:
    data_providers:
      DataProvider_2:
        data_offerings: []
    templates:
    - id: test_sca_three_party_template_JOaVG_v0
Copy

Especificação da oferta de dados

Define um conjunto de tabelas que um provedor está disposto a compartilhar com os executores de análise, bem como regras de compartilhamento, como políticas, formatos de coluna e se a tabela deve ser utilizada com um modelo.

O provedor de dados envia essa definição chamando REGISTRY.REGISTER_DATA_OFFERING, que retorna um ID de oferta que pode ser utilizado na definição de colaboração.

Uma oferta de dados não estará disponível em uma colaboração até que a conta que registrou a oferta de dados entre na colaboração.

Você precisa ter o privilégio de conta REGISTER DATA OFFERING para participar de qualquer colaboração na qual possa ativar dados; ou seja, você é um executor de análises, e a especificação da colaboração inclui um campo activation_destinations. Para obter mais informações, consulte o guia de referência de API de gerenciamento de acesso.

Esquema:

api_version: 2.0.0              # Required: Must be "2.0.0"
spec_type: data_offering        # Required: Must be "data_offering"
name: <data_offering_name>      # Required: Unique name (max 75 chars)
version: <version_string>       # Required: Version identifier (max 20 chars)
description: <data_offering_description>  # Optional: Description (max 1,000 chars)

datasets:                       # Required: Tables to share
  - alias: <dataset_name>       # One or more dataset items...
    data_object_fqn: <database.schema.table_name>  # Required: Fully-qualified table name
    allowed_analyses: <allowed_analysis_type>      # Required: template_only or template_and_freeform_sql
    object_class: <object_class>    # Optional: ads_log or custom
    schema_and_template_policies:   # Required: Column definitions
      <column_name>:                # One or more column definitions...
        category: <category_type>   # Required: join_standard, join_custom, timestamp, or passthrough
        column_type: <format_type>  # Required for join_standard category, omitted for other categories.
        activation_allowed: <true_or_false>  # Optional: Whether column can be used for activation
    freeform_sql_policies:      # Optional: Policies for freeform SQL queries
      aggregation_policy:       # Optional: Single aggregation policy
        name: <fully_qualified_policy_name>
        entity_keys:            # Optional: Entity key columns
          - <column_name>       # One or more column names...
      join_policy:              # Optional: Single join policy
        name: <fully_qualified_policy_name>
        columns:                # Optional: Columns this policy applies to
          - <column_name>       # One or more column names...
      masking_policies:         # Optional: Masking policies
        - name: <fully_qualified_policy_name>  # One or more masking policy items...
          columns:              # Optional: Columns this policy applies to
            - <column_name>     # One or more column names...
      projection_policies:      # Optional: Projection policies
        - name: <fully_qualified_policy_name>  # One or more projection policy items...
          columns:              # Optional: Columns this policy applies to
            - <column_name>     # One or more column names...
      row_access_policy:        # Optional: Row access policies
        - name: <fully_qualified_policy_name>  # One or more row access policy items...
          columns:              # Optional: Columns this policy applies to
            - <column_name>     # One or more column names...
    require_freeform_sql_policy: <true_or_false>  # Optional: Require a policy for freeform SQL
Copy
api_version

A versão da API do Collaboration utilizada. Deve ser 2.0.0.

spec_type

Identificador do tipo de especificação. Deve ser data_offering.

version

Um identificador de versão personalizado para esta especificação de oferta de dados (máximo de 20 caracteres). Deve seguir as regras do identificador do Snowflake. A cadeia de caracteres de versão recebe sua própria coluna na resposta a VIEW_DATA_OFFERINGS e VIEW_REGISTERED_DATA_OFFERINGS; portanto, use um valor que possa ser classificado por valor crescente. Exemplo: V0

name: data_offering_name

Um nome para um conjunto de tabelas e colunas a serem expostas aos colaboradores. Esse nome é utilizado como o valor de referência da oferta de dados em uma definição de colaboração. Você pode criar várias ofertas de dados com tabelas e colunas sobrepostas para diferentes casos de uso. Deve seguir as regras do identificador do Snowflake com um máximo de 75 caracteres e ser exclusivo na conta de sala limpa de dados do Snowflake. O par name_version deve ser único para todas as ofertas de dados nesta conta.

description: data_offering_description (opcional)

Uma descrição da oferta de dados (máximo de 1.000 caracteres).

datasets

Uma lista de um ou mais conjuntos de dados para disponibilizar à colaboração.

alias: dataset_name

Um nome para este objeto de dados, utilizado em collaboration.run. Deve seguir as :doc:`regras do identificador do Snowflake </sql-reference/identifiers-syntax>`e ser único nesta oferta.

data_object_fqn: fully_qualified_table_name

Descreve uma única tabela disponível para os colaboradores. Forneça o nome totalmente qualificado do objeto de origem em sua conta (database.schema.table_name). O comprimento máximo é de 773 caracteres.

allowed_analyses: allowed_analysis_type

O tipo de análises que os colaboradores podem executar nesta tabela. Campo obrigatório com os seguintes valores:

  • template_only: O executor de análise pode consultar esta tabela somente usando um modelo listado na definição da colaboração.

  • template_and_freeform_sql: O executor de análise pode consultar esta tabela usando um modelo listado na definição da colaboração ou usando consultas SQL de formato livre em um ambiente de código.

object_class (opcional)

O tipo de objeto. Um dos seguintes valores:

  • ads_log: As tabelas e colunas listadas aqui devem atender aos requisitos do log de anúncios.

  • custom: Um conjunto personalizado de tabelas e colunas que não tem requisitos especiais.

schema_and_template_policies

Forneça uma lista de nomes de colunas da tabela listada por data_object_fqn e defina as políticas e o formato de cada coluna. Somente as colunas listadas aqui estão disponíveis para colaboradores. Cada coluna tem os seguintes descritores:

category: category_type

A categoria determina se alguma renomeação de coluna é aplicada e qualquer aplicação de formato de dados que deve ser aplicada. category e column_type determinam o nome da coluna exposta ao executor de análise. Os seguintes valores são suportados:

  • join_standard: Esta é uma coluna que pode ser unida com dados em um formato especificado no campo column_type. Esta coluna é renomeada para o valor column_type na oferta de dados compartilhados.

  • join_custom: Esta é uma coluna que pode ser unida em qualquer formato. Use esta opção quando não houver um column_type apropriado para sua coluna de junção. O nome da coluna original é utilizado na oferta de dados compartilhados.

  • timestamp: Esta é uma coluna projetável que especifica um carimbo de data/hora para qualquer evento. A coluna é renomeada como timestamp na oferta de dados compartilhados.

  • passthrough: Esta é uma coluna projetável de qualquer outro tipo. O nome da coluna original é utilizado na oferta de dados compartilhados.

column_type: <format_type> (Obrigatório quando category=join_standard, ignorado para outros tipos de categoria)

O formato dos dados. Se os dados não estiverem em conformidade com esse formato, sua chamada para REGISTER_DATA_OFFERING falhará. Forneça esse campo para colunas em que category = join_standard. category e column_type :ref:` determinam o nome da coluna exposto ao executor de análise <label-dcr_source_column_renaming>`. Não é possível atribuir o mesmo valor column_type a várias colunas na mesma tabela. Os seguintes tipos de formato são compatíveis:

  • email: Um endereço de e-mail bruto.

  • hashed_email_sha256: Um e-mail com hash SHA256.

  • hashed_email_b64_encoded: Um e-mail com hash codificado em base64.

  • phone: Um número de telefone sem pontuação. Por exemplo: 2015551212.

  • hashed_phone_sha256: Um número de telefone com hash SHA256. O número original deve estar no formato phone.

  • hashed_phone_b64_encoded: Um número de telefone com hash codificado em base64.

  • device_id: O ID de um dispositivo bruto, como o de um dispositivo de publicidade móvel ou de um dispositivo CTV.

  • hashed_device_id_sha256: ID do dispositivo com hash SHA256. O original deve estar no formato device_id.

  • hashed_device_b64_encoded: ID de um dispositivo com hash codificado em base64.

  • ip_address: um endereço IP bruto em formato IPv4.

  • hashed_ip_address_sha256: endereço IPv4 com hash SHA256. O original deve estar no formato ip_address.

  • hashed_ip_address_b64_encoded: um endereço IP com hash codificado em base64.

activation_allowed (opcional)

Indica se esta coluna pode ser utilizada para fins de ativação. O padrão é false.

freeform_sql_policies (opcional)

Se allowed_analyses for template_and_freeform_sql, este campo opcional listará todas as políticas do Snowflake que devem ser aplicadas em consultas SQL de formato livre executadas nesta oferta de dados. Para obter mais informações, consulte Aplicar a política à oferta de dados (somente para uso de consulta de forma livre).

Os seguintes tipos são suportados:

aggregation_policy (opcional)

Uma única configuração de política de agregação.

  • name: O nome da política totalmente qualificada.

  • entity_keys (opcional): lista de nomes de colunas que servem como chaves de entidade para a política de agregação.

join_policy (opcional)

Uma única configuração de política de junção.

  • name: O nome da política totalmente qualificada.

  • columns (opcional): lista de nomes de colunas às quais esta política se aplica.

masking_policies (opcional)

Uma matriz de configurações de políticas de mascaramento.

  • name: O nome da política totalmente qualificada.

  • columns (opcional): lista de nomes de colunas às quais esta política se aplica.

projection_policies (opcional)

Uma matriz de configurações de políticas de projeção.

  • name: O nome da política totalmente qualificada.

  • columns (opcional): lista de nomes de colunas às quais esta política se aplica.

row_access_policy (opcional)

Uma matriz de configurações de políticas de acesso a linhas.

  • name: O nome da política totalmente qualificada.

  • columns (opcional): lista de nomes de colunas às quais esta política se aplica.

require_freeform_sql_policy (opcional)

Indica se esta fonte de dados deve ter um freeform_sql_policies definido. Isso é utilizado como uma medida de segurança para impedir a adição de uma fonte de dados que suporte consultas SQL de formato livre sem a atribuição de políticas a ela.

Especificação de recurso de modelo

Define um único modelo em uma colaboração. Enviado para REGISTRY.REGISTER_TEMPLATE para registrar um modelo para uso em uma colaboração.

Esquema:

api_version: 2.0.0              # Required: Must be "2.0.0"
spec_type: template             # Required: Must be "template"
name: <template_name>           # Required: Unique name (max 75 chars)
version: <version_string>       # Required: Version identifier (max 20 chars)
type: <template_type>           # Required: sql_analysis or sql_activation
description: <template_description>  # Optional: High-level description (max 1,000 chars)
methodology: <methodology_description>  # Optional: Detailed description (max 1,000 chars)

parameters:                     # Optional: User-provided parameters
  - name: <parameter_name>      # One or more parameter items...
    description: <parameter_description>  # Optional: Description (max 500 chars)
    required: <true_or_false>   # Optional: Whether required (default: false)
    default: <default_value>    # Optional: Default value
    type: <data_type>           # Optional: String, integer, number, Boolean, array, or object

template: |                     # Required: JinjaSQL template content
  <template_content>
Copy
api_version

A versão da API do Collaboration utilizada. Deve ser 2.0.0.

spec_type

Identificador do tipo de especificação. Deve ser template.

name

Um nome exclusivo e amigável para este modelo. Deve seguir as Regras do identificador do Snowflake com no máximo 75 caracteres. O par name_version deve ser exclusivo para todos os modelos nesta conta.

version

Um identificador de versão para este modelo (máximo de 20 caracteres). Deve seguir as regras do identificador do Snowflake. A cadeia de caracteres de versão recebe sua própria coluna na resposta a VIEW_TEMPLATES e VIEW_REGISTERED_TEMPLATES; portanto, use um valor que possa ser classificado por valor crescente. Exemplo: V0

type

O tipo de modelo. Um dos seguintes valores:

  • sql_analysis: modelo para operações de análise de dados.

  • sql_activation: modelo para operações de ativação de dados.

description: template_description (opcional)

Uma descrição de alto nível do que este modelo faz (máximo de 1.000 caracteres).

methodology: methodology_description (opcional)

Uma descrição mais detalhada de como este modelo funciona (máximo de 1.000 caracteres).

parameters (opcional)

A lista de todos os parâmetros fornecidos pelo usuário neste modelo. Cada item pode ter os seguintes campos:

  • name: Nome do parâmetro como um identificador Snowflake válido.

  • description (opcional): descrição legível do parâmetro (máximo de 500 caracteres).

  • required (opcional): indica se o parâmetro é obrigatório ou não. O padrão é false.

  • default (opcional): valor padrão para o parâmetro, que pode ser qualquer tipo de dados.

  • type (opcional): tipo de dados esperado para o parâmetro. Um dos seguintes: string, integer, number, boolean, array ou object.

template

O conteúdo do modelo. Para modelos SQL, este contém o modelo JinjaSQL. Para obter mais informações, consulte Criação de modelo para uma colaboração.

Os nomes das colunas expostos ao modelo são determinados pelos valores category e column_type da coluna na definição da oferta de dados. Para obter mais informações, consulte Renomeação da coluna de origem.

Exemplo:

api_version: 2.0.0
spec_type: template
name: trivial_template
version: V1
type: sql_analysis
description: Simple one-row template.
methodology: Always returns "1". Requires one source table.

parameters:
  - name: row_count
    description: Count of rows
    required: true

template: |
    SELECT 1 FROM IDENTIFIER( {{ source_table[0] }} ) LIMIT {{ row_count }};
Copy

Especificação da solicitação de análise

Especifica todas as informações que os executores de análise precisam para executar uma análise, incluindo qual modelo usar, quais tabelas passar para o modelo e quaisquer valores de variáveis ​​utilizados ​​por um modelo. Se não estiver usando o SQL de formato livre para consultar dados, qualquer executor de análise que deseje executar uma análise usará esta especificação para definir o modelo e os dados de entrada.

Esquema:

api_version: 2.0.0              # Required: Must be "2.0.0"
spec_type: analysis             # Required: Must be "analysis"
template: <template_id>         # Required: ID of the template to use
name: <analysis_name>           # Optional: Unique name (max 75 chars)
version: <version_string>       # Optional: Version identifier (max 20 chars)
description: <analysis_description>  # Optional: Description (max 1,000 chars)

template_configuration:         # Optional: Values used when running the template
  view_mappings:                # Optional: Mappings for shared data
    source_tables:              # Optional: Tables from data offerings. Populates the source_table array variable.
      - <source_table_name>     # One or more source table names...
    <argument_name>: <view_name>  # Custom argument to template view name mapping
  local_view_mappings:          # Optional: Mappings for local data
    my_tables:                  # Optional: Tables from local data offerings. Populates the my_table array variable.
      - <my_table_name>         # One or more local table names...
    <argument_name>: <view_name>  # Custom argument to local template view name mapping
  arguments:                    # Optional: Template arguments as key-value pairs
    <argument_name>: <argument_value>  # One or more argument key-value pairs...
  activation:                   # Required for activation templates
    snowflake_collaborator: <alias>  # Collaborator alias for activation destination
    segment_name: <segment_name>     # Unique segment name for this activation
Copy
api_version

A versão da API do Collaboration utilizada. Deve ser 2.0.0.

spec_type

Identificador do tipo de especificação. Deve ser analysis.

template: template_name

O ID do modelo a ser utilizado para esta análise, conforme definido em um modelo YAML. Deve seguir as Regras do identificador do Snowflake com no máximo 75 caracteres.

name (opcional)

Um nome exclusivo e amigável para esta análise. Deve seguir as regras do identificador do Snowflake com um máximo de 75 caracteres e ser exclusivo na conta de sala limpa de dados do Snowflake.

version (opcional)

Um identificador de versão para esta especificação de análise (máximo de 20 caracteres). Deve seguir as Regras do identificador do Snowflake e ser único em sua conta para esse nome de análise. Um bom formato para usar é YYYY_MM_DD_V#. Por exemplo: 2025_10_22_V1.

description (opcional)

Uma descrição de alto nível do que esta análise faz (máximo de 1.000 caracteres).

template_configuration (opcional)

Valores utilizados ​​ao executar o modelo especificado.

view_mappings (opcional)

Mapeamento de nomes de argumentos para nomes de exibição de modelo para ofertas de dados compartilhadas.

source_tables (opcional)

Lista de nomes de tabelas para preencher a variável de modelo source_table. Use os aliases de tabela especificados na especificação da oferta de dados. Você pode obter uma lista de tabelas disponíveis chamando COLLABORATION.VIEW_DATA_OFFERINGS. O formato de cada entrada é collaborator alias.data offering ID.dataset alias.

argument_name: view_name

Mapeamento personalizado de um nome de argumento para um nome de exibição de modelo (máximo de 255 caracteres cada).

local_view_mappings (opcional)

Mapeamento de nomes de argumentos para nomes de exibição de modelo locais para conjuntos de dados privados.

my_tables (opcional)

Lista de nomes de tabelas para preencher a variável de modelo my_table. Isso está disponível apenas para conjuntos de dados privados que você vinculou chamando LINK_LOCAL_DATA_OFFERING. O formato de cada entrada é collaborator alias.data offering ID.dataset alias.

argument_name: view_name

Mapeamento personalizado de um nome de argumento para um nome de exibição de modelo local (máximo de 255 caracteres cada).

arguments (opcional)

Argumentos de modelo como pares chave-valor. Os valores dos argumentos podem ser cadeias de caracteres, números, booleanos, matrizes ou objetos, dependendo dos requisitos do modelo.

activation (obrigatório para modelos de ativação)

Configuração específica de ativação necessária ao executar modelos de ativação.

snowflake_collaborator

Alias ​​do colaborador para o destino da ativação (máximo de 25 caracteres). Deve corresponder a um alias definido na seção collaborator_identifier_aliases da especificação de colaboração, e o colaborador deve estar listado na seção activation_destinations.

segment_name

Nome de segmento exclusivo para esta ativação (máximo de 255 caracteres). Utilizado para identificar e rastrear os resultados da ativação. Deve seguir as regras do identificador do Snowflake.