Snowflake Data Clean Rooms: Erstellen Sie eine benutzerdefinierte Analysevorlage mit einer Weboberfläche

In diesem Thema wird beschrieben, wie ein Anbieter einen Reinraum programmatisch erstellen und für einen Verbraucher freigeben kann. Gleichzeitig wird eine Weboberfläche bereitgestellt, über die der Verbraucher eine Analyse in der Web-App durchführen kann. Dieser Workflow ähnelt dem [Machine Learning-Workflow] (maschinelles Lernen), zeigt aber, wie dem Verbraucher eine Benutzeroberfläche für einen ansonsten komplexen Machine-Learning-Workflow zur Verfügung gestellt werden kann.

Dieses Beispiel generiert einen Reinraum mit einer Lookalike Modeling-Vorlage. Lookalike Modeling ist eine Art der Analyse, bei der ein Verbraucher versucht, „wertvolle“ Kunden aus den Daten eines Anbieters zu finden, indem er ein statistisches Modell auf deren hochwertige Kunden trainiert. Dieses Modell verwendet vom Verbraucher definierte Flags, um im Datenset des Verbrauchers wertvolle Benutzer zu kennzeichnen, z. B. solche, deren Ausgaben einen bestimmten Schwellenwert überschreiten. Das trainierte Modell wird dann verwendet, um abzuleiten, welche Kunden in den Daten des Anbieters für den Verbraucher potenziell „wertvoll“ sein könnten.

Sie können mehrere benutzerdefinierte Vorlagen auf einen Reinraum anwenden, von denen jede in der Web-App für den Verbraucher angezeigt wird.

Dies ist der allgemeine Ablauf für die Erstellung und gemeinsame Nutzung eines Reinraums mit einer UI:

  • Anbieter:

    1. Richten Sie Ihre Coding-Umgebung ein, einschließlich der Angabe der richtigen Rolle und des zu verwendenden Warehouses.

    2. Erstellen Sie den Reinraum, und aktivieren Sie die für den Reinraum erforderliche regionenübergreifende Freigabe.

    3. Fügen Sie Ihre Daten zu den Reinräumen hinzu, und legen Sie Verknüpfungsrichtlinien für die Tabelle fest.

    4. Fügen Sie die von Ihnen benötigten Skripte hinzu.

    5. Legen Sie die Spaltenrichtlinien für die Vorlage fest.

    6. Erstellen Sie die UI für Ihre Vorlage, und wenden Sie sie auf die Web-App an.

    7. Teilen Sie Ihren Reinraum mit den Verbrauchern.

  • Verbraucher:

    1. Verwenden Sie die Web-App, um den Reinraum zu installieren und Analysen darin auszuführen.

Voraussetzungen

Sie benötigen zwei separate Snowflake-Konten, um diesen Workflow durchführen zu können. Verwenden Sie das erste Konto, um die Befehle des Anbieters auszuführen, und wechseln Sie dann zum zweiten Konto, um die Befehle des Verbrauchers auszuführen.

Anbieter

Verwenden Sie ein Snowflake-Arbeitsblatt im Anbieterkonto, um die Befehle in diesem Abschnitt auszuführen.

Umgebung einrichten

Bevor Sie die Developer-APIs verwenden, müssen Sie die Rolle SAMOOHA_APP_ROLE annehmen und das Warehouse angeben, das zur Ausführung der APIs verwendet wird. Wenn Sie nicht über die Rolle SAMOOHA_APP_ROLE verfügen, wenden Sie sich an Ihren Kontoadministrator.

Führen Sie die folgenden Befehle aus, um Ihre Umgebung einzurichten:

USE ROLE samooha_app_role;
USE WAREHOUSE app_wh;
Copy

Reinraum erstellen

Bevor Sie einen Reinraum erstellen, müssen Sie einen alphanumerischen Namen für den Reinraum angeben. Der Name darf keine Sonderzeichen außer Leerzeichen und Unterstrichen enthalten. Vergewissern Sie sich, dass der Name des Reinraums nicht mit einem bereits bestehenden Reinraum übereinstimmt.

Um den Namen des Reinraums anzugeben, führen Sie den folgenden Befehl aus:

SET cleanroom_name = 'UI Registration ML Clean room';
Copy

Sie sind nun bereit, den Befehl provider.cleanroom_init auszuführen, um den Reinraum zu erstellen. Das zweite Argument definiert die Distribution des Reinraums. In diesem Beispiel setzen Sie diese Option auf INTERNAL, um die automatische Sicherheitsscans zu umgehen, die stattfindet, bevor der Reinraum für Teilnehmer freigegeben werden kann. Die Anbieter- und Verbraucherkonten müssen sich in derselben Organisation befinden, um die Distributionsmethode INTERNAL verwenden zu können. Für Reinräume, die an ein Konto in einer anderen Organisation verteilt werden, müssen Sie eine EXTERNAL-Distribution verwenden.

Um den Reinraum zu erstellen, führen Sie den folgenden Befehl aus:

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

Nachdem Sie Ihren Reinraum erstellt haben, müssen Sie erst seine Release-Richtlinie festlegen, bevor Sie ihn für andere Teilnehmer freigeben können.

Bemerkung

Wenn Sie für die Distribution eines Reinraums EXTERNAL eingestellt haben, müssen Sie warten, bis der Sicherheitsscan abgeschlossen ist, bevor Sie die Release-Richtlinie festlegen können. 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);
Copy

Sie können während der Sicherheitsüberprüfung weiterhin Befehle ausführen, solange Sie die Release-Richtlinie setzen, bevor Sie versuchen, den Befehl provider.create_or_update_cleanroom_listing auszuführen.

Um die Release-Richtlinie für den Reinraum festzulegen, führen Sie den folgenden Befehl aus:

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

Regionsübergreifende Freigabe

Um einen Reinraum mit einem Snowflake-Kunden zu teilen, dessen Konto sich in einer anderen Region befindet als Ihr Konto, müssen Sie Cross-Cloud Auto-Fulfillment aktivieren. Informationen über die zusätzlichen Kosten, die mit der Zusammenarbeit mit Verbrauchern in anderen Regionen verbunden sind, finden Sie unter Cross-Cloud Auto-Fulfillment Kosten.

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 Anweisung finden Sie unter [Mit Konten in verschiedenen Regionen zusammenarbeiten] (https://docs.snowflake.com/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 Cross-Cloud Auto-Fulfillment für den Reinraum aktiviert haben, können Sie mit dem Befehl provider.create_or_update_cleanroom_listing wie gewohnt Verbraucher zu Ihrem Freigabeangebot hinzufügen. Das Freigabeangebot wird bei Bedarf automatisch in externe Clouds und Regionen repliziert.

Fügen Sie Ihre Daten hinzu, und legen Sie Verknüpfungsrichtlinien fest

Verknüpfen Sie Snowflake-Tabellen mit dem Reinraum, 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, ['samooha_provider_sample_database.lookalike_modeling.customers']);
Copy

Bemerkung

Wenn dieser Schritt nicht funktioniert, obwohl Ihre Tabelle existiert, ist es wahrscheinlich, dass die Rolle SAMOOHA_APP_ROLE noch keinen Zugriff auf die Tabelle erhalten hat. Wenn ja, wechseln Sie in die Rolle ACCOUNTADMIN, rufen die folgende Prozedur in der Datenbank auf und wechseln dann für den Rest des Ablaufs zurück:

USE ROLE accountadmin;
CALL samooha_by_snowflake_local_db.provider.register_db('<DATABASE_NAME>');
USE ROLE samooha_app_role;
Copy

Sie können die mit dem Reinraum verknüpften Datensetnamen anzeigen, indem Sie die folgende Prozedur aufrufen.

CALL samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);
Copy

Sie können die mit dem Reinraum verknüpften Datensätze mit der folgenden Abfrage anzeigen:

SELECT * FROM <PROVIDER_TABLE> LIMIT 10;
Copy

Legen Sie fest, auf welche Spalten der Verbraucher zugreifen darf, wenn er Vorlagen im Reinraum ausführt. Diese Prozedur sollte bei Identitätsspalten wie E-Mail aufgerufen werden. Die Verknüpfungsrichtlinie ist „nur ersetzen“, d. h. wenn die Funktion erneut aufgerufen wird, wird die zuvor festgelegte Verknüpfungsrichtlinie vollständig durch die neue ersetzt.

CALL samooha_by_snowflake_local_db.provider.set_join_policy($cleanroom_name, ['samooha_provider_sample_database.lookalike_modeling.customers:hashed_email']);
Copy

Wenn Sie alle Spalten anzeigen möchten, um die Spalten der Verknüpfungsrichtlinie zu bestimmen, rufen Sie die folgende Prozedur auf.

CALL samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);
Copy

Fügen Sie Ihren eigenen Code hinzu

Vertraulichen Machine-Learning-Python-Code zum Reinraum hinzufügen

Laden Sie einige Python-Funktionen in den Reinraum, um die ML-Aktivitäten nachzubilden. Alle im Reinraum installierten Python-Funktionen bleiben absolut vertraulich. Sie sind für den Verbraucher nicht sichtbar.

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.

Bemerkung

Beachten Sie, dass diese Implementierung durch die Einschränkung der Gesamtgröße von Snowflake auf die Datenmenge, die von ARRAY_AGG aggregiert werden kann (d. h. 16 MB), begrenzt ist. Eine Implementierung, die Batching- und Streaming-Modelle nutzt und mithilfe von Batching auf beliebig große Datensets skalieren kann, ist auf Anfrage erhältlich.

CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'lookalike_train',
    ['input_data variant', 'labels variant'],
    ['pandas', 'numpy', 'xgboost'],
    'variant',
    'train',
$$
import numpy as np
import pandas as pd
import xgboost
from sklearn import preprocessing
import sys
import os
import pickle
import codecs
import threading


class TrainXGBoostClassifier(object):
    def __init__(self):
        self.model = None
        self._params = {
            "objective": "binary:logistic",
            "max_depth": 3,
            "nthread": 1,
            "eval_metric": "auc",
        }
        self.num_boosting_rounds = 10

    def get_params(self):
        if self.model is not None and "updater" not in self._params:
            self._params.update(
                {"process_type": "update", "updater": "refresh", "refresh_leaf": True}
            )
        return self._params

    def train(self, X, y):
        # Train the model in a threadsafe way

        # pick only the categorical attributes
        categorical = X.select_dtypes(include=[object])

        # fit a one-hot-encoder to convert categorical features to binary features (required by XGBoost)
        ohe = preprocessing.OneHotEncoder()
        categorical_ohe = ohe.fit_transform(categorical)
        self.ohe = ohe

        # get the rest of the features and add them to the binary features
        non_categorical = X.select_dtypes(exclude=[object])
        train_x = np.concatenate((categorical_ohe.toarray(), non_categorical.to_numpy()), axis=1)

        xg_train = xgboost.DMatrix(train_x, label=y)

        params = self.get_params()
        params["eval_metric"] = "auc"
        evallist = [(xg_train, "train")]
        evals_result = {}

        self.model = xgboost.train(
            params, xg_train, self.num_boosting_rounds, evallist, evals_result=evals_result
        )

        self.evals_result = evals_result

    def __dump_model(self, model):
        # Save down the model as a json string to load up for scoring/inference

        pickle_jar = codecs.encode(pickle.dumps([model, self.ohe]), "base64").decode()
        return pickle_jar

    def dump_model(self):
        # Save down the model as a json string to load up for scoring/inference
        if self.model is not None:
            return self.__dump_model(self.model)
        else:
            raise ValueError("Model needs to be trained first")


def train(d1, l1):
    # get take training features and put them in a pandas dataframe
    X = pd.DataFrame(d1)

    # get the labels into a Numpy array
    y = np.array(l1)

    trainer = TrainXGBoostClassifier()
    trainer.train(X, y)

    # return training stats, accuracy, and the pickled model and pickled one-hot-encoder
    return {
        "total_rows": len(d1),
        "total_bytes_in": sys.getsizeof(d1),
        "model": trainer.dump_model(),
        "iteration": trainer.num_boosting_rounds,
        "auc": np.max(trainer.evals_result["train"]["auc"]),
        "error": 1 - np.max(trainer.evals_result["train"]["auc"])
    }   
$$);
Copy

Installieren Sie nun eine Scoring-Funktion im Reinraum:

CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'lookalike_score',
    ['pickle_jar variant', 'emails variant', 'features variant'],
    ['pandas', 'numpy', 'xgboost', 'scikit-learn'],
    'string',
    'score',
$$
import numpy as np
import pandas as pd
import xgboost as xgb
import pickle
import codecs
import json


def score(model, emails, features):
    # load model
    model = model[0] if not isinstance(model, str) else model
    model = pickle.loads(codecs.decode(model.encode(), "base64"))

    # retrieve the XGBoost trainer from the pickle jar
    bst = model[0]

    # retrieve the fitted one-hot-encoder from the pickle jar
    ohe2 = model[1]

    # create pandas dataframe from the inference features
    Y = pd.DataFrame(features)

    # select the categorical attributes and one-hot-encode them
    Y1 = Y.select_dtypes(include=[object])
    Y2 = ohe2.transform(Y1)

    # select the non-categorical attributes
    Y3 = Y.select_dtypes(exclude=[object])

    # join the results of the one-hot encoding to the rest of the attributes
    Y_pred = np.concatenate((Y2.toarray(), Y3.to_numpy()), axis=1)

    # inference
    dscore = xgb.DMatrix(Y_pred)
    pred = bst.predict(dscore)

    retval = list(zip(np.array(emails), list(map(str, pred))))
    retval = [{"email": r[0], "score": r[1]} for r in retval]
    return json.dumps(retval)  
$$);
Copy

Bemerkung

Wenn Sie Python in den Reinraum laden, wird ein neuer Patch für den Reinraum erstellt. Wenn Ihre Reinraum-Distribution auf EXTERNAL eingestellt ist, müssen Sie warten, bis der Sicherheitsscan abgeschlossen ist, bevor Sie die Standard-Release-Richtlinie wie folgt aktualisieren:

-- See the versions available inside the cleanroom
SHOW VERSIONS IN APPLICATION PACKAGE samooha_cleanroom_UI_Registration_ML_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', '2');
Copy

Benutzerdefinierte Lookalike Modeling-Vorlage 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 JinjaSQL-Vorlagen übergibt der Verbraucher eine Liste von Anbieter- und Verbrauchertabellennamen, wenn er eine Vorlage ausführt. Diese Listen werden den folgenden globalen Variablen zugewiesen, die der Vorlage zur Verfügung stehen: durch den Verbraucher

  • source_table: Ein Array von Tabellennamen des Anbieters.

  • my_table: Ein Array von Tabellennamen des Verbrauchers.

Die Vorlage kann diese Variablen verwenden, um die Tabellennamen dynamisch zu machen, oder die Tabellennamen fest codieren, wenn Sie sicher sind, welche Tabellen Sie in Ihrer Vorlage verwenden möchten (und wenn die Tabellen vorhanden sind und die erwarteten Namen haben).

Spaltennamen können auch entweder fest in die Vorlage kodiert oder dynamisch durch vom Verbraucher bereitgestellte Argumente festgelegt werden. 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.

Bemerkung

Alle Anbieter- und Verbrauchertabellen müssen mit diesen Argumenten referenziert werden, da der Name der mit dem Reinraum tatsächlich verknüpften sicheren Ansicht ein anderer ist als der Tabellenname. Wichtig: Anbieter-Tabellen-Aliasse müssen p (oder p1), p2, p3, p4 usw. sein und Verbraucher-Tabellen-Aliasse müssen c (oder c1), c2, c3 usw. sein. Dies ist erforderlich, um die Sicherheitsrichtlinien im Reinraum durchzusetzen.

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.

Aus dem Datenset des Anbieters wird ein Satz von Merkmalen (Features) ausgewählt, und aus dem Datenset des Verbrauchers wird ein Satz von Labels ausgewählt, zusammen mit einem Flag für „hochwertig“ („label_value“ genannt). Diese beiden Tabellen werden dann über die E-Mail-Adresse per INNER JOIN verknüpft und an den Random Forest-Trainingsalgorithmus übergeben. Schließlich wird die Ausgabe des Modelltrainingsschritts an eine Inferenzfunktion übergegeben, die das trainierte Modell verwendet, um zu schlussfolgern („infer“), welche Anbieterkunden NICHT in den Verbraucher-Datensets „wertvoll“ sein könnten. Die Anzahl dieser Personen wird dann zusammen mit dem Modellfehler zurückgegeben.

Der Schwellenwert für die Bestimmung der Punktzahl, ab der ein Kunde „wahrscheinlich wertvoll“ ist, wird in der Vorlage manuell auf 0,5 festgelegt. Dies kann leicht geändert werden, wenn Sie die Vorlage zum Reinraum hinzufügen.

CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template($cleanroom_name, 'prod_custom_lookalike_template',
$$
WITH
features AS (
    SELECT
        identifier({{ provider_join_col | join_policy }}) AS joincol,
        array_construct({{ dimensions[0] | sqlsafe }} {% for feat in dimensions[1:] %} , {{ feat | sqlsafe }} {% endfor %}) AS features
    FROM
        identifier({{ source_table[0] }}) AS p
),
labels AS (
    SELECT
        c.{{ consumer_join_col | sqlsafe }} AS joincol,
        c.{{ filter_column | default('SALES_DLR') | sqlsafe }} {{ operator | default('>=') | sqlsafe }} {{ filter_value | default(2000) | sqlsafe }} AS label_value
    FROM
        identifier({{ my_table[0] }}) AS c
),
trained_model AS (
    SELECT
        train_out:model::varchar AS model,
        train_out:error::float AS error
    FROM (
      SELECT
        cleanroom.{{ lookalike_train_function | default('lookalike_train') | sqlsafe }}(array_agg(f.features), array_agg(l.label_value)) AS train_out
      FROM features f, labels l
      WHERE f.joincol = l.joincol
    )
),
inference_output AS (
    SELECT
        MOD(seq4(), 100) AS batch,
        cleanroom.{{ lookalike_score_function | default('lookalike_score') | sqlsafe }}(
            array_agg(distinct t.model), 
            array_agg(identifier({{ provider_join_col | join_policy }})), 
            array_agg(array_construct( identifier({{ dimensions[0] }}) {% for feat in dimensions[1:] %} , identifier({{ feat }}) {% endfor %}) )
        ) AS scores
    FROM trained_model t, identifier({{ source_table[0] }}) p
    WHERE identifier({{ provider_join_col | join_policy }}) NOT IN (SELECT c.{{ consumer_join_col | sqlsafe }} FROM identifier({{ my_table[0] }}) c)
    GROUP BY batch
),
processed_output AS (
    SELECT value:email::string as id, value:score::float AS score FROM (select scores from inference_output), lateral flatten(input => parse_json(scores))
), train_results AS (
    SELECT {{ num_boosting_rounds | sqlsafe }} AS num_boosting_rounds, {{ trim_extremes | sqlsafe }} AS trim_extremes, p.audience_size AS audience_size, t.error AS error FROM (SELECT count(distinct id) AS audience_size FROM processed_output WHERE score > 0.5) p, trained_model t
), seed_size AS (
    select count(*) AS seed_audience_size FROM features f, labels l WHERE f.joincol = l.joincol
)
SELECT s.seed_audience_size, t.audience_size AS num_lookalikes_found, t.error FROM train_results t, seed_size s
$$);

-- Last parameter (Differential Privacy) is optional and omitted here. Default is 1
Copy

Wenn Sie die derzeit im Reinraum aktiven Vorlagen anzeigen möchten, rufen Sie die folgende Prozedur auf. Sie können die Änderungen vornehmen, um Differential-Privacy-Garantien für Ihre Analyse zu aktivieren. Ein ähnliches Muster kann in jede benutzerdefinierte Vorlage integriert werden, die Sie erstellen möchten.

CALL samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);
Copy

Legen Sie die Spaltenrichtlinien für jede Vorlage fest

Sobald Sie Ihre benutzerdefinierte Vorlage hinzugefügt haben, können Sie Spaltenrichtlinien auf alle durch diese Vorlage definierten Tabellenspalten anwenden.

Um die obersten 10 Zeilen der Tabelle anzuzeigen, die Ihren Verbrauchern zur Verfügung stehen, führen Sie die folgende Abfrage aus:

SELECT * FROM <PROVIDER_TABLE> LIMIT 10;
Copy

Legen Sie die Spalten fest, auf denen Sie gruppieren und aggregieren (z. B. SUM oder AVG) und generell in einer Analyse für jede Kombination aus Tabelle und Vorlage verwenden möchten. Dies bietet Flexibilität, sodass dieselbe Tabelle je nach der zugrunde liegenden Vorlage eine unterschiedliche Spaltenauswahl zulassen kann. Diese Funktion sollte erst nach dem Hinzufügen der Vorlage aufgerufen werden.

Beachten Sie, dass set_column_policy nicht additiv ist; wenn die Funktion erneut aufgerufen wird, wird die vorherige Spaltenrichtlinie vollständig durch die neue ersetzt.

Die Spaltenrichtlinie darf nicht für Identitätsspalten wie E-Mail, HEM oder RampID verwendet werden, da der Verbraucher sonst in der Lage wäre, nach diesen Spalten zu gruppieren. In der Produktionsumgebung erkennt das System auf intelligente Weise die PII-Spalten und blockiert diese Operation, aber dieses Feature ist in der Sandbox-Umgebung nicht verfügbar. Sie sollte nur für Spalten verwendet werden, die Sie dem Verbraucher zur Verfügung stellen möchten, um sie zu aggregieren und zu gruppieren, z. B. Status, Altersgruppe, Regionscode oder Aktive Tage.

CALL samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name, [
    'prod_custom_lookalike_template:samooha_provider_sample_database.lookalike_modeling.customers:status', 
    'prod_custom_lookalike_template:samooha_provider_sample_database.lookalike_modeling.customers:age', 
    'prod_custom_lookalike_template:samooha_provider_sample_database.lookalike_modeling.customers:region_code', 
    'prod_custom_lookalike_template:samooha_provider_sample_database.lookalike_modeling.customers:days_active', 
    'prod_custom_lookalike_template:samooha_provider_sample_database.lookalike_modeling.customers:income_bracket'
]);
Copy

Wenn Sie die zum Reinraum hinzugefügte Spaltenrichtlinie anzeigen möchten, rufen Sie die folgende Prozedur auf.

CALL samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);
Copy

Erstellen und Anwenden Ihrer Vorlage UI

Als Nächstes definieren Sie die UI für Ihre Vorlage, damit die Verbraucher sie im Browser verwenden können:

  1. Rufen Sie den Befehl provider.add_ui_form_customizations auf, um festzulegen, wie die Vorlage in der Web-App erscheint.

  2. Melden Sie sich im Web als Anbieter an.

Definieren Sie die UI für die Vorlage

Der Befehl provider.add_ui_form_customizations definiert, wie die Vorlage im Reinraum in der Web-App erscheint. Eine vollständige Beschreibung der Anpassungen, die Sie zur Gestaltung der Benutzeroberfläche verwenden können, finden Sie im Abschnitt Aktualisierungsbefehle für die Reinraum-UI der API-Referenz des Anbieters.

Bemerkung

Sie können optional die Anpassung warehouse_hints verwenden, um zu steuern, welche Art von Warehouse das Konto des Benutzers zur Durchführung von Analysen verwendet. Für die meisten Anwendungsfälle des maschinellen Lernens empfiehlt Snowflake beispielsweise die Angabe eines Snowpark-optimierten Warehouses. Gültige Werte für warehouse_size, siehe CREATE WAREHOUSE.

Für dieses Beispiel führen Sie den Befehl provider.add_ui_form_customizations mit den folgenden Anpassungen aus:

CALL samooha_by_snowflake_local_db.provider.add_ui_form_customizations(
    $cleanroom_name,
    'prod_custom_lookalike_template',
    {
        'display_name': 'Custom Lookalike Template',
        'description': 'Use our customized ML techniques to find lookalike audiences.',
        'methodology': 'Specify your own seed audience, while matching against our users. Then customize the lookalike model across number of boosting rounds and removing outliers.',
        'warehouse_hints': {
            'warehouse_size': 'medium',
            'snowpark_optimized': TRUE
        }
    },
    {
    'num_boosting_rounds': {
        'display_name': 'Number of Boosting Rounds',
        'type': 'integer',
        'default': 10,
        'order': 7,
        'description': 'How many rounds of boosting should the model do?',
        'size': 'M',
        'group': 'Training & Inference Configuration'
    },
    'trim_extremes': {
        'display_name': 'Trim Extremes',
        'type': 'boolean',
        'default': False,
        'order': 8,
        'description': 'Remove outliers by default?',
        'size': 'M',
        'group': 'Training & Inference Configuration'
    },
    'lookalike_train_function': {
        'display_name': 'Training Function',
        'choices': ['lookalike_train'],
        'type': 'dropdown',
        'order': 9,
        'description': 'Which function do you want to use for training?',
        'size': 'M',
        'group': 'Training & Inference Configuration'
    },
    'lookalike_score_function': {
        'display_name': 'Scoring Function',
        'choices': ['lookalike_score'],
        'type': 'dropdown',
        'order': 10,
        'description': 'Which function do you want to use for scoring?',
        'size': 'M',
        'group': 'Training & Inference Configuration'
    },    
    'provider_join_col': {
        'display_name': 'Provider Join Column',
        'choices': ['p.HASHED_EMAIL'],
        'type': 'dropdown',
        'order': 4,
        'description': 'Select the provider column to join users on.',
        'infoMessage': 'We recommend using HASHED_EMAIL.',
        'size': 'M',
        'group': 'Enable Provider Features'
    },
    'consumer_join_col': {
        'display_name': 'Consumer Join Column',
        'description': 'Specify column in your table that matches the providers (i.e. HASHED_EMAIL).',
        'size': 'M',
        'default': 'HASHED_EMAIL',
        'infoMessage': 'We recommend using HASHED_EMAIL.',
        'order': 5,
        'group': 'Enable Provider Features'
    },
    'dimensions': {
        'display_name': 'Feature Selection',
        'choices': ['p.STATUS', 'p.AGE', 'p.REGION_CODE', 'p.DAYS_ACTIVE'],
        'type': 'multiselect',
        'order': 6,
        'description': 'What features do you want to train on?',
        'infoMessage': 'We recommend selecting all features for maximum signal.',
        'size': 'M',
        'group': 'Enable Provider Features'
    },
    'filter_column': {
        'display_name': 'Filter Column',
        'type': 'any',
        'order': 1,
        'description': 'Specify column in your table to filter for high value users (i.e. SALES_DLR)',
        'size': 'S',
        'default': 'SALES_DLR',
        'infoMessage': 'We recommend you input SALES_DLR over here.',
        'group': 'Seed Audience Selection'
    },
    'operator': {
        'display_name': 'Operator',
        'choices': ['>=', '=', '<='],
        'type': 'dropdown',
        'order': 2,
        'description': 'What is the operator your want to use for the filter?',
        'size': 'S',
        'group': 'Seed Audience Selection'
    },
    'filter_value': {
        'display_name': 'Filter Value',
        'order': 3,
        'description': 'What value do you want to filter to?',
        'default': 2000,        
        'size': 'S',
        'group': 'Seed Audience Selection'
    }
}, {
    'measure_columns': ['seed_audience_size', 'audience_size', 'num_lookalikes_found', 'error'],
    'default_output_type': 'BAR'
});
Copy

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.

Bemerkung

Um die folgenden Prozeduren aufzurufen, stellen Sie sicher, dass Sie zuerst die Releaserichtlinie mit provider.set_default_release_directive gesetzt haben. Die letzte verfügbare Version und die letzten Patches können Sie wie folgt anzeigen:

SHOW VERSIONS IN APPLICATION PACKAGE samooha_cleanroom_UI_Registration_ML_clean_room;
Copy
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_or_update_cleanroom_listing($cleanroom_name);
Copy

Wenn Sie die vom Anbieter durchgeführte Analyse aktivieren möchten, rufen Sie enable_provider_run_analysis nach dem Aufruf von add_consumers und vor dem Aufruf von create_or_update_cleanroom_listing auf.

Wichtig

Wann immer Sie wichtige Informationen in einem Reinraum ändern, wie z. B. die UI, Richtlinien oder Datensätze, müssen Sie provider.create_or_update_cleanroom_listing aufrufen, um den Reinraum in der Produktion zu aktualisieren. Es kann bis zu 10 Minuten dauern, bis die Änderungen in der UI erscheinen, sowohl für den Produzenten als auch für den Verbraucher.

Hilfsmethoden

Hier finden Sie einige nützliche Hilfsfunktionen für die Erstellung eines Reinraums.

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);
Copy

Wenn Sie sich die kürzlich erstellten Reinräume anzeigen möchten, verwenden Sie die folgende Prozedur.

CALL samooha_by_snowflake_local_db.provider.view_cleanrooms();
Copy

Wenn Sie mehr über den von Ihnen erstellten Reinraum erfahren möchten, verwenden Sie die folgende Prozedur.

CALL samooha_by_snowflake_local_db.provider.describe_cleanroom($cleanroom_name);
Copy

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);
Copy

Verbraucher-Workflow

Der Reinraum, den Sie gerade als Anbieter erstellt haben, ist jetzt in der Web-App in der Reinraumumgebung des Verbrauchers verfügbar.

Bemerkung

Sie können das UI-Formular im Anbieterkonto weiter bearbeiten und sehen dann die Änderungen in der Reinraumumgebung des Verbrauchers in Echtzeit.

Zugriff auf das Verbraucherkonto in der Web-App

So melden Sie sich als Verbraucher im Reinraum an:

  1. Melden Sie sich bei der Web-App des Snowflake Data Clean Room an. Einzelheiten finden Sie unter Snowflake Data Clean Room: Web-App.

  2. Geben Sie Ihre E-Mail-Adresse ein, und wählen Sie „Continue“ aus.

  3. Geben Sie Ihr Kennwort ein.

  4. Wählen Sie das Snowflake-Konto aus, das mit dem Verbraucherkonto verbunden ist.

Reinraum installieren

Suchen Sie auf der Seite „Clean Rooms“ die Kachel, die dem gerade erstellten Reinraum entspricht, und wählen Sie Installieren aus.

Analyse ausführen

So führen Sie eine Analyse im Reinraum aus:

  1. Suchen Sie auf der Seite Reinräume die Kachel für den neuen Reinraum, und wählen Sie Ausführen.

  2. Wählen Sie die auszuführende Analyse oder Abfrage aus, und wählen Sie dann Fortfahren.

  3. Konfigurieren Sie die erforderlichen Felder für die gewählte Analyse, wählen Sie optional eine Warehouse-Größe, und wählen Sie dann Ausführen.

  4. Optional können Sie einen Namen für die Analyse angeben. Wenn Sie möchten, dass die Analyse in regelmäßigen Abständen durchgeführt wird, wählen Sie ein Zeitintervall, andernfalls wählen Sie Aus, um Ihre Analyse nur einmal durchzuführen.

  5. Wählen Sie Speichern, um Ihre Analyse zu starten.

  6. Wählen Sie Alle Analysen anzeigen, um Ihre Liste der geplanten, laufenden und abgeschlossenen Analysen anzuzeigen, einschließlich der soeben erstellten Analyse.

  7. Wenn die Analyse abgeschlossen ist, wählen Sie sie aus, um die Ergebnisse zu sehen.