Interroger un Cortex Search Service

Lorsque vous créez un Cortex Search Service, le système fournit un point de terminaison API pour servir les requêtes à faible latence. Vous pouvez utiliser trois APIs pour interroger un Cortex Search Service :

Paramètres

Toutes les APIs prennent en charge le même ensemble de paramètres de requête :

Paramètre

Description

Obligatoire

query

La requête de recherche, à rechercher dans la colonne de texte du service.

Facultatif

columns

Une liste de colonnes séparées par des virgules à renvoyer pour chaque résultat pertinent dans la réponse. Ces colonnes doivent être incluses dans la requête source du service. Si ce paramètre n’est pas fourni, seule la colonne de recherche est renvoyée dans la réponse.

filter

Un objet de filtre pour filtrer les résultats en fonction des données dans les colonnes ATTRIBUTES. Consultez Syntaxe de filtre pour la syntaxe.

scoring_config

Objet de configuration pour personnaliser le comportement du classement de la recherche. Pour plus d’informations sur la syntaxe, voir Personnalisation de Cortex Search Scoring.

scoring_profile

Le profil de notation nommé à utiliser avec la requête, précédemment défini avec ALTER CORTEX SEARCH SERVICE … ADD SCORING PROFILE. Si le scoring_profile est fourni, tout scoring_config fourni est ignoré.

limit

Nombre maximal de résultats à renvoyer dans la réponse, jusqu’à 1 000. La limite par défaut est de 10.

Syntaxe

Les exemples suivants montrent comment interroger un Cortex Search Service en utilisant les trois surface :

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

# connect to Snowflake
CONNECTION_PARAMETERS = { ... }
session = Session.builder.configs(CONNECTION_PARAMETERS).create()
root = Root(session)

# 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())
Copy

Configuration et authentification

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.

Installer la bibliothèque API Python Snowflake

Tout d’abord, installez la dernière version du paquet des APIs’ python snowflake depuis PyPI. Consultez installer la bibliothèque des APIs python snowflake pour obtenir des instructions sur l’installation de ce paquet à partir de PyPI.

pip install snowflake -U
Copy

Se connecter à Snowflake

Connectez-vous à Snowflake en utilisant une Session Snowpark ou une Connection Python Connector et créez un objet Root. Consultez se connecter à snowflake avec les APIs python snowflake pour plus d’instructions sur la connexion à snowflake. L’exemple suivant utilise l’objet de la Session Snowpark et un dictionnaire Python pour la configuration.

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)
Copy

Note

La version 0.8.0 ou ultérieure de la bibliothèque des APIs Python est nécessaire pour interroger un Cortex Search Service.

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
Copy

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 à appeler 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.

Authentification

Les APIs REST Snowflake prennent en charge l’authentification via des jetons d’accès programmatiques (PATs), l’authentification par paire de clés à l’aide des jetons web JSON (JWTs), et OAuth. Pour plus de détails, consultez Authentification des APIsREST Snowflake avec Snowflake.

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 vérifier facilement et de manière interactive qu’un service est correctement renseigné et fournit des résultats raisonnables.

Important

La fonction SEARCH_PREVIEW est fournie pour tester et valider les Cortex Search Services. Elle n’est pas destinée à servir des requêtes de recherche dans une application d’utilisateur final.

  • La fonction fonctionne uniquement sur les chaînes littérales. Elle n’accepte pas de données de texte par lots.

  • La fonction a une latence plus élevée que les APIs REST et Python.

Syntaxe de filtre

Cortex Search prend en charge le filtrage sur les colonnes ATTRIBUTES spécifiées dans la commande CREATE CORTEX SEARCH SERVICE.

Cortex Search prend en charge cinq opérateurs de recherche :

Ces opérateurs de correspondance peuvent être composés de différents opérateurs logiques :

  • @and

  • @or

  • @not

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

Exigences en matière de contrôle d’accès

Le rôle qui interroge le Cortex Search Service doit disposer des privilèges suivants pour récupérer les résultats :

Privilège

Objet

USAGE

Le Cortex Search Service

USAGE

La base de données dans laquelle réside le Cortex Search Service

USAGE

Le schéma dans lequel réside le Cortex Search Service

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.

Limitations connues

L’interrogation d’un Cortex Search Service est soumise aux limitations suivantes :

  • Taille de la réponse : La taille totale de la charge utile de la réponse renvoyée par une requête de recherche à un Cortex Search Service ne doit pas dépasser les limites suivantes :

Exemples

Cette section fournit des exemples complets pour interroger les Cortex Search Services sur les trois méthodes API.

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;
Copy

Exemples de filtre

Requête simple avec un filtre d’égalité

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

Filtre de plage

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

Exemples de notation

Améliorations numériques

Appliquez des améliorations numériques aux colonnes des J’aime et des commentaires, avec deux fois la pondération d’amélioration sur les valeurs de commentaires par rapport aux valeurs J’aime.

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}
            ]
        }
    }
)
Copy

Dans les résultats, notez :

  • Avec les améliorations, le document « Feuille de route de produit 2024 :… » est le meilleur résultat en raison de son grand nombre de J’aime et de commentaires, même s’il a une pertinence légèrement moindre pour la requête « technologie ».

  • Sans aucune amélioration, le meilleur résultat principal de la requête est « Manuel IT pour les employés:… »

Décroissances temporelles

Appliquer des décroissances temporelles basées sur la colonneLAST_MODIFIED_TIMESTAMP, où :

  • les documents avec les valeurs LAST_MODIFIED_TIMESTAMP les plus récentes, relatives à l’horodatage actuel, sont améliorées.

  • les documents avec une valeur LAST_MODIFIED_TIMESTAMP supérieure à 240 heures à partir de l’horodatage actuel reçoivent peu d’amélioration

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"}
            ]
        }
    }
)
Copy

Dans les résultats, notez :

  • Avec les décroissances, le document « Feuille de route de produit 2024 :… » est le meilleur résultat en raison de sa référence à l’horodatage actuel, même s’il a une pertinence légèrement inférieure à la requête « technologie ».

  • Sans aucune décroissance, le meilleur résultat de la requête est « Manuel IT pour les employés….. »

Désactivation du reclassement

Pour désactiver le reclassement :

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

Astuce

Pour interroger un service avec le reclasseur, omettez le paramètre "reranker": "none" de l’objet scoring_config, car le reclassement est le comportement par défaut.

Langage: Français