Skip to content
Back to blog
Measurement

BigQuery AI Functions: AI.RANK GA, Syntax, Permissions, Cost

BigQuery AI functions guide to AI.RANK, now GA: syntax, Discovery Engine permissions, cost control, and a two-stage search that reranks only 50 candidates.

6 min readMeasurement
BigQueryAI.RANKBigQuery AI functionsSemantic rankingSearch relevanceMeasurement
BigQuery AI Functions: AI.RANK GA, Syntax, Permissions, Cost

BigQuery AI.RANK is one of the BigQuery AI functions. It reorders the rows of a table by "how well each row answers a query." Google Cloud announced in the BigQuery release notes of November 17 that the function is now generally available (GA). Say you have a table of reviews, support requests, or document titles. If you ask "how to reset my password," AI.RANK can lift a row like "change your login information" to the top, even though it shares no words with the query.

AI.RANK returns a 0.0 to 1.0 score and a rank showing how well the text column you choose answers the query, and it keeps your original columns attached.

It does not use an index, so cost grows with every row you send. The official docs recommend narrowing candidates with vector search first, then reranking with AI.RANK.

To use it, enable the Discovery Engine API in your project and give the account that runs the query the Discovery Engine Viewer role. Billing goes through separate ranking API pricing.

How AI.RANK differs from keyword and vector search in BigQuery AI functions

AI.RANK reads the query and each row's text together and then scores them. According to the official Google docs, keyword search, vector search, and hybrid search score the query and each row separately. That lets them use indexes and stay fast on large tables. AI.RANK gives a more precise score, but it cannot use an index, and its cost grows in proportion to the number of rows being ranked (AI.RANK reference).

Diagram comparing how BigQuery AI functions like AI.RANK and keyword or vector search score a query against rows
Figure 1. Keyword and vector search read the question and the row separately. AI.RANK reads them together.
BigQuery search methods compared (based on the official docs)
TypeHow it scoresIndexCost and scale
Keyword, vector, and hybrid searchScores the query and each row separatelyCan use an indexScales to large tables
AI.RANKEvaluates the query and each row's text togetherDoes not use an indexCost grows with every ranked row

So AI.RANK works best as the second stage of a search, not as a replacement for search. The release note entry says only this: it reranks rows by how well a text column answers a query, and it is now GA.

BigQuery AI functions release note entry for November 17 announcing the AI.RANK function is generally available
Figure 2. The November 17, 2026 entry in the BigQuery release notes. Source: Google Cloud docs screenshot (November 18, 2026)

How to write an AI.RANK query: syntax and a first example

AI.RANK takes the data, the column to rank, and the query. The model and the number of returned rows are optional.

AI.RANK arguments (based on the official docs)
ArgumentRequiredDescription
TABLE table_name or (query)RequiredThe data to rank. Pass one of the two
column_to_rankRequiredName of the text column to rank. It must be a STRING, and the input data must not have a column named rank or score (case-insensitive)
queryRequiredThe search query to compare against. An empty string is not allowed
modelOptionalThe ranking model. Defaults to semantic-ranker-default@latest
top_nOptionalMaximum number of rows to return. Must be positive. If omitted, all ranked rows are returned
First screen of the official BigQuery AI functions doc for AI.RANK: three features and setup notes
Figure 4. The first screen of the AI.RANK reference. It shows three features (semantic ranking, rank output, original columns kept) and a note about the Discovery Engine API. Source: Google Cloud docs screenshot (November 18, 2026)

The first example in the official docs uses the public BBC News table. It picks the 5 titles that best match a downturn in the housing market.

SELECT rank, score, title
FROM AI.RANK(
  TABLE `bigquery-public-data.bbc_news.fulltext`,
  'title',
  'downward trends in the housing market',
  top_n => 5
);

The result adds rank (a 1-based position, INT64) and score (0.0 to 1.0 relevance, FLOAT64) to the input columns, sorted by rank ascending. The official docs show output like the table below. Scores change from run to run.

Official example output (rank, score, title, sample values from the docs)
rankscoretitle
10.6353House prices drop as sales slow
20.4060House prices suffer festive fall
30.3988Survey confirms property slowdown
40.3728UK house prices dip in November
50.2671No seasonal lift for house market

Moving the same syntax to a review table looks like AI.RANK(TABLE `프로젝트.데이터세트.reviews`, 'review_text', '배송이 늦어서 불만인 리뷰', top_n => 20). The docs describe the behavior as lifting text that answers the question even when no words overlap. Which reviews actually rise to the top is something you can only learn by opening the results on your own table.

Which column to rank with AI.RANK: title or body

The official docs give this rule. If the query names a topic, a short column such as a title or summary works better, because a long body spreads the topic across unrelated paragraphs. If the query is a detail that would not appear in a headline, pick the long column. The docs use the example of finding "executives who resigned after an accounting scandal." Ranking by title misses the article about the Airing Goose executive resignation, and ranking by body finds it.

To limit the ranking to one category, pass a query instead of a table. The query below picks only business articles and returns 3 by body text.

SELECT rank, score, title
FROM AI.RANK(
  (
    SELECT title, body
    FROM `bigquery-public-data.bbc_news.fulltext`
    WHERE category = 'business'
  ),
  'body',
  'executives who resigned after an accounting scandal',
  top_n => 3
);

AI.RANK ranks every row it receives, so narrowing with WHERE first is the easiest way to control cost. The official docs recommend this too.

On a large table, do not run AI.RANK from the start. The docs describe the most useful pattern as a two-stage search: a cheap stage picks candidates, and AI.RANK reranks only those candidates.

Two-stage search with BigQuery AI functions: VECTOR_SEARCH picks 50 candidates, then AI.RANK reranks the top 5
Figure 3. Narrowing candidates first caps the cost at the number of candidates.

The official example runs VECTOR_SEARCH on a column that already holds embeddings (text converted into numeric vectors) to pull 50 similar articles. AI.RANK then reorders those 50 by the question and returns 5.

SELECT rank, score, title
FROM AI.RANK(
  (
    SELECT base.title AS title, base.body AS body
    FROM VECTOR_SEARCH(
      TABLE `bigquery-public-data.bbc_news.fulltext`,
      'body_embedded',
      (
        SELECT body_embedded
        FROM `bigquery-public-data.bbc_news.fulltext`
        WHERE title = 'Bank opts to leave rates on hold'
      ),
      top_k => 50)
  ),
  'body',
  'downward trends in the housing market',
  top_n => 5
);

VECTOR_SEARCH compares vectors, not text, so the subquery passes in the embedding of an existing article. To search with a sentence you wrote yourself, create its embedding with AI.EMBED and pass that in. In this setup AI.RANK ranks only 50 rows, so the query is fast and the cost is capped by the candidate count. AI.SEARCH can also pick the candidates. If you want to summarize the result rows into one paragraph, read how to use the BigQuery AI.AGG function next. AI.RANK accepts only STRING columns, so to pass images or PDFs into SQL, use the approach in how to use BigQuery ObjectRef.

Before you use AI.RANK: API, permissions, and pricing

AI.RANK calls the Agent Search ranking API of the project that runs the query. So you need two things in place first.

  1. Enable the Discovery Engine API in the project. Enabling it requires the serviceusage.services.enable permission. If you created the project yourself, you likely already have it through the owner role.
  2. Give the account that runs the query the project-level Discovery Engine Viewer (roles/discoveryengine.viewer) role. This role includes the discoveryengine.rankingConfigs.rank permission that an AI.RANK call needs.

Usage is billed separately at ranking API pricing, and call volume counts against that project's Agent Search quotas. The only cost control the docs mention is to shrink the input first. If a row's text is longer than the model's token limit, the excess is truncated. Per-model limits are in the supported models table.

How to check that AI.RANK results are correct

The AI.RANK score is meant only for comparing rows within a single result. It is not calibrated across queries. If you set a fixed cutoff such as "only rows with score above 0.5," it may work for one query and cut off correct answers for another. A score of 0.0 cannot tell irrelevant text apart from a row that was not ranked. To shrink results, use top_n or filter on the rank column.

Here is the order to check it on your own data.

  1. Start with a table of a few hundred rows, or a query narrowed by WHERE, to cap the cost.
  2. Pick a query where you already know 3 to 5 correct rows, and run it with top_n => 10.
  3. Check by rank whether the known rows rise to the top. Look at the order, not the score numbers.
  4. If they do not, rerun the same query with column_to_rank switched from title to body (or the reverse).

If the query finishes without errors and rank runs from 1 onward, the run succeeded. Getting fewer rows than you put in is not an error. According to the docs, rows where the ranked column is NULL or an empty string are dropped before ranking, and rows beyond top_n are dropped from the result.

Frequently asked questions

Do I have to set the model argument?

No. If you omit it, semantic-ranker-default@latest is used, which always points to the latest ranking model. The official docs recommend omitting it so model improvements apply automatically.

Which project is billed for AI.RANK queries?

The project that runs the query. According to the official docs, AI.RANK calls that project's Agent Search ranking API with the running account's credentials, and usage is billed at ranking API pricing.

Can I search a whole table with AI.RANK alone?

It is fine for a small table or a result narrowed by WHERE. On a large table it cannot use an index and costs money for every row, so the structure the official docs recommend is to pick candidates first with VECTOR_SEARCH or AI.SEARCH.

Found this useful? Share it

Latest posts

Related projects

Get new posts by email

Insights on marketing, analytics, and dev, delivered to your inbox.