Umgebung einrichten¶

Führen Sie die folgenden Befehle aus, um die Snowflake-Umgebung einzurichten, bevor Sie Entwickler-APIs für die Arbeit mit einem Snowflake Data Clean Room verwenden. Wenn Sie nicht über die Rolle SAMOOHA_APP_ROLE verfügen, wenden Sie sich an Ihren Kontoadministrator.

use role samooha_app_role;
use warehouse app_wh;

Reinraum erstellen¶

Erstellen Sie einen Namen für den Reinraum. Geben Sie einen neuen Reinraumnamen ein, um Kollisionen mit bestehenden Reinraumnamen zu vermeiden. Beachten Sie, dass Reinraumnamen nur alphanumerisch sein können. Reinraumnamen dürfen keine anderen Sonderzeichen als Leerzeichen und Unterstriche enthalten.

set cleanroom_name = 'Snowpark Demo clean room';

Sie können einen neuen Reinraum mit dem oben festgelegten Reinraumnamen erstellen. Wenn der oben angegebene Name des Reinraums bereits als bestehender Reinraum existiert, schlägt dieser Vorgang fehl.

Die Ausführung dieser Prozedur dauert etwa 45 Sekunden.

Das zweite Argument von provider.cleanroom_init ist die Distribution des Reinraums. Diese kann entweder INTERNAL oder EXTERNAL sein. Wenn Sie zu Testzwecken den Reinraum für ein Konto in derselben Organisation freigeben, können Sie INTERNAL verwenden, um den automatischen Sicherheitsscan zu umgehen, der stattfinden muss, bevor ein Anwendungspaket für Teilnehmer freigegeben wird. Wenn Sie diesen Reinraum jedoch für ein Konto in einer anderen Organisation freigeben, müssen Sie eine EXTERNAL-Distribution des Reinraums verwenden.

call samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

Um den Status des Sicherheitsscans zu anzuzeigen, führen Sie Folgendes aus:

call samooha_by_snowflake_local_db.provider.view_cleanroom_scan_status($cleanroom_name);

Sobald Sie Ihren Reinraum erstellt haben, müssen Sie erst seine Release-Richtlinie festlegen, bevor er für andere Teilnehmer freigegeben werden kann. Wenn Ihre Distribution jedoch auf EXTERNAL eingestellt wurde, müssen Sie zunächst den Abschluss der Sicherheitsscan abwarten, bevor Sie die Release-Richtlinie festlegen. Während des Scan läuft, können Sie mit den restlichen Schritten fortfahren und vor dem Schritt provider.create_cleanroom_listing hierher zurückkehren.

Um die Release-Richtlinie festzulegen, rufen Sie Folgendes auf:

call samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '0');

Regionsübergreifende Freigabe¶

Um einen Reinraum für einen Snowflake-Kunden freizugeben, dessen Konto sich in einer anderen Region befindet als Ihr Konto, müssen Sie die Cloud-übergreifende automatische Ausführung (Cross-Cloud Auto-Fulfillment) aktivieren. Informationen zu den zusätzlichen Kosten, die bei der Zusammenarbeit mit Verbrauchern in anderen Regionen anfallen, finden Sie unter Kosten für Cloud-übergreifende automatische Ausführung.

Wenn Sie Entwickler-APIs verwenden, müssen Sie die regionsübergreifende Freigabe in zwei Schritten aktivieren:

1. Ein Snowflake-Administrator mit der Rolle ACCOUNTADMIN muss die Cloud-übergreifende automatische Ausführung für Ihr Snowflake-Konto aktivieren. Eine Anleitung dazu finden Sie unter [Mit Konten in verschiedenen Regionen zusammenarbeiten] (https://docs.snowflake.com/en/user-guide/cleanrooms/getting-started#collaborate-with-accounts-in-different-regions).

2. Sie führen den Befehl provider.enable_laf_for_cleanroom aus, um die Cloud-übergreifende automatische Ausführung für den Reinraum zu aktivieren. Beispiel:

   call samooha_by_snowflake_local_db.provider.enable_laf_for_cleanroom($cleanroom_name);
   

   Copy

Nachdem Sie die Cloud-übergreifende automatische Ausführung für den Reinraum aktiviert haben, können Sie mit dem Befehl provider.create_cleanroom_listing wie gewohnt Verbraucher zu Ihrem Freigabeangebot hinzufügen. Das Freigabeangebot wird bei Bedarf automatisch in externe Clouds und Regionen repliziert.

Datenset verknüpfen und Verknüpfungsrichtlinie festlegen¶

Verknüpfen Sie Snowflake-Tabellen mit dem Reinraum. Diese Datensets werden Ihnen mit dem neuesten Patch auf Ihrem Konto zur Verfügung gestellt. Durchsuchen Sie die Liste der Tabellen in Ihrem Snowflake-Konto, und geben Sie die vollqualifizierten Tabellennamen (Database.Schema.Table) als Array ein. Die Prozedur macht die Tabelle automatisch für den Reinraum zugänglich, indem es eine sichere Ansicht der Tabelle vom Reinraum aus erstellt, sodass keine Kopie Ihrer Tabelle erstellt werden muss.

call samooha_by_snowflake_local_db.provider.link_datasets($cleanroom_name, ['<IMPRESSIONS_TABLE>']);

Wenn Sie stattdessen eine Ansicht mit dem Reinraum verknüpfen möchten, die nachgelagerte Abhängigkeiten hat, verwenden Sie provider.link_datasets_advanced:

call samooha_by_snowflake_local_db.provider.link_datasets_advanced($cleanroom_name, ['<VIEW_NAME>'], ['<SOURCE_DB_NAMES>']);

use role accountadmin;
call samooha_by_snowflake_local_db.provider.register_db('<DATABASE_NAME>');
use role samooha_app_role;

Sie können die mit dem Reinraum verknüpften Datensets mit der folgenden Prozedur anzeigen:

call samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

Um herauszufinden, welche Spalten als Verknüpfungsrichtlinie verwendet werden sollen, können Sie einen Blick in Ihr Datenset werfen, um die PII-Spalten zu ermitteln. Um die obersten 10 Zeilen zu sehen, führen Sie die folgende Abfrage aus:

select * from <IMPRESSIONS_TABLE> limit 10;

Snowpark-Prozedur vertraulich in den Reinraum laden¶

In diesem Abschnitt erfahren Sie, wie Sie die Snowpark-Prozedur in den Reinraum laden. Die Prozedur führt die folgenden Schritte aus:

1. Impressionsdaten vorverarbeiten: Es wird ein dynamischer SQL-Code erstellt, der die Impressionsdaten des Anbieters mit den Benutzerdaten des Verbrauchers verknüpft, wenn die Tabelle des Verbrauchers bereitgestellt wird, dann die Anzahl der Impressions und die Reichweite nach Datum berechnet und die Ergebnisse in eine Zwischentabelle im Reinraum speichert. Wenn die Verbrauchertabelle nicht angegeben wird, wird die gesamte Impressions-Tabelle des Anbieters verwendet.

2. Zwischentabelle laden: Die Zwischentabelle wird als Pandas-Datenframe in die Snowpark-Prozedur geladen.

3. Regression durchführen: Die Regression wird mit der Bibliothek statsmodels berechnet, und die Ergebnisse werden als Pandas-Datenframe zurückgegeben.

4. Ergebnisse in Snowflake-Tabelle schreiben: Die Ergebnisse werden in eine Ergebnistabelle innerhalb des Reinraums geschrieben, und das ID-Suffix der Tabelle wird an den Verbraucher zurückgegeben.

   a. Da die Snowpark-Prozedur innerhalb des Reinraums ausgeführt wird, kann sie nur begrenzt direkt in den Verbraucher-Mandanten schreiben. Um die Ergebnisse sicherer zu machen, werden sie stattdessen in eine Tabelle innerhalb des Reinraums geschrieben, und die Verbraucher haben die Möglichkeit, aus der Tabelle zu lesen.

5. Zwischentabellen löschen: Zwischentabellen, die während der Berechnung im Reinraum erstellt wurden und nicht mehr benötigt werden, werden gelöscht, bevor die Snowpark-Prozedur beendet wird.

Mit der folgenden API können Sie Ihre Python-Funktionen direkt als Inline-Funktionen im Reinraum definieren. Alternativ können Sie Python auch aus Stagingdateien laden, die Sie in den Reinraum-Stagingbereich hochgeladen haben. Ein Beispiel dafür finden Sie im API-Referenzhandbuch.

call samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'reach_impression_regression',
    ['source_table string', 'my_table string'],
    ['snowflake-snowpark-python', 'pandas', 'statsmodels', 'numpy'],
    'string',
    'main',
    $$
import traceback
import pandas as pd
import numpy as np

import statsmodels.formula.api as sm


def drop_tables(session, table_names):
    """
    Drop the tables passed in
    """
    for tbl in table_names:
        session.sql(f'drop table {tbl}').collect()

def preprocess_regression_data(session, source_table, my_table, suffix):
    """
    Preprocess the impressions and customer data into an intermediary table for regression
    """
    table_name = f'cleanroom.intermediary_{suffix}'

    my_table_statement = f'inner join {my_table} c on p.hem = c.hem' if my_table != 'NONE' else ''
    session.sql(f"""
    create or replace table {table_name} as (
        with joint_data as (
            select
                date,
                p.hem as hem,
                impression_id
            from {source_table} p
            {my_table_statement}
        )
        select
            date,
            count(distinct hem) as reach,
            count(distinct impression_id) as num_impressions
        from joint_data
        group by date
        order by date
    );
    """).collect()

    return table_name

def calculate_regression(df):
    """
    Calculate the regression data from the dataframe we put together
    """
    result = sm.ols('REACH ~ 1 + NUM_IMPRESSIONS', data=df).fit()
    retval = pd.concat([
        result.params,
        result.tvalues,
        result.pvalues
    ], keys=['params', 't-stat', 'p-value'], names=['STATISTIC', 'PARAMETER']).rename('VALUE').reset_index()
    return retval

def main(session, source_table, my_table):
    """
    First compute the regression data from an overlap between customer and provider data, and counting
    the number of impressions and reach per day. Next regress these locally and compute the regression
    statistics. Finally write it to a results table which can be queried to get the output.
    """
    suffix = f'regression_results_{abs(hash((source_table, my_table))) % 10000}'

    try:
        # Preprocess impressions and customer data into an intermediary form to use for regression
        intermediary_table_name = preprocess_regression_data(session, source_table, my_table, suffix)

        # Load the data into Python locally
        df = session.table(intermediary_table_name).to_pandas()

        # Carry out the regression and get statistics as an output
        regression_output = calculate_regression(df)

        # Write the statistics to an output table
        # The table and the schema names should be in upper case to quoted identifier related issues.
        table = f'results_{suffix}'.upper()
        retval_df = session.write_pandas(regression_output, table,  schema = 'CLEANROOM', auto_create_table = True)

        # Drop any intermediary tables
        drop_tables(session, [intermediary_table_name])

        # Tell the user the name of the table the results have been written to
        return f'Done, results have been written to the following suffix: {suffix}'
    except:
        return traceback.format_exc()
$$
);

-- See the versions available inside the clean room
show versions in application package samooha_cleanroom_Snowpark_Demo_clean_room;

-- Once the security scan is approved, update the release directive to the latest version
call samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '1');

Benutzerdefinierte Vorlage unter Verwendung der UDFs hinzufügen¶

Um eine benutzerdefinierte Analysevorlage zum Reinraum hinzuzufügen, benötigen Sie einen Platzhalter für Tabellennamen auf Anbieter- und Verbraucherseite sowie Join-Spalten auf der Anbieterseite. In SQL Jinja-Vorlagen müssen diese Platzhalter immer wie folgt sein:

• source_table: Ein Array von Tabellennamen des Anbieters.

• my_table: Ein Array von Tabellennamen des Verbrauchers.

Tabellennamen können durch die Verwendung dieser Variablen dynamisch gemacht werden, aber sie können in der Vorlage auch hartkodiert werden, wenn Sie den Namen der mit dem Reinraum verknüpften Ansicht verwenden. Die Spaltennamen können entweder fest in der Vorlage kodiert oder dynamisch über Parameter festgelegt werden. Wenn sie über Parameter festgelegt werden, denken Sie daran, dass Sie die Parameter dimensions oder measure_column aufrufen müssen, die Arrays sein müssen, damit sie mit der Spaltenrichtlinie abgeglichen werden können. Sie fügen diese als SQL Jinja-Parameter in die Vorlage ein, die später vom Verbraucher beim Ausführen der Abfrage übergeben werden. Die Verknüpfungsrichtlinien stellen sicher, dass der Verbraucher keine anderen als die autorisierten Spalten verknüpfen kann.

Alternativ kann jedes Argument in einer benutzerdefinierten SQL Jinja-Vorlage mit den folgenden Filtern auf die Einhaltung der Verknüpfungs- und Spaltenrichtlinien überprüft werden:

• join_policy: Prüft, ob ein String-Wert oder eine Filterklausel mit der Verknüpfungsrichtlinie konform ist.

• column_policy: Prüft, ob ein String-Wert oder eine Filterklausel mit der Spaltenrichtlinie konform ist.

• join_and_column_policy: Prüft, ob Spalten, die für eine Verknüpfung in einer Filterklausel verwendet werden, mit der Verknüpfungsrichtlinie übereinstimmen, und ob Spalten, die als Filter verwendet werden, mit der Spaltenrichtlinie übereinstimmen.

Beispielsweise wird in der Klausel {{ provider_id | sqlsafe | join_policy }} eine Eingabe von p.HEM geparst, um zu prüfen, ob p.HEM in der Verknüpfungsrichtlinie enthalten ist. Hinweis: Verwenden Sie den Filter sqlsafe nur mit Vorsicht, da er es Teilnehmern erlaubt, reines SQL in die Vorlage einzubringen.

Beachten Sie, dass diese Funktion jede vorhandene Vorlage mit demselben Namen überschreibt. Wenn Sie eine bestehende Vorlage aktualisieren möchten, rufen Sie einfach diese Funktion erneut mit der aktualisierten Vorlage auf.

call samooha_by_snowflake_local_db.provider.add_custom_sql_template(
        $cleanroom_name,
        'prod_calculate_regression',
        $$
call cleanroom.reach_impression_regression({{ source_table[0] }}, {{ my_table[0] | default('NONE') }});
$$
);

Schließlich wird eine benutzerdefinierte Vorlage hinzugefügt, die es dem Verbraucher ermöglicht, die Ergebnisse seiner Analyse anhand der Ergebnissuffix-ID abzurufen, die von der „calculate_regression“-Vorlage zurückgegeben werden.

call samooha_by_snowflake_local_db.provider.add_custom_sql_template(
        $cleanroom_name,
        'prod_get_results',
        $$
select * from cleanroom.results_{{ results_suffix | sqlsafe }};
$$
);

Wenn Sie die derzeit im Reinraum aktiven Vorlagen anzeigen möchten, rufen Sie die folgende Prozedur auf.

call samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);

Für Verbraucher freigeben¶

Fügen Sie schließlich einen Datenverbraucher zum Reinraum hinzu, indem Sie dessen Snowflake-Konto-Locator und Kontonamen wie unten gezeigt hinzufügen. Der Name des Snowflake-Kontos muss das Format <ORGANIZATION>.<ACCOUNT_NAME\> haben.

show versions in application package samooha_cleanroom_Snowpark_Demo_clean_room;

call samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name, '<CONSUMER_ACCOUNT_LOCATOR>', '<CONSUMER_ACCOUNT_NAME>');
call samooha_By_snowflake_local_db.provider.create_cleanroom_listing($cleanroom_name, '<CONSUMER_ACCOUNT_NAME>');

Mehrere Verbraucherkonto-Locators können der Funktion provider.add_consumers als kommagetrennte Zeichenfolge oder als separate Aufrufe von provider.add_consumers übergeben werden.

Wenn Sie die Verbraucher anzeigen möchten, die diesem Reinraum hinzugefügt wurden, rufen Sie die folgende Prozedur auf.

call samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

Sie können die zuletzt erstellten Reinräume anzeigen, indem Sie die folgende Prozedur ausführen:

call samooha_by_snowflake_local_db.provider.view_cleanrooms();

Sie können sich weitere Informationen zu dem zuletzt erstellten Reinraum anzeigen, indem Sie die folgende Prozedur ausführen:

call samooha_by_snowflake_local_db.provider.describe_cleanroom($cleanroom_name);

Jeder erstellte Reinraum kann auch wieder gelöscht werden. Mit dem folgenden Befehl wird der Reinraum vollständig gelöscht, sodass alle Verbraucher, die zuvor Zugang zum Reinraum hatten, diesen nicht mehr nutzen können. Wenn in Zukunft ein Reinraum mit demselben Namen gewünscht wird, muss er mit dem oben beschriebenen Workflow neu initialisiert werden.

call samooha_by_snowflake_local_db.provider.drop_cleanroom($cleanroom_name);

Umgebung einrichten¶

Führen Sie die folgenden Befehle aus, um die Snowflake-Umgebung einzurichten, bevor Sie Entwickler-APIs für die Arbeit mit einem Snowflake Data Clean Room verwenden. Wenn Sie nicht über die Rolle SAMOOHA_APP_ROLE verfügen, wenden Sie sich an Ihren Kontoadministrator.

use role samooha_app_role;
use warehouse app_wh;

Reinraum installieren¶

Nachdem eine Reinraumfreigabe installiert wurde, können Sie die Liste der verfügbaren Reinräume mit dem folgenden Befehl anzeigen.

call samooha_by_snowflake_local_db.consumer.view_cleanrooms();

Vergeben Sie einen Namen für den Reinraum, den der Anbieter für Sie freigegeben hat.

set cleanroom_name = 'Snowpark Demo clean room';

Mit dem folgenden Befehl wird der Reinraum im Verbraucherkonto mit dem zugehörigen Anbieter und dem ausgewählten Reinraum installiert.

Die Ausführung dieser Prozedur dauert etwa 45 Sekunden.

call samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<PROVIDER_ACCOUNT_LOCATOR>');

Nachdem der Reinraum installiert wurde, muss der Anbieter den Reinraum auf seiner Seite fertig einrichten, bevor er für die Nutzung aktiviert wird. Mit der folgenden Funktion können Sie den Status des Reinraums überprüfen. Sobald er aktiviert ist, sollten Sie den „run_analysis“-Befehl ausführen können. Es dauert normalerweise etwa 1 Minute, bis der Reinraum aktiviert ist.

Stellen Sie sicher, dass die Funktion install_cleanroom beendet ist, bevor Sie diese Funktion ausführen.

call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);

Datenset verknüpfen¶

Jetzt können Sie Datensets mit dem Reinraum verknüpfen, um sicheres Computing mit den Daten des Anbieters durchzuführen. Diese Datensets werden Ihnen mit dem neuesten Patch auf Ihrem Konto zur Verfügung gestellt.

call samooha_by_snowflake_local_db.consumer.link_datasets($cleanroom_name, ['<USERS_TABLE>']);

use role accountadmin;
call samooha_by_snowflake_local_db.consumer.register_db('<DATABASE_NAME>');
use role samooha_app_role;

Um die Analyse durchzuführen, müssen Sie die Verbrauchertabelle übergeben. Wenn Sie die Datensets anzeigen möchten, die Sie dem Reinraum hinzugefügt haben, rufen Sie die folgende Prozedur auf.

call samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

Analyse ausführen¶

Jetzt, da der Reinraum installiert ist, können Sie die Analysevorlage, die der Anbieter im Reinraum bereitgestellt hat, mit dem Befehl „run_analysis“ ausführen. In den folgenden Abschnitten erfahren Sie, wie die einzelnen Felder bestimmt werden.

Die Anzahl der Datensets, die übergeben werden können, wird durch die Vorlage eingeschränkt, die der Anbieter implementiert hat. Einige Vorlagen erfordern eine spezifizierte Anzahl von Tabellen. Der Vorlagenersteller kann die Anforderungen implementieren, die unterstützt werden sollen.

call samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,               -- cleanroom
  'prod_calculate_regression',    -- template name

  ['<USERS_TABLE>'],    -- consumer tables

  ['<IMPRESSSIONS_TABLE>'],     -- provider tables

  object_construct()     -- Rest of the custom arguments needed for the template
);

Die Ausgabe dieser Analyse ist eine ID, die zum Abrufen der Ergebnisse der Regression mit der folgenden Vorlage verwendet werden kann:

set result_suffix = 'regression_results_<ID>';

call samooha_by_snowflake_local_db.consumer.run_analysis(
    $cleanroom_name,        -- cleanroom
    'prod_get_results',     -- template name
    [],                     -- consumer tables
    [],                     -- provider tables
    object_construct(
        'results_suffix', $result_suffix  -- The suffix with the results
    )
);

Eingaben für „run_analysis“ bestimmen¶

Um die Analyse auszuführen, müssen Sie einige Parameter an die Funktion „run_analysis“ übergeben. In diesem Abschnitt erfahren Sie, wie Sie ermitteln, welche Parameter Sie übergeben müssen.

Vorlagennamen

Zuerst können Sie die unterstützten Analysevorlagen anzeigen, indem Sie die folgende Prozedur aufrufen.

call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

Um die Analyse auszuführen, müssen Sie einige Parameter an die Funktion „run_analysis“ übergeben. In diesem Abschnitt erfahren Sie, wie Sie ermitteln, welche Parameter Sie übergeben müssen.

call samooha_by_snowflake_local_db.consumer.view_template_definition($cleanroom_name, 'prod_calculate_regression');

Diese kann oft auch eine große Anzahl verschiedener SQL Jinja-Parameter enthalten. Die folgende Funktion analysiert die Jinja-Vorlage SQL und extrahiert die Argumente, die in „run_analysis“ spezifiziert werden müssen, in eine Liste.

call samooha_by_snowflake_local_db.consumer.get_arguments_from_template($cleanroom_name, 'prod_calculate_regression');

Datensetnamen

Wenn Sie die Namen der Datensets anzeigen möchten, die vom Anbieter zum Reinraum hinzugefügt wurden, rufen Sie die folgende Prozedur auf. Beachten Sie, dass Sie die Daten in den Datensets, die vom Anbieter zum Reinraum hinzugefügt wurden, aufgrund der Sicherheitseigenschaften des Reinraums nicht anzeigen können.

call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

Sie können auch die Tabellen anzeigen, die Sie mit dem Reinraum verknüpft haben, indem Sie den folgenden Befehl ausführen:

call samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);