Référence de schéma des salles blanches de données de collaboration¶

Cette rubrique décrit les schémas de spécification pour toutes les ressources de collaboration. Les spécifications sont indiquées au format YAML.

Les spécifications comportent un champ de version de schéma api_version. Utilisez le numéro de version de l’API indiqué ici ; la prise en charge des versions de schéma antérieures n’est pas garantie.

Version actuelle de l’API de collaboration DCR : 2.0.0

Spécification de collaboration¶

Définit la collaboration de haut niveau. La spécification définit les gestionnaires d’analyses invités, et pour chaque gestionnaire d’analyses, les données et les modèles auxquels il peut accéder et qu’il peut exécuter. Les modèles ou les offres de données listés ici doivent être enregistrés avant d’être inclus dans la spécification de collaboration.

Le propriétaire soumet cette définition en appelant COLLABORATION.INITIALIZE.

Schéma :

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

Version de l’API de collaboration utilisée. Doit être 2.0.0.

spec_type

Identificateur du type de spécification. Doit être collaboration.

name: collaboration_name

Nom convivial pour cette collaboration. Doit être unique dans le compte du créateur et suivre les règles des identificateurs Snowflake (maximum 75 caractères).

version (Facultatif)

Identificateur de version pour cette collaboration (maximum 20 caractères). Doit suivre les règles des identificateurs Snowflake. Un bon format à utiliser est YYYY_MM_DD_V#. Par exemple : 2025_10_22_V1.

description: collaboration_description (Facultatif)

Description de la collaboration lisible par l’utilisateur (maximum 1 000 caractères), destinée aux collaborateurs.

owner: owner_alias (Facultatif)

Alias ou identificateur de compte de partage de données du propriétaire de la collaboration. Si non spécifié, le compte qui enregistre cette spécification sera attribué en tant que propriétaire.

collaborator_identifier_aliases

Mappage des alias de collaborateurs à leurs identificateurs de compte de partage de données. Seuls les utilisateurs listés ici peuvent participer à la collaboration. Utilisez les alias définis ici pour faire référence à tous les collaborateurs, plutôt que d’utiliser directement leur identificateur de compte de partage de données.

analysis_runners

Décrit qui peut exécuter une analyse dans cette collaboration. Chaque gestionnaire d’analyses est associé à un alias unique. Vous devez autoriser au moins un compte à exécuter une analyse dans cette collaboration.

<analysis_runner_alias>

Alias du compte qui peut exécuter une analyse dans cette collaboration. L’alias est défini dans la liste collaborator_identifier_aliases.

data_providers

Fournisseurs de données dont les données peuvent être accessibles à ce gestionnaire d’analyses. Chaque fournisseur est lié par l’alias défini dans collaborator_identifier_aliases.

data_offerings

Liste des offres de données de ce fournisseur de données auxquelles le gestionnaire d’analyses peut accéder, ou un tableau vide []. Si des éléments sont présents, chaque élément possède les propriétés suivantes :

data_offering_id : ID de référence pour cette offre de données, généré lorsque le fournisseur de données appelle REGISTRY.REGISTER_DATA_OFFERING.

templates (Facultatif)

Modèles qui peuvent être utilisés par ce gestionnaire d’analyses. Chaque modèle est référencé par son ID.

activation_destinations (Facultatif)

Définit les paramètres d’activation pour les résultats de l’analyse.

snowflake_collaborators (Facultatif): Liste des collaborateurs qui peuvent recevoir des résultats d’analyse activés. Utilisez l’alias depuis la liste collaborator_identifier_aliases dans cette spécification. Tous les collaborateurs listés ici doivent disposer des autorisations décrites dans Activer les résultats de la requête.

Exemples¶

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

Spécification de l’offre de données¶

Définit un ensemble de tables qu’un fournisseur est prêt à partager avec les gestionnaires d’analyses, ainsi que des règles de partage, telles que des politiques, des formats de colonnes et la possibilité d’utiliser la table avec un modèle.

Le fournisseur de données soumet cette définition en appelant REGISTRY.REGISTER_DATA_OFFERING, qui renvoie un ID d’offre qui peut être utilisé dans la définition de la collaboration.

Une offre de données ne sera pas disponible dans une collaboration tant que le compte qui a enregistré l’offre de données ne rejoindra pas la collaboration.

Vous devez disposer du privilège de compte REGISTER DATA OFFERING pour rejoindre toute collaboration dans laquelle vous pouvez activer des données (c’est-à-dire que vous êtes un gestionnaire d’analyses et que la spécification de la collaboration inclut un champ activation_destinations). Pour plus d’informations, consultez le guide de référence de l’API de gestion des accès.

Schéma :

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

Version de l’API de collaboration utilisée. Doit être 2.0.0.

spec_type

Identificateur du type de spécification. Doit être data_offering.

version

Identificateur de version personnalisé pour cette spécification d’offre de données (20 caractères maximum). Doit suivre les règles des identificateurs Snowflake. La chaîne de version reçoit sa propre colonne dans la réponse à VIEW_DATA_OFFERINGS et VIEW_REGISTERED_DATA_OFFERINGS ; utilisez donc une valeur qui peut être triée par ordre croissant. Exemple : V0

name: data_offering_name

Nom d’un ensemble de tables et de colonnes à exposer aux collaborateurs. Ce nom est utilisé comme valeur de référence pour l’offre de données dans une définition de collaboration. Vous pouvez créer plusieurs offres de données avec des tables et des colonnes qui se chevauchent pour différents cas d’utilisation. Doit suivre les règles des identificateurs Snowflake avec un maximum de 75 caractères et être unique au sein de votre compte de salles blanches de données Snowflake. La paire name_version doit être unique pour toutes les offres de données de ce compte.

description: data_offering_description (Facultatif)

Description de l’offre de données (1 000 caractères maximum).

datasets

Liste d’un ou plusieurs ensembles de données à mettre à la disposition de la collaboration.

alias: dataset_name

Nom pour cet objet de données, utilisé dans collaboration.run. Doit suivre les règles des identificateurs Snowflake et être unique au sein de cette offre.

data_object_fqn: fully_qualified_table_name

Décrit une seule table disponible pour les collaborateurs. Indiquez le nom pleinement qualifié de l’objet source dans votre compte (database.schema.table_name). La longueur maximale est de 773 caractères.

allowed_analyses: allowed_analysis_type

Le type d’analyses que les collaborateurs peuvent effectuer sur cette table. Champ obligatoire avec les valeurs suivantes :

template_only : Le gestionnaire d’analyses peut effectuer des requêtes dans cette table uniquement en utilisant un modèle répertorié dans la définition de la collaboration.
template_and_freeform_sql : Le gestionnaire d’analyses peut interroger cette table en utilisant un modèle répertorié dans la définition de la collaboration, ou en utilisant des requêtes SQL de forme libre dans un environnement de code.

object_class (Facultatif)

Type d’objet. Une des valeurs suivantes :

ads_log : Les tables et les colonnes listées ici doivent répondre aux exigences du journal des annonces.
custom : Ensemble personnalisé de tables et de colonnes qui n’a pas d’exigences particulières.

schema_and_template_policies

Fournissez une liste des noms de colonnes de la table listée par data_object_fqn et définissez les politiques et le format de chaque colonne. Seules les colonnes listées ici sont disponibles pour les collaborateurs. Chaque colonne possède les descripteurs suivants :

category: category_type

La catégorie détermine si un renommage de colonne est appliqué et si une contrainte de format de données doit être appliquée. category et column_type déterminent le nom de la colonne exposée au gestionnaire d’analyses. Les valeurs suivantes sont prises en charge :

join_standard : Il s’agit d’une colonne joignable avec des données dans un format spécifié dans le champ column_type. Cette colonne est renommée en valeur column_type dans l’offre de données partagées.
join_custom : Il s’agit d’une colonne joignable dans n’importe quel format. Utilisez ceci lorsqu’il n’existe pas de column_type approprié pour votre colonne de jointure. Le nom de colonne d’origine est utilisé dans l’offre de données partagées.
timestamp : Il s’agit d’une colonne projetable qui spécifie un horodatage pour tout événement. La colonne est renommée timestamp dans l’offre de données partagées.
passthrough : Il s’agit d’une colonne projetable de tout autre type. Le nom de colonne d’origine est utilisé dans l’offre de données partagées.

column_type: <format_type> (Obligatoire lorsque catégorie=join_standard, ignoré pour les autres types de catégories)

Format des données. Si les données ne sont pas conformes à ce format, votre appel à REGISTER_DATA_OFFERING échouera. Fournissez ce champ pour les colonnes où category = join_standard. category et column_type déterminent le nom de la colonne exposée au gestionnaire d’analyses. Vous ne pouvez pas attribuer la même valeur column_type à plusieurs colonnes d’une même table. Les types de formats suivants sont pris en charge :

email : Adresse e-mail brute.
hashed_email_sha256 : E-mail haché SHA256.
hashed_email_b64_encoded : E-mail haché codé en base64.
phone : Numéro de téléphone sans ponctuation. Par exemple : 2015551212.
hashed_phone_sha256 : Numéro de téléphone haché SHA256. Le numéro d’origine doit être au format phone.
hashed_phone_b64_encoded : Numéro de téléphone haché codé en base64.
device_id : Un ID d’appareil brut, comme un ID publicitaire mobile ou un ID d’appareil CTV.
hashed_device_id_sha256 : ID d’appareil haché SHA256. L’identifiant d’origine doit être au format device_id.
hashed_device_b64_encoded : ID d’appareil haché codé en base64.
ip_address : Adresse IP brute au format IPv4.
hashed_ip_address_sha256 : adresse IPv4 hachée SHA256. L’adresse IP d’origine doit être au format ip_address.
hashed_ip_address_b64_encoded : Adresse IP hachée codée en base64.

activation_allowed (Facultatif)

Indique si cette colonne peut être utilisée à des fins d’activation. La valeur par défaut est false.

freeform_sql_policies (Facultatif)
Si allowed_analyses correspond à template_and_freeform_sql, ce champ facultatif répertorie toutes les politiques de Snowflake qui doivent être appliquées sous forme de requêtes SQL de forme libre exécutées sur cette offre de données. Pour plus d’informations, voir Appliquer la politique à l’offre de données (utilisation des requêtes libres uniquement).

Les types suivants sont pris en charge :

aggregation_policy (Facultatif)
Configuration unique de la politique d’agrégation.

name : Nom pleinement qualifié de la politique.

entity_keys (Facultatif) : Liste des noms de colonnes qui servent de clés d’entité pour la politique d’agrégation.

join_policy (Facultatif)
Configuration unique de la politique de jointure.

name : Nom pleinement qualifié de la politique.

columns (Facultatif) : Liste des noms de colonnes auxquels cette politique s’applique.

masking_policies (Facultatif)
Tableau des configurations de la politique de masquage.

name : Nom pleinement qualifié de la politique.

columns (Facultatif) : Liste des noms de colonnes auxquels cette politique s’applique.

projection_policies (Facultatif)
Tableau des configurations de la politique de projection.

name : Nom pleinement qualifié de la politique.

columns (Facultatif) : Liste des noms de colonnes auxquels cette politique s’applique.

row_access_policy (Facultatif)
Tableau des configurations de la politique d’accès aux lignes.

name : Nom pleinement qualifié de la politique.

columns (Facultatif) : Liste des noms de colonnes auxquels cette politique s’applique.

require_freeform_sql_policy (Facultatif)
Indique si cette source de données doit avoir une freeform_sql_policies définie. Ce type est utilisé comme un Fail-safe pour empêcher l’ajout d’une source de données qui prend en charge les requêtes SQL de forme libre sans lui attribuer de politiques.

Spécification des ressources du modèle¶

Définit un modèle unique dans une collaboration. Envoyé à REGISTRY.REGISTER_TEMPLATE pour enregistrer un modèle à utiliser dans une collaboration.

Schéma :

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

Version de l’API de collaboration utilisée. Doit être 2.0.0.

spec_type

Identificateur du type de spécification. Doit être template.

name

Nom unique et convivial pour ce modèle. Doit suivre les règles des identificateurs Snowflake avec un maximum de 75 caractères. La paire name_version doit être unique pour tous les modèles de ce compte.

version

Identificateur de version pour ce modèle (20 caractères maximum). Doit suivre les règles des identificateurs Snowflake. La chaîne de version reçoit sa propre colonne dans la réponse à VIEW_TEMPLATES et VIEW_REGISTERED_TEMPLATES ; utilisez donc une valeur qui peut être triée par ordre croissant. Exemple : V0

type

Type de modèle. Une des valeurs suivantes :

sql_analysis : Modèle pour les opérations d’analyse des données.
sql_activation : Modèle pour les opérations d’activation des données.

description: template_description (Facultatif)

Description de haut niveau de ce que fait ce modèle (maximum 1 000 caractères).

methodology: methodology_description (Facultatif)

Description plus détaillée du fonctionnement de ce modèle (maximum 1 000 caractères).

parameters (Facultatif)

Liste de tous les paramètres fournis par l’utilisateur dans ce modèle. Chaque élément peut contenir les champs suivants :

name : Nom du paramètre sous forme d’identificateur Snowflake valide.
description (Facultatif) : Description du paramètre lisible par l’utilisateur (maximum 500 caractères).
required (Facultatif) : Indique si le paramètre est requis ou non. La valeur par défaut est false.
default (Facultatif) : Valeur par défaut pour le paramètre, qui peut être n’importe quel type de données.
type (Facultatif) : Type de données attendu du paramètre. L’un des types suivants : string, integer, number, boolean, array ou object.

template

Contenu du modèle. Pour les modèles SQL, contient le modèle JinjaSQL. Pour plus d’informations, voir Conception de modèles pour une collaboration.

Les noms des colonnes exposées au modèle sont déterminés par les valeurs category et column_type pour la colonne dans la définition de l’offre de données. Pour plus d’informations, voir Renommage de colonne source.

Exemple :

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

Spécification de la requête d’analyse¶

Spécifie toutes les informations dont les gestionnaires d’analyses ont besoin pour exécuter une analyse, y compris le modèle à utiliser, les tables à transmettre au modèle et toutes les valeurs des variables utilisées par un modèle. Si vous n’utilisez pas de SQL de forme libre pour interroger des données, tous les gestionnaires d’analyses qui souhaitent effectuer une analyse utilisent cette spécification pour définir le modèle et les données d’entrée.

Schéma :

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

Version de l’API de collaboration utilisée. Doit être 2.0.0.

spec_type

Identificateur du type de spécification. Doit être analysis.

template: template_name

ID du modèle à utiliser pour cette analyse, tel que défini dans un YAML de modèle. Doit suivre les règles des identificateurs Snowflake avec un maximum de 75 caractères.

name (Facultatif)

Nom unique et convivial pour cette analyse. Doit suivre les règles des identificateurs Snowflake avec un maximum de 75 caractères et être unique au sein de votre compte de salles blanches de données Snowflake.

version (Facultatif)

Identificateur de version pour cette spécification d’analyse (maximum 20 caractères). Doit suivre les règles des identificateurs Snowflake et être unique au sein de votre compte pour ce nom d’analyse. Un bon format à utiliser est YYYY_MM_DD_V#. Par exemple : 2025_10_22_V1.

description (Facultatif)

Description de haut niveau de ce que fait cette analyse (maximum 1 000 caractères).

template_configuration (Facultatif)

Valeurs utilisées lors de l’exécution du modèle spécifié.

view_mappings (Facultatif)

Mappage des noms des arguments avec les noms des vues des modèles pour les offres de données partagées.

source_tables (Facultatif): Liste des noms de tables à utiliser pour remplir la variable de modèle source_table. Utilisez les alias de tables spécifiés dans la spécification de l’offre de données. Vous pouvez obtenir une liste des tables disponibles en appelant COLLABORATION.VIEW_DATA_OFFERINGS. Le format de chaque entrée est collaborator alias.data offering ID.dataset alias.
argument_name: view_name: Mappage personnalisé d’un nom d’argument vers un nom de vue de modèle (maximum 255 caractères chacun).

local_view_mappings (Facultatif)

Mappage des noms des arguments avec les noms des vues des modèles locaux pour les ensembles de données privés.

my_tables (Facultatif): Liste des noms de tables à utiliser pour remplir la variable de modèle my_table. Celle-ci n’est disponible que pour les ensembles de données privés que vous avez liés en appelant LINK_LOCAL_DATA_OFFERING. Le format de chaque entrée est collaborator alias.data offering ID.dataset alias.
argument_name: view_name: Mappage personnalisé d’un nom d’argument vers un nom de vue de modèle local (maximum 255 caractères chacun).

arguments (Facultatif)

Arguments du modèle sous forme de paires clé-valeur. Les valeurs des arguments peuvent être des chaînes, des nombres, des booléens, des tableaux ou des objets, en fonction des exigences du modèle.

activation (Requis pour les modèles d’activation)

Configuration spécifique à l’activation requise lors de l’exécution de modèles d’activation.

snowflake_collaborator: Alias de collaborateur pour la destination de l’activation (maximum 25 caractères). Doit correspondre à un alias défini dans la section collaborator_identifier_aliases de la spécification de collaboration, et le collaborateur doit être répertorié dans la section activation_destinations.
segment_name: Nom de segment unique pour cette activation (maximum 255 caractères). Utilisé pour identifier et suivre les résultats de l’activation. Doit suivre les règles des identificateurs Snowflake.