Abfrage eines Cortex Search Service¶

Python API¶

Die Cortex Search Services können mit der Version 0.8.0 oder höher von Snowflake-Python-APIs abgefragt werden. Weitere Informationen zu den Snowflake-Python-APIs finden Sie unter Snowflake-Python-APIs: Verwalten von Snowflake-Objekten mit Python.

pip install snowflake -U

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)

REST-API¶

Cortex Search stellt einen REST API-Endpunkt in der Suite von Snowflake REST APIs zur Verfügung. Der für einen Cortex Search Service generierte REST-Endpunkt hat die folgende Struktur:

https://<account_url>/api/v2/databases/<db_name>/schemas/<schema_name>/cortex-search-services/<service_name>:query

Wobei:

• <account_url>: Die URL Ihres Snowflake-Kontos. Informationen dazu, wie Sie die URL Ihres Kontos finden, erhalten Sie unter Suchen von Organisations- und Kontonamen eines Kontos.

• <db_name>: Datenbank, in der sich der Dienst befindet.

• <schema_name>: Schema, in dem sich der Dienst befindet

• <service_name>: Name des Dienstes.

• :query: Die Methode, die für den Dienst aufgerufen werden soll. In diesem Fall ist es die query-Methode.

Weitere Einzelheiten finden Sie in der REST API-Referenz für Cortex Search Service.

SQL-SEARCH_PREVIEW-Funktion¶

Mit der Funktion SNOWFLAKE.CORTEX.SEARCH_PREVIEW können Sie eine Vorschau der Ergebnisse einzelner Abfragen an einen Cortex Search Service aus einer SQL Umgebung wie einem Arbeitsblatt oder einer Snowflake-Notebook-Zelle heraus anzeigen. Mit dieser Funktion können Sie schnell und einfach überprüfen, ob ein Service korrekt ausgefüllt ist und vernünftige Ergebnisse liefert.

Nutzungshinweise¶

• Der Abgleich mit NaN-Werten („Keine Zahl“-Werten) in der Quellabfrage wird wie unter Besondere Werte beschrieben behandelt.

• Numerische Festkommawerte mit mehr als 19 Ziffern (einschließlich führender Nullen) funktionieren nicht mit @eq, @gte oder @lte und werden von diesen Operatoren nicht zurückgegeben (obwohl sie von der Gesamtabfrage mit Verwendung von @not trotzdem zurückgegeben werden könnten).

• Die Filter TIMESTAMP und DATE akzeptieren Werte im folgenden Format: YYYY-MM-DD und für zeitzonenabhängige Daten YYYY- MM-DD+HH:MM. Wenn der Zeitzonen-Offset nicht angegeben wird, wird das Datum in UTC interpretiert.

• @primarykey wird nur für Services unterstützt, die mit einem Primärschlüssel konfiguriert wurden. Der Wert des Filters muss ein JSON-Objekt sein, das jede Primärschlüsselspalte ihrem entsprechenden Wert (oder NULL) zuordnet.

Diese Operatoren können in einem einzigen Filterobjekt kombiniert werden.

Beispiel¶

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

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

  Copy

• Filtern einer Zeile mit den angegebenen Primärschlüsselwerten us-west-1 in der Spalte region und abc123 in der Spalte agent_id:

  { "@primarykey": { "region": "us-west-1", "agent_id": "abc123" } }
  

  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": "val2" } },
      { "@contains": { "array_col": "val3" } }
    ]
  }
  

  Copy

Numerische Erhöhungen und Zeitabfälle¶

Sie können Suchergebnisse auf der Grundlage von numerischen oder Zeitstempel-Metadaten erhöhen oder Abfälle anwenden. Dieses Feature ist nützlich, wenn Sie über strukturierte Metadaten (z. B. Popularitäts- oder Aktualitätssignale) pro Ergebnis verfügen, die bei der Bestimmung der Relevanz von Dokumenten zum Zeitpunkt der Abfrage helfen können. Sie können bei einer Abfrage zwei Kategorien von Ranking-Signalen angeben:

Erhöhungs- und Abfall-Metadaten stammen aus Spalten der Quelltabelle, aus der ein Cortex Search Service erstellt wird. Sie geben die Metadaten-Spalten an, die für die Erhöhung oder den Abfall verwendet werden sollen, wenn Sie die Abfrage durchführen; diese Spalten müssen aber bei der Erstellung des Cortex Search Service berücksichtigt werden.

Abfragen eines Service mit Erhöhungs- oder Abfallsignalen

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.

Neueinstufung¶

Standardmäßig nutzen Abfragen an Cortex Search Services semantische Neueinstufung zur Verbesserung der Relevanz der Suchergebnisse. Neueinstufung kann zwar die Relevanz der Ergebnisse messbar erhöhen, aber auch die Latenz bei Abfragen spürbar steigern. Sie können die Neueinstufung in jeder Cortex Search-Abfrage deaktivieren, wenn Sie festgestellt haben, dass der Qualitätsvorteil, den die Neueinstufung bietet, für eine schnellere Abfragegeschwindigkeit in Ihrem geschäftlichen Anwendungsfall geopfert werden kann.

Abfragen eines Cortex Search Service ohne erneutes Ranking

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.

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.

Einrichtung für die Beispiele¶

Die folgenden Beispiele verwenden eine Tabelle namens business_documents mit Zeitstempel- und numerischen Spalten zur Veranschaulichung verschiedener Funktionen:

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.',
     '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.',
     '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.',
     '2024-02-10 15:00:00', '2024-02-05 14:30:00', 85, 10),

    ('Marketing strategy document: Target audience segmentation for upcoming product launch.',
     '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.',
     '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.',
     '2024-05-02 09:30:00', '2024-05-01 08:45:00', 60, 5);

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

Filtern von Beispielen¶

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LIKES"],
    filter={"@eq": {"REGION": "US"}},
    limit=5
)

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": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LIKES"],
  "filter": {"@eq": {"REGION": "US"}},
  "limit": 5
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "technology",
         "columns": ["DOCUMENT_CONTENTS", "LIKES"],
         "filter": {"@eq": {"REGION": "US"}},
         "limit": 5
      }'
  )
)['results'] as results;

resp = business_documents_css.search(
    query="business",
    columns=["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
    filter={"@and": [
        {"@gte": {"LIKES": 50}},
        {"@lte": {"COMMENTS": 50}}
    ]},
    limit=10
)

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": "business",
  "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
  "filter": {"@and": [
    {"@gte": {"LIKES": 50}},
    {"@lte": {"COMMENTS": 50}}
  ]},
  "limit": 10
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "business",
         "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
         "filter": {"@and": [
           {"@gte": {"LIKES": 50}},
           {"@lte": {"COMMENTS": 50}}
         ]},
         "limit": 10
      }'
  )
)['results'] as results;

Bewertungsbeispiele¶

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
    scoring_config={
        "functions": {
            "numeric_boosts": [
                {"column": "comments", "weight": 2},
                {"column": "likes", "weight": 1}
            ]
        }
    }
)

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": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
  "scoring_config": {
    "functions": {
      "numeric_boosts": [
        {"column": "comments", "weight": 2},
        {"column": "likes", "weight": 1}
      ]
    }
  }
}'

SELECT 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'] as results;

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
    scoring_config={
        "functions": {
            "time_decays": [
                {"column": "LAST_MODIFIED_TIMESTAMP", "weight": 1, "limit_hours": 240, "now": "2024-04-23T00:00:00.000-08:00"}
            ]
        }
    }
)

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": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
  "scoring_config": {
    "functions": {
      "time_decays": [
        {"column": "LAST_MODIFIED_TIMESTAMP", "weight": 1, "limit_hours": 240, "now": "2024-04-23T00:00:00.000-08:00"}
      ]
    }
  }
}'

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

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

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": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
  "scoring_config": {
    "reranker": "none"
  }
}'

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