Abfrage eines Cortex Search Service¶

Installieren der Snowflake Python APIs-Bibliothek¶

Installieren Sie zunächst die neueste Version des Pakets Snowflake Python APIs von PyPI. Siehe Installieren der Snowflake Python APIs-Bibliothek für Anweisungen zur Installation dieses Pakets von PyPI.

pip install snowflake -U

Mit Snowflake verbinden¶

Stellen Sie die Verbindung zu Snowflake entweder über einen Snowpark-Session oder einen Python Connector Connection her und erstellen Sie ein Root Objekt. Unter Verbinden mit Snowflake mit dem Snowflake Python APIs finden Sie weitere Anweisungen zur Verbindung mit Snowflake. Das folgende Beispiel verwendet das Snowpark Session-Objekt und ein Python Wörterbuch für die Konfiguration.

import os
from snowflake.core import Root
from snowflake.snowpark import Session

CONNECTION_PARAMETERS = {
    "account": os.environ["snowflake_account_demo"],
    "user": os.environ["snowflake_user_demo"],
    "password": os.environ["snowflake_password_demo"],
    "role": "test_role",
    "database": "test_database",
    "warehouse": "test_warehouse",
    "schema": "test_schema",
}

session = Session.builder.configs(CONNECTION_PARAMETERS).create()
root = Root(session)

Den Dienst abfragen¶

Fragen Sie den Dienst mit der folgenden Syntax ab:

# fetch service
my_service = (root
  .databases["<service_database>"]
  .schemas["<service_schema>"]
  .cortex_search_services["<service_name>"]
)

# query service
resp = my_service.search(
  query="<query>",
  columns=["<col1>", "<col2>"],
  filter={"@eq": {"<column>": "<value>"} },
  limit=5
)
print(resp.to_json())

Parameter¶

Konfigurieren Sie RESTAPI-Authentifizierung¶

Snowflake REST-APIs unterstützen die Authentifizierung über programmatische Zugriffstoken (PATs), die Authentifizierung über ein Schlüsselpaar mit JSON-Web Token (JWTs) und OAuth. Weitere Details dazu finden Sie unter Authentifizierung von Snowflake REST APIs mit Snowflake.

Beispiel für die Abfrage des Dienstes¶

So fragen Sie den Dienst mit curl ab:

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>\:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "<search_query>",
  "columns": ["col1", "col2"],
  "filter": <filter>
  "limit": <limit>
}'

Beispiel¶

Das folgende Beispiel zeigt eine Vorschau des Services mit der Abfragezeichenfolge preview query und analysiert die Ergebnisse in einem VARIANT-Objekt.

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'my_search_service',
      '{
         "query": "preview query",
         "columns":[
            "col1",
            "col2"
         ],
         "filter": {"@eq": {"col1": "filter value"} },
         "limit":10
      }'
  )
)['results'] as results;

Beispiel¶

• Filtern von Zeilen, bei denen die Zeichenfolge-ähnliche Spalte string_col gleich dem Wert value ist.

  { "@eq": { "string_col": "value" } }
  

  Copy

• Filtern nach Zeilen, in denen die Spalte ARRAY array_col den Wert value enthält.

  { "@contains": { "array_col": "arr_value" } }
  

  Copy

• Filtern nach Zeilen, in denen NUMERIC Spalte numeric_col zwischen 10,5 und 12,5 (einschließlich) liegt:

  { "@and": [
    { "@gte": { "numeric_col": 10.5 } },
    { "@lte": { "numeric_col": 12.5 } }
  ]}
  

  Copy

• Filtern nach Zeilen, in denen die Spalte TIMESTAMP timestamp_col zwischen 2024-11-19 und 2024-12-19 (einschließlich) liegt.

  { "@and": [
    { "@gte": { "timestamp_col": "2024-11-19" } },
    { "@lte": { "timestamp_col": "2024-12-19" } }
  ]}
  

  Copy

• Zusammenstellen von Filtern mit logischen Operatoren:

  // Rows where the "array_col" column contains "arr_value" and the "string_col" column equals "value":
  {
      "@and": [
        { "@contains": { "array_col": "arr_value" } },
        { "@eq": { "string_col": "value" } }
      ]
  }
  
  // Rows where the "string_col" column does not equal "value"
  {
    "@not": { "@eq": { "string_col": "value" } }
  }
  
  // Rows where the "array_col" column contains at least one of "val1", "val2", or "val3"
  {
    "@or": [
        { "@contains": { "array_col": "val1" } },
        { "@contains": { "array_col": "val1" } },
        { "@contains": { "array_col": "val1" } }
    ]
  }
  

  Copy

Abfrage eines Dienstes mit Erhöhungs- oder Abfall-Signalen¶

Bei der Abfrage eines Cortex Search Service geben Sie in den optionalen Feldern numeric_boosts und time_decays im Feld scoring_config.functions die Spalten an, die für das Erhöhen oder Abfallen verwendet werden sollen. Sie können auch das Gewicht für jede Erhöhung oder jeden Abfall festlegen.

{
  "scoring_config": {
    "functions": {
      "numeric_boosts": [
        {
          "column": "<column_name>",
          "weight": <weight>
        },
        // ...
      ],
      "time_decays": [
        {
          "column": "<column_name>",
          "weight": <weight>,
          "limit_hours": <limit_hours>
        },
        // ...
      ]
    }
  }
}

Eigenschaften:

• numeric_boosts (Array, optional):

  • <numeric_boost_object> (Objekt, optional):

    • column_name (string): Gibt die numerische Spalte an, auf die die Erhöhung angewendet werden soll.

    • weight (float): Gibt das Gewicht oder die Wichtigkeit an, die der erhöhte Spalte im Rankingprozess zugewiesen wird. Wenn mehrere Spalten angegeben sind, erhöht ein höheres Gewicht den Einfluss des Feldes.

• time_decays (Array, optional):

  • <time_decay_object> (Objekt, optional):

    • column_name (string): Gibt die Zeit- oder Datumsspalte an, auf die der Abfall angewendet werden soll.

    • weight (float): Gibt die Gewichtung oder Wichtigkeit an, die der abfallenden Spalte im Rankingprozess zugewiesen wird. Wenn mehrere Spalten angegeben sind, erhöht ein höheres Gewicht den Einfluss des Feldes.

    • limit_hours (float): Legt die Grenze fest, ab der die Zeit einen geringeren Einfluss auf die Relevanz oder Wichtigkeit des Dokuments hat. Ein limit_hours-Wert von 240 bedeutet zum Beispiel, dass Dokumente mit Zeitstempeln, die mehr als 240 Stunden (10 Tage) vor dem now-Zeitstempel liegen, keine signifikante Erhöhung erhalten, während Dokumente mit einem Zeitstempel innerhalb der letzten 240 Stunden eine stärkere Erhöhung erhalten sollten.

    • now (Zeichenfolge, optional): Optionaler Referenzzeitstempel, von dem aus die Abfälle im Format ISO-8601 berechnet werden yyyy-MM-dd'T'HH:mm:ss.SSSXXX. Zum Beispiel "2025-02-19T14:30:45.123-08:00". Standardmäßig wird der aktuelle Zeitstempel verwendet, wenn er nicht angegeben wird.

Beispiel¶

Beispieldaten und Cortex Search Service erstellen

Dieses Beispiel verwendet eine Tabelle mit dem Namen business_documents, die zwei Zeitstempelspalten (last_modified, created_timestamp) und zwei Ganzzahl-Spalten (likes, columns) enthält, die für Erhöhungen und Abfälle bei Suchergebnissen verwendet werden können.

CREATE OR REPLACE TABLE business_documents (
    document_contents VARCHAR,
    last_modified_timestamp TIMESTAMP,
    created_timestamp TIMESTAMP,
    likes INT,
    comments INT
);

INSERT INTO business_documents (document_contents, last_modified_timestamp, created_timestamp, likes, comments)
VALUES
    ('Quarterly financial report for Q1 2024: Revenue increased by 15%, with expenses stable. Highlights include strategic investments in marketing and technology.',
     '2024-01-12 10:00:00', '2024-01-10 09:00:00', 10, 20),

    ('IT manual for employees: Instructions for usage of internal technologies, including hardware and software guides and commonly asked tech questions.',
     '2024-02-10 15:00:00', '2024-02-05 14:30:00', 85, 10),

    ('Employee handbook 2024: Updated policies on remote work, health benefits, and company culture initiatives. Includes new guidelines on hybrid working models.',
     '2024-02-10 15:00:00', '2024-02-05 14:30:00', 85, 10),

    ('Marketing strategy document: Target audience segmentation for upcoming product launch. Detailed plans for social media, influencer partnerships, and content creation.',
     '2024-03-15 12:00:00', '2024-03-12 11:15:00', 150, 32),

    ('Product roadmap 2024: Key milestones for tech product development, including the launch of new features, bug fixes, and performance improvements.',
     '2024-04-22 17:30:00', '2024-04-20 16:00:00', 200, 45),

    ('Annual performance review process guidelines: Procedures for managers to conduct employee evaluations, set goals, and provide constructive feedback.',
     '2024-05-02 09:30:00', '2024-05-01 08:45:00', 60, 5);

Als nächstes erstellen Sie einen Cortex Search Service mit dem Namen business_documents_css in der Spalte document_contents der Tabelle business_documents.

CREATE OR REPLACE CORTEX SEARCH SERVICE business_documents_css
    ON document_contents
    WAREHOUSE = <warehouse_name>
    TARGET_LAG = '1 minute'
AS SELECT * FROM business_documents;

Abfrage des Dienstes mit numerischen Erhöhungen

Die folgende Abfrage wendet numerische Erhöhungen auf die Spalten likes und comments an, wobei die Werte von comments doppelt so stark wie die von likes gewichtet werden. Die Abfrage verwendet die SQL-Funktion SEARCH_PREVIEW, um nach „Technologie“ zu suchen.

SELECT
    index,
    value['DOCUMENT_CONTENTS']::string as DOCUMENT_CONTENTS,
    value['LIKES']::int as LIKES,
    value['COMMENTS']::int as COMMENTS,
FROM TABLE(FLATTEN(PARSE_JSON(SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
    'business_documents_css',
    '{
      "query": "technology",
      "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
      "scoring_config": {
        "functions": {
          "numeric_boosts": [
            {"column": "comments", "weight": 2},
            {"column": "likes", "weight": 1}
          ]
        }
      }
    }'
))['results'] ))

Beachten Sie bei den Ergebnissen:

• Mit den Erhöhungen ist das Dokument "Product roadmap 2024:..." aufgrund der großen Anzahl von Likes und Kommentaren das Top-Ergebnis, auch wenn es eine etwas geringere Relevanz für die Abfrage "technology" hat

• Ohne Erhöhungen ist das Top-Ergebnis für die Abfrage "IT manual for employees:..."

Abfrage des Dienstes mit Hilfe von Zeitabfällen

Die folgende Abfrage wendet Zeitabfälle basierend auf der Spalte LAST_MODIFIED_TIMESTAMP an, wobei:

• Dokumente mit neueren LAST_MODIFIED_TIMESTAMP-Werten, relativ zum now-Zeitstempel, erhöht werden

• Dokumente mit einem LAST_MODIFIED_TIMESTAMP-Wert von mehr als 240 Stunden ab dem now Zeitstempel eine geringe Erhöhung erhalten

SELECT
  value['DOCUMENT_CONTENTS']::string as DOCUMENT_CONTENTS,
  value['LAST_MODIFIED_TIMESTAMP']::timestamp as LAST_MODIFIED_TIMESTAMP
FROM TABLE(FLATTEN(PARSE_JSON(SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
    'business_documents_css',
    '{
      "query": "technology",
      "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP", "CREATED_TIMESTAMP", "LIKES", "COMMENTS"],
      "scoring_config": {
          "functions": {
              "time_decays": [
                {"column": "LAST_MODIFIED_TIMESTAMP", "weight": 1, "limit_hours": 240, "now": "2024-04-23T00:00:00.000-08:00"}
              ]
            }
        }
    }'
))['results'] ));

Beachten Sie bei den Ergebnissen:

• Mit den Abfällen ist das Dokument "Product roadmap 2024:..." aufgrund seiner Aktualität zum Zeitstempel now das Top-Ergebnis, auch wenn es eine etwas geringere Relevanz für die Abfrage "technology" hat

• Ohne Abfälle ist das Top-Ergebnis für die Abfrage "IT manual for employees:..."

Abfrage eines Cortex Search Service ohne den Neueinstufer¶

Sie können den Neueinstufer für eine einzelne Abfrage zum Zeitpunkt der Abfrage im Feld scoring_config.reranker im folgenden Format deaktivieren:

{
  "scoring_config": {
      "reranker": "none"
}

Eigenschaften:

• reranker (Zeichenfolge, optional): Parameter, der auf „none“ gesetzt werden kann, wenn der Neueinstufer ausgeschaltet werden soll. Wenn ausgeschlossen oder null, wird der Standard-Neueinstufer verwendet.

Beispiele¶

Abfrage eines Suchdienstes ohne den Neueinstufer (Python)

Der folgende Code fragt den Dienst ohne den Schritt der Neueinstufung ab, indem er die Python-API verwendet:

resp = business_documents_css.search(
  query="technology",
  columns=["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
  limit=5,
  scoring_config={
    "reranker": "none"
  }
)

Abfrage eines Dienstes ohne den Neueinstufer (SQL)

Die folgende SQL-Anweisung fragt den Dienst ohne den Schritt der Neueinstufung mit der SEARCH_PREVIEW-Funktion ab.

SELECT
    value['DOCUMENT_CONTENTS'], value['LAST_MODIFIED_TIMESTAMP']
FROM TABLE(FLATTEN(PARSE_JSON(SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
    'business_documents_css',
    '{
      "query": "technology",
      "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
      "scoring_config": {
        "reranker": "none"
      }
    }'
))['results'] ));

Abfragen mit Eigentümerrechten¶

Cortex Search Services führen Suchvorgänge mit den Rechten des Eigentümers durch und folgen demselben Sicherheitsmodell wie andere Snowflake-Objekte, die mit den Rechten des Eigentümers laufen.

Dies bedeutet insbesondere, dass jede Rolle, die über ausreichende Berechtigungen für die Abfrage eines Cortex Search Service verfügt, alle vom Dienst indizierten Daten abfragen kann, unabhängig von den Berechtigungen dieser Rolle für die zugrunde liegenden Objekte (wie Tabellen und Ansichten), auf die in der Quellabfrage des Dienstes verwiesen wird.

Bei einem Cortex Search Service, der auf eine Tabelle mit Maskierungsrichtlinien auf Zeilenebene verweist, können abfragende Benutzer dieses Dienstes beispielsweise Suchergebnisse von Zeilen sehen, auf die die Rolle des Eigentümers eine Leseberechtigung hat, auch wenn die Rolle des abfragenden Benutzers diese Zeilen in der Quelltabelle nicht lesen kann.

Seien Sie vorsichtig, wenn Sie z. B. einem anderen Snowflake-Benutzer eine Rolle mit USAGE-Berechtigungen auf einem Cortex Search Service gewähren.