Customizing Cortex Search Scoring¶

Numeric boosts and time decays¶

You can boost or apply decays search results based on numeric or timestamp metadata. This feature is useful when you have structured metadata, such as popularity or recency signals, for each result that can help determine the relevance of documents at query time. You can specify two categories of ranking signals when making a query:

Boost and decay metadata come from columns in the source table from which a Cortex Search Service is created. You specify the metadata columns to use for boosting or decaying when you make the query, but those columns must be included when creating the Cortex Search service.

When querying a Cortex Search Service, specify the columns to use for boosting or decaying in the optional numeric_boosts and time_decays fields in the scoring_config.functions field. You can also specify the weight for each boost or decay.

{
  "scoring_config": {
    "functions": {
      "numeric_boosts": [
        {
          "column": "column_name",
          "weight": 1
        },
        /* ... */
      ],
      "time_decays": [
        {
          "column": "column_name",
          "weight": 1,
          "limit_hours": 120
        },
        /* ... */
      ]
    }
  }
}

Reranking¶

By default, queries to Cortex Search Services leverage semantic reranking to improve search result relevance. While reranking can measurably increase result relevance, it can also noticeably increase query latency. You can disable reranking in any Cortex Search query if you’ve found that the quality benefit that reranking provides can be sacrificed for faster query speeds in your business use case.

You can disable the reranker for an individual query at query time in the scoring_config.reranker field in the following format:

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

Component weights¶

The weights field in the scoring_config object allows you to specify the weights of individual scoring components (vectors, texts, reranker) in the overall score for each result. By default, the weights are set to 1.0 for each component, with an equal contribution to the overall scoring.

You can specify weights in the following format:

{
  "scoring_config": {
    "functions": {
      "weights": {
        "texts": 3,
        "vectors": 2,
        "reranker": 1
      }
    }
  }
}

{
  "scoring_config": {
    "functions": {
      "weights": {
        "texts": 3,
        "vectors": 1,
        "reranker": 2
      }
    }
  }
}

Named scoring profiles¶

Boosts/decays and reranker settings together form a scoring configuration, which can be specified in the scoring_config parameter when making a query. Scoring configurations can also be given a name and attached to the Cortex Search service.

Using a named scoring profile lets you easily use a scoring configuration across applications and queries without having to specify the full scoring configuration each time. If you change the scoring configuration, you only need to update it in one place, not in every query.

To add a scoring profile to your Cortex Search Service, use the ALTER CORTEX SEARCH SERVICE … ADD SCORING PROFILE command, as shown in the following example:

ALTER CORTEX SEARCH SERVICE my_search_service
  ADD SCORING PROFILE heavy_comments_with_likes IF NOT EXISTS
  '{
    "functions": {
            "numeric_boosts": [
                { "column": "comments", "weight": 6 },
                { "column": "likes", "weight": 1 }
            ]
    }
  }'

The syntax of the scoring profile definition is the same schema used in the scoring_config parameter when making a query.

Scoring profiles can’t be modified after being created; to change a profile, drop it and recreate it with the new scoring configuration. To delete a named scoring profile, use ALTER CORTEX SEARCH SERVICE … DROP SCORING PROFILE.

To query a Cortex Search Service using a named scoring profile, specify the profile name in the scoring_profile parameter when making a query, as shown in the following examples:

results = svc.search(
    query="technology",
    columns=["comments", "likes"],
    scoring_profile="heavy_comments_with_likes",
    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": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
  "scoring_profile": "heavy_comments_with_likes",
  "limit": 10
}'

SELECT SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
  'my_search_service',
  '{
    "query": "technology",
    "columns": ["comments", "likes"],
    "scoring_profile": "heavy_comments_with_likes",
    "limit": 10
  }'
);

To see a service’s stored scoring profiles, query the CORTEX_SEARCH_SERVICE_SCORING_PROFILES view in the INFORMATION_SCHEMA schema, as shown in the following example:

SELECT *
  FROM my_db.INFORMATION_SCHEMA.CORTEX_SEARCH_SERVICE_SCORING_PROFILES
  WHERE service_name = 'my_search_service';

Component Scores¶

Component Scores provide detailed scoring information for search results. They allow developers to understand how search rankings are determined and debug search performance. Scores for each result are returned in the @scores field for each retrieval “component” (text, vector). Component scores are useful in scenarios where there is a need to:

• Establish thresholds: Use component scores to determine when to pass results on to a downstream process, like an agent.

• Debug search rankings: Understand why certain documents rank higher than others in search results.

{
  "results": [
    {
      "@scores": {
        "cosine_similarity": <cosine_similarity_score>,
        "text_match": <text_match_score>
      }
    }
  ]
}