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 REGISTER_DATA_OFFERING, que retorna um ID de oferta que pode ser usado na especificação da 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, passthrough, or event_type
        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 POSSIBLY RENAMED 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 POSSIBLY RENAMED 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 POSSIBLY RENAMED 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 POSSIBLY RENAMED column names...
      row_access_policy:        # Optional: Row access policy
        name: <fully_qualified_policy_name>
        columns:              # Optional: Columns this policy applies to
          - <column_name>     # One or more POSSIBLY RENAMED column names...
    require_freeform_sql_policy: <true_or_false>  # Optional: Require a policy for freeform SQL

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.

name: data_offering_name

Um nome para um conjunto de tabelas e colunas a serem expostas aos colaboradores. Esse nome é usado como o valor de referência da oferta de dados em uma especificaçã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.

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

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. Máximo de 75 caracteres.

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 da análise pode consultar essa tabela somente usando um modelo listado na especificação da colaboração.
template_and_freeform_sql: O executor da análise pode consultar essa tabela usando um modelo listado na especificaçã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. Essa coluna é adicionada à política de junção da sala limpa.
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. Essa coluna é adicionada à política de junção da sala limpa.
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.
event_type: Essa é uma coluna programável que registra uma classificação de tipo de evento para a linha, por exemplo: “compra”, “inscrição”, “impressão”, “clique” e assim em diante.

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.
first_name: Um nome bruto.
hashed_first_name_sha256: Um nome SHA256 com hash. O original deve estar no formato first_name.
hashed_first_name_b64_encoded: Um nome com hash codificado em base64.
last_name: Um sobrenome bruto.
hashed_last_name_sha256: Um sobrenome SHA256 com hash. O original deve estar no formato last_name.
hashed_last_name_b64_encoded: Um sobrenome 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 do Snowflake à oferta de dados (somente para uso da 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. NOTE: se essas colunas tiverem sido renomeadas, você deve usar o nome da coluna gerada.

join_policy (opcional)
Uma única configuração de política de junção.

name: O nome da política totalmente qualificada. NOTE: se essa coluna tiver sido renomeada, você deve usar o nome da coluna gerada.

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. NOTE: se essa coluna tiver sido renomeada, você deve usar o nome da coluna gerada.

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. NOTE: se essa coluna tiver sido renomeada, você deve usar o nome da coluna gerada.

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

row_access_policy (opcional)
Um objeto que descreve uma configuração de política de acesso a linhas.

name: O nome da política totalmente qualificada. NOTE: se essa coluna tiver sido renomeada, você deve usar o nome da coluna gerada.

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

require_freeform_sql_policy (opcional)
Se essa fonte de dados deve definir freeform_sql_policies. Isso é utilizado como uma medida de segurança para impedir a vinculação de uma fonte de dados compatível com as consultas SQL de formato livre sem atribuir políticas a ela.