Rank and score search results
Stay organized with collections Save and categorize content based on your preferences.

This page describes how to rank or score your search results for applications using the Vertex AI ranking model endpoint registered in the Model endpoint management.

The Vertex AI ranking API takes a list of documents and ranks those documents based on how relevant the documents are to a given query (a search string). When you use the ai.rank() function, it returns scores for how well a document answers a given query.

To use instructions on this page, you must have an understanding of AlloyDB for PostgreSQL and be familiar with generative AI concepts.

AlloyDB reserves the ai schema, and tries to create this schema when you install the google_ml_integration extension. If the schema creation fails, then use the functions with the same name in the google_ml schema.

Before you begin

Request access to rank your search results using ranking models and wait until you receive the enablement confirmation before you follow the instructions on this page.
Ensure that the Vertex AI ranking model is registered. For more information, see Vertex AI ranking models.

Rank your search results

The following SQL query shows how to rank your search results :

SELECT
  ai.rank(
    model_id => 'MODEL_ID',
    search_string => 'SEARCH_STRING',
    documents => ARRAY['DOCUMENT_1', 'DOCUMENT_2', 'DOCUMENT_3']);

Replace the following:

Parameter	Description
`MODEL_ID`	A unique ID for the model endpoint that you define.
`SEARCH_STRING`	Search string against which the records are ranked or scored.
`DOCUMENTS`	A unique string that identifies the record.

Examples

To rank search results using the registered ranking endpoint, run the following query:

SELECT index, score
FROM
  ai.rank(
    model_id => 'semantic-ranker-512-002',
    search_string => 'AlloyDB is a PostgreSQL compatible AI database that is ready for production.',
    documents =>
      ARRAY[
        'Alloys are made from combination of metals',
        'The best enterprise-ready PostgreSQL database.',
        'You can feel the heat in Alloy apartments.']);

The response is a table that shows each document and the score based on relevance to the search query.The following is the sample response:

 index | score
-------+-------
     1 |  0.03
     2 |  0.02
     3 |  0.01
(3 rows)

Consider an example AlloyDB database with a list of review descriptions that are converted to embeddings. The following sample code snippet shows how to use the ranking model to retrieve the name of the top-ranked products based on their review descriptions' semantic similarity to a query. It assumes that both the text-embedding-005 and semantic-ranker-512@002 model endpoints are registered.

WITH
  initial_results AS (
    SELECT product_id, name, review, review_id,
            ROW_NUMBER() OVER () AS ref_number
    FROM user_reviews
    ORDER BY
      review_desc_embedding <=> google_ml.embedding(
        'text-embedding-005', 'good desserts')
    LIMIT 100
  ),
reranked AS (
    SELECT
      ai.rank(
        model_id => 'semantic-ranker-512@002',
        search_string => 'good desserts',
        documents => ARRAY_AGG(review ORDER BY ref_number))
    FROM initial_results
  )
SELECT product_id, name
FROM initial_results, reranked
WHERE initial_results.ref_number = reranked.index
ORDER BY reranked.score;