Method: projects.locations.rankingConfigs.rank

Ranks a list of text records based on the given input query.

HTTP request

POST https://discoveryengine.googleapis.com/v1/{rankingConfig=projects/*/locations/*/rankingConfigs/*}:rank

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
rankingConfig

string

Required. The resource name of the rank service config, such as projects/{projectNum}/locations/{location}/rankingConfigs/default_ranking_config.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "model": string,
  "topN": integer,
  "query": string,
  "records": [
    {
      object (RankingRecord)
    }
  ],
  "ignoreRecordDetailsInResponse": boolean,
  "userLabels": {
    string: string,
    ...
  }
}
Fields
model

string

The identifier of the model to use. It is one of:

  • semantic-ranker-512@latest: Semantic ranking model with maximum input token size 512.

It is set to semantic-ranker-512@latest by default if unspecified.
topN

integer

The number of results to return. If this is unset or no bigger than zero, returns all results.
query

string

The query to use.
records[]

object (RankingRecord)

Required. A list of records to rank.
ignoreRecordDetailsInResponse

boolean

If true, the response will contain only record ID and score. By default, it is false, the response will contain record details.
userLabels

map (key: string, value: string)

The user labels applied to a resource must meet the following requirements:

  • Each resource can have multiple labels, up to a maximum of 64.
  • Each label must be a key-value pair.
  • Keys have a minimum length of 1 character and a maximum length of 63 characters and cannot be empty. Values can be empty and have a maximum length of 63 characters.
  • Keys and values can contain only lowercase letters, numeric characters, underscores, and dashes. All characters must use UTF-8 encoding, and international characters are allowed.
  • The key portion of a label must be unique. However, you can use the same key with multiple resources.
  • Keys must start with a lowercase letter or international character.

See Google Cloud Document for more details.

Response body

Response message for RankService.Rank method.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "records": [
    {
      object (RankingRecord)
    }
  ]
}
Fields
records[]

object (RankingRecord)

A list of records sorted by descending score.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the rankingConfig resource:

  • discoveryengine.rankingConfigs.rank

For more information, see the IAM documentation.

RankingRecord

Record message for RankService.Rank method.

JSON representation 
{
  "id": string,
  "title": string,
  "content": string,
  "score": number
}
Fields
id

string

The unique ID to represent the record.
title

string

The title of the record. Empty by default. At least one of title or content should be set otherwise an INVALID_ARGUMENT error is thrown.
content

string

The content of the record. Empty by default. At least one of title or content should be set otherwise an INVALID_ARGUMENT error is thrown.
score

number

The score of this record based on the given query and selected model. The score will be rounded to 2 decimal places. If the score is close to 0, it will be rounded to 0.0001 to avoid returning unset.