N/llm Module Adds reRank Method for Document Relevance Scoring

What changed

NetSuite 2026.2 introduces llm.reRank(options) in the N/llm module. The method accepts an array of document strings and a prompt, then returns those documents ranked by relevance. It is available in SuiteScript 2.1 server scripts only and consumes 50 governance units per invocation.

Key parameters

• options.documents (string[], required) — 1 to 1,000 document strings to rank.
• options.prompt (string, required) — the query text used to evaluate relevance.
• options.topN (number, optional) — how many ranked results to return (1 through the length of the documents array). Defaults to 1, so you must set this explicitly if you want more than one result.
• options.maxTokensPerDocument (number, optional) — truncation limit per document, between 1 and 32,768. Default is 4,096.
• options.reRankModelFamily (string, optional) — model family enum value. Defaults to llm.ReRankModelFamily.COHERE_RERANK. Currently this appears to be the only documented option.
• options.timeout (number, optional) — request timeout in milliseconds. Default 30,000 ms.

Response shape

Returns an llm.ReRankResponse object. The response contains a documentRanks array where each entry has:

• index — the position of the document in the original options.documents array.
• relevance — a numeric relevance score.

The response does not echo back the document text or generate an answer. You must map index back to your input array yourself.

Concurrency limit

A parallel-request cap exists (error code MAXIMUM_PARALLEL_RE_RANK_REQUESTS_LIMIT_EXCEEDED), but Oracle does not document the exact threshold. Plan for retry/back-off logic if you are issuing concurrent reRank calls from scheduled or map/reduce scripts.

Error codes to handle

• CAN_RERANK_1_DOCUMENTS_AT_MAXIMUM — more than 1,000 documents supplied.
• NO_DOCUMENTS_TO_RERANK — empty array.
• TOP_N_CANNOT_EXCEED_NUMBER_OF_DOCUMENTS / TOP_N_MUST_BE_POSITIVE — topN out of range.
• MAX_TOKENS_PER_DOCUMENT_CANNOT_EXCEED_1 / MAX_TOKENS_PER_DOCUMENT_MUST_BE_POSITIVE — maxTokensPerDocument out of range (note: the error code text says "1" but the actual ceiling is 32,768).
• INVALID_MODEL_FAMILY_VALUE — unsupported enum value.

Example

const documents = [
  "Standard delivery takes three to five business days.",
  "Contact support about damaged items to request a refund."
];

const response = llm.reRank({
  documents: documents,
  prompt: "How can I get a refund for a damaged item?",
  reRankModelFamily: llm.ReRankModelFamily.COHERE_RERANK,
  topN: documents.length
});

const rankedDocuments = response.documentRanks.map((rank) => ({
  document: documents[rank.index],
  relevance: rank.relevance
}));

What to do

1. Governance budgeting — at 50 units per call, reRank is relatively expensive. In a Map/Reduce or Scheduled script, account for this alongside any other N/llm calls (e.g., llm.generateText) to avoid hitting governance ceilings.
2. Set topN explicitly — the default of 1 is almost certainly not what you want. Pass topN: documents.length to get a full ranking, or a smaller value if you only need the top few matches.
3. Handle concurrency errors — wrap calls in try/catch for MAXIMUM_PARALLEL_RE_RANK_REQUESTS_LIMIT_EXCEEDED and implement exponential back-off, especially in parallelized Map/Reduce stages.
4. Token truncation awareness — documents longer than 4,096 tokens (default) are silently truncated. If your documents are long-form (e.g., saved-search HTML results, PDF text extracts), raise maxTokensPerDocument up to 32,768 or pre-truncate to the portion that matters.
5. SuiteScript 2.1 only — this method is not available in SuiteScript 2.0. Ensure your script’s @NApiVersion tag is set to 2.1.
6. Server-side only — client scripts, Suitelets rendering client-side UI, and user-event beforeLoad running in the browser cannot call this method. Offload relevance ranking to a Suitelet, RESTlet, or scheduled script and call it asynchronously if you need results on the client.