Skip to content

README.md

Latest commit

 

History

History
191 lines (145 loc) · 6 KB

README.md

File metadata and controls

191 lines (145 loc) · 6 KB

Databricks Genie Chat Visualization App

A modern conversational interface for Databricks Genie with AI-powered data visualization and geospatial mapping capabilities.

Demo

Features

  • Natural language queries to Databricks Genie
  • Automatic chart recommendations powered by AI
  • Geospatial visualizations (US choropleth maps, scatter geo)
  • Multi-series charts for complex time series data
  • Dark theme UI optimized for extended sessions
  • Real-time data fetching and updates

Tech Stack

  • Frontend: Angular 17 with standalone components
  • Backend: Node.js + Express with TypeScript
  • Visualization: Chart.js (standard charts), Plotly.js (geospatial)
  • AI: Databricks Model Serving for intelligent chart selection

Quick Start

The easiest way to get started is with the automated setup script:

./run_setup.sh \
  --workspace myworkspace.cloud.databricks.com \
  --catalog main \
  --schema genie_demo

This single command will:

  1. Install dependencies and build the app
  2. Create a serverless SQL warehouse
  3. Generate sample sales data (2,000 records)
  4. Create a Genie Space with the data
  5. Configure app.yaml with all settings
  6. Deploy the app to Databricks

See setup/README.md for all options.

Prerequisites

  • Node.js 18+ and npm
  • Python 3.8+
  • Databricks CLI configured with authentication: 
    pip install databricks-cli
databricks configure

Local Development

To run locally without deploying:

# 1. Install dependencies
npm run install:all

# 2. Configure environment
cp backend/env.example backend/.env
# Edit backend/.env:
#   DATABRICKS_HOST=myworkspace.cloud.databricks.com
#   DATABRICKS_SPACE_ID=your-space-id
#   MODEL_SERVING_ENDPOINT=databricks-meta-llama-3-1-70b-instruct

# 3. Run development servers
npm run dev

Access the application:

Project Structure

databricks-genie-chat/
├── backend/                 # Express.js API server
│   ├── src/
│   │   ├── routes/          # API endpoints
│   │   ├── services/        # Databricks API, chart recommendations
│   │   └── server.ts        # Express app setup
│   ├── env.example          # Environment template
│   └── package.json
├── frontend/                # Angular 17 application
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/  # Chat, Message, Chart components
│   │   │   └── services/    # API, Chat, Chart services
│   │   └── styles.css       # Global styles
│   └── package.json
├── setup/                   # Automated setup scripts
├── shared/                  # Shared TypeScript types
├── app.yaml                 # Databricks Apps configuration
└── package.json             # Root scripts

Configuration

app.yaml (Required for Databricks Apps Deployment)

Before deploying, update app.yaml with your workspace-specific values:

- name: DATABRICKS_HOST
  value: <your-workspace>.cloud.databricks.com       # Your workspace URL
- name: DATABRICKS_SPACE_ID
  value: <your-genie-space-id>                        # Your Genie Space ID
resources:
- name: genie-space
  genie_space:
    id: <your-genie-space-id>                         # Same Genie Space ID as above

You can find your Genie Space ID from the URL when viewing a Genie Space: https://<workspace>.cloud.databricks.com/genie/rooms/<space-id>

Note: If you use the automated setup script (./run_setup.sh), app.yaml is configured automatically.

Environment Variables

Variable Description
DATABRICKS_HOST Your workspace URL (e.g., myworkspace.cloud.databricks.com)
DATABRICKS_SPACE_ID Your Genie Space ID
MODEL_SERVING_ENDPOINT Model endpoint for chart recommendations
PORT Server port (default: 3000, use 8000 for Databricks Apps)

Authentication

  • Local Development: Uses Databricks CLI profile (~/.databrickscfg)
  • Databricks Apps: Uses built-in OAuth (automatic)

Supported Visualizations

Standard Charts (Chart.js)

  • Bar, Line, Pie, Doughnut
  • Scatter, Radar, Polar Area, Bubble

Geospatial Charts (Plotly.js)

  • Choropleth maps (US state-level data)
  • Scatter geo (latitude/longitude points)

How It Works

  1. User asks a question → sent to Databricks Genie API
  2. Genie returns SQL + data → displayed in expandable table
  3. AI analyzes the data → recommends appropriate chart type
  4. Chart is rendered → using Chart.js or Plotly.js

The system intelligently:

  • Detects time series data → recommends line charts
  • Identifies categorical data → creates bar/pie charts
  • Finds US state data → generates choropleth maps

Troubleshooting

App fails to start

  • Check logs in Databricks Apps UI
  • Verify app.yaml has correct environment variables
  • Ensure Model Serving endpoint exists and is running

Authentication errors

  • Databricks Apps uses built-in OAuth - no token needed
  • For local development, configure Databricks CLI: databricks configure

Chart recommendations not working

  • Verify MODEL_SERVING_ENDPOINT is set correctly
  • Check that the endpoint is deployed and running
  • View backend logs for error details

Available Scripts

npm run install:all      # Install all dependencies
npm run dev              # Run frontend + backend for development
npm run dev:frontend     # Run only frontend (port 4200)
npm run dev:backend      # Run only backend (port 3000)
npm run build:frontend   # Build Angular app for production
npm run build:backend    # Compile TypeScript backend
npm start                # Start production server

License

This project is licensed under the Databricks License - see the LICENSE.md file for details.

The Databricks License allows you to use this software in connection with Databricks Services. See the license file for full terms and conditions.