Interroger un Cortex Search Service¶

Python API¶

Les cortex search services peuvent être interrogés à l’aide de la version 0.8.0 ou ultérieure des APIs python snowflake. Consultez APIs python snowflake : gestion des objets snowflake avec python pour plus d’informations sur les APIs python snowflake.

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 expose un point de terminaison d’API REST dans la suite des APIs REST Snowflake Cortex. Le point de terminaison REST généré pour un Cortex Search Service présente la structure suivante :

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

Où :

• <account_url>: URL de votre compte Snowflake. Consultez recherche de l’organisation et du nom d’utilisateur pour un compte pour obtenir des instructions sur comment trouver l’URL de votre compte.

• <db_name> : Base de données dans laquelle réside le service.

• <schema_name> : Schéma dans lequel réside le service.

• <service_name> : Nom du service.

• :query : La méthode à invoquer sur le service. Dans ce cas, la méthode query.

Pour plus de détails, consultez la référence REST API pour le Cortex Search Service.

Fonction SQL SEARCH_PREVIEW¶

La fonction SNOWFLAKE.CORTEX.SEARCH_PREVIEW vous permet de prévisualiser les résultats des requêtes individuelles adressées à un Cortex Search Service à partir d’un environnement SQL tel qu’une feuille de calcul ou une cellule de carnet Snowflake. Cette fonction permet de valider rapidement et facilement qu’un service est correctement renseigné et fournit des résultats raisonnables.

Notes sur l’utilisation¶

• la correspondance avec les valeurs NaN (’pas un nombre’) de la requête source est traitée comme décrit dans la section valeurs spéciales.

• les valeurs numériques à virgule fixe comportant plus de 19 chiffres (sans les zéros d’en-tête) ne fonctionnent pas avec @eq, @gte, ou @lte et ne seront pas renvoyés par ces opérateurs (bien qu’elles puissent toujours être renvoyées par la requête globale avec l’utilisation de @not).

• Les filtres TIMESTAMP et DATE acceptent des valeurs au format : YYYY-MM-DD et, pour les dates tenant compte des fuseaux horaires : YYYY- MM-DD+HH:MM. Si le décalage du fuseau horaire n’est pas spécifié, la date est interprétée en UTC.

• @primarykey est uniquement pris en charge pour les services configurés avec une clé principale. La valeur du filtre doit être un objet JSON mappant chaque colonne de clé principale avec sa valeur correspondante (ou NULL).

Ces opérateurs peuvent être combinés en un seul objet filtre.

Exemple¶

• Le filtrage sur les lignes où se trouve une colonne de type chaîne string_col est égal à la valeur value.

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

  Copy

• Filtrage sur une ligne avec les valeurs de clé principale spécifiées us-west-1 dans la colonne``region`` et abc123 dans la colonne agent_id :

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

  Copy

• Filtrage sur les lignes où la colonne ARRAY array_col contient de la valeur value.

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

  Copy

• Filtrage des lignes dont la colonne NUMERIC numeric_col est comprise entre 10,5 et 12,5 (inclus) :

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

  Copy

• Filtrer les lignes où la colonne TIMESTAMP timestamp_col est comprise entre 2024-11-19 et 2024-12-19 (inclus).

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

  Copy

• Composition de filtres avec des opérateurs logiques :

  // 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

Accroissements numériques et déclins avec le temps¶

Vous pouvez accroître les résultats de recherche ou y appliquer des déclins avec le temps en fonction de métadonnées numériques ou d’horodatage. Cette fonction est utile lorsque vous disposez de métadonnées structurées (par exemple, des signaux de popularité ou de récence) par résultat qui peuvent aider à déterminer la pertinence des documents au moment de la requête. Vous pouvez spécifier deux catégories de signaux de classement lorsque vous effectuez une requête :

Les métadonnées d’amélioration et de décroissance proviennent des colonnes du tableau source à partir desquelles un Cortex Search Service est créé. Vous spécifiez les colonnes de métadonnées à utiliser pour l’amélioration ou la décroissance lorsque vous effectuez la requête, mais ces colonnes doivent être incluses lors de la création du Cortex Search Service.

Interrogation d’un service avec des signaux d’amélioration ou de décroissance

Lors d’une requête auprès d’un Cortex Search Service, indiquez les colonnes à utiliser pour l’accroissement ou le déclin dans les champs facultatifs numeric_boosts et time_decays dans le champ scoring_config.functions. Vous pouvez également spécifier le poids de chaque accroissement ou déclin.

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

Propriétés :

• numeric_boosts (tableau, facultatif) :

  • <numeric_boost_object> (objet, facultatif) :

    • column_name (string) : Spécifie la colonne numérique à laquelle l’accroissement doit être appliqué.

    • weight (flottant) : Spécifie le poids ou l’importance attribué à la colonne avec accroissement dans le processus de classement. Lorsque plusieurs colonnes sont spécifiées, un poids plus élevé augmente l’influence du champ.

• time_decays (tableau, facultatif) :

  • <time_decay_object> (objet, facultatif) :

    • column_name (string) : Spécifie la colonne de date et d’heure à laquelle le déclin doit être appliquée.

    • weight (flottant) : Spécifie le poids ou l’importance attribué à la colonne avec déclin dans le processus de classement. Lorsque plusieurs colonnes sont spécifiées, un poids plus élevé augmente l’influence du champ.

    • limit_hours (flottant) : Définit la limite à partir de laquelle le temps commence à avoir moins d’effet sur la pertinence ou l’importance du document. Par exemple, une valeur limit_hours de 240 indique que les documents dont l’horodatage est supérieur à 240 heures (10 jours) par rapport à l’horodatage now ne bénéficient pas d’un accroissement significatif, tandis que les documents dont l’horodatage se situe dans les 240 dernières heures doivent bénéficier d’un accroissement plus important.

    • now (chaîne, facultatif) : Horodatage de référence facultatif à partir duquel les déclins sont calculés au format ISO-8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX. Par exemple, "2025-02-19T14:30:45.123-08:00". La valeur par défaut est l’horodatage actuel si ce n’est pas spécifié.

Reclassement¶

Par défaut, les requêtes adressées à Cortex Search Services exploitent un reclassement sémantique pour améliorer la pertinence des résultats de recherche. Si le reclassement peut sensiblement améliorer la pertinence des résultats, il peut aussi augmenter sensiblement le temps de latence des requêtes. Vous pouvez désactiver le reclassement dans n’importe quelle requête de Cortex Search si vous estimez que l’avantage qualitatif que procure le reclassement peut être sacrifié au profit d’une vitesse de requête plus rapide dans votre cas d’utilisation.

Interrogation d’un Cortex Search Service sans le reranker

Vous pouvez désactiver le reclasseur pour une requête individuelle au moment de la requête dans le champ scoring_config.reranker au format suivant :

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

Propriétés :

• reranker (chaîne, facultatif) : Paramètre pouvant être défini sur « none » si le reclasseur doit être désactivé. S’il est exclu ou nul, le reclasseur par défaut est utilisé.

Requête avec les droits du propriétaire¶

Les services Cortex Search Service effectuent des recherches avec les droits du propriétaire et suivent le même modèle de sécurité que les autres objets Snowflake qui s’exécutent avec les droits du propriétaire.

Plus particulièrement, cela signifie que tout rôle disposant de privilèges suffisants pour interroger un Cortex Search Service peut interroger n’importe quelle donnée indexée par le service, quels que soient les privilèges de ce rôle sur les objets sous-jacents (tels que les tables et les vues) référencés dans la requête source du service.

Par exemple, pour un Cortex Search Service qui référence une table avec des politiques de masquage au niveau des lignes, les utilisateurs effectuant des requêtes sur ce service pourront voir les résultats de la recherche à partir des lignes sur lesquelles le rôle du propriétaire dispose d’une autorisation de lecture, même si le rôle de l’utilisateur effectuant la requête ne peut pas lire ces lignes dans la table source.

Faites preuve de prudence, par exemple, lorsque vous accordez un rôle avec des privilèges USAGE sur un Cortex Search Service à un autre utilisateur Snowflake.

Préparer des exemples :¶

les exemples suivants utilisent un tableau nommé business_documents avec des colonnes d’horodatage et des colonnes numériques pour illustrer diverses fonctionnalités :

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;

Exemples de filtre¶

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;

Exemples de notation¶

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;