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.

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.