> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Search Recommendations

Rank items by their predicted conversion for each known search term during the next 30 days. This is a term to item ranking decision. It does not predict the results for a new raw search string or determine which items are textually relevant to that string.

## Data and relationships

The example assumes a Kumo Engine `graph` and matching `snapshot` with these tables:

| Table             | Required columns and role                                                                                                                                             |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stemmed_queries` | `stemmed_query_id` is the primary key for each normalized search term to score.                                                                                       |
| `items`           | `item_id` is the primary key for each candidate item.                                                                                                                 |
| `search_events`   | `search_event_id` is the primary key; `stemmed_query_id` identifies the term used in a search.                                                                        |
| `conversions`     | `conversion_id` is the primary key; `search_event_id`, `stemmed_query_id`, `item_id`, and `timestamp` identify the attributed search, term, converted item, and time. |

Connect `search_events.stemmed_query_id` to `stemmed_queries.stemmed_query_id`. Connect each conversion to its search event and item. Also connect `conversions.stemmed_query_id` directly to `stemmed_queries.stemmed_query_id`, and mark `conversions.timestamp` as the time column. Populate each conversion's `stemmed_query_id` from its referenced search event before building the graph. The predictive query requires this direct term key; the search event relationship alone does not supply it.

Only include conversions that your source data can attribute to a search event. A search without a linked conversion is not a conversion label. Keep the normalized term catalog and attribution rule consistent between training and prediction.

## Rank future conversions by search term

This Python query ranks distinct items that may convert after an observation time and within the following 30 days. `graph` and `snapshot` refer to the data described above. `trainer` is a fitted model for this query; fitting it is outside this use case.

```python
from datetime import datetime
from kumo.engine import PredictiveQuery

query_text = (
    "PREDICT LIST_DISTINCT(conversions.item_id, 0, 30, days) "
    "RANK TOP 20 FOR EACH stemmed_queries.stemmed_query_id"
)
query = PredictiveQuery(graph, query_text)
query.validate()
print(query.get_task_type())  # temporal_link_prediction

prediction_time = datetime(2024, 4, 30, 12)  # Replace with your chosen UTC time.
prediction_table = query.generate_prediction_table(
    snapshot, prediction_time=prediction_time
)
ranked = trainer.predict(
    prediction_table, snapshot=snapshot, num_classes_to_return=20
).frame
```

Choose a prediction time after the latest observed conversion for a live forecast. The prediction table selects the catalog of known terms at that time; it does not train a model. In `ranked`, `ENTITY` identifies a normalized search term, `CLASS` identifies an item, and `SCORE` orders candidate items for that term. A score is not a guaranteed conversion probability.

For a live search, first map the submitted text to a term in `stemmed_queries`. Apply your search system's relevance, availability, and policy rules to the ranked candidates before displaying them. If the text has no matching known term, this example does not produce a term specific ranking for it. Because `RANK TOP 20` limits candidates before those rules run, a search may have fewer than 20 eligible items or none.