Verwenden von SQL, um Objektbeschreibungen automatisch zu generieren

Mit dem Feature „Cortex-gesteuerte Objektbeschreibungen“ können Sie die Snowflake Cortex COMPLETE-Funktion verwenden, um Beschreibungen für Tabellen, Ansichten und Spalten automatisch zu erstellen. Dieses Feature nutzt die in Snowflake gehosteten großen Sprachmodelle (LLMs), um Objekt-Metadaten und, falls gewünscht, Beispieldaten auszuwerten und eine Beschreibung zu erstellen.

In diesem Thema wird beschrieben, wie Sie eine gespeicherte Prozedur verwenden, um Beschreibungen programmgesteuert zu erstellen. Weitere Informationen zur Verwendung von Snowsight zum Erstellen der Beschreibungen finden Sie unter Beschreibungen mit Snowflake Cortex erzeugen.

Generieren einer Beschreibung

Die gespeicherte Prozedur AI_GENERATE_TABLE_DESC generiert automatisch eine Beschreibung für eine Tabelle und eine Ansicht. Sie kann auch Beschreibungen für die Spalten dieser Tabelle oder Ansicht erstellen.

Die gespeicherte Prozedur AI_GENERATE_TABLE_DESC akzeptiert zwei Argumente:

  • Der Name der Tabelle oder der Ansicht, für die Sie eine Beschreibung erstellen möchten.

  • Ein optionales Konfigurationsobjekt, mit dem Sie Folgendes tun können:

    • Generieren von Beschreibungen für die Spalten der angegebenen Tabelle oder Ansicht

    • Verwenden von Beispieldaten aus der Tabelle oder der Ansicht, um möglicherweise die Genauigkeit der Spaltenbeschreibungen zu verbessern

Beispiel: Eine Tabellenbeschreibung generieren
CALL AI_GENERATE_TABLE_DESC( 'my_table');
Copy
Beispiel: Tabellen- und Spaltenbeschreibungen ohne die Verwendung von Beispieldaten generieren
CALL AI_GENERATE_TABLE_DESC(
  'mydb.sch1.hr_data',
  {
    'describe_columns': true,
    'use_table_data': false
  });
Copy
Beispiel: Ansichts- und Spaltenbeschreibungen anhand von Beispieldaten zur Verbesserung der Genauigkeit generieren
CALL AI_GENERATE_TABLE_DESC(
  'mydb.sch1.v1',
  {
    'describe_columns': true,
    'use_table_data': true
  });
Copy

Die vollständige Syntax der gespeicherten Prozedur finden Sie unter AI_GENERATE_TABLE_DESC.

Arbeiten mit der Antwort

Die gespeicherte Prozedur AI_GENERATE_TABLE_DESC gibt ein JSON-Objekt zurück, das die generierten Beschreibungen sowie allgemeine Informationen zu Tabelle und Spalten enthält. Innerhalb dieses Objekts enthält das Feld description die generierte Beschreibung.

Angenommen, Sie haben die folgende Tabelle erstellt:

CREATE OR REPLACE TABLE mydb.sch1.hr_data (fname VARCHAR, age INTEGER);

INSERT INTO hr_data (fname, age)
    VALUES
        ('Thomas',    44),
        ('Katherine', 29),
        ('Lisa',      29);
Copy

Bei dieser Tabelle finden Sie im Folgenden ein Beispiel für das JSON-Objekt, das von AI_GENERATE_TABLE_DESC zurückgegeben wird:

{
  "COLUMNS": [
    {
      "database_name": "mydb",
      "description": "The first name of the employee.",
      "name": "FNAME",
      "schema_name": "sch1",
      "table_name": "hr_data"
    }
    {
      "database_name": "mydb",
      "description": "A column holding data of type DecimalType representing age values.",
      "name": "AGE",
      "schema_name": "sch1",
      "table_name": "hr_data"
    },
  ],
  "TABLE": [
    {
      "database_name": "mydb",
      "description": " The table contains records of employee data, specifically demographic information. Each record includes an employee's age and name.",
      "name": "hr_data",
      "schema_name": "sch1"
    }
  ]
}

Weitere Informationen zu den einzelnen JSON-Feldern finden Sie unter Rückgabewerte.

Festlegen von generierten Beschreibungen als Kommentare

Um eine generierte Beschreibung als Kommentar für eine Tabelle, Ansicht oder Spalte festzulegen, müssen Sie manuell eine SQL-Anweisung ausführen, die den Parameter SET COMMENT enthält. Um beispielsweise eine generierte Beschreibung für eine Tabelle t1 zu speichern, führen Sie ALTER TABLE t1 SET COMMENT = 'ai generated description'; aus.

Sie können benutzerdefinierten Code schreiben, um Beschreibungen automatisch zu erstellen und zu speichern. Beispiele für gespeicherte Prozeduren, die dies tun, finden Sie unter Beispiele.

Anforderungen an die Zugriffssteuerung

Benutzer müssen über die folgenden Berechtigungen und Rollen verfügen, um die gespeicherte Prozedur AI_GENERATE_TABLE_DESC aufrufen zu können:

  • SELECT-Berechtigung für die Tabelle oder Ansicht.

  • SNOWFLAKE.CORTEX_USER-Datenbankrolle.

Verfügbarkeit des Features

Ihre Region muss die LLM unterstützen, die von Snowflake Cortex (wie Mistral-7b und Llama 3.1-8b) verwendet wird, um die Beschreibungen zu erstellen. Überprüfen Sie die Verfügbarkeit der COMPLETE-Funktion. Wenn die Funktion COMPLETE in Ihrer Region nicht unterstützt wird, müssen Sie die regionenübergreifende Inferenz aktivieren, um das Feature nutzen zu können.

Verwenden von Beispieldaten

Wenn Sie eine Beschreibung für eine Spalte erstellen, können Sie sich nur auf Metadaten verlassen oder Sie können Beispieldaten verwenden, um die Snowflake Cortex-gesteuerten Beschreibungen zu verbessern. Beispieldaten beziehen sich auf Daten innerhalb einer bestimmten Spalte, die ausgewertet werden, wenn Sie Snowflake Cortex zur Erstellung von Beschreibungen verwenden. Wenn Sie sich für die Verwendung von Beispieldaten entscheiden, verwendet Snowflake einen Teil der Beispieldaten, um die Beschreibung zu erstellen, was zu genaueren Beschreibungen führt. Beispieldaten werden von Snowflake nicht als Nutzungsdaten gespeichert.

Hinweise zu Kosten

Das Erstellen von Beschreibungen verursacht die folgenden Kosten:

  • Vom verwendeten Warehouse verbrauchte Credits

  • Credit-Gebühren für die Benutzung von Snowflake Cortex mit kleineren LLMs wie Mistral-7b und Llama 3.1-8b. Diese Gebühren erscheinen auf der Rechnung als AI-Services, die alle Nutzungen von Snowflake Cortex umfassen.

Einschränkungen

Sie können keine Spaltenbeschreibungen für Objekte mit mehr als 1.000 Spalten erstellen.

Beispiele

Beispiel: Erstellen von Beschreibungen und Festlegen dieser Beschreibungen als Kommentare

Schritt 1: Erstellen Sie eine gespeicherte Prozedur.

Die folgende gespeicherte Prozedur tut Folgendes:

  • Erstellt automatisch Beschreibungen für alle Tabellen (und ihre Spalten) in einem Schema.

  • Legt diese Beschreibungen als Kommentare für die Tabellen und Spalten fest.

CREATE OR REPLACE PROCEDURE DESCRIBE_TABLES_SET_COMMENT (database_name STRING, schema_name STRING,
  set_table_comment BOOLEAN,
  set_column_comment BOOLEAN)
  RETURNS STRING
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.10'
  PACKAGES=('snowflake-snowpark-python','joblib')
  HANDLER = 'main'
AS
$$
import json
from joblib import Parallel, delayed
import multiprocessing

def generate_descr(session, database_name, schema_name, table, set_table_comment, set_column_comment):
  table_name =  table['TABLE_NAME']
  async_job = session.sql(f"CALL AI_GENERATE_TABLE_DESC( '{database_name}.{schema_name}.{table_name}',{{'describe_columns': true, 'use_table_data': true}})").collect_nowait()
  result = async_job.result()
  output = json.loads(result[0][0])
  columns_ret = output["COLUMNS"]
  table_ret = output["TABLE"][0]

  table_description = table_ret["description"]
  table_name = table_ret["name"]
  database_name = table_ret["database_name"]
  schema_name = table_ret["schema_name"]

  if (set_table_comment):
      table_description = table_description.replace("'", "\\'")
      session.sql(f"""ALTER TABLE {database_name}.{schema_name}.{table_name} SET COMMENT = '{table_description}'""").collect()

  for column in columns_ret:
      column_description = column["description"];
      column_name = column["name"];
      if not column_name.isupper():
        column_name = '"' + column_name + '"'

      if (set_column_comment):
          column_description = column_description.replace("'", "\\'")
          session.sql(f"""ALTER TABLE  {database_name}.{schema_name}.{table_name} MODIFY COLUMN {column_name}  COMMENT '{column_description}'""").collect()

  return 'Success';

def main(session, database_name, schema_name, set_table_comment, set_column_comment):

    schema_name = schema_name.upper()
    database_name = database_name.upper()
    tablenames = session.sql(f"""SELECT table_name
                      FROM {database_name}.information_schema.tables
                      WHERE table_schema = '{schema_name}'
                      AND table_type = 'BASE TABLE'""").collect()
    try:
        Parallel(n_jobs=multiprocessing.cpu_count(), backend="threading")(
                delayed(generate_descr)(
                    session,
                    database_name,
                    schema_name,
                    table,
                    set_table_comment,
                    set_column_comment,
                ) for table in tablenames
            )
        return 'Success'
    except Exception as e:
        # Catch and return the error message
        return f"An error occurred: {str(e)}"
$$;
Copy

Schritt 2: Rufen Sie die gespeicherte Prozedur auf.

Angenommen, Ihr Schema heißt my_db.sch1. Rufen Sie in diesem Fall die gespeicherte Prozedur wie folgt auf, um Beschreibungen für Tabellen und Spalten zu erstellen:

CALL describe_tables_set_comment('my_db', 'sch1', true, true);
Copy

Sie können einen DESC TABLE-Befehl ausführen, um zu überprüfen, ob die generierten Beschreibungen als Kommentare in einer Tabelle festgelegt wurden.

Beispiel: Erstellen von Beschreibungen und Speichern dieser Beschreibungen in einer Katalogtabelle

Schritt 1: Erstellen Sie eine gespeicherte Prozedur.

Die folgende gespeicherte Prozedur tut Folgendes:

  • Erstellt automatisch Beschreibungen für alle Tabellen (und ihre Spalten) in einem Schema.

  • Füllt eine Katalogtabelle aus, wobei jede Zeile eine Tabelle oder Spalte mit der generierten Beschreibung darstellt.

CREATE OR REPLACE PROCEDURE DESCRIBE_TABLES_SET_CATALOG (database_name string, schema_name string, catalog_table string)
  RETURNS STRING
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.10'
  PACKAGES=('snowflake-snowpark-python','joblib')
  HANDLER = 'main'
AS
$$
import json
from joblib import Parallel, delayed
import multiprocessing

def generate_descr(session, database_name, schema_name, table, catalog_table):
    table_name =  table['TABLE_NAME']
    async_job = session.sql(f"CALL AI_GENERATE_TABLE_DESC( '{database_name}.{schema_name}.{table_name}',{{'describe_columns': true, 'use_table_data': true}})").collect_nowait()
    result = async_job.result()
    output = json.loads(result[0][0])
    columns_ret = output["COLUMNS"]
    table_ret = output["TABLE"][0]

    table_description = table_ret["description"]
    table_description = table_description.replace("'", "\\'")
    table_name = table_ret["name"]
    database_name = table_ret["database_name"]
    schema_name = table_ret["schema_name"]

    session.sql(f"""INSERT INTO {catalog_table} (domain, description, name, database_name, schema_name, table_name)
                          VALUES ('TABLE', '{table_description}', '{table_name}', '{database_name}', '{schema_name}', null)""").collect()

    for column in columns_ret:
        column_description = column["description"];
        column_description = column_description.replace("'", "\\'")
        column_name = column["name"];
        if not column_name.isupper():
            column_name = '"' + column_name + '"'
        session.sql(f"""INSERT INTO {catalog_table} (domain, description, name, database_name, schema_name, table_name)
                          VALUES ('COLUMN', '{column_description}', '{column_name}', '{database_name}', '{schema_name}', '{table_name}')""").collect()

    return 'Success';

def main(session, database_name, schema_name, catalog_table):

    schema_name = schema_name.upper()
    database_name = database_name.upper()
    catalog_table_upper = catalog_table.upper()
    tablenames = session.sql(f"""SELECT table_name
                      FROM {database_name}.information_schema.tables
                      WHERE table_schema = '{schema_name}'
                      AND table_type = 'BASE TABLE'
                      AND table_name !='{catalog_table_upper}'""").collect()
    try:
        Parallel(n_jobs=multiprocessing.cpu_count(), backend="threading")(
                delayed(generate_descr)(
                    session,
                    database_name,
                    schema_name,
                    table,
                    catalog_table,
                ) for table in tablenames
            )
        return 'Success'
    except Exception as e:
        # Catch and return the error message
        return f"An error occurred: {str(e)}"
$$;
Copy

Schritt 2: Erstellen Sie die auszufüllende Katalogtabelle.

Verwenden Sie den folgenden Code, um die Katalogtabelle zu erstellen, in der Tabellen- und Spaltenbeschreibungen gespeichert sind.

CREATE OR REPLACE TABLE catalog_table (
  domain VARCHAR,
  description VARCHAR,
  name VARCHAR,
  database_name VARCHAR,
  schema_name VARCHAR,
  table_name VARCHAR
  );
Copy

Schritt 3: Rufen Sie die gespeicherten Prozeduren auf.

Angenommen, Ihr Schema heißt my_db.sch1. Rufen Sie in diesem Fall die gespeicherte Prozedur wie folgt auf:

CALL describe_tables_set_catalog('my_db', 'sch1', 'catalog_table');
Copy
Sprache: Deutsch