Table of contents

Keboola Integration

Keboola is a data platform that helps organizations build scalable, automated data pipelines by orchestrating data collection, transformation, and delivery.

Recombee provides two components in Keboola:

Data Destination for uploading items, users, and interactions
Data Source for requesting recommendations

Data Destination

The Recombee Data Destination for Keboola uploads items, users, and interactions from CSV tables in Keboola to Recombee to power personalized recommendations and search.

It supports all major Recombee APIs for catalog and behavior data ingestion.

✨ Features

Uploads Items Catalog and Users Catalog
Supports all standard Recombee interactions:
- AddDetailView
- AddPurchase
- AddRating
- AddBookmark
- AddCartAddition
- SetViewPortion
Supports optional fields (e.g., timestamp, recomm_id, additional_data)
Gracefully handles bad data (e.g. NaN, invalid types) and logs summarizations

⚙️ Configuration

You can configure the component directly in the Keboola UI when setting up the component.

Field	Description
Database ID	Your Recombee Database ID
Private Token	Associated private token
Region	Recombee cluster region of your DB (eu-west, us-west, ap-se, etc.)
Batch Size	[Optional] Number of requests sent per batch. Defaults to 1000.

Recombee Data Destination configuration in Keboola

🧱 Input Structure

Place CSV files in in/tables/.

Catalog

Filename	Recombee API	Required Columns	Optional Columns
items.csv	SetItemValues	item_id	All others based on your Recombee item properties (e.g. title, price, tags)
users.csv	SetUserValues	user_id	All others based on your Recombee user properties (e.g. subscribed_topics, age, country)

Interactions

Filename	Recombee API	Required Columns	Optional Columns
bookmarks.csv	AddBookmark	user_id, item_id	timestamp, recomm_id, additional_data
cart_additions.csv	AddCartAddition	user_id, item_id	timestamp, recomm_id, amount, additional_data
detail_views.csv	AddDetailView	user_id, item_id	timestamp, recomm_id, duration, additional_data
purchases.csv	AddPurchase	user_id, item_id	timestamp, recomm_id, amount, price, profit, additional_data
ratings.csv	AddRating	user_id, item_id, rating	timestamp, recomm_id, additional_data
view_portions.csv	SetViewPortion	user_id, item_id, portion	timestamp, recomm_id, additional_data

Notes

item_id / user_id must always be in the first column for catalog files.
Columns such as tags, additional_data, imageList should be passed as valid JSON strings.

📤 Example Input - detail_views.csv

user_id,item_id,timestamp,recomm_id,additional_data
user-1,item-10,2025-07-06T21:12:43Z,644c005f-aa99-4bce-aa55-a0c610e80df0,"{""source"": ""newsletter""}"
user-2,item-09,2025-07-06T21:09:13Z,,"{""source"": ""newsletter""}"
user-3,item-05,2025-07-06T21:14:45Z,2d2eb48f-cd65-421a-943c-0e015055fd8e,"{""source"": ""homepage""}"

📤 Example Input - items.csv

Item properties must be created in the Recombee Admin UI.

item_id,title,price,available,date_added,tags
item-01,Wireless Mouse,25.99,true,2025-07-20T10:11:49.039302,"[""electronics"", ""accessory"", ""mouse""]"
item-42,Mechanical Keyboard,75.49,false,2025-08-04T10:11:49.039318,"[""electronics"", ""keyboard""]"
item-77,USB-C Hub,34.9,true,2025-08-19T10:11:49.039321,"[""electronics"", ""usb"", ""hub""]"

Data Source

The Recombee Data Source fetches recommendations from Recombee via selected recommendation endpoint and exports the results as structured CSV tables.

✨ Features

Supports following Recombee recommendation endpoints:
Uses batch requests with automatic retry handling
Supports using Scenarios
Supports returning item properties (metadata) of the recommended items
Outputs results with full Recombee API response for auditability

⚙️ Configuration

You can configure the component directly in the Keboola UI when setting up the component.

Field	Description
Database ID	The ID of your Recombee database (e.g., "your-database-id").
Private Token	The private token used to authenticate requests to Recombee.
Region	Region where your Recombee database is hosted (ap-se, ca-east, eu-west, us-west). Defaults to eu-west.
Scenario	The recommendation scenario to be used (e.g., "emailing", "related-items"). Should match the scenario set up in Recombee Admin UI.
Recommendation Endpoint	Which Recombee endpoint to use for fetching recommendations. Must align with the selected scenario (e.g., Recommend Items to User, Recommend Items to Item, etc.).
Number of Recommendations	How many recommended items to fetch per user or item. Integer from 1 to 30. Defaults to 5.
Included Properties	Optional. List of item properties to include in the response (e.g., ["title", "url", "image"]).
Batch Size	Number of users or items to fetch recommendations for in one batch. Optional. Defaults to 100. Range: 10–10000.

Recombee Data Source configuration in Keboola

🧱 Input Structure

Place one CSV file into in/tables/, depending on the selected recommendation endpoint.

Filename	Used For Endpoint(s)
users.csv	Recommend Items to User / Recommend Item Segments to User
items.csv	Recommend Items to Item

The CSV file must contain a single column with IDs of users / items for which recommendations should be generated.

Example Input

user_id
user_3fa8c1
user_4b92d8
user_7c13f0
user_1d8a9e

📤 Output Format

The recommendations are exported to out/tables/recomms.csv.

Column	Description
user_id / item_id	The ID the recommendation was generated for
recomm_id	Recombee recommId used for tracking
recommended_items / recommended_item_segments	List of recommended item or segment IDs
api_response	Full JSON response from Recombee (including e.g., the returned properties)

Example Output - recomms.csv

user_id,recomm_id,recommended_items,api_response
user_3fa8c1,cc08bcf0-9d8e-4726-8b21-e47f770316e1,"[""item-165"", ""item-69"", ""item-857""]","{""recommId"": ""cc08bcf0-9d8e-4726-8b21-e47f770316e1"", ""recomms"": [{""id"": ""item-165""}, {""id"": ""item-69""}, {""id"": ""item-857""}], ""numberNextRecommsCalls"": 0}"
user_4b92d8,9c291302-abcd-4ab4-b926-aceac05ad15a,"[""item-165"", ""item-69"", ""item-857""]","{""recommId"": ""9c291302-abcd-4ab4-b926-aceac05ad15a"", ""recomms"": [{""id"": ""item-165""}, {""id"": ""item-69""}, {""id"": ""item-857""}], ""numberNextRecommsCalls"": 0}"

Notes

Use the Included Properties configuration parameter to include item metadata such as title, url, category, or price in the api_response column.
All values in recommended_items or recommended_item_segments are exported as JSON arrays.