feat: add recommendation engine use case by robfrank · Pull Request #1 · ArcadeData/arcadedb-usecases

robfrank · 2026-02-25T11:15:51Z

Summary

Adds the first use case: recommendation-engine/, a self-contained ArcadeDB demo showing multi-model capabilities (graph traversal, vector similarity, time-series)
Five query patterns demonstrated via both curl (queries/queries.sh) and a Java fat JAR (java/ with arcadedb-network:26.2.1)
Includes Docker Compose (ArcadeDB 26.2.1), SQL schema/data files, and a setup script

What's included

recommendation-engine/
├── docker-compose.yml       ArcadeDB 26.2.1
├── setup.sh                 creates DB, applies schema + data
├── sql/01-schema.sql        User, Product, Show vertices; PURCHASED, WATCHED, INTERACTED edges; ProductInteraction documents; LSM_VECTOR indexes
├── sql/02-data.sql          5 users, 10 products, 5 shows, ~30 edges
├── queries/queries.sh       all 5 queries via curl
├── java/pom.xml             standalone Maven, arcadedb-network dep, fat JAR
└── java/src/.../RecommendationEngine.java  runs all 5 queries

Query patterns

#	Pattern	Signal
1	Collaborative Filtering	Graph (Cypher)
2	Vector Similarity Search	Vector (SQL + vectorNeighbors)
3	Trending Detection	Time-series (SQL)
4	Multi-Model Hybrid (Streaming)	Graph + Vector (MATCH)
5	Personalized Category Page	Vector (SQL + vectorNeighbors)

Test plan

docker compose up -d starts ArcadeDB healthy
./setup.sh completes without errors
./queries/queries.sh returns results for all 5 queries
cd java && mvn package -q && java -jar target/recommendation-engine.jar prints all 5 query result sets

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

… string Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

…INDEX

…rs in curl queries

…rs in Java, add per-query error handling

…ectorNeighbors calls

…atibility - Query 2: use vectorNeighbors in ORDER BY for sorted vector similarity - Query 4: replace unsupported LET+GROUP BY with MATCH syntax - Query 5: switch from Cypher to SQL for vectorNeighbors support Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

gemini-code-assist · 2026-02-25T11:16:17Z

Summary of Changes

Hello @robfrank, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new, self-contained recommendation-engine use case designed to showcase ArcadeDB's powerful multi-model features. It provides a practical, end-to-end example of how to combine graph traversal, vector similarity search, and time-series data to build intelligent recommendation systems. The inclusion of both curl and Java-based runnable demos, along with a complete setup, aims to facilitate easy adoption and experimentation with ArcadeDB's capabilities.

Highlights

New Use Case Added: Introduced a comprehensive recommendation-engine/ use case demonstrating ArcadeDB's multi-model capabilities.
Multi-Model Capabilities: Showcases graph traversal, vector similarity search, and time-series data for intelligent recommendations within a single database.
Diverse Query Patterns: Includes five distinct query patterns covering collaborative filtering, vector similarity, trending detection, and multi-model hybrids.
Runnable Demos: Provides runnable examples via both curl scripts and a Java fat JAR using arcadedb-network.
Easy Setup: Comes with Docker Compose, SQL schema/data files, and a setup.sh script for quick deployment and testing.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

.gitignore
- Added log/ to the ignore list for Maven build output.
README.md
- Updated the root README to introduce the new 'ArcadeDB Use Cases' section.
- Added a table listing the recommendation-engine use case with its description and features.
- Included a 'Structure' section detailing common files within each use case directory.
docs/plans/2026-02-25-recommendation-engine-design.md
- Added a new design document outlining the architecture, repository structure, Docker Compose setup, schema, sample data, query patterns, and Java program details for the recommendation engine.
docs/plans/2026-02-25-recommendation-engine.md
- Added a detailed implementation plan document for the recommendation engine use case, including step-by-step tasks for scaffolding, Docker Compose, SQL schema/data, scripts, and Java code.
recommendation-engine/README.md
- Added a dedicated README for the recommendation engine use case, providing an overview, prerequisites, quickstart guide, schema details, query patterns, sample data, and ArcadeDB version notes.
recommendation-engine/docker-compose.yml
- Added a Docker Compose file to set up an ArcadeDB 26.2.1 instance with exposed port and root password environment variable.
recommendation-engine/java/pom.xml
- Added a Maven pom.xml file for the Java demo application, including arcadedb-network dependency and assembly plugin configuration to create a fat JAR.
recommendation-engine/java/src/main/java/com/arcadedb/examples/RecommendationEngine.java
- Added the main Java application class (RecommendationEngine.java) which connects to ArcadeDB and executes all five recommendation query patterns, printing their results.
recommendation-engine/queries/queries.sh
- Added a shell script (queries.sh) that demonstrates all five recommendation query patterns using curl commands against the ArcadeDB HTTP API.
recommendation-engine/setup.sh
- Added an executable shell script (setup.sh) to wait for ArcadeDB, create the RecommendationEngine database, and apply the SQL schema and sample data files.
recommendation-engine/sql/01-schema.sql
- Added SQL statements to define the schema for User, Product, Show vertex types, PURCHASED, WATCHED, INTERACTED edge types, and ProductInteraction document type, including unique and LSM_VECTOR indexes.
recommendation-engine/sql/02-data.sql
- Added SQL statements to insert sample data for users, products (electronics, sports), shows, and various PURCHASED, WATCHED, and INTERACTED edges, along with ProductInteraction documents for trending analysis.

Activity

A new recommendation-engine use case was added, complete with Docker Compose setup, SQL schema and data, curl query scripts, and a Java demo application.
Detailed design and implementation plan documents were created to guide the development of this new use case.
The root README.md was updated to reflect the addition of this new example and provide a structured overview of the repository's use cases.
The .gitignore file was updated to include log/ for Maven output.
The entire feature, including code and documentation, was generated using Claude Code, indicating an AI-assisted development process.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a new, self-contained recommendation engine use case, which is a valuable addition for demonstrating ArcadeDB's capabilities. The implementation is well-structured with Docker, SQL setup, and examples in both shell script and Java.

My review focuses on several areas for improvement:

Consistency: There are multiple discrepancies between the documentation (READMEs, design/implementation plans) and the actual code, particularly regarding the logic of the example queries. Some queries do not perform the multi-model operations they are described to.
Correctness: The database setup script is not idempotent and will fail if run more than once due to missing IF NOT EXISTS clauses on CREATE INDEX statements.
Clarity: Some query descriptions are misleading, which can confuse users trying to understand the examples.

Addressing these points will significantly improve the quality and clarity of this new use case.

gemini-code-assist · 2026-02-25T11:19:06Z

+# Recommendation Engine Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build a fully self-contained `recommendation-engine/` directory demonstrating ArcadeDB's multi-model capabilities (graph traversal, vector similarity, time-series) via five query patterns, runnable with both `curl` and a Java program.
+
+**Architecture:** Self-contained directory per the design doc. Docker Compose brings up ArcadeDB 26.2.1. A `setup.sh` creates the database and applies SQL files. Five queries are demonstrated via `queries/queries.sh` (curl) and `java/` (Maven fat JAR using `arcadedb-network`).
+
+**Tech Stack:** ArcadeDB 26.2.1, Docker Compose, Maven 3.x, Java 17+, `com.arcadedb:arcadedb-network:26.2.1`, `jq` (for setup script)
+


This implementation plan, along with the design document, appears to be out of sync with the final implementation. There are several discrepancies:

The method for setting the database password in Docker Compose is different.

The queries for patterns 2, 4, and 5 use different functions (vectorDistance vs vectorNeighbors) and logic than what is implemented.

Query 4 in the plan is a hybrid query, but the implementation is a simple collaborative filter.

Outdated planning documents can cause confusion for future developers. To improve maintainability, please consider either updating these documents to match the final code or removing them if they are no longer relevant.

Added an "Implementation notes" block at the top of the plan doc (8f2cd50) listing the four deviations from the plan: Docker env var, vectorDistance → vectorNeighbors, unsupported LET+GROUP BY, and the full index name requirement for vectorNeighbors.

- Add IF NOT EXISTS to LSM_VECTOR CREATE INDEX statements (idempotency) - Rename Query 4 from 'Multi-Model Hybrid' to 'Graph Traversal' to accurately reflect that it uses graph traversal only, not a vector+graph hybrid (LET+GROUP BY not supported in ArcadeDB 26.2.1) - Remove misleading '+ trending interactions' from Query 5 description - Update README query pattern table to show Graph signal for pattern 4 - Add implementation notes to plan doc documenting 26.2.1 deviations Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

robfrank and others added 21 commits February 25, 2026 10:19

Add recommendation engine design doc

851c09e

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Add recommendation engine implementation plan

fc152ab

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

chore: scaffold recommendation-engine directory structure

1982d9d

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

feat(recommendation-engine): add docker-compose for ArcadeDB 26.2.1

93aa460

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

feat(recommendation-engine): add graph schema SQL

1840511

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

feat(recommendation-engine): add sample data SQL

ab397e4

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

feat(recommendation-engine): add database setup script

306a081

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

fix(recommendation-engine): fix shebang in setup.sh

59b57fc

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

feat(recommendation-engine): add curl query demonstrations

b185ab4

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

feat(recommendation-engine): add Maven project for Java demo

b8f6323

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

feat(recommendation-engine): add Java RecommendationEngine main class

bef1d90

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

fix(recommendation-engine): fix escaped \!= operators in Java Query 4…

4b532a9

… string Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

fix(recommendation-engine): add vector indexes and idempotent CREATE …

ea48b6a

…INDEX

fix(recommendation-engine): replace vectorDistance with vectorNeighbo…

de9c93b

…rs in curl queries

fix(recommendation-engine): replace vectorDistance with vectorNeighbo…

f4dcb6a

…rs in Java, add per-query error handling

fix(recommendation-engine): use JAVA_OPTS to set ArcadeDB root password

fffa5b7

fix(recommendation-engine): use full index name 'Type[property]' in v…

e7ecbe6

…ectorNeighbors calls

docs(recommendation-engine): add README with quickstart guide

4bf9917

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

docs: update root README with use cases table

c2957c2

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

chore: ignore Maven log/ directories

397786a

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

gemini-code-assist Bot reviewed Feb 25, 2026

View reviewed changes

robfrank merged commit d859a08 into main Feb 25, 2026

claude Bot mentioned this pull request Feb 25, 2026

Feat/knowledge graphs #9

Merged

robfrank mentioned this pull request Feb 26, 2026

feat: add Graph RAG use case #10

Merged

6 tasks

claude Bot mentioned this pull request Mar 2, 2026

feat: add fraud detection use case #16

Merged

8 tasks

claude Bot mentioned this pull request Mar 23, 2026

feat(feature-store): add AI/ML Feature Store use case #60

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add recommendation engine use case#1

feat: add recommendation engine use case#1
robfrank merged 22 commits into
mainfrom
feat/recommendation-engine

robfrank commented Feb 25, 2026

Uh oh!

gemini-code-assist Bot commented Feb 25, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist Bot Feb 25, 2026

Uh oh!

robfrank Feb 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

robfrank commented Feb 25, 2026

Summary

What's included

Query patterns

Test plan

Uh oh!

gemini-code-assist Bot commented Feb 25, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist Bot Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

robfrank Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant