Beispiele für Python-UDF-Handler¶

Voraussetzungen¶

Bevor der Python-Handler-Code eine in einem Stagingbereich befindliche Datei lesen kann, müssen Sie Folgendes tun, um die Datei für den Code zur Verfügung zu stellen:

1. Erstellen Sie einen Stagingbereich, auf den Ihr Handler zugreifen kann.

   Sie können einen externen Stagingbereich oder eine interne Stagingbereich verwenden. Wenn Sie einen internen Stagingbereich verwenden und planen, eine gespeicherte Prozedur mit Aufruferrechten zu erstellen, dann kann es sich um einen Benutzer-Stagingbereich handeln. Andernfalls müssen Sie einen benannten Stagingbereich verwenden. Snowflake unterstützt derzeit nicht die Verwendung eines Tabellen-Stagingbereichs für UDF-Abhängigkeiten.

   Weitere Informationen zum Erstellen eines Stagingbereichs finden Sie unter CREATE STAGE. Weitere Informationen zur Auswahl des Typs eines internen Stagingbereichs finden Sie unter Auswahl eines internen Stagingbereichs für lokale Dateien.

   Je nach Anwendungsfall müssen der folgenden Rolle entsprechende Berechtigungen für den Stagingbereich zugewiesen werden:

   Anwendungsfall	Rolle
   UDF oder gespeicherte Prozedur mit Eigentümerrechten	Die Rolle, die Eigentümer der ausführenden UDF oder gespeicherten Prozedur ist.
   Gespeicherte Prozedur mit Aufruferrechten	Die Benutzerrolle.

   Weitere Informationen dazu finden Sie unter Granting Privileges for User-Defined Functions.

2. Kopieren Sie die Datei, die Ihr Code lesen soll, in den Stagingbereich.

   Sie können die Datei von einem lokalen Laufwerk in einen internen Stagingbereich kopieren, indem Sie den Befehl PUT verwenden. Weitere Informationen zum Staging von Dateien mit PUT finden Sie unter Staging von Datendateien aus einem lokalen Dateisystem.

   Sie können die Datei von einem lokalen Laufwerk in einen externen Stagingbereich kopieren, indem Sie eines der von Ihrem Cloudspeicherdienst bereitgestellten Tools verwenden. Weitere Informationen dazu finden Sie in der Dokumentation Ihres Cloudspeicherdienstes:

Berechnen des Wahrnehmungshashs eines Bildes (Perceptual Hashing) mit einem Inline-Python-Handler¶

In diesem Beispiel wird SnowflakeFile verwendet, um ein Paar von Staging-Bilddateien zu lesen und über den perzeptuellen Hash (pHash) jeder Datei festzustellen, wie ähnlich die Bilder sind.

Erstellen einer UDF, die den pHash-Wert eines Bildes zurückgibt, wobei der Eingabemodus als binär angegeben wird, indem rb als mode-Argument übergeben wird:

CREATE OR REPLACE FUNCTION calc_phash(file_path string)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python','imagehash','pillow')
HANDLER = 'run'
AS
$$
from PIL import Image
import imagehash
from snowflake.snowpark.files import SnowflakeFile

def run(file_path):
  with SnowflakeFile.open(file_path, 'rb') as f:
  return imagehash.average_hash(Image.open(f))
$$;

Erstellen einer zweiten UDF, die den Abstand zwischen den pHash-Werten zweier Bilder berechnet:

CREATE OR REPLACE FUNCTION calc_phash_distance(h1 string, h2 string)
RETURNS INT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('imagehash')
HANDLER = 'run'
as
$$
import imagehash

def run(h1, h2):
  return imagehash.hex_to_hash(h1) - imagehash.hex_to_hash(h2)
$$;

Speichern der Bilddateien im Stagingbereich und Aktualisieren der Verzeichnistabelle:

PUT file:///tmp/image1.jpg @images AUTO_COMPRESS=FALSE;
PUT file:///tmp/image2.jpg @images AUTO_COMPRESS=FALSE;

ALTER STAGE images REFRESH;

Aufrufen der UDFs:

SELECT
  calc_phash_distance(
    calc_phash(build_scoped_file_url(@images, 'image1.jpg')),
    calc_phash(build_scoped_file_url(@images, 'image2.jpg'))
  ) ;

Verarbeitung einer CSV-Datei mit einer UDTF¶

In diesem Beispiel wird SnowflakeFile verwendet, um eine UDTF zu erstellen, die den Inhalt einer CSV-Datei extrahiert und die Zeilen in einer Tabelle zurückgibt.

Erstellen der UDTF mit einem Inline-Handler:

CREATE FUNCTION parse_csv(file_path string)
RETURNS TABLE (col1 string, col2 string, col3 string)
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'csvparser'
AS
$$
from snowflake.snowpark.files import SnowflakeFile

class csvparser:
  def process(self, stagefile):
    with SnowflakeFile.open(stagefile) as f:
      for line in f.readlines():
        lineStr = line.strip()
        row = lineStr.split(",")
        try:
          # Read the columns from the line.
          yield (row[1], row[0], row[2], )
        except:
          pass
$$;

Speichern der CSV-Datei im Stagingbereich und Aktualisieren der Verzeichnistabelle:

PUT file:///tmp/sample.csv @data_stage AUTO_COMPRESS=FALSE;

ALTER STAGE data_stage REFRESH;

Aufrufen der UDTF und Übergeben einer Datei-URL:

SELECT * FROM TABLE(PARSE_CSV(build_scoped_file_url(@data_stage, 'sample.csv')));

Verarbeitung mehrerer Dateien¶

Sie können mehrere Dateien lesen und verarbeiten, indem Sie die Spalte RELATIVE_PATH einer Verzeichnistabelle an Ihren Handler übergeben. Weitere Informationen zur Spalte RELATIVE_PATH finden Sie in der Ausgabe einer Verzeichnistabellenabfrage.

Aufrufen einer UDF, um mehrere Dateien zu verarbeiten:

Das folgende Beispiel ruft eine UDF innerhalb einer CREATE TABLE-Anweisung auf, um jede Datei in einem Stagingbereich zu verarbeiten und die Ergebnisse dann in einer neuen Tabelle zu speichern.

Zu Demonstrationszwecken geht das Beispiel von folgenden Annahmen aus:

• In einem Stagingbereich mit dem Namen my_stage befinden sich mehrere Textdateien.

• Es gibt eine UDF mit dem Namen get_sentiment, die eine Stimmungsanalyse für unstrukturierten Text durchführt. Die UDF verwendet einen Pfad zu einer Textdatei als Eingabe und gibt einen Wert zurück, der die Stimmung repräsentiert.

CREATE OR REPLACE TABLE sentiment_results AS
SELECT
  relative_path
  , get_sentiment(build_scoped_file_url(@my_stage, relative_path)) AS sentiment
FROM directory(@my_stage);

Copy

Aufrufen einer UDTF, um mehrere Dateien zu verarbeiten:

Im nächsten Beispiel wird eine UDTF namens parse_excel_udtf aufgerufen. Das Beispiel übergibt den relativen Pfad (relative_path) aus der Verzeichnistabelle an den Stagingbereich mit dem Namen my_excel_stage.

SELECT t.*
FROM directory(@my_stage) d,
table(parse_excel_udtf(build_scoped_file_url(@my_excel_stage, relative_path)) t;

Copy

Lesen von Dateien mit Stagingbereichs-URIs und -URLs¶

Für den Dateizugriff mit SnowflakeFile werden standardmäßig Bereichs-URLs benötigt. Damit wird Ihr Code widerständig gegen Angriffe per Dateieinschleusung. Sie können jedoch stattdessen auch mit einer Stagingbereichs-URI oder einer Stagingbereich-URL auf einen Dateispeicherort verweisen. Dazu müssen Sie die Methode SnowflakeFile.open mit dem Schlüsselwortargument require_scoped_url = False aufrufen.

Diese Option ist nützlich, wenn Sie möchten, dass ein Aufrufer eine URI bereitstellen kann, auf die nur der UDF-Eigentümer zugreifen darf. Sie könnten zum Beispiel eine Stagingbereichs-URI für den Dateizugriff verwenden, wenn Sie Eigentümer einer UDF sind und Sie Ihre Konfigurationsdateien oder Ihre Modelle für maschinelles Lernen lesen möchten. Wir empfehlen diese Option nicht, wenn Sie Dateien verwenden, die unvorhersehbare Namen haben können, wie z. B. Dateien, die auf Basis von Benutzereingaben erstellt werden.

Dieses Beispiel liest ein Modell des maschinellen Lernens aus einer Datei und verwendet das Modell in einer Funktion zur Verarbeitung natürlicher Sprache für die Stimmungsanalyse. In dem Beispiel wird die Methode open mit require_scoped_url = False aufgerufen. In beiden Dateispeicherformaten (Stagingbereichs-URI und Stagingbereichs-URL) muss der UDF-Eigentümer Zugriff auf die Modelldatei haben.

Erstellen der UDF mit einem Inline-Handler:

CREATE OR REPLACE FUNCTION extract_sentiment(input_data string)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python','scikit-learn')
HANDLER = 'run'
AS
$$
from snowflake.snowpark.files import SnowflakeFile
from sklearn.linear_model import SGDClassifier
import pickle

def run(input_data):
  model_file = '@models/NLP_model.pickle'
  # Specify 'mode = rb' to open the file in binary mode.
  with SnowflakeFile.open(model_file, 'rb', require_scoped_url = False) as f:
    model = pickle.load(f)
    return model.predict([input_data])[0]
$$;

Speichern der Modelldatei im Stagingbereich und Aktualisieren der Verzeichnistabelle:

PUT file:///tmp/NLP_model.pickle @models AUTO_COMPRESS=FALSE;

ALTER STAGE models REFRESH;

Alternativ können Sie die UDF mit der Stagingbereichs-URL des Modells angeben, um die Stimmung zu extrahieren.

Erstellen Sie zum Beispiel eine UDF mit einem Inline-Handler, der eine Datei mit einer Stagingbereichs-URL angibt:

CREATE OR REPLACE FUNCTION extract_sentiment(input_data string)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python','scikit-learn')
HANDLER = 'run'
AS
$$
from snowflake.snowpark.files import SnowflakeFile
from sklearn.linear_model import SGDClassifier
import pickle

def run(input_data):
  model_file = 'https://my_account/api/files/my_db/my_schema/models/NLP_model.pickle'
  # Specify 'rb' to open the file in binary mode.
  with SnowflakeFile.open(model_file, 'rb', require_scoped_url = False) as f:
    model = pickle.load(f)
    return model.predict([input_data])[0]
$$;

Aufrufen der UDF mit den Eingabedaten:

SELECT extract_sentiment('I am writing to express my interest in a recent posting made.');

Copy