User Documentation
API Clients & Integrations
Scenario Recipes
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:
AddDetailViewAddPurchaseAddRatingAddBookmarkAddCartAdditionSetViewPortion
- 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. |
🧱 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_idmust always be in the first column for catalog files.- Columns such as
tags,additional_data,imageListshould 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. |
🧱 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 Propertiesconfiguration parameter to include item metadata such astitle,url,category, orpricein theapi_responsecolumn. - All values in
recommended_itemsorrecommended_item_segmentsare exported as JSON arrays.