# Keboola Integration > Source: https://docs.recombee.com/keboola > For the complete documentation index, see [llms.txt](/llms.txt). **Table of contents** * [Data Destination](#data-destination) * [✨ Features](#data-destination-features) * [⚙️ Configuration](#data-destination-configuration) * [🧱 Input Structure](#data-destination-input-structure) * [Catalog](#data-destination-input-structure-catalog) * [Interactions](#data-destination-input-structure-interactions) * [Notes](#data-destination-input-structure-notes) * [📤 Example Input - detail\_views.csv](#data-destination-example-input-detail-views) * [📤 Example Input - items.csv](#data-destination-example-input-items) * [Data Source](#data-source) * [✨ Features](#data-source-features) * [⚙️ Configuration](#data-source-configuration) * [🧱 Input Structure](#data-source-input-structure) * [Example Input](#data-source-example-input) * [📤 Output Format](#data-source-output-format) * [Example Output - recomms.csv](#data-source-output-format-example) * [Notes](#data-source-output-format-notes) # Keboola Integration Keboola is a data platform that helps organizations build scalable, automated data pipelines by orchestrating data collection, transformation, and delivery. ![](/img/keboola/recombee-keboola-header.png) Recombee provides two components in Keboola: * [**Data Destination**](#data-destination) for uploading items, users, and interactions * [**Data Source**](#data-source) for requesting recommendations ## Data Destination The Recombee Data Destination for [Keboola](https://keboola.com) 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](/img/keboola/keboola_data_destination_configuration.png)](/img/keboola/keboola_data_destination_configuration.png) ### 🧱 Input Structure Place CSV files in `in/tables/`. #### Catalog | Filename | Recombee API | Required Columns | Optional Columns | | --------- | --------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------- | | items.csv | [SetItemValues](/api#request-set-item-values) | item\_id | All others based on your Recombee item properties (e.g. title, price, tags) | | users.csv | [SetUserValues](/api#request-set-user-values) | 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](/api#request-add-bookmark) | user\_id, item\_id | timestamp, recomm\_id, additional\_data | | cart\_additions.csv | [AddCartAddition](/api#request-add-cart-addition) | user\_id, item\_id | timestamp, recomm\_id, amount, additional\_data | | detail\_views.csv | [AddDetailView](/api#request-add-detail-view) | user\_id, item\_id | timestamp, recomm\_id, duration, additional\_data | | purchases.csv | [AddPurchase](/api#request-add-purchase) | user\_id, item\_id | timestamp, recomm\_id, amount, price, profit, additional\_data | | ratings.csv | [AddRating](/api#request-add-rating) | user\_id, item\_id, rating | timestamp, recomm\_id, additional\_data | | view\_portions.csv | [SetViewPortion](/api#request-set-view-portion) | 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](https://admin.recombee.com). ``` 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](https://www.recombee.com/) via selected recommendation endpoint and exports the results as structured CSV tables. ### ✨ Features * Supports following **Recombee recommendation endpoints**: * [Recommend Items to User](https://docs.recombee.com/api#recommend-items-to-user) * [Recommend Items to Item](https://docs.recombee.com/api#recommend-items-to-item) * [Recommend Item Segments to User](https://docs.recombee.com/api#recommend-item-segments-to-user) * Uses batch requests with automatic retry handling * Supports using [Scenarios](https://docs.recombee.com/scenarios) * Supports [returning item properties](https://docs.recombee.com/api#recommend-items-to-user-param-includedProperties) (metadata) of the recommended items * Outputs results with full Recombee API response for auditability [![Recombee Data Source in Keboola](/img/keboola/keboola_data_source.png)](/img/keboola/keboola_data_source.png) ### ⚙️ 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](/img/keboola/keboola_data_source_configuration.png)](/img/keboola/keboola_data_source_configuration.png) ### 🧱 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](https://docs.recombee.com/api#recommend-items-to-user) / [Recommend Item Segments to User](https://docs.recombee.com/api#recommend-item-segments-to-user) | | items.csv | [Recommend Items to Item](https://docs.recombee.com/api#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](https://docs.recombee.com/getting_started#reporting-successful-recommendations) 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.